# @flourish/controls 中文文档

规范地址：https://npmcn.com/package/%40flourish/controls/

版本：11\.0\.1
npm 元数据更新时间：2026-09-01T12:50:04.532Z
中文译文更新时间：2026-11-15T00:03:07.611Z
软件包许可：LicenseRef-LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flourish/controls
原文对照：https://npmcn.com/package/%40flourish/controls/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：257 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：8 个
- 首次发布：2017-09-26T16:47:07.426Z
- 最新版本发布：2026-09-01T12:50:04.326Z
- 近 30 天下载量：5889（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 6 个）

## 中文简介

可切换的下放/按钮/滑行控制

## 安装

```sh
npm install @flourish/controls
```

也可以使用：`pnpm add @flourish/controls`、`yarn add @flourish/controls`、`bun add @flourish/controls`

## README

# 面粉控件

将可互换的控制器(倒放、按钮或滑动器)和控制容器添加到页面中.

## 如何安装

`npm install -s @flourish/controls`

将一个或多个控制对象添加到您的模板状态以及控制容器的对象

```js
export var state = {
    controls_container: {},
    buttons_control: {
        control_type: "buttons"
    },
    dropdown_control: {
        control_type: "dropdown"
    },
    ...
}
```

添加控制容器的设置 `template.yml`。 。 。 .

```yaml
  - property: controls_container
    import: "@flourish/controls/container"
```

这将在设置中增加控制容器对齐和间隔选项.

然后导入 `@flourish/controls` 每个控件实例.

```yaml
- property: buttons_control
    import: "@flourish/controls"
- property: dropdown_control
    import: "@flourish/controls"
```

## 基本情况

初始化任何函数以外的控制容器和个人控制:

```js
import { createControlsContainer, createControls } from "@flourish/controls";

var buttons_control = createControls(state.buttons_control);
var dropdown_control = createControls(state.dropdown_control)

var controls_container = createControlsContainer(state.controls_container)
    .appendTo(layout.getSection("controls"))
    .add([buttons_control, dropdown_control]);

```

您可以使用第二个参数在控件中添加 id 字符串 :

```js
var buttons_control = createControls(state.buttons_control, "fl-buttons-control");
```

在每个控件实例中添加一个更改处理器 : `buttons_control.on("change", update);`。通常在 `draw` 函数.

单位 `update` 组合 `options` 然后打电话 `update` 容器和控制器上的方法:

```
controls_container.update();

buttons_control
    .options(button_options)
    .update();

dropdown_control
    .options(dropdown_options)
    .update();
```

如果你同时使用这个模块 `@flourish/ui-styles` 您应该首先从 ui 样式对象中调用更新方法(这将确保下拉图标正确匹配 ui 样式面板中设置的大小和颜色样式)。 例如:

```
function updateControlStyles() {
    controls_style.update();
    button_style.update();
    dropdown_style.update();
    slider_style.update();
}

updateControlStyles();
```

## 集装箱方法

### `appendTo(parent_container)`

将控制容器附加到 `parent_container` DOM 节点( 这通常应该是 `layout.getSection("controls")`) (中文(简体) ). 返回控制容器对象.

### `add([controls_instances])`

取出一系列控制实例并将其附加到控制容器中。 返回控制容器对象.

### `update()`

这更新了控制容器和所有附加的控制实例(调用其个人) `update()` 方法问题。 返回控制容器对象.

## 控制方法

### `appendTo(parent_container)`

将控件附加到 `parent_container` DOM 节点并注入 CSS `head` 必要时.

返回控制对象.

### `format(formatterFunction, exclude)`

指定用于格式化控件内容的输出格式。 这个功能来自 `@flourish/formatters` 模块或一个 `output_format_id` 从 `@flourish/interpreter` 模块。 可选通过一系列的数值来排除格式化.

### `getNode()`

返回已创建的控件容器。 它会有一个阶级 `"fl-controls-container"`

### `getSortedIndex()`

在选项数组的排序版本中返回当前所选值的索引.

### `index([i])`

没有参数返回当前所选选项的(未分类)索引。 若为 `i` 指定并对应到 `options` 数组,设置当前选中的选项到 `i`返回控制对象.

### `n_options()`

返回当前选项数.

### `on(event, callback)`

添加 `callback` 名单 `event` 管理者。 目前唯一得到支持的 `event` 是"改变"。 返回控制对象.

### `options([arr])`

没有参数返回当前控件显示的当前选项列表的副本 。 用数组,将当前选项替换为副本 `arr` 并返回控制对象.

### `parse(parserFunction)`

指定用于解析控件内容的函数。 这个功能来自 `@flourish/localization` 或者说 `@flourish/interpreter` 模块.

### `remove()`

从 DOM 中删除控件(及其大小调整事件处理器) 。 返回控制对象.

### `trigger(event)`

呼叫指派给的所有处理者 `event` 并返回控制对象。 目前唯一获得支持的 `event` 类型是“改变”.

### `update()`

以最新设置重建控件。 返回控制对象.

### `value([val])`

没有参数返回当前选中选项的字符串值 。 与 `val` 当前修改当前索引以匹配 `val` 在选项数组中返回控制对象。 若为 `val` 不在选项数组中,则没有更改,但仍然返回控制对象.

### `visible([boolean])`

设置控件的能见度

## 设置控件

控制有非常基本的外观。 你可以用自己的cs和造型来覆盖这些风格. 我们建议使用 [@flourish/ui风格](https://github.com/kiln/flourish-ui-styles) 用于样式控件.

## 常见问题

### @flourish/controls 是什么？

可切换的下放/按钮/滑行控制

### 如何安装 @flourish/controls？

在项目目录运行 npm install @flourish/controls，或使用 pnpm add / yarn add / bun add。

### @flourish/controls 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flourish\_\_controls 是否存在。

### @flourish/controls 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flourish/controls 可以商用吗？

@flourish/controls 使用 LicenseRef-LICENSE 许可。声明的许可为 LicenseRef-LICENSE，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @flourish/controls 的下载量有多少？

根据 npm 官方下载统计，@flourish/controls 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,889 次，日均约 196 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flourish/controls 还在维护吗？

最新版本 11\.0\.1 发布于 2026/09/01（2 个月前）；至今共发布 61 个版本，其中过去 12 个月发布了 6 个；首次发布于 2017/09/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。