# @financial-times/o-forms 中文文档

规范地址：https://npmcn.com/package/%40financial-times/o-forms/

版本：10\.0\.4
npm 元数据更新时间：2026-10-06T13:39:44.351Z
中文译文更新时间：2026-11-14T18:42:58.305Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40financial-times/o-forms
原文对照：https://npmcn.com/package/%40financial-times/o-forms/?lang=original
项目主页：https://registry.origami.ft.com/components/o-forms

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

- 包体积（解压后）：253 kB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@financial-times/math ^1\.0\.0，@financial-times/o-grid ^6\.1\.8，@financial-times/o-brand ^4\.1\.0，@financial-times/o-utils ^2\.2\.0，@financial-times/o-loading ^6\.0\.0，@financial-times/o-private-foundation ^1\.0\.0
- 首次发布：2019-02-13T10:51:42.628Z
- 最新版本发布：2025-06-30T09:33:41.335Z
- 近 30 天下载量：4785（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：104（近 12 个月 0 个）

## 中文简介

本部分为形式字段和输入提供了响应性的样式。 它为表格提供验证和错误处理.

## 安装

```sh
npm install @financial-times/o-forms
```

也可以使用：`pnpm add @financial-times/o-forms`、`yarn add @financial-times/o-forms`、`bun add @financial-times/o-forms`

## README

# o-形式 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40financial-times/o-forms/#readme-licence)

FT-品牌样式用于形式元素.

-   [o-形式](https://npmcn.com/package/%40financial-times/o-forms/#readme-o-forms-)
    -   [使用量](https://npmcn.com/package/%40financial-times/o-forms/#readme-usage)
    -   [标记](https://npmcn.com/package/%40financial-times/o-forms/#readme-markup)
        -   [单输入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields)
            -   [文本输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-text-input)
            -   [文件输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-file-input)
            -   [密码输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-password-input)
            -   [文本区域输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-textarea-input)
            -   [选择输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-select-input)
            -   [其他单一投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-other-single-inputs)
        -   [多个输入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-multiple-input-fields)
            -   [无线电投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-radio-inputs)
                -   [轮式无线电投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-round-radio-inputs)
                -   [盒式无线电投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-box-radio-inputs)
                -   [Pseudo 盒式无线电输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-pseudo-box-radio-inputs)
            -   [复选框输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-checkbox-inputs)
                -   [平方复选框输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-square-checkbox-inputs)
                -   [切换复选框输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-toggle-checkbox-inputs)
                -   [带有描述的复选框输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-checkbox-inputs-with-description)
            -   [日期投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-date-inputs)
        -   [提示文本](https://npmcn.com/package/%40financial-times/o-forms/#readme-prompt-text)
        -   [可选](https://npmcn.com/package/%40financial-times/o-forms/#readme-optional)
        -   [后缀](https://npmcn.com/package/%40financial-times/o-forms/#readme-suffix)
        -   [小型](https://npmcn.com/package/%40financial-times/o-forms/#readme-small)
        -   [内入](https://npmcn.com/package/%40financial-times/o-forms/#readme-inline)
            -   [内入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-inline-field)
            -   [内置输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-inline-inputs)
        -   [有效性](https://npmcn.com/package/%40financial-times/o-forms/#readme-validity)
            -   [错误摘要](https://npmcn.com/package/%40financial-times/o-forms/#readme-error-summary)
    -   [萨斯](https://npmcn.com/package/%40financial-times/o-forms/#readme-sass)
        -   [选项](https://npmcn.com/package/%40financial-times/o-forms/#readme-options)
        -   [自定义](https://npmcn.com/package/%40financial-times/o-forms/#readme-customisation)
    -   [Java 脚本](https://npmcn.com/package/%40financial-times/o-forms/#readme-javascript)
        -   [初始化](https://npmcn.com/package/%40financial-times/o-forms/#readme-initialise)
        -   [自定义行为](https://npmcn.com/package/%40financial-times/o-forms/#readme-customise-behaviour)
        -   [个人投入](https://npmcn.com/package/%40financial-times/o-forms/#readme-individual-inputs)
        -   [状态](https://npmcn.com/package/%40financial-times/o-forms/#readme-state)
    -   [移徙指南](https://npmcn.com/package/%40financial-times/o-forms/#readme-migration-guide)
    -   [联系人](https://npmcn.com/package/%40financial-times/o-forms/#readme-contact)
    -   [许可证](https://npmcn.com/package/%40financial-times/o-forms/#readme-licence)

## 使用量

检查出来 [如何将 Origami 组件纳入您的项目](https://origami.ft.com/documentation/components/#including-origami-components-in-your-project) 开始 `o-forms`。 。 。 .

## 标记

`o-forms` 含有“ 字段” 元素, 包含关于该输入的输入和信息, 例如其标签文本 。 使用独有的ID来关联窗体输入及其标签. 需要这样做,因为 [一些辅助技术不支持隐含标签](https://a11ysupport.io/tests/html_label_element_implicit)就像龙自然说话.

所有形式字段都遵循相同的结构:

```
┌— field container (.o-forms-field) —————┐
|      (one of div or label)             |
|                                        |
|  ┌ title container (.o-forms-title) ┐  |
|  |    (group titles or              |  |
|  |     individual input labels)     |  |
|  └——————————————————————————————————┘  |
|                                        |
|  ┌ input container (.o-forms-input) ┐  |
|  |    (group inputs or              |  |
|  |     individual inputs)           |  |
|  └——————————————————————————————————┘  |
└————————————————————————————————————————┘
```

窗体字段可能支持 [单输入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields),例如文本或选择框。 或者说 [多个输入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-multiple-input-fields),例如复选框或切换. 还有一些修改类来改变布局或字段,例如显示与其标签相通的输入,或显示一个输入有效性.

### 单输入字段

创建单个输入字段 `label` 元素和类 `o-forms-field`。所有标签副本被包裹在一个孩子体内 `o-forms-title` 元素,输入本身被包裹在一个孩子体内 `o-forms-input` 键.

输入及其标签副本相关,因为它们都在 [`label` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)。关联允许屏幕阅读器在用户专注于输入时读出标签。 关联还意味着点击标签会聚焦输入.

以下示例显示了文本输入:

```html
<label for="text" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--text">
        <input id="text" type="text" name="text-example" />
    </span>
</label>
```

对于不同的单一输入,请在 `o-forms-input` 并添加到 `o-forms-input` 键。 例如 [`textarea` 投入](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)数字 :

```diff
<label for="text-example" class="o-forms-field">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

- <span class="o-forms-input o-forms-input--text">
+ <span class="o-forms-input o-forms-input--textarea">
-  <input id="text-example"  type="text" name="text-example">
+  <textarea id="text-example" name="text-example"></textarea>
 </span>
</label>
```

#### 文本输入

要创建文本输入,请使用 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--text` 修改器类 `o-forms-input` 元素和输入类型 `type="text"`。 。 。 .

```html
<label for="text-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--text">
        <input id="text-example" type="text" name="text-example" value />
    </span>
</label>
```

#### 文件输入

要创建文件输入,请使用 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--file` 修改器类 `o-forms-input` 元素和输入类型 `type="file"`。 。 。 .

```html
<label for="text-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--file">
        <input id="text-example" type="file" name="file-example" value />
    </span>
</label>
```

#### 密码输入

要创建密码输入,请使用 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--password` 修改器类 `o-forms-input` 元素和输入类型 `type="password"`。 。 。 .

```html
<label for="password-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--password">
        <input
            id="password-example"
            type="password"
            name="password-example"
            value
        />
    </span>
</label>
```

#### 文本区域输入

要创建文本区域输入使用一个 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--textarea` 修改器类 `o-forms-input` 要素和a [`textarea` 输入元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)。 。 。 .

```html
<label for="textarea-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--textarea">
        <textarea id="textarea-example"></textarea>
    </span>
</label>
```

#### 选择输入

要创建选定的输入,请使用 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--select` 修改器类 `o-forms-input` 要素和a [`select` 输入元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)。 。 。 .

```html
<label for="select-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--select">
        <select id="select-example">
            <option>Option 1</option>
            <!-- further options -->
        </select>
    </span>
</label>
```

#### 其他单一投入

用于文本类输入类型 `o-forms` 不提供特定的修改者类别 `o-forms-input--text` 可使用修改语句. [_详见"折叠史"中的例子._](https://o2-core.origami.ft.com/?path=/story/maintained-o-forms-text-box--optional-text)

例如,创建电子邮件输入使用 [单项输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 外地结构,包括 `o-forms-input--text` 修改器类 `o-forms-input` 元素和输入类型 `type="email"`。 。 。 .

```html
<label for="email-example" class="o-forms-field">
    <span class="o-forms-title">
        <span class="o-forms-title__main">Label for input here</span>
    </span>

    <span class="o-forms-input o-forms-input--text">
        <input id="email-example" type="email" name="email-example" value />
    </span>
</label>
```

### 多个输入字段

对于有多个输入要素的字段,我们必须在以下几个字段的基础上更上一层楼: [单输入字段](https://npmcn.com/package/%40financial-times/o-forms/#readme-single-input-fields) 结构。 由于每个字段有多个输入 `o-forms-field` 元素变为 a `div` 而每个输入都与自己的输入关联 [`label` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)。每个窗体元素必须有一个独特的 `id` 属性,和 `for` 属性 `label` 元素必须匹配 `id` 与满足无障碍要求相关的形式要素.

例如,对于一组无线电按钮:

```html
<div class="o-forms-field" aria-labelledby="example-group-title" role="group">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--radio-round">
        <label for="radio-1">
            <input id="radio-1" type="radio" name="radio-1" value="Radio 1" checked />
            <span class="o-forms-input__label">Radio 1</span>
        </label>
        <label for="radio-2">
            <input id="radio-2" type="radio" name="radio-2" value="Radio 2" checked />
            <span class="o-forms-input__label">Radio 2</span>
        </label>
    </span>
</div>
```

请注意,为了将字段标题与投入类别联系起来,我们应该使用 [字段集和图例元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend)不过 `o-forms` 而不是依赖 `role="group"` 属性与 `aria-labelledby` 属性和相关 `id`, (中文(简体) ), `example-group-title` 上方标签.

_我们选择不与一个场集合作 因为他们是 [特别难保持风格](https://thatemil.com/blog/2015/01/03/reset-your-fieldset/)我们想给我们的用户提供视觉灵活性._

其他使用多输入元素的字段遵循相同的结构. 例如,为一组 [`checkbox` 投入](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox)数字 :

```diff
<div class="o-forms-field" aria-labelledby="example-group-title">
 <span class="o-forms-title">
  <span class="o-forms-title__main" id="example-group-title">Group Title</span>
 </span>

- <span class="o-forms-input o-forms-input--radio-round">
+ <span class="o-forms-input o-forms-input--checkbox">
  <label for="checkbox-1">
-   <input id="checkbox-1" type="radio" name="example-radio"/>
-   <span class="o-forms-input__label">Radio 1</span>
+   <input id="checkbox-1" type="checkbox" name="checkbox-1" value="1">
+   <span class="o-forms-input__label">Checkbox 1</span>
  </label>
  <label for="checkbox-2">
-   <input id="checkbox-2" type="radio" name="example-radio"/>
-   <span class="o-forms-input__label">Radio 2</span>
+   <input id="checkbox-2" type="checkbox" name="checkbox-2" value="2">
+   <span class="o-forms-input__label">Checkbox 2</span>
  </label>
 </span>
</div>
```

#### 无线电投入

##### 轮式无线电投入

创建无线电输入使用一个 [多重输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-multiple-input-fields) 外地结构,包括 `o-forms-input--radio-round` 修改器类 `o-forms-input` 元素和儿童 [无线电输入元件](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio) 在标签内。 这个 `id` 输入元素的属性必须匹配 `for` 标签元素的属性,它们必须是表单内独有的.

```html
<div class="o-forms-field" aria-labelledby="example-group-title" role="group">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--radio-round">
        <label for="radio-1">
            <input id="radio-1" type="radio" name="radio-1" value="Radio 1" checked />
            <span class="o-forms-input__label">Radio 1</span>
        </label>
        <label for="radio-2">
            <input id="radio-2" type="radio" name="radio-2" value="Radio 2" />
            <span class="o-forms-input__label">Radio 2</span>
        </label>
    </span>
</div>
```

圆形无线电投入支持3个主题.

-   **专业**: 对于带有 FT 专业主题的圆形收音机,设置 `o-forms-field--professional` 的字段.
-   **专业反向**: 对于带有反向 FT 专业主题的圆形收音机,设置 `o-forms-field--professional-inverse` 的字段.
-   **ft-活度**: 对于带有 FT Live 主题的圆形收音机,添加 `o-forms-field--ft-live` 的字段.

[_在故事书中看到收音机按钮_](https://o2-core.origami.ft.com/?path=/story/maintained-o-forms-radio-buttons--radio-button)

##### 盒式无线电投入

对于盒式长方形无线电按钮,替换 `o-forms-input--radio-round` 修改器类 `o-forms-input--radio-box`。 。 。 .

盒式收音机按钮也可以通过应用 `o-forms-input__label--negative` 更改其标签的类别。 这对“是/否”输入有用.

装入状态也由盒式收音机按钮支持. 我们建议使用 [`o-forms` Java 脚本](https://npmcn.com/package/%40financial-times/o-forms/#readme-javascript) 将状态添加到现有表格中。 不过,如果手动添加状态,则会添加一个额外的状态 `o-forms-input__state` 元素为 `role=status` 财务报告和审定财务报表 `aria-label="[STATE]"` 属性。 此外,在 `o-forms-input` 元素, `o-forms-input--saving` 或者说 `o-forms-input--saved`。 。 。 .

以下示例显示一个有正"是"和负"否"选项的盒式收音机按钮. 选中“ no” 选项并显示保存状态 .

```html
<div class="o-forms-field" aria-labelledby="example-group-title" role="group">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--radio-round o-forms-input--saved">
        <label for="radio-yes">
            <input id="radio-yes" type="radio" name="positive" value="Yes" />
            <span class="o-forms-input__label">Yes</span>
        </label>
        <label for="radio-no">
            <input id="radio-no" type="radio" name="negative" value="No" checked />
            <span class="o-forms-input__label o-forms-input__label--negative"
                >No</span
            >
        </label>

        <span role="status" class="o-forms-input__state"></span>
    </span>
</div>
```

显示没有文本的状态标签 `o-forms-input__state--icon-only` 编辑 `o-forms-input__state` 状态元素。 或使用自定义副本保存和保存状态添加修饰类 `o-forms-input__state--custom` 并把你的副本放在状态元素中。 但是,如前所述,我们建议设置一个自定义标签 [设置状态 JavaScript 方法](https://npmcn.com/package/%40financial-times/o-forms/#readme-state) 而不是手动添加此标记.

方框无线电投入支持3个主题.

-   **专业**: 用于装有 FT 专业主题集的盒式收音机 `o-forms-field--professional` 的字段.
-   **专业反向**: 对于带有反向 FT 专业主题集的盒式收音机 `o-forms-field--professional-inverse` 的字段.
-   **ft-活度**: 对于带有 FT Live主题的盒式收音机,设置 `o-forms-field--professional-inverse` 的字段.

##### Pseudo 盒式无线电输入

**贬值后,我们不再推荐伪箱无线电输入. 这些内容将在今后的主要版本中删除:**

它有可能用主播元素实现盒式无线电输入的外观,而不是实际的无线电输入,我们称之为这些伪盒式无线电输入. 不再建议这样做,不应用于新项目.

```html
<div class="o-forms-input o-forms-input--pseudo-radio-link">
    <a class="o-forms-input__link o-forms-input__link--current" href="/category"
        >Category View</a
    >
    <a class="o-forms-input__link" href="/timeline">Timeline View</a>
</div>
```

看起来像形式输入的链接对于一些辅助技术的使用者来说可能令人困惑,因为它们可能被访问或行为与预期不同。 此外,与真实的o-forms收音机输入不同,没有有传奇的字段集来分组链接. 在大多数情况下,使用标准 [盒式无线电输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-box-radio-inputs) 换句话说.

#### 复选框输入

##### 平方复选框输入

要创建复选框输入,请使用 [多重输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-multiple-input-fields) 外地结构,包括 `o-forms-input--checkbox` 修改器类 `o-forms-input` 元素和儿童 [复选框输入元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox) 在标签内.

```html
<div class="o-forms-field" aria-labelledby="example-group-title">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--checkbox">
        <label for="checkbox-1">
            <input id="checkbox-1" type="checkbox" name="checkbox-1" value="1" />
            <span class="o-forms-input__label">Checkbox 1</span>
        </label>
        <label for="checkbox-2">
            <input id="checkbox-2" type="checkbox" name="checkbox-2" value="2" />
            <span class="o-forms-input__label">Checkbox 2</span>
        </label>
    </span>
</div>
```

将复选框与 **对** 联 合 国 `label`中,添加 `o-forms-input__right` 类到 `label` 元素 :

```diff
...
<span class="o-forms-input o-forms-input--checkbox">
-  <label for="my-checkbox">
+  <label for="my-checkbox"class="o-forms-input__right">
   <input id="my-checkbox" type="checkbox" name="my-checkbox"/>
   <span class="o-forms-input__label">Checkbox 1</span>
  </label>
 </span>
...
```

平方复选框还支持一个额外的主题 :

-   **专业**: 要将专业主题添加到平方复选框中,请添加 `o-forms-field--professional` 修改字段元素的分类.
-   **专业反向**: 要将反向 FT 专业主题添加到平方复选框中, 请添加 `o-forms-field--professional-inverse` 修改字段元素的分类.
-   **ft-活度**: 要将 FT Live 主题添加到平方复选框中, 请添加 `o-forms-field--ft-live` 修改字段元素的分类.

##### 切换复选框输入

对于切换复选框,请替换 `o-forms-input--checkbox` 修改器类 `o-forms-input--toggle`。 。 。 .

```html
<div class="o-forms-field" aria-labelledby="example-group-title">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--toggle">
        <label for="checkbox-1">
            <input id="checkbox-1" type="checkbox" name="checkbox-1" value="1" />
            <span class="o-forms-input__label">Checkbox 1</span>
        </label>
        <label for="checkbox-2">
            <input id="checkbox-2" type="checkbox" name="checkbox-2" value="2" />
            <span class="o-forms-input__label">Checkbox 2</span>
        </label>
    </span>
</div>
```

切换支持两个主题 .

-   反向:用于在黑暗背景上切换. 设定 `o-forms-field--inverse` 的字段.
-   白色:用于在白色背景上切换. 设定 `o-forms-field--white` 的字段.

##### 带有描述的复选框输入

添加描述到切换/ 复选框 `o-forms-input__label__main` 财务报告和审定财务报表 `o-forms-input__label__prompt` 横跨元素。 这些必须和使用 `aria-labelledby` 财务报告和审定财务报表 `aria-describedby` 属性 :

```html
<div
    class="o-forms-field"
    role="group"
    aria-labelledby="[your-title-id]"
    aria-describedby="[your-description-id]"
>
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="[your-title-id]"
            >Toggle inputs with description</span
        >
        <span class="o-forms-title__prompt" id="[your-description-id]"
            >Optional prompt text</span
        >
    </span>

    <span class="o-forms-input o-forms-input--toggle">
        <label for="checkbox-example">
            <input
                id="checkbox-example"
                type="checkbox"
                name="default"
                value="Lorem ipsum dolor sit amet"
                checked=""
                aria-labelledby="[your-checkbox-label-id]"
                aria-describedby="[your-checkbox-description-id]"
                required=""
            />
            <span class="o-forms-input__label">
                <span id="[your-checkbox-label-id]" class="o-forms-input__label__main">
                    Lorem ipsum dolor sit amet
                </span>
                <span
                    id="[your-checkbox-description-id]"
                    class="o-forms-input__label__prompt"
                >
                    Lorem ipsum dolor sit amet consectetur adipisicing elit. Ad earum
                    magnam vel possimus harum suscipit.
                </span>
            </span>
        </label>
    </span>
</div>
```

#### 日期投入

我们不使用 `input[type=date]`组合 3 `input[type=text]` 投入。 我们用 `inputmode="numeric"` 在移动浏览器中显示支持属性的数字键盘。 用一个 `pattern` 属性用于基本的客户端日期验证.

要创建日期输入使用 [多重输入](https://npmcn.com/package/%40financial-times/o-forms/#readme-multiple-input-fields) 外地结构,包括 `o-forms-input--date` 修改器类 `o-forms-input` 元素,包含显示的输入:

```html
<div class="o-forms-field" aria-labelledby="example-group-title">
    <span class="o-forms-title">
        <span class="o-forms-title__main" id="example-group-title"
            >Group Title</span
        >
    </span>

    <span class="o-forms-input o-forms-input--date">
        <label for="date">
            <input
                id="date"
                class="o-forms-input__day-part"
                type="text"
                inputmode="numeric"
                pattern="(0[1-9]|1[0-9]|2[0-9]|3[01])"
                name="my-date"
                aria-label="Day (DD)"
            />
            <span class="o-forms-input__label">DD</span>
        </label>
        <label for="month">
            <input
                id="month"
                class="o-forms-input__month-part"
                type="text"
                inputmode="numeric"
                pattern="(0[1-9]|1[012])"
                name="my-date"
                aria-label="Month (MM)"
            />
            <span class="o-forms-input__label">MM</span>
        </label>
        <label for="year">
            <input
                id="year"
                class="o-forms-input__year-part"
                type="text"
                inputmode="numeric"
                pattern="[0-9]{4}"
                name="my-date"
                aria-label="Year (YYYY)"
            />
            <span class="o-forms-input__label">YYYY</span>
        </label>
    </span>
</div>
```

_我们避开 `type="number"` 这里有若干与可访问性和浏览器如何处理数字输入有关的理由 [在博客文章中](https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-team-changed-the-input-type-for-numbers/)。 。 。 ._

### 提示文本

要添加附加信息, 输入标签上的背景信息会添加标题元素, 有类 `o-forms-title__prompt`。当在多个输入字段,如复选框或收音机按钮组中添加提示时,给提示元素一个 `id` 和相关的 `aria-describedby` 标记字段.

对于单个输入字段,例如文本输入:

```diff
<span class="o-forms-field">
 <span class="o-forms-title">
  <label for="text-example" class="o-forms-title__main">Label for input here</label>
+  <span class="o-forms-title__prompt">Extra context for the input</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
  <input id="text-example" type="text" name="text-example" value>
 </span>
</span>
```

对于多个输入字段, 如复选框组 :

```diff
-<div class="o-forms-field" aria-labelledby="example-group-title">
+<div class="o-forms-field" aria-labelledby="example-group-title" aria-describedby="example-group-prompt">
 <span class="o-forms-title">
  <span id="example-group-title" class="o-forms-title__main">Group Title</span>
+  <span id="example-group-prompt" class="o-forms-title__prompt">Extra context for the input</span>
 </span>

 <span class="o-forms-input o-forms-input--checkbox">
  <label for="checkbox-1">
   <input id="checkbox-1" type="checkbox" name="checkbox-1" value="1">
   <span class="o-forms-input__label">Checkbox 1</span>
  </label>
  <label for="checkbox-2">
   <input id="checkbox-2" type="checkbox" name="checkbox-2" value="2">
   <span class="o-forms-input__label">Checkbox 2</span>
  </label>
 </span>
</div>
```

### 可选

添加数据 `o-forms-field--optional` 分类以表示一个字段是可选的。 例如,将文本字段标为可选 :

```diff
-<label for="text-example" class="o-forms-field">
+<label for="text-example" class="o-forms-field o-forms-field--optional">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
  <input id="text-example" type="text" name="text-example" value>
 </span>
</label>
```

### 后缀

在输入后插入元素, 如按钮, 添加类 `o-forms-input--suffix` 编辑 `o-forms-input` 键。 例如,用按钮插入文本输入的按钮:

```diff
<label for="text-example" class="o-forms-field">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Search for an example thing</span>
 </span>

- <span class="o-forms-input o-forms-input--text">
+ <span class="o-forms-input o-forms-input--text o-forms-input--suffix">
  <input id="text-example type="text" name="text-example" value>
+  <button class="[...]">Search</button>
 </span>
</label>
```

### 小型

添加类 `o-forms-input--small` 编辑 `o-forms-input` 元素以缩小输入的大小。 例如,输出一个小的文本输入:

```diff
<label for="text-example" class="o-forms-field">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

- <span class="o-forms-input o-forms-input--text">
+ <span class="o-forms-input o-forms-input--text o-forms-input--small">
  <input id="text-example" type="text" name="text-example" value>
 </span>
</label>
```

### 内入

#### 内入字段

要显示其标签旁边而不是下面的输入设置 `o-forms-field--inline`。 。 。 .

```diff
-<label for="text-example" class="o-forms-field">
+<label for="text-example" class="o-forms-field o-forms-field--inline">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
  <input id="text-example" type="text" name="text-example" value>
 </span>
</label>
```

如果内嵌字段的标签短于类 `o-forms-title--vertical-center` 可添加标题元素与输入垂直对齐.

```diff
-<label for="text-example" class="o-forms-field">
+<label for="text-example" class="o-forms-field o-forms-field--inline">
- <span class="o-forms-title">
+ <span class="o-forms-title o-forms-title--vertical-center">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
  <input id="text-example"  type="text" name="text-example" value>
 </span>
</label>
```

默认情况下,内线标签和输入将是设定宽度,以确保多个内线字段相互对齐. 设定 `o-forms-title--shrink` 允许输入占用所有可用的空间.

```diff
-<label for="text-example" class="o-forms-field">
+<label for="text-example" class="o-forms-field o-forms-field--inline">
- <span class="o-forms-title o-forms-title--shrink">
+ <span class="o-forms-title o-forms-title--shrink">
  <span class="o-forms-title__main">short label</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
  <input id="text-example"  type="text" name="text-example" value>
 </span>
</label>
```

#### 内置输入

添加类 `o-forms-input--inline` 页:1 `o-forms-input` 元素以显示内在的多个输入。 例如,默认情况下,多个复选框会叠叠到相上,但可能显示在一行中:

```diff
<div class="o-forms-field" aria-labelledby="example-group-title">
 <span class="o-forms-title">
  <span class="o-forms-title__main" id="example-group-title">Group Title</span>
 </span>

- <span class="o-forms-input o-forms-input--checkbox">
+ <span class="o-forms-input o-forms-input--checkbox o-forms-input--inline">
  <label for="checkbox-1">
   <input id="checkbox-1" type="checkbox" name="checkbox-1" value="1">
   <span class="o-forms-input__label">Checkbox 1</span>
  </label>
  <label for="checkbox-2">
   <input id="checkbox-2" type="checkbox" name="checkbox-2" value="2">
   <span class="o-forms-input__label">Checkbox 2</span>
  </label>
 </span>
</div>
```

### 有效性

[`o-forms` Java 脚本](https://npmcn.com/package/%40financial-times/o-forms/#readme-javascript) 以 [包含在浏览器中的窗体校验](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation) 以视觉显示输入为有效或无效;在输入下方显示自定义错误消息;并生成 [错误摘要](https://npmcn.com/package/%40financial-times/o-forms/#readme-error-summary)。 。 。 .

要在输入下方显示自定义错误消息, 请添加有类的元素 `o-forms-input__error` 作为儿童 `o-forms-input` 键。 将您的消息添加到 `o-forms-input__error` 和会议 [无障碍标准](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) 我们添加 `role="alert"`。 。 。 .

例如,用自定义错误消息创建所需的文本字段,同时包含 [`o-forms` Java 脚本](https://npmcn.com/package/%40financial-times/o-forms/#readme-javascript)。 。 。 .

```diff
<label for="required-text" class="o-forms-field">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

 <span class="o-forms-input o-forms-input--text">
-  <input id="required-text" type="text" name="required-text-example">
+  <input id="required-text" type="text" name="required-text-example" required>
+  <span role="alert" class="o-forms-input__error>Error message here for a required input</span>
 </span>
</label>
```

例如,使一个字段无效而不 [`o-forms` Java 脚本](https://npmcn.com/package/%40financial-times/o-forms/#readme-javascript)数字 :

```diff
<label for="required-text" class="o-forms-field">
 <span class="o-forms-title">
  <span class="o-forms-title__main">Label for input here</span>
 </span>

- <span class="o-forms-input o-forms-input--text">
+ <span class="o-forms-input o-forms-input--text o-forms-input--invalid">
-  <input id="required-text" type="text" name="required-text-example">
+  <input id="required-text" type="text" name="required-text-example" required>
+  <span role="alert" class="o-forms-input__error>Error message here for a required input</span>
 </span>
</label>
```

#### 错误摘要

`o-forms` 当提交一个表单和确认无效输入时,还生成一个错误消息元素。 输入必须有一个独特的ID和字段标题元素,以便在错误摘要中显示.

此特性将收集无效字段的自定义消息, 如果它们存在于标记中的话, 或者默认为浏览器的本地错误消息 。 它将把消息与无效的输入标题联系起来,生成窗体上方的链接列表,并聚焦于第一个链接.

如果 [错误摘要选项](https://npmcn.com/package/%40financial-times/o-forms/#readme-form-instance) 未设定为 `false`。 。 。 .

如果你没有使用 `o-forms` JavaScript 您可以在其中手动创建错误摘要 `o-forms` 使用下列标记的元素:

```html
<!-- error summary, `labelledby` the error heading  -->
<div
    class="o-forms__error-summary"
    aria-labelledby="my-error-summary"
    role="alert"
>
    <h4 id="my-error-summary" class="o-forms__error-summary__heading">
        There is a problem
    </h4>
    <ul class="o-forms__error-summary__list">
        <li class="o-forms__error-summary__item">
            <!-- link to the invalid input -->
            <a href="#my-date-input">
                <!-- the name of the invalid input -->
                <span class="o-forms__error-summary__item-overview">My date input</span
                >:
                <!-- a description of what is wrong and how to fix it -->
                <span class="o-forms__error-summary__item-detail">
                    Please use the format (DD/MM/YYYY)
                </span>
            </a>
        </li>
    </ul>
</div>
```

## 萨斯

`o-forms` 具有初级混合剂; `oForms()`。 。 。 .

通过调用混音符,您可以包含每个输入类型和特性的样式:

```scss
@import '@financial-times/o-forms/main';
@include oForms();
```

如果您想更具体地说明样式的哪些方面得到输出,那么您就需要提供初级混音器,并配有 `$opts` 地图。 例如,为了输出文本输入和复选框的样式,并添加吸收它们的能力,您将使用下列方法:

```scss
@import '@financial-times/o-forms/main';
@include oForms(
    $opts: (
        'elements': (
            'text',
            'checkbox',
        ),
        'features': (
            'inline',
        ),
    )
);
```

### 选项

`o-forms` 由于其全面性,有许多选择. 这个 `$opts` 映射接受以下两个列表:

-   `'elements'`数字 :
    -   `'checkbox'`
    -   `'date'`
    -   `'file'`
    -   `'password'`
    -   `'pseudo-radio-link'`
    -   `'radio-round'`
    -   `'radio-box'`
    -   `'select'`
    -   `'textarea'`
    -   `'text'`
    -   `'toggle'`
-   `'features'`数字 :
    -   `'disabled'`
    -   `'inline'`
    -   `'right'`
    -   `'inverse'` (折旧,见“主题”选项)
    -   `'small'`
    -   `'state'`
    -   `'suffix'`
    -   `error-summary`
-   `'themes'`
    -   `'inverse'`
    -   `'professional'`
    -   `'professional-inverse'`
    -   `'white'`

_说明1: `valid` 财务报告和审定财务报表 `invalid` 样式是带有底部的输出 `o-forms` 因此,没有必要将它们列入上述清单._

_注2:重要的是要记住,并非所有特性都将适用于所有输入类型. 如果您想在输入中看到任何功能, 请 [联系小组](https://npmcn.com/package/%40financial-times/o-forms/#readme-contact)。 。 。 ._

### 自定义

要定制两类输入有一个公共组合: [伪无线电链接](https://npmcn.com/package/%40financial-times/o-forms/#readme-pseudo-radio-links) 财务报告和审定财务报表 [框样式 `input[type=radio]`](https://npmcn.com/package/%40financial-times/o-forms/#readme-inputttyperadio-box)。 。 。 . 它接受四个论点:

-   `$input`: (必须) 或 `'pseudo-radio-link'` 或者说 `'radio'`
-   `$modifier`: (需要) 这将命名修改器以添加到输入容器类列表中
-   `$icons`: (可选) 接受图标或图标列表,根据自定义主题输出
-   `$theme`: (需要) 定义自定义主题的颜色地图 :
    -   `'controls-base'`: 主题的基础颜色
    -   `'controls-checked-base'`: 选中输入的背景颜色
    -   `'controls-negative-checked-background'`: 检查输入“ 负” 的背景颜色
    -   `'controls-border'`: 控件周围的边界颜色

```scss
@include oFormsAddCustom(
    (
        $input: 'radio',
        $modifier: 'my-theme',
        // outputs the class 'o-forms-input--my-theme',
        $icons: 'burger' $theme:
            (
                controls-base: 'claret',
                controls-checked-base: 'white',
                controls-negative-checked-background: 'claret-30',
            ),
    )
);
```

## Java 脚本

没有代码会自动运行, 除非你正在使用构建服务 。 您必须构建一个 `o-forms` 物体或起火 `o.DOMContentLoaded` 事件,哪个 `o-forms` 听着.

此组件的JavaScript主要负责单个输入验证和整体形式验证.

如果您想要使用一个没有窗体元素的输入, 您仍然可以使用 `o-forms` [个人 `Input` API 密码](https://npmcn.com/package/%40financial-times/o-forms/#readme-individual-inputs)。 。 。 .

### 初始化

主要内容 `o-forms` 已写入 JavaScript 以识别和运行于 `<form>` 键。 需要设置表格并包含数据属性 `data-o-component="o-forms"`数字 :

```html
<form data-o-component="o-forms">
    <!-- form elements as demonstrated in the markup section above  -->
</form>
```

默认, `o-forms` 以校验逻辑连接 。 它会在提交表单时生成无效元素的错误摘要 :

```js
import oForms from '@financial-times/o-forms';
oForms.init();
```

### 自定义行为

默认行为 `o-forms` 可以通过配置选项对象来更改。 例如,设定 `preventSubmit: true` 以防止用户提交表格。 在提交表单之前,您可以先使用自己的逻辑 `oForms.submit` 活动.

```js
oForms.init(null, {
    preventSubmit: true,
});

window.addEventListener('oForms.submit', e => {
    console.log(
        `A user would like to submit a form, it is ${
            e.detail.valid ? 'valid' : 'invalid'
        }.`
    );
    if (e.detail.valid) {
        e.detail.instance.form.submit();
    }
});
```

设置也可以防止错误摘要 `errorSummary: false`虽然我们不建议将此作为错误摘要,但有助于用户发现和导航有错误的表格,对于一些辅助技术的用户来说尤其如此.

```js
oForms.init(null, {
    errorSummary: false,
});
```

为了使用默认浏览器验证集 `useBrowserValidation: true`数字 :

```js
oForms.init(null, {
    useBrowserValidation: true,
    errorSummary: false,
});
```

您也可以将这些值设置为数据属性,例如:. `data-o-forms-prevent-submit`, (中文(简体) ), `data-o-forms-use-browser-validation`,以及 `data-o-forms-error-summary` 编辑 `<form>` 键.

### 个人投入

单项输入对产品足够但需要验证的,您可以登录一个 `Input` 实例:

```js
import Input from '@financial-times/o-forms/src/js/input';
new Input(myInputEl);
```

### 状态

`o-forms` 提供了显示“ 保存” 或“ 保存” 状态的能力 。 然而,目前唯一接受状态的输入是: [框样式 `input[type=radio]`](https://npmcn.com/package/%40financial-times/o-forms/#readme-inputtyperadio-box)。如果您想对其它输入应用状态,请 [联系小组](https://npmcn.com/package/%40financial-times/o-forms/#readme-contact)。 。 。 .

`o-forms` 对各州的时机没有看法——它不知道何时从"拯救"改为"拯救",但它有公开的方法 `setState` 允许项目控制此功能.

这个 `setState` 方法接受三个参数:状态、名称和标签。 州可以是"拯救","拯救"或"无"之一. “ 无” 从输入中删除任何状态 。 取名辩才,必为取回所取出所取之入取之名. 标签在用户界面中用于描述状态. 标签是可选的,默认为保存状态的"保存"和保存状态的"保存" .

```html
<form data-o-component="o-forms">
    ...
    <label for="daily">
        <span class="o-forms-input__label">Daily</span>
        <input id="daily" type="radio" name="my-radio-box" />
    </label>
    <label for="weekly">
        <span class="o-forms-input__label">Weekly</span>
        <input id="weekly" type="radio" name="my-radio-box" />
    </label>
    ...
</form>
```

```js
import oForms from '@financial-times/o-forms';
let myForm = oForms.init();
// on event, e.g. click
myForm.setState('saving', 'my-radio-box');
```

将保存标签通过第三个参数,例如将标签从"保存"更新为"发送":

```diff
-myForm.setState('saving', 'my-radio-box');
+myForm.setState('saving', 'my-radio-box', {
+ iconLabel: 'Sending'
+});
```

您也可以选择将状态显示为没有文本的图标 。 为了做到这一点,您可以用额外的选项参数调用上面的方法 :

```js
myForm.setState('saving', 'my-radio-box', {
    iconOnly: true,
});
```

## 移徙指南

| 状态 | 主要版本 | 最后一个小版本 | 移徙指南 |
| :-: | :-: | :-: | :-: |
| 维护 | 10个 | 9.12 联合国 | [迁移到 v10](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v9-to-v10) |
| 已贬值 | 第9条 | 不详 | [迁移到 v9](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v8-to-v9) |
| 已贬值 | 第8条 | 第8.5条 | [迁移到 v8](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v7-to-v8) |
| 已贬值 | 第7条 | 第7.1条 | [迁移到 v7](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v6-to-v7) |
| 已贬值 | 6个 | 6.0 (韩语) | [迁移到 v6](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v5-to-v6) |
| 已贬值 | 页:1 | 5.11 联合国 | [迁移到 v5](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v4-to-v5) |
| 已贬值 | 页:1 | 4.1 国家 | [迁移到 v4](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v3-to-v4) |
| 已贬值 | 3个 | 3.5 (中文(简体) ) | [迁移到 v3](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v2-to-v3) |
| 已贬值 | 2个 | 2.0 数据 | [迁移到 v2](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-from-v1-to-v2) |
| 已贬值 | 1个 | 1.0 国家 | [迁移到 v1](https://npmcn.com/package/%40financial-times/o-forms/MIGRATION.md#migrating-to-v1) |
| 已贬值 | 0 个 | 0.13 (韩语) | 不详 |

## 联系人

如果您对本部分有任何问题或评论,或需要帮助使用本部分,请 [提出问题](https://github.com/Financial-Times/o-forms/issues)访问 [#origami - 支持](https://financialtimes.slack.com/messages/origami-support/) 或电子邮件 [折纸支持](mailto:origami-support@ft.com)。 。 。 .

## 许可证

本软件由金融时报根据以下规定出版: [麻省理工学院许可证](http://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @financial-times/o-forms 是什么？

本部分为形式字段和输入提供了响应性的样式。 它为表格提供验证和错误处理\.

### 如何安装 @financial-times/o-forms？

在项目目录运行 npm install @financial-times/o-forms，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@financial-times/math（^1\.0\.0）、@financial-times/o-grid（^6\.1\.8）、@financial-times/o-brand（^4\.1\.0）、@financial-times/o-utils（^2\.2\.0）、@financial-times/o-loading（^6\.0\.0）、@financial-times/o-private-foundation（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @financial-times/o-forms 支持 TypeScript 吗？

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

### @financial-times/o-forms 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @financial-times/o-forms 可以商用吗？

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

### @financial-times/o-forms 的下载量有多少？

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

### @financial-times/o-forms 还在维护吗？

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