@financial-times/o-forms

中文文档

10.0.4发布于 2025/06/30MITES Module近 30 天下载 4785

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

文档目录21 节

使用量
标记
单输入字段
多个输入字段
提示文本
可选
后缀
小型
内入
有效性
萨斯
选项
自定义
Java 脚本
初始化
自定义行为
个人投入
状态
移徙指南
联系人
许可证

o-形式

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

o-形式

使用量

检查出来如何将 Origami 组件纳入您的项目开始 o-forms。。。 .

标记

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

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

┌— 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)           |  |
|  └——————————————————————————————————┘  |
└————————————————————————————————————————┘

窗体字段可能支持单输入字段,例如文本或选择框。或者说多个输入字段,例如复选框或切换. 还有一些修改类来改变布局或字段,例如显示与其标签相通的输入,或显示一个输入有效性.

单输入字段

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

输入及其标签副本相关,因为它们都在 label 元素。关联允许屏幕阅读器在用户专注于输入时读出标签。关联还意味着点击标签会聚焦输入.

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

<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 投入数字 :

<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>

文本输入

要创建文本输入,请使用单项输入外地结构,包括 o-forms-input--text 修改器类 o-forms-input 元素和输入类型 type="text"。。。 .

<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>

文件输入

要创建文件输入,请使用单项输入外地结构,包括 o-forms-input--file 修改器类 o-forms-input 元素和输入类型 type="file"。。。 .

<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>

密码输入

要创建密码输入,请使用单项输入外地结构,包括 o-forms-input--password 修改器类 o-forms-input 元素和输入类型 type="password"。。。 .

<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>

文本区域输入

要创建文本区域输入使用一个单项输入外地结构,包括 o-forms-input--textarea 修改器类 o-forms-input 要素和a textarea 输入元素。。。 .

<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>

选择输入

要创建选定的输入,请使用单项输入外地结构,包括 o-forms-input--select 修改器类 o-forms-input 要素和a select 输入元素。。。 .

<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 可使用修改语句. 详见"折叠史"中的例子.

例如,创建电子邮件输入使用单项输入外地结构,包括 o-forms-input--text 修改器类 o-forms-input 元素和输入类型 type="email"。。。 .

<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>

多个输入字段

对于有多个输入要素的字段,我们必须在以下几个字段的基础上更上一层楼: 单输入字段结构。由于每个字段有多个输入 o-forms-field 元素变为 a div 而每个输入都与自己的输入关联 label 元素。每个窗体元素必须有一个独特的 id 属性,和 for 属性 label 元素必须匹配 id 与满足无障碍要求相关的形式要素.

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

<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>

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

我们选择不与一个场集合作因为他们是特别难保持风格我们想给我们的用户提供视觉灵活性.

其他使用多输入元素的字段遵循相同的结构. 例如,为一组 checkbox 投入数字 :

<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>

无线电投入

轮式无线电投入

创建无线电输入使用一个多重输入外地结构,包括 o-forms-input--radio-round 修改器类 o-forms-input 元素和儿童无线电输入元件在标签内。这个 id 输入元素的属性必须匹配 for 标签元素的属性,它们必须是表单内独有的.

<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 的字段.

在故事书中看到收音机按钮

盒式无线电投入

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

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

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

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

<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 方法而不是手动添加此标记.

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

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

Pseudo 盒式无线电输入

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

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

<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收音机输入不同,没有有传奇的字段集来分组链接. 在大多数情况下,使用标准盒式无线电输入换句话说.

复选框输入

平方复选框输入

要创建复选框输入,请使用多重输入外地结构,包括 o-forms-input--checkbox 修改器类 o-forms-input 元素和儿童复选框输入元素在标签内.

<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 元素 :

...
<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。。。 .

<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 属性 :

<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 属性用于基本的客户端日期验证.

要创建日期输入使用多重输入外地结构,包括 o-forms-input--date 修改器类 o-forms-input 元素,包含显示的输入:

<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" 这里有若干与可访问性和浏览器如何处理数字输入有关的理由在博客文章中。。。 .

提示文本

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

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

<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>

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

-<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 分类以表示一个字段是可选的。例如,将文本字段标为可选 :

-<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 键。例如,用按钮插入文本输入的按钮:

<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 元素以缩小输入的大小。例如,输出一个小的文本输入:

<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。。。 .

-<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 可添加标题元素与输入垂直对齐.

-<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 允许输入占用所有可用的空间.

-<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 元素以显示内在的多个输入。例如,默认情况下,多个复选框会叠叠到相上,但可能显示在一行中:

<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 脚本以包含在浏览器中的窗体校验以视觉显示输入为有效或无效;在输入下方显示自定义错误消息;并生成错误摘要。。。 .

要在输入下方显示自定义错误消息, 请添加有类的元素 o-forms-input__error 作为儿童 o-forms-input 键。将您的消息添加到 o-forms-input__error 和会议无障碍标准我们添加 role="alert"。。。 .

例如,用自定义错误消息创建所需的文本字段,同时包含 o-forms Java 脚本。。。 .

<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 脚本数字 :

<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和字段标题元素,以便在错误摘要中显示.

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

如果错误摘要选项未设定为 false。。。 .

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

<!-- 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()。。。 .

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

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

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

@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:重要的是要记住,并非所有特性都将适用于所有输入类型. 如果您想在输入中看到任何功能, 请联系小组。。。 .

自定义

要定制两类输入有一个公共组合: 伪无线电链接财务报告和审定财务报表框样式 input[type=radio]。。。 . 它接受四个论点:

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

@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 密码。。。 .

初始化

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

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

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

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

自定义行为

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

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虽然我们不建议将此作为错误摘要,但有助于用户发现和导航有错误的表格,对于一些辅助技术的用户来说尤其如此.

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

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

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 实例:

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

状态

o-forms 提供了显示“ 保存” 或“ 保存” 状态的能力。然而,目前唯一接受状态的输入是: 框样式 input[type=radio]。如果您想对其它输入应用状态,请联系小组。。。 .

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

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

<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>

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

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

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

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

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

移徙指南

状态	主要版本	最后一个小版本	移徙指南
维护	10个	9.12 联合国	迁移到 v10
已贬值	第9条	不详	迁移到 v9
已贬值	第8条	第8.5条	迁移到 v8
已贬值	第7条	第7.1条	迁移到 v7
已贬值	6个	6.0 (韩语)	迁移到 v6
已贬值	页:1	5.11 联合国	迁移到 v5
已贬值	页:1	4.1 国家	迁移到 v4
已贬值	3个	3.5 (中文(简体) )	迁移到 v3
已贬值	2个	2.0 数据	迁移到 v2
已贬值	1个	1.0 国家	迁移到 v1
已贬值	0 个	0.13 (韩语)	不详

联系人

如果您对本部分有任何问题或评论,或需要帮助使用本部分,请提出问题访问 #origami - 支持或电子邮件折纸支持。。。 .

许可证

本软件由金融时报根据以下规定出版: 麻省理工学院许可证。。。 .

版本与发布记录

@financial-times/o-forms 共发布 104 个版本，首次发布于 2019/02/13；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`10.0.4`latest	2025/06/30	1.4 年前
`10.0.3`	2025/06/27	1.4 年前
`10.0.2`	2025/04/17	1.6 年前
`10.0.1`	2025/02/27	1.7 年前
`10.0.0`	2025/02/20	1.7 年前
`9.12.1`	2023/10/27	3 年前

其他发布通道：prerelease → 9.0.0-beta.1。

关于 @financial-times/o-forms 的常见问题

@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 和提交记录判断。

npm install @financial-times/o-forms

pnpmpnpm add @financial-times/o-forms
yarnyarn add @financial-times/o-forms
bunbun add @financial-times/o-forms

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 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

4,785

约 4785 次日均 160 次

统计周期 2026/10/15 – 2026/11/13
数据来自 npm 官方下载统计，今天更新

最新版本10.0.4发布于 1.4 年前

开源许可MIT宽松许可

包体积253 kB71 个文件 · 解压后

运行依赖2 个另有 6 个 peer 依赖

模块格式ES Module

TypeScript未声明类型可查找 @types/financial-times__o-forms

发布版本104 个近 12 个月 0 个

首次发布2019/02/137 年前

元数据更新2026/10/06

每一个软件包背后，
都有分享与创造的人。