# @fiscozen/button 中文文档

规范地址：https://npmcn.com/package/%40fiscozen/button/

版本：3\.2\.0
npm 元数据更新时间：2026-09-29T15:21:52.501Z
中文译文更新时间：2026-11-14T20:23:02.290Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：1 MB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1，@fiscozen/icons ^1\.0\.8
- 首次发布：2024-05-08T13:39:22.183Z
- 最新版本发布：2026-09-29T15:21:52.316Z
- 近 30 天下载量：21294（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 12 个）

## 中文简介

设计系统图标按钮组件

## 安装

```sh
npm install @fiscozen/button
```

也可以使用：`pnpm add @fiscozen/button`、`yarn add @fiscozen/button`、`bun add @fiscozen/button`

## README

# @ fiscozen/ 按钮

Vue 3应用程序的完整按钮组件库,以多个变体,大小和图标支持为主.

## 特征

-   **多种变式**: 初等、中等、隐形、危险和成功风格
-   **环境规模**: 针对不同用途的两种环境选项(后台、前台)
-   **图标支持**: 内建图标集成和自定义定位
-   **无障碍**: 全键盘导航和ARIA支持
-   **可自定义**: 具有集装箱类别覆盖的灵活样式
-   **类型脚本**: 具有类型脚本定义的完整类型安全
-   **语义色彩**: 使用设计系统代号,以保持一致的主题

## 安装

```bash
npm install @fiscozen/button
```

## 构成部分

此套件输出三个组件:

-   `FzButton` - 有标签和可选图标的标准按钮
-   `FzIconButton` - 紧凑界面的仅图标按钮
-   `FzButtonGroup` - 用于组合相关按钮的容器

## 基本用途

### Fz 按钮

```vue
<script setup lang="ts">
import { FzButton } from '@fiscozen/button'
</script>

<template>
  <FzButton label="Click me" />
</template>
```

### 有备选案文

```vue
<template>
  <!-- Primary (default) -->
  <FzButton variant="primary" label="Primary Action" />
  
  <!-- Secondary -->
  <FzButton variant="secondary" label="Secondary Action" />
  
  <!-- Invisible -->
  <FzButton variant="invisible" label="Subtle Action" />
  
  <!-- Danger -->
  <FzButton variant="danger" label="Delete" />
  
  <!-- Success -->
  <FzButton variant="success" label="Confirm" />
</template>
```

### 带有图标

```vue
<template>
  <!-- Icon before label (default) -->
  <FzButton 
    label="Save" 
    iconName="save" 
    iconPosition="before" 
  />
  
  <!-- Icon after label -->
  <FzButton 
    label="Next" 
    iconName="arrow-right" 
    iconPosition="after" 
  />
  
  <!-- Custom icon variant -->
  <FzButton 
    label="Settings" 
    iconName="gear" 
    iconVariant="fas" 
  />
</template>
```

### 环境( 小)

```vue
<template>
  <!-- Frontoffice environment (default) -->
  <FzButton environment="frontoffice" label="Frontoffice Button" />
  
  <!-- Backoffice environment -->
  <FzButton environment="backoffice" label="Backoffice Button" />
</template>
```

### 大小道具( 已过期)

这个 `size` 道具被贬值了,但对于后向相容性来说仍然具有功能. 使用 `environment` 相反:

```vue
<template>
  <FzButton size="lg" label="Legacy Large" />
</template>
```

### 残疾状态

```vue
<template>
  <FzButton label="Disabled Button" :disabled="true" />
</template>
```

### 使用槽

```vue
<template>
  <!-- Default slot (overrides label prop) -->
  <FzButton>
    <span>Custom <strong>HTML</strong> Content</span>
  </FzButton>
  
  <!-- Custom icon slots -->
  <FzButton label="Custom Icon">
    <template #before>
      <CustomIcon />
    </template>
  </FzButton>
  
  <FzButton label="Custom Icon After">
    <template #after>
      <CustomIcon />
    </template>
  </FzButton>
</template>
```

## 道具

### Fz按钮道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | `undefined` | 按钮上显示的文本标签 |
| `tooltip` | `string` | `undefined` | **折旧:** 工具提示文本( 使用 FzTooltip 组件代替) |
| `variant` | `'primary' | 'secondary' | 'invisible' | 'danger' | 'success'` | `'primary'` | 视觉样式变体 |
| `environment` | `'backoffice' | 'frontoffice'` | `'frontoffice'` | 大小和间隔的按钮环境 |
| `size` | `'xs' | 'sm' | 'md' | 'lg'` | `undefined` | **折旧:** 按钮大小( 使用) `environment` 代替道具) |
| `disabled` | `boolean` | `false` | 是否禁用按钮 |
| `iconName` | `string` | `undefined` | FontAsome 图标名称( 如 “ 铃声 ” 、 “ 保存 ” ) |
| `iconVariant` | `IconVariant` | `undefined` | FontAwesome 图标变体(fas, far, fal等) |
| `iconPosition` | `'before' | 'after'` | `'before'` | 图标相对于标签的位置 |
| `containerClass` | `string` | `undefined` | 标签容器的额外CSS类 |
| `overrideContainerClass` | `boolean` | `false` | 如果选中, 则替换默认的容器类, 而不是合并 |

## 槽数

| 槽 | 说明 |
| --- | --- |
| `default` | 自定义按钮的内容( 覆盖) `label` 圆柱形) |
| `before` | 自定义标签前的内容( 提供图标时替换图标) |
| `after` | 标签后自定义内容( 提供图标时替换图标) |

## 行为和概念

### 标签对 Slot 优先级

当两者 `label` 提供了道具和默认槽,槽优先:

```vue
<FzButton label="This won't show">
  This will show instead
</FzButton>
```

### 图标显示逻辑

图标仅在两者同时显示时显示 `label` (或默认槽)和 `iconName` 已提供。 这确保了适当的间隔和布局.

### 集装箱类自定义

默认情况下,标签容器有 `truncate` 用于处理文本溢出。 你可以这样:

1.  **添加类** (默认行为):

```vue
<FzButton label="Text" containerClass="font-bold" />
<!-- Results in: class="truncate font-bold" -->
```

2.  **完全覆盖**数字 :

```vue
<FzButton 
  label="Text" 
  containerClass="custom-class" 
  :overrideContainerClass="true" 
/>
<!-- Results in: class="custom-class" (no truncate) -->
```

## 实例

### 窗体动作

```vue
<template>
  <div class="flex gap-12">
    <FzButton 
      variant="primary" 
      label="Submit" 
      @click="handleSubmit"
    />
    <FzButton 
      variant="secondary" 
      label="Cancel" 
      @click="handleCancel"
    />
  </div>
</template>
```

### 经确认的破坏行动

```vue
<template>
  <FzButton 
    variant="danger" 
    label="Delete Account" 
    iconName="trash"
    :disabled="!confirmed"
    @click="handleDelete"
  />
</template>
```

### 带有图标的导航

```vue
<template>
  <div class="flex gap-8">
    <FzButton 
      variant="secondary" 
      label="Back" 
      iconName="arrow-left" 
      iconPosition="before"
      environment="backoffice"
    />
    <FzButton 
      variant="primary" 
      label="Continue" 
      iconName="arrow-right" 
      iconPosition="after"
      environment="backoffice"
    />
  </div>
</template>
```

### 装入状态( 海关执行)

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { FzButton } from '@fiscozen/button'

const isLoading = ref(false)

async function handleAction() {
  isLoading.value = true
  try {
    await performAction()
  } finally {
    isLoading.value = false
  }
}
</script>

<template>
  <FzButton 
    :disabled="isLoading"
    @click="handleAction"
  >
    <span v-if="isLoading">Loading...</span>
    <span v-else>Submit</span>
  </FzButton>
</template>
```

## 无障碍

FzButton遵循WCAG 2.1 AA标准,包括:

-   **语义 HTML**:作为本地人 `<button>` 元素为 `type="button"`
-   **键盘导航**: Enter 和 Space 键的完整支持
-   **ARIA 属性**数字 :
    -   `aria-disabled` 总是清晰地显示 `"true"` 或者说 `"false"` 值( 相容的 Vue 3)
-   **残疾状态**: 禁用时适当防止点击事件和视觉反馈
-   **屏幕阅读器兼容性**: 与NVDA、JAWS和Voice Over合作
-   **重点指标**: 明显焦点状态, 3:1 对比比 (蓝色边框)
-   **颜色对比**:所有变体都符合4.5:1文本对比比

## 页:1

### 环境对大小

按钮支持两个决定大小的环境:

-   **后台办公室**: 内部应用程序的压缩按钮
-   **前台办公室**: 客户界面的大按钮( 默认)

堕落者 `size` 向环境投放道具图如下:

-   `xs`, (中文(简体) ), `sm`, (中文(简体) ), `md` 地图到 `backoffice`
-   `lg` 地图到 `frontoffice`

### 选项选择

这个 `variant` 使用属性代替 `type` 以避免与 HTML 相混淆 `type` 属性.

## Fz 按钮组

装有固定间距的横向布局组合按钮的容器。 用途 `FzContainer` 组件在内部显示连续的按钮,并保持它们之间的相距。 按钮保持了固定宽度(2个按钮为50%,3个按钮为33.333%),无论内容如何,由Fz按钮组件处理文本截取. 组件占其容器的100%宽度.

### 特征

-   仅水平布局
-   固定间隔
-   固定按钮宽:2个按钮为50%,3个按钮为33.333%
-   FzButton 组件自动处理的文本截取
-   不包装 - 按钮留在一行
-   集装箱的100%宽度
-   无需道具

### 基本用途

```vue
<script setup>
import { FzButtonGroup, FzButton } from '@fiscozen/button'
</script>

<template>
  <FzButtonGroup>
    <FzButton variant="primary">Save</FzButton>
    <FzButton variant="secondary">Cancel</FzButton>
    <FzButton variant="secondary">Delete</FzButton>
  </FzButtonGroup>
</template>
```

### Fz按钮组道具

无需道具. 组件总是用固定的16px缺口水平显示按钮.

**贬值的道具 :**

以下道具被去化并会在未来版本被去除. 它们为后向相容性而维持,但没有效果:

-   `horizontal` - 组件总是横向的。 此道具将被忽略 .
-   `gap` - 组件始终使用固定间隔。 此道具将被忽略 .
-   `size` - 组件总是使用固定的缺口大小。 此道具将被忽略 .

使用这些道具时会显示运行时间警告 。 请从密码中删除.

### Fz按钮组示例

#### 动作按钮组

```vue
<template>
  <FzButtonGroup>
    <FzButton variant="primary">Primary Action</FzButton>
    <FzButton variant="secondary">Secondary Action</FzButton>
    <FzButton variant="invisible">Cancel</FzButton>
  </FzButtonGroup>
</template>
```

#### 两个按钮( 前沿办公室)

```vue
<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="frontoffice">Save</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Cancel</FzButton>
  </FzButtonGroup>
</template>
```

#### 两个按钮( 后台)

```vue
<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="backoffice">Save</FzButton>
    <FzButton variant="secondary" environment="backoffice">Cancel</FzButton>
  </FzButtonGroup>
</template>
```

#### 三键 (前沿办公室)

```vue
<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="frontoffice">Save</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Cancel</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Delete</FzButton>
  </FzButtonGroup>
</template>
```

#### 三键 (后台)

```vue
<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="backoffice">Save</FzButton>
    <FzButton variant="secondary" environment="backoffice">Cancel</FzButton>
    <FzButton variant="secondary" environment="backoffice">Delete</FzButton>
  </FzButtonGroup>
</template>
```

### Fz按钮组行为

-   **固定宽度布局**:按钮根据按钮数量维持固定宽度:
    -   2个按钮:每个按钮占容器宽度的50%
    -   3个按钮:每个按钮占用容器宽度的33.333%
-   **文本截断**: 长按钮文本会自动切入椭圆形(`...`) 由 FzButton 组件
-   **无需要配置**: 组件自动检测按钮数并应用适当的缩放

### Fz按钮组无障碍

该组件保留按钮子的无障碍属性 :

-   键盘导航工作正确
-   ARIA 标签和说明得到维护
-   保留残疾状态
-   屏幕阅读器通常可以通过按钮导航

组件本身是一个语义 `div` 并不妨碍按钮的可访问性.

## FzIcon 按钮

带有通知徽章支持的仅图标按钮组件 。 有限空间的紧凑界面和工具栏的理想 .

### 特征

-   紧凑界面的仅图标设计
-   多种变种(初级、二级、隐形、危险)
-   两个环境(后台、前台)
-   压缩模式: 20x20 控制, 带有44x44接触区域
-   通知徽章覆盖支持
-   自定义图标变体
-   全面无障碍支持
-   类型脚本支持

### 基本用途

```vue
<template>
  <FzIconButton iconName="bell" ariaLabel="Notifications" />
</template>
```

### 备选案文

```vue
<template>
  <div class="flex gap-8">
    <FzIconButton iconName="bell" variant="primary" ariaLabel="Notifications" />
    <FzIconButton iconName="settings" variant="secondary" ariaLabel="Settings" />
    <FzIconButton iconName="trash" variant="invisible" ariaLabel="Delete" />
    <FzIconButton iconName="trash" variant="danger" ariaLabel="Delete" />
  </div>
</template>
```

### 环境

```vue
<template>
  <div class="flex gap-8 items-center">
    <FzIconButton 
      iconName="settings" 
      environment="backoffice" 
      ariaLabel="Settings (backoffice)" 
    />
    <FzIconButton 
      iconName="settings" 
      environment="frontoffice" 
      ariaLabel="Settings (frontoffice)" 
    />
  </div>
</template>
```

### 带有通知徽章

```vue
<template>
  <FzIconButton 
    iconName="bell" 
    hasNotification 
    ariaLabel="Notifications with badge"
  />
</template>
```

### 压缩

`compact` 画出一个20x20的盒子和一个12pxglyph, 对于一个控制设置在小的东西,例如 作为图像预览中移除的 X 。 可点击区域仍为44x44(最小值) 触摸目标)越过可见的边缘,而不取出布局空间:组件量度 20x20 (英语).

```vue
<template>
  <FzIconButton
    compact
    variant="secondary"
    iconName="xmark"
    ariaLabel="Rimuovi allegato"
    @click="remove"
  />
</template>
```

触摸区域每边都以12px 溢出盒子,所以你把盒子放在哪里决定 是否保持完整:

-   **将盒从任何容器外的边缘至少保留12px**页:1 图像它坐上,一个水平滚动条. 比这更近,剪接的部分 触摸区域停止响应。 对于一个图像角落中的20px框,这意味着12px来自 上面和右边的12px.
-   **将两个压缩按钮至少分开 24px** 或它们的触摸区 它们之间有重叠和相接点 以DOM的后期为准.

压缩模式需要一个背景来保存可读图像,所以 `invisible` 作为 `secondary` 并记录一个警告. `environment` 无效时 `compact` 开始.

### 带有工具提示( 建议)

```vue
<template>
  <FzTooltip content="Notifications">
    <FzIconButton iconName="bell" ariaLabel="Notifications" />
  </FzTooltip>
</template>
```

### FzIcon 按钮道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `iconName` | `string` | _所需经费_ | FontAsome 图标名称( 如 “ 铃声 ” 、 “ 设置” ) |
| `variant` | `'primary' | 'secondary' | 'invisible' | 'danger'` | `'primary'` | 确定颜色和交互状态的视觉样式变体 |
| `environment` | `'backoffice' | 'frontoffice'` | `'frontoffice'` | 环境决定按钮大小 |
| `disabled` | `boolean` | `false` | 是否禁用按钮 |
| `iconVariant` | `IconVariant` | `'far'` | FontAwesome 图标变体(fas, far, fal等) |
| `hasNotification` | `boolean` | `false` | 在按钮右上角显示通知徽章 |
| `compact` | `boolean` | `false` | 20×20盒有12px glyph和44×44触地区. 覆盖 `environment`· ; `invisible` 作为 `secondary` |
| `ariaLabel` | `string` | `undefined` | 屏幕阅读器可访问标签 。 仅需要图标按钮 。 如果通知属实,则自动在标签上附加通知状态 |
| `tooltip` | `string` | `undefined` | **折旧:** 使用 FzTooltip 组件来包装按钮 |

### FzIcon 按钮行为和概念

#### 通知标签

通知徽章在右上角显示为圆形指示器 `hasNotification` 实值 `true`。 。 。 .

### FzIcon 按钮访问

FzIcon按钮遵循了WCAG 2.1 AA标准并包括:

-   **ARIA 标签**:图标按钮需要屏幕阅读器的清晰标签. 使用 `ariaLabel` 道具或包装 `FzTooltip` 可访问标签
-   **键盘导航**: Enter 和 Space 键的完整支持
-   **残疾状态**: 禁用时适当防止点击事件和视觉反馈
-   **屏幕阅读器兼容性**: 与NVDA、JAWS和Voice Over合作
-   **重点指标**:在紧凑模式下,一圈2px环被画入20px盒内,与按钮本身的填充相对:一圈为白色(4.11:1),二圈为蓝色-600(5.93:1). 在较大的面积下,边界会变暗,比起原始面积(1.44:1)和危险值(1.76:1),边界低于3:1
-   **触摸目标**: 压缩模式在 20x20 盒周围保留一个44x44可点击区域
-   **通知标签**: 标记为 `aria-hidden="true"` 防止屏幕阅读器通知

### FzIcon 按钮示例

#### 工具栏动作

```vue
<template>
  <div class="flex gap-4">
    <FzTooltip content="Notifications">
      <FzIconButton iconName="bell" hasNotification ariaLabel="Notifications" />
    </FzTooltip>
    <FzTooltip content="Settings">
      <FzIconButton iconName="settings" variant="secondary" ariaLabel="Settings" />
    </FzTooltip>
    <FzTooltip content="Help">
      <FzIconButton iconName="question" variant="invisible" ariaLabel="Help" />
    </FzTooltip>
  </div>
</template>
```

#### 窗体动作

```vue
<template>
  <div class="flex gap-4">
    <FzIconButton 
      iconName="save" 
      variant="primary" 
      ariaLabel="Save"
      @click="handleSave"
    />
    <FzIconButton 
      iconName="trash" 
      variant="secondary" 
      ariaLabel="Delete"
      :disabled="!canDelete"
      @click="handleDelete"
    />
  </div>
</template>
```

## 相关构成部分

-   **FzIcon 按钮**: 仅用于没有标签的图标按钮
-   **Fz 按钮组**: 用于组合具有一致间隔的相关按钮

## 常见问题

### @fiscozen/button 是什么？

设计系统图标按钮组件

### 如何安装 @fiscozen/button？

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

### @fiscozen/button 支持 TypeScript 吗？

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

### @fiscozen/button 支持 ESM 还是 CommonJS？

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

### @fiscozen/button 可以商用吗？

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

### @fiscozen/button 的下载量有多少？

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

### @fiscozen/button 还在维护吗？

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