# @dloizides/ui-forms 中文文档

规范地址：https://npmcn.com/package/%40dloizides/ui-forms/

版本：1\.38\.0
npm 元数据更新时间：2026-11-12T08:46:28.623Z
中文译文更新时间：2026-11-12T12:48:06.894Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dloizides/ui-forms
原文对照：https://npmcn.com/package/%40dloizides/ui-forms/?lang=original
项目主页：https://github.com/openmindednewby/ui-forms#readme
源码仓库：https://github.com/openmindednewby/ui-forms

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

- 包体积（解压后）：1.5 MB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0，react-native \>=0\.74\.0，react-native-svg \>=13\.0\.0，@dloizides/ui-buttons \>=1\.20\.1，@dloizides/ui-feedback \>=1\.1\.0
- 首次发布：2026-06-16T06:51:49.030Z
- 最新版本发布：2026-11-12T08:46:28.467Z
- 近 30 天下载量：5794（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

”FormField、ChipSelector、FormSwitch ”共享@dloizides/ui-feedback UI语境。 dloizides.com部分共享UI套装.

## 安装

```sh
npm install @dloizides/ui-forms
```

也可以使用：`pnpm add @dloizides/ui-forms`、`yarn add @dloizides/ui-forms`、`bun add @dloizides/ui-forms`

## README

# @dloizides/ui-形式

(原始内容存档于2013-10-12). Themable, Brand-anoistic React Introduction (RN-web) **表单** dloizides.com 组件 组合 : `Field`, (中文(简体) ), `FormField`, (中文(简体) ), `ChipSelector`, (中文(简体) ), `FormSwitch`。它们读取共享的主题颜色 `@dloizides/ui-feedback` UI 语境( E)`useUi`) ——上一个 `UiProvider` 编号 : `FeedbackUiProvider` 在您的应用根中, 这些组件自动拾取您的主题 .

## 安装

```bash
npm install @dloizides/ui-forms @dloizides/ui-feedback
```

同伴依赖性 : `@dloizides/ui-feedback >= 1.1.0`, (中文(简体) ), `react >= 18`, (中文(简体) ), `react-native >= 0.74` (使用时 `react-native-web` ) (中文(简体) ).

## 使用量

```tsx
import { FormField, ChipSelector, FormSwitch } from '@dloizides/ui-forms';

<FormField label="Email" required error={errors.email} value={email} onChangeText={setEmail} />
<ChipSelector label="Plan" options={plans} value={plan} onChange={setPlan} />
<FormSwitch label="Email notifications" value={notify} onValueChange={setNotify} />
```

## `Field` 标记任何控件,而不仅仅是文字输入

`FormField` 被硬线接入文本输入。 对于 **任何其他控制** 滴滴滴滴 取枣子, 芯片选择器 — 把它包入 `Field` 以获取相同的标签行、所需的标记、出错行和 底间距. 这也是保持下降与 `FormField` 旁边:没有它 倒放的框会启动高一行的标签,而行会失去它的垂直节奏.

```tsx
import { Field } from '@dloizides/ui-forms';

<Field label="Currency" required error={errors.currency}>
  <ModalDropdown options={currencies} value={currency} onChange={setCurrency} />
</Field>
```

`FormField` **财务报告和审定财务报表** `ChipSelector` 编曲 `Field` 内部,所以标签行永远不能漂移 由于它们之间相互一致,工具包中就有一个标签.

将出错线接入自定义控制器 `aria-describedby` / 无效状态, 通过 a **函数** 儿童——接受 `{ describedById, hasError }` (单位:千美元)`describedById` 实值 `undefined` 当没有错误的时候:

```tsx
<Field label="Country" error={errors.country}>
  {({ describedById, hasError }) => (
    <CountryPicker aria-describedby={describedById} hasError={hasError} value={country} onChange={setCountry} />
  )}
</Field>
```

| Prop | 类型 | 页:1 |
| --- | --- | --- |
| `label` | `string` | 选项 —— 空白或空标签使无标签行 |
| `children` | `ReactNode | (ctx) => ReactNode` | 控件 |
| `required` | `boolean` | 使装饰 `*` (隐藏在辅助技术) |
| `error` | `string` | 制作一个 `role="alert"` 线条,通过孩子的链接 `describedById` |
| `containerStyle` | `ViewStyle` | 在容器上合并 |
| `testID` | `string` | 在容器上 |

注入的主题需要 `colors.{surface,text,textSecondary,border}`, (中文(简体) ), `palette.primary['500']` 财务报告和审定财务报表 `semantic.error['500']` - 通过下列渠道提供: `@dloizides/ui-feedback`供养者. 没有供应商 中性默认主题.

## `ChipSelector`

```tsx
<ChipSelector
  label="Plan"
  required
  error={errors.plan}
  options={plans}
  value={plan}
  onChange={setPlan}
  variant="outline"
/>
```

其标签、 需要的标记、 错误行和下行间隔来自 `Field`。 。 。 . `label` 可选 : 没有标签, 标签行不会被渲染, 因此它会干净地掉入工具栏或过滤栏 .

| Prop | 类型 | 页:1 |
| --- | --- | --- |
| `label` | `string` | 可选的 — 没有标签表示没有标签行 |
| `options` | `Array<{ value, label }>` | `value` 是一个 `string` 或者说 `number` |
| `value` | `T | T[]` | 数组 `multiple` |
| `onChange` | `(value: T) => void` | 点出按下值; 父公司拥有切换逻辑 |
| `multiple` | `boolean` | 选择是数组 |
| `disabled` | `boolean` | 禁用每个芯片 |
| `variant` | `'solid' | 'outline'` | `solid` (默认) = 填充药; `outline` = 有锡的大纲 |
| `required` | `boolean` | 调制 `Field`装饰性 `*` |
| `error` | `string` | `role="alert"` ,通过 `aria-describedby` |
| `containerStyle` | `ViewStyle` | 在容器上合并 |
| `testID` | `string` | 在容器上 |

## 强化控制 - `SelectControl` 编号 : `TypeaheadControl` 编号 : `DateRangeControl`

晋升到1.8.0人 `@dloizides/ui-tables`' 私人过滤栏,他们在那里工作正确 为6个门户出口到零——这就是为什么舰队增加了6个选择区,5个日期区 和两个打字头.

他们是 **设计时无标签**。在内部编曲 `Field` 所以有一个标签 实施每个控制而不是每个控制一个:

```tsx
<Field label="Status" labelVariant="control" containerStyle={{ marginBottom: 0 }}>
  <SelectControl
    accessibilityLabel={t('filters.statusName', 'Status', selectedLabel)}
    options={options}
    testID="filters-status"
    value={value}
    onChange={setValue}
  />
</Field>
```

`labelVariant="control"` 是来自 11/700/ oppercase 语音 [`FORMS.md`](https://npmcn.com/PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md) - 声音为 标签为SCAND(过滤条、工具栏)而不是READ.

### 每个字符串都预先本地化

此软件包从不调用 `t`特别是 `SelectControl`是因为 `accessibilityLabel` 必须是 由你组成,必须携带 **选择** ——"状态:活动",不是"状态". 无障碍 名称 REPLACES 触发器的可见文本用于屏幕读取器, 因此仅用字段命名 默默地隐藏所选择的内容 .

| 控制权 | 关键道具 | 测试ID |
| --- | --- | --- |
| `SelectControl` | `options`, (中文(简体) ), `value`, (中文(简体) ), `onChange`, (中文(简体) ), `placeholder`, (中文(简体) ), `accessibilityLabel`, (中文(简体) ), `optionHint` | `<testID>-trigger`, (中文(简体) ), `-menu`, (中文(简体) ), `-option-<value>` |
| `TypeaheadControl` | `options`, (中文(简体) ), `value`, (中文(简体) ), `onChange`, (中文(简体) ), `onSubmit`, (中文(简体) ), `error`, (中文(简体) ), `minChars`, (中文(简体) ), `maxSuggestions` | `<testID>-input`, (中文(简体) ), `-menu`, (中文(简体) ), `-error` |
| `DateRangeControl` | `value` (单位:千美元)`{from,to}`, (中文(简体) ), `onChange`, (中文(简体) ), `onSubmit`, (中文(简体) ), `fromLabel`, (中文(简体) ), `toLabel` | `<testID>-range`, (中文(简体) ), `-from`, (中文(简体) ), `-to` |
| `AnchoredMenu` | 浮点列表前两作曲 | `<testID>-menu` |

也导出 : `controlStyles` (调制的度量衡), `suggestOptions` 编号 : `isUnmatched` (单位:千美元) 类型头的分级符),和 `ControlOption` 编号 : `DateRangeValue` 类型.

## 测试ID

`form-field-input`, (中文(简体) ), `chip-selector-chip-<value>`, (中文(简体) ), `form-switch` (在FormSwitch上可以覆盖).

## 许可证

麻省理工学院

## 常见问题

### @dloizides/ui-forms 是什么？

”FormField、ChipSelector、FormSwitch ”共享@dloizides/ui-feedback UI语境。 dloizides\.com部分共享UI套装\.

### 如何安装 @dloizides/ui-forms？

在项目目录运行 npm install @dloizides/ui-forms，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-native（\>=0\.74\.0）、react-native-svg（\>=13\.0\.0）、@dloizides/ui-buttons（\>=1\.20\.1）、@dloizides/ui-feedback（\>=1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dloizides/ui-forms 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dloizides/ui-forms 支持 ESM 还是 CommonJS？

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

### @dloizides/ui-forms 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dloizides/ui-forms 可以商用吗？

@dloizides/ui-forms 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dloizides/ui-forms 的下载量有多少？

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

### @dloizides/ui-forms 还在维护吗？

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