# @financial-times/o3-button 中文文档

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

版本：3\.16\.0
npm 元数据更新时间：2026-10-06T13:40:04.357Z
中文译文更新时间：2026-11-14T18:53:43.385Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：94.2 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@financial-times/o3-foundation ^3\.0\.0
- 首次发布：2023-10-23T16:08:55.448Z
- 最新版本发布：2025-12-03T10:03:49.454Z
- 近 30 天下载量：3755（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 1 个）

## 中文简介

带有设计符号的折纸按钮

## 安装

```sh
npm install @financial-times/o3-button
```

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

## README

# o3- 按钮

o3-按钮包括按键,按键组,和花图案. 看我们的 [使用信息和品牌支持设计准则](https://origami-beta.ft.com/components/buttons/)。 。 。 .

-   [o3- 按钮](https://npmcn.com/package/%40financial-times/o3-button/#readme-o3-button)
    -   [标记](https://npmcn.com/package/%40financial-times/o3-button/#readme-markup)
        -   [类型](https://npmcn.com/package/%40financial-times/o3-button/#readme-types)
        -   [主题](https://npmcn.com/package/%40financial-times/o3-button/#readme-themes)
        -   [大小](https://npmcn.com/package/%40financial-times/o3-button/#readme-sizes)
        -   [流体,全宽](https://npmcn.com/package/%40financial-times/o3-button/#readme-fluid-full-width)
        -   [图标](https://npmcn.com/package/%40financial-times/o3-button/#readme-icons)
        -   [组](https://npmcn.com/package/%40financial-times/o3-button/#readme-groups)
        -   [倾斜](https://npmcn.com/package/%40financial-times/o3-button/#readme-pagination)
        -   [已禁用](https://npmcn.com/package/%40financial-times/o3-button/#readme-disabled)
    -   [联合来文十](https://npmcn.com/package/%40financial-times/o3-button/#readme-jsx)
    -   [移徙](https://npmcn.com/package/%40financial-times/o3-button/#readme-migration)
    -   [联系人](https://npmcn.com/package/%40financial-times/o3-button/#readme-contact)
    -   [许可证](https://npmcn.com/package/%40financial-times/o3-button/#readme-licence)

## 标记

o3- 按钮支持 [用于反应用户的JSX模板](https://npmcn.com/package/%40financial-times/o3-button/#readme-jsx),或直接 HTML。 我们建议尽可能使用JSX.

### 类型

扣子有三种类型,一是一是一是一是二是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一是一 何时使用我们描述的哪个按钮类型 [设计准则](https://origami-beta.ft.com/components/buttons/)。 。 。 .

| 类型 | 选择器 |
| :-: | :-: |
| 小学 | .o3-按钮-主 |
| 中学 | .o3-按钮-中学 |
| 幽灵 | .o3-按钮-鬼 |

```html
<button class="o3-button o3-button--primary">Submit</button>
<button class="o3-button o3-button--secondary">Cancel</button>
<button class="o3-button o3-button--ghost">Options</button>
```

o3- 按钮可用其中之一 `<button>` 或者说 `<a>` 要素.

### 主题

主题可以应用到按钮上,以使用 `data-o3-theme`见我们 [设计准则](https://origami-beta.ft.com/components/buttons/) 用于您品牌可用的主题列表。 例如:

| 主题 | 数据属性 |
| :-: | :-: |
| 反转 | 数据-o3-主题=“反向” |
| 单 | 数据-o3-主题="mono" |

主题可以被应用在一个父元素上,以便所有内部的组件继承. 例如FT专业品牌按钮,带有反向主题:

```html
<body data-o3-brand="professional" data-o3-theme="inverse">
    <button class="o3-button o3-button--primary">
        Inverse professional button
    </button>
</body>
```

或者,主题可以被专门应用于一个按钮:

```html
<body data-o3-brand="professional">
    <button class="o3-button o3-button--primary" data-o3-theme="inverse">
        Inverse professional button
    </button>
</body>
```

### 大小

应用 `o3-button--small` 用于较小按钮的修改器类,酌情与 [设计准则](https://origami-beta.ft.com/components/buttons/#small)。 。 。 .

```html
<button class="o3-button o3-button--primary o3-button--small">Click me</button>
```

### 流体,全宽

应用 `data-o3-fluid` 数据属性来制作按钮"fluid",并扩展至其容器的全宽. 默认这仅适用于小而可移动的取景口. 在更大的取景口上,一个流体按钮的宽度是默认根据其内容.

```html
<button class="o3-button o3-button--primary" data-o3-fluid>Click me</button>
```

对于按钮何时应该是全宽,请设置更多控件 `--o3-button-fluid` CSS自定义属性. 例如:

强制按钮永远是全宽的,因为它们是一个"我的按钮-容器"元素的直接子.

```css
.my-button-container > .o3-button {
    --o3-button-fluid: initial;
}
```

使用 a 使按钮全宽 [容器查询](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries),给出了“我的按钮容器”父元素,小于 `500px` 宽度.

```css
.my-button-container {
    container-type: inline-size;
}

@supports (container-type: inline-size) {
    @container (width < 500px) {
        .my-button-container > .o3-button {
            --o3-button-fluid: initial;
        }
    }
}
```

### 图标

#### 图标和标签

要在按钮上添加图标, 添加类 `o3-button-icon` 财务报告和审定财务报表 `o3-button-icon--{icon-name}`。 。 。 .

可用的按钮图标数量有限. 限制图标数量会让CSS捆绑得更小.

如果您需要我们目前不支持的图标按钮,请联系Origami团队.

```html
<button
    class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevron-down"
>
    Chevron down arrow
</button>
<button
    class="o3-button o3-button--secondary o3-button-icon o3-button-icon--download"
>
    Download
</button>
```

#### 图标位置

按钮图标可以被定位到右侧的图标指示方向或继续. 添加数据 `o3-button-icon--end` CSS修改器. 见 [按钮设计准则](https://origami-beta.ft.com/components/buttons/) 更多细节.

```html
<button
    class="o3-button o3-button--primary o3-button-icon o3-button-icon--chevron-down o3-button-icon--end"
>
    Continue
</button>
```

#### 仅图标

如果您希望按钮只显示图标, 请添加类 `o3-button-icon--icon-only` ,并为屏幕阅读器用户提供可视化隐藏标签 `o3-button-icon__label`。 。 。 .

```html
<button
    class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevron-down o3-button-icon--icon-only"
>
    <span class="o3-button-icon__label"> Chevron down arrow </span>
</button>
```

#### 自定义图标

如果您想要使用未在 o3- 按钮支持的图标列表中与 Origami 团队交谈的图标, 我们将引导您使用现有的图标或帮助您采用新的图标 。 或者, 您的图标可以对我们的标准集进行适当的添加 .

在共同讨论之后,我们可以决定一个自定义图标是最合适的选项. 在这种情况下,设定 `--o3-button-icon` 带有自定义属性 [URL 编码 SVG](https://yoksel.github.io/url-encoder/) 图标 :

```css
.my-button-modifier-class {
    --o3-button-icon: url('data:image/svg+xml,[ENCODED_SVG_STRING]');
}
```

```html
<button
    class="o3-button o3-button--secondary o3-button-icon my-button-modifier-class"
>
    My custom icon button
</button>
```

### 组

在容器中包装按钮 `.o3-button-group` 将它们组合在一起:

```html
<div class="o3-button-group">
    <button class="o3-button o3-button--secondary" aria-selected="true">
        One
    </button>
    <button class="o3-button o3-button--secondary">Two</button>
    <button class="o3-button o3-button--secondary">Three</button>
</div>
```

### 倾斜

我们的平面图案因它可用的空间而异,例如移动式对桌面设备.

我们建议尽可能使用我们的JSX模板。 或者,你必须重新执行 标记逻辑跟着我们 [标本设计准则](https://origami-beta.ft.com/patterns/pagination/)。 。 。 .

`data-o3-button-show-when` 用于根据可用的空间显示/隐藏页标元素。 以下是以10页标出页码的示例,其中选择了第5页.

```html
<div class="o3-button-pagination">
    <a
        href="#previous"
        class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevrons-left o3-button-icon--icon-only"
        ><span class="o3-button-icon__label">previous</span></a
    ><a
        href="#1"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="wide"
        >1</a
    ><span data-o3-button-show-when="wide" class="o3-button-pagination__ellipsis"
        >...</span
    ><a
        href="#4"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="wide"
        >4</a
    ><a
        href="#5"
        class="o3-button o3-button--secondary "
        aria-current="page"
        data-o3-button-show-when="wide"
        >5</a
    ><a
        href="#6"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="wide"
        >6</a
    ><span data-o3-button-show-when="wide" class="o3-button-pagination__ellipsis"
        >...</span
    ><a
        href="#10"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="wide"
        >10</a
    ><a
        href="#1"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="narrow"
        >1</a
    ><span
        data-o3-button-show-when="narrow"
        class="o3-button-pagination__ellipsis"
        >...</span
    ><a
        href="#5"
        class="o3-button o3-button--secondary "
        aria-current="page"
        data-o3-button-show-when="narrow"
        >5</a
    ><span
        data-o3-button-show-when="narrow"
        class="o3-button-pagination__ellipsis"
        >...</span
    ><a
        href="#10"
        class="o3-button o3-button--secondary "
        data-o3-button-show-when="narrow"
        >10</a
    ><a
        href="#next"
        class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevrons-right o3-button-icon--icon-only"
        ><span class="o3-button-icon__label">next</span></a
    >
</div>
```

我们再次建议在可能时使用我们的JSX模板,而不是重新实施我们所说的逻辑 [标本设计准则](https://origami-beta.ft.com/patterns/pagination/)。 。 。 .

### 已禁用

避免禁用按钮, 除非用户研究显示它们改进了您的界面, 查看我们的 [按钮使用准则](https://origami-beta.ft.com/components/buttons/#usage-guidelines) 为了更多.

要禁用按钮,请添加 `disabled` 属性。 将已禁用按钮隐藏到正在激活时添加类 `o3-button--hide-disabled`。 。 。 .

```html
<!-- Visibly disabled because of the `disabled` attribute. -->
<button class="o3-button" disabled>My Button</button>

<!-- Visually hidden because of the `disabled` attribute and `o3-button--hide-disabled`.-->
<button class="o3-button o3-button--hide-disabled" disabled>My Button</button>
```

## 联合来文十

对于反应用户,Origami组件现在包括JSX模板. 导入 JSX 模板以及组件 CSS 。 JSX 模板导出为 `cjs` (共同联合来文)和 `esm` (ECMAScript)模块,因此取决于您的系统配置,您可能需要导入正确的模块类型.

见 [完整o3-按钮JSX文件的故事书](https://o3.origami.ft.com/?path=/docs/core-o3-button--jsx-documentation)。 。 。 .

例如,对于主按钮:

```jsx
import {Button} from '@financial-times/o3-button/cjs';

import '@financial-times/o3-button/css/[your brand].css';

<div data-o3-brand="[your brand]">
    <Button label="Hello" type="primary" />
</div>;
```

标注:

```jsx
import {ButtonPagination} from '@financial-times/o3-button/cjs';

import '@financial-times/o3-button/css/[your brand].css';

<div data-o3-brand="[your brand]">
    <ButtonPagination
        previousPager={{label: 'previous', href: '#previous'}}
        nextPager={{label: 'next', href: '#next'}}
        pages={[
            {href: '#1', current: false, number: 1},
            {href: '#2', current: false, number: 2},
            {href: '#3', current: false, number: 3},
            {href: '#4', current: false, number: 4},
            {href: '#5', current: true, number: 5},
            {href: '#6', current: false, number: 6},
            {href: '#7', current: false, number: 7},
            {href: '#8', current: false, number: 8},
            {href: '#9', current: false, number: 9},
            {href: '#10', current: false, number: 10},
        ]}
        currentPageOnly={false}
    />
</div>;
```

## 移徙

| 状态 | 主要版本 | 最后一个小版本 | 移徙指南 |
| :-: | :-: | :-: | :-: |
| 活动 | 3个 | 不详 | [迁移到 v3](https://npmcn.com/package/%40financial-times/o3-button/MIGRATION.md#migrating-from-v2-to-v3) |
| 已贬值 | 2个 | 2.0 数据 | [迁移到 v2](https://npmcn.com/package/%40financial-times/o3-button/MIGRATION.md#migrating-from-v1-to-v2) |
| 已贬值 | 1个 | 1.1 国家 | \- 说吧 |

## 联系人

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

* * *

## 许可证

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

## 常见问题

### @financial-times/o3-button 是什么？

带有设计符号的折纸按钮

### 如何安装 @financial-times/o3-button？

在项目目录运行 npm install @financial-times/o3-button，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@financial-times/o3-foundation（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @financial-times/o3-button 支持 TypeScript 吗？

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

### @financial-times/o3-button 支持 ESM 还是 CommonJS？

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

### @financial-times/o3-button 可以商用吗？

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

### @financial-times/o3-button 的下载量有多少？

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

### @financial-times/o3-button 还在维护吗？

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