# @fiscozen/checkbox 中文文档

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

版本：3\.0\.19
npm 元数据更新时间：2026-10-23T08:35:52.339Z
中文译文更新时间：2026-11-14T20:52:23.013Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：420 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1，@fiscozen/icons ^1\.0\.8
- 首次发布：2024-07-08T12:50:53.765Z
- 最新版本发布：2026-10-23T08:35:52.020Z
- 近 30 天下载量：2423（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 25 个）

## 中文简介

设计系统复选框和复选框组组件

## 安装

```sh
npm install @fiscozen/checkbox
```

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

## README

# @ fiscozen/ 检查框

一个完全无障碍的WCAG 2.1 AA兼容的Vue 3应用程序的复选框组件库. 以企业级无障碍功能所建,支持单选和多选取模式,分级复选组,自动不确定状态管理,并实现键盘综合导航.

## 特征

-   **WCAG 2.1 AA 公司** - 全面无障碍支助,具有全面的ARIA属性
-   **弹性数据模型** - 支持布尔(单一)和阵列(多选择) v-模型绑定
-   **等级结构** - 具有自动不确定状态的父子复选框关系
-   **纸牌式复选框** - 有图像、标题、字幕和工具提示的富选卡
-   **键盘导航** - 完成有可见重点指标的键盘存取
-   **屏幕阅读器优化** - 适当的语义标记和现场区域公告
-   **处理错误** - 内建验证状态,可获取错误信息
-   **可自定义** - 多重大小变体、强调模式和工具提示支持

## 安装

```bash
npm install @fiscozen/checkbox
```

**同伴依赖关系 :** 这个包需要Vue 3.x 和以下的 Fiscozen 设计系统包:

-   `@fiscozen/icons` - 图标系统
-   `@fiscozen/tooltip` - 用于环境帮助的工具提示组件
-   `@fiscozen/alert` - 错误消息的提醒组件

## 基本用途

### 单复选框( Boolean 模型)

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const accepted = ref(false);
</script>

<template>
  <div>
    <FzCheckbox 
      v-model="accepted" 
      label="I accept the terms and conditions" 
    />
    
    <p v-if="accepted">Terms accepted!</p>
  </div>
</template>
```

### 多个复选框( Arrray 模型)

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const selectedFeatures = ref<string[]>([]);
</script>

<template>
  <div>
    <h3>Select Features:</h3>
    
    <FzCheckbox 
      v-model="selectedFeatures" 
      value="feature-a" 
      label="Feature A" 
    />
    
    <FzCheckbox 
      v-model="selectedFeatures" 
      value="feature-b" 
      label="Feature B" 
    />
    
    <FzCheckbox 
      v-model="selectedFeatures" 
      value="feature-c" 
      label="Feature C" 
    />
    
    <p>Selected: {{ selectedFeatures.join(', ') }}</p>
  </div>
</template>
```

### 复选框组

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxGroup } from '@fiscozen/checkbox';

const selectedOptions = ref<string[]>([]);

const options = [
  { label: 'Option 1', value: 'opt1' },
  { label: 'Option 2', value: 'opt2' },
  { label: 'Option 3', value: 'opt3' },
];
</script>

<template>
  <FzCheckboxGroup
    v-model="selectedOptions"
    label="Choose your options"
    :options="options"
  >
    <template #help>
      <span>Select one or more options</span>
    </template>
  </FzCheckboxGroup>
</template>
```

### 复选框卡

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxCard } from '@fiscozen/checkbox';

const selected = ref<(string | number)[]>([]);
</script>

<template>
  <div style="display: flex; gap: 12px;">
    <FzCheckboxCard
      v-model="selected"
      label="option-a"
      value="option-a"
      title="Option A"
      subtitle="Description for option A"
    />

    <FzCheckboxCard
      v-model="selected"
      label="option-b"
      value="option-b"
      title="Option B"
      subtitle="Description for option B"
    />
  </div>
</template>
```

## API 参考

### Fz 检查框

支持单选和多选取模式的核心复选框组件. 可在复选框组内单独使用或组成.

#### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | **所需经费** | 框标签文本 |
| `value` | `string | number | boolean` | `label` | 数组模型中使用的值 |
| `indeterminate` | `boolean` | `false` | 显示不确定状态( 部分选择) |
| `emphasis` | `boolean` | `false` | 应用强调样式( 检查时为蓝色) |
| `disabled` | `boolean` | `false` | 禁用复选框 |
| `error` | `boolean` | `false` | 显示错误状态 |
| `required` | `boolean` | `false` | 需要标记字段 |
| `standalone` | `boolean` | `false` | 只渲染没有标签文本的图标 |
| `tooltip` | `FzTooltipProps` | `undefined` | 工具提示配置 |
| `ariaOwns` | `string` | `undefined` | 等级结构的空间分离儿童身份证 |
| `checkboxId` | `string` | 自动生成 | 输入元素的自定义ID |

#### v 型号

```typescript
// Single checkbox
v-model: boolean | null | undefined

// Multi-select checkbox
v-model: (string | number | boolean)[]
```

#### 活动

| 活动 | 有效载荷 | 说明 |
| --- | --- | --- |
| `change` | `Event` | 复选框状态更改时发送 |

#### 槽数

| 槽 | 说明 |
| --- | --- |
| `error` | 错误消息内容 |
| `children` | 儿童复选框(由等级结构内部使用) |

* * *

### Fz 检查框组

用于管理多个具有共享标签、验证和无障碍功能的相关复选框的集装箱组件.

#### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | **所需经费** | 组标签 |
| `options` | `ParentCheckbox[]` | **所需经费** | 复选框选项矩阵 |
| `emphasis` | `boolean` | `false` | 适用于所有复选框 |
| `disabled` | `boolean` | `false` | 禁用所有复选框 |
| `error` | `boolean` | `false` | 显示错误状态 |
| `required` | `boolean` | `false` | 需要的标记组 |
| `horizontal` | `boolean` | `false` | 水平排列复选框 |

#### v 型号

```typescript
v-model: string[]
```

#### 槽数

| 槽 | 说明 |
| --- | --- |
| `help` | 标签下显示的帮助文本 |
| `error` | 错误消息内容 |

* * *

### Fz 检查框卡

一个卡片风格的复选框组件,支持标题,字幕,可选图像,和工具提示. 以横向和纵向布局变体提供。 多选择模式使用数组 v- 模型 .

#### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | **所需经费** | 基本复选框输入的可访问标签 |
| `value` | `string | number` | `label` | 数组 v 模型中跟踪的值 |
| `title` | `string` | **所需经费** | 在卡片中显示的主标题文本 |
| `subtitle` | `string` | `undefined` | 标题下可选次要文本 |
| `variant` | `'horizontal' | 'vertical'` | `'horizontal'` | 卡片的布局方向 |
| `imageUrl` | `string` | `undefined` | 卡片图像的 URL( 当需要时) `variant` 实值 `'vertical'`(中文(简体) ) |
| `imageAlt` | `string` | `undefined` | 卡片图像的换文本 |
| `hasCheckbox` | `boolean` | `true` | 是否在卡片内显示复选框图标 |
| `emphasis` | `boolean` | `false` | 应用强调样式( 选中时为蓝色图标) |
| `disabled` | `boolean` | `false` | 禁用卡片 |
| `error` | `boolean` | `false` | 显示出错状态( 红色复选框图标) |
| `required` | `boolean` | `false` | 按要求标记输入 |
| `tooltip` | `string` | `undefined` | 在信息工具提示中显示的文本 |
| `tooltipStatus` | `FzTooltipStatus` | `'neutral'` | 工具提示颜色/ 状态变量 |
| `name` | `string` | `undefined` | 投入 `name` 表格提交属性 |

> **说明:** 何时 `variant` 实值 `'vertical'`,则 `imageUrl` 需要道具,因为垂直布局是围绕全向图像设计的.

#### v 型号

```typescript
v-model: (string | number | boolean)[]
```

#### 变式布局

-   **水平** (default) – 复选框图标,可选缩略图图像(58×58),和文本被一行排列. 适合列表的压缩布局 .
-   **垂直** ——上方为全宽16:9的图像,复选框图标被覆盖,下方为文字. 设计于视觉丰富的选择.

* * *

## 高级使用

### 有错误验证

```vue
<script setup lang="ts">
import { ref, computed } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const agreedToTerms = ref(false);
const submitted = ref(false);

const hasError = computed(() => submitted.value && !agreedToTerms.value);

function handleSubmit() {
  submitted.value = true;
  if (!agreedToTerms.value) {
    // Handle validation error
    return;
  }
  // Process form
}
</script>

<template>
  <div>
    <FzCheckbox
      v-model="agreedToTerms"
      label="I agree to the terms"
      required
      :error="hasError"
    >
      <template #error>
        <p>You must accept the terms to continue</p>
      </template>
    </FzCheckbox>
    
    <button @click="handleSubmit">Submit</button>
  </div>
</template>
```

### 带有工具提示

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const enableFeature = ref(false);
</script>

<template>
  <FzCheckbox
    v-model="enableFeature"
    label="Enable advanced mode"
    :tooltip="{
      text: 'This enables experimental features that may be unstable',
      status: 'informative'
    }"
  />
</template>
```

### 强调模式

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const isPrimary = ref(false);
</script>

<template>
  <FzCheckbox
    v-model="isPrimary"
    label="Primary selection"
    emphasis
  />
</template>
```

### 独立( 只有Icon)

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox } from '@fiscozen/checkbox';

const selected = ref(false);
</script>

<template>
  <div>
    <label for="custom-checkbox">Select this item:</label>
    <FzCheckbox
      v-model="selected"
      label="Select item"
      standalone
    />
  </div>
</template>
```

### 等级复选框组

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxGroup } from '@fiscozen/checkbox';

const selectedPermissions = ref<string[]>([]);

const permissionOptions = [
  {
    label: 'Admin Access',
    value: 'admin',
    children: [
      { label: 'User Management', value: 'admin.users' },
      { label: 'System Settings', value: 'admin.settings' },
      { label: 'View Logs', value: 'admin.logs' },
    ]
  },
  {
    label: 'Content Access',
    value: 'content',
    children: [
      { label: 'Create Content', value: 'content.create' },
      { label: 'Edit Content', value: 'content.edit' },
      { label: 'Delete Content', value: 'content.delete' },
    ]
  }
];
</script>

<template>
  <FzCheckboxGroup
    v-model="selectedPermissions"
    label="Select Permissions"
    :options="permissionOptions"
  >
    <template #help>
      <span>Parent checkboxes show indeterminate state when partially selected</span>
    </template>
  </FzCheckboxGroup>
</template>
```

### 水平布局

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxGroup } from '@fiscozen/checkbox';

const selectedDays = ref<string[]>([]);

const dayOptions = [
  { label: 'Mon', value: 'monday' },
  { label: 'Tue', value: 'tuesday' },
  { label: 'Wed', value: 'wednesday' },
  { label: 'Thu', value: 'thursday' },
  { label: 'Fri', value: 'friday' },
];
</script>

<template>
  <FzCheckboxGroup
    v-model="selectedDays"
    label="Working Days"
    :options="dayOptions"
    horizontal
  />
</template>
```

### 复选框卡——与图像垂直

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxCard } from '@fiscozen/checkbox';

const selected = ref<(string | number)[]>([]);
</script>

<template>
  <div style="display: flex; gap: 16px; max-width: 720px;">
    <FzCheckboxCard
      v-model="selected"
      label="plan-basic"
      value="basic"
      variant="vertical"
      image-url="/images/basic-plan.jpg"
      image-alt="Basic plan illustration"
      title="Basic Plan"
      subtitle="For individuals getting started"
      tooltip="Includes 5 GB storage"
    />

    <FzCheckboxCard
      v-model="selected"
      label="plan-pro"
      value="pro"
      variant="vertical"
      image-url="/images/pro-plan.jpg"
      image-alt="Pro plan illustration"
      title="Pro Plan"
      subtitle="For growing teams"
      tooltip="Includes 50 GB storage"
    />
  </div>
</template>
```

### 复选框卡 — 没有复选框图标

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckboxCard } from '@fiscozen/checkbox';

const selected = ref<(string | number)[]>([]);
</script>

<template>
  <FzCheckboxCard
    v-model="selected"
    label="option"
    value="option"
    title="Selectable Card"
    subtitle="The card border highlights on selection"
    :has-checkbox="false"
  />
</template>
```

### 残疾状态

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FzCheckbox, FzCheckboxGroup } from '@fiscozen/checkbox';

const checked = ref(true);
const groupSelection = ref<string[]>(['opt1']);

const options = [
  { label: 'Option 1', value: 'opt1' },
  { label: 'Option 2', value: 'opt2' },
];
</script>

<template>
  <div>
    <!-- Disabled single checkbox -->
    <FzCheckbox
      v-model="checked"
      label="This is disabled"
      disabled
    />
    
    <!-- Disabled group -->
    <FzCheckboxGroup
      v-model="groupSelection"
      label="Disabled Group"
      :options="options"
      disabled
    />
  </div>
</template>
```

### 带有窗体验证

```vue
<script setup lang="ts">
import { ref, computed } from 'vue';
import { FzCheckboxGroup } from '@fiscozen/checkbox';

const selectedOptions = ref<string[]>([]);
const touched = ref(false);

const options = [
  { label: 'Option A', value: 'a' },
  { label: 'Option B', value: 'b' },
  { label: 'Option C', value: 'c' },
];

const hasError = computed(() => 
  touched.value && selectedOptions.value.length === 0
);

function handleBlur() {
  touched.value = true;
}
</script>

<template>
  <div @blur="handleBlur">
    <FzCheckboxGroup
      v-model="selectedOptions"
      label="Required Selection"
      :options="options"
      required
      :error="hasError"
    >
      <template #help>
        <span>Select at least one option</span>
      </template>
      
      <template #error>
        <span>Please select at least one option to continue</span>
      </template>
    </FzCheckboxGroup>
  </div>
</template>
```

## 类型脚本支持

这个包被用TypeScript来写,并提供了完整的类型定义.

```typescript
import type { 
  FzCheckboxProps, 
  FzCheckboxGroupProps,
  FzCheckboxCardProps,
  ParentCheckbox,
  ChildCheckbox 
} from '@fiscozen/checkbox';

// Example: Typed options array
const options: ParentCheckbox[] = [
  {
    label: 'Parent Option',
    value: 'parent',
    children: [
      { label: 'Child 1', value: 'child1' },
      { label: 'Child 2', value: 'child2' }
    ]
  }
];

// Example: Typed card props (vertical variant requires imageUrl)
const verticalCard: FzCheckboxCardProps = {
  label: 'card',
  title: 'Card Title',
  subtitle: 'Description',
  variant: 'vertical',
  imageUrl: '/images/card.jpg',
};
```

## 无障碍特性

### WCAG 2.1 AA 遵守情况

本部分按照WCAG 2.1 AA级准则执行全面的无障碍功能:

-   **键盘导航** - 全力支持Tab和Space关键互动
-   **屏幕阅读器支持** - 适当的ARIA角色、标签和国家公告
-   **重点管理** - 明显重点指标满足3:1对比比率要求
-   **处理错误** - 动态验证信息的现场区域公告
-   **语义标记** - 具有无障碍标签协会的本地复选框输入

### 键盘交互

| 密钥 | 行动 |
| --- | --- |
| `Tab` | 将焦点移动到下一个复选框 |
| `Shift + Tab` | 将焦点移动到上一个复选框 |
| `Space` | 切换复选框状态 |

### 屏幕阅读器行为

该部分为辅助技术提供了丰富的语义信息:

-   **状态** - “检查”、“未检查”或“混合”(不确定)
-   **标签协会** - 说吧 `aria-labelledby` 财务报告和审定财务报表 `aria-label` 适当身份证明
-   **错误消息** - 说吧 `aria-describedby` 链接到错误内容 `role="alert"`
-   **组合背景** - 说吧 `role="group"` 与 `aria-labelledby` 用于相关的复选框集
-   **等级关系** - 说吧 `aria-owns` 建立父子复选框连接
-   **所需字段** - 说吧 `aria-required` 表示强制性选择
-   **审定状态** - 说吧 `aria-invalid` 显示验证错误

### 重点指标

-   焦点环显示为复选框图标周围的蓝色边框
-   与背景相对比的要求
-   在所有州可见:默认、徘徊、检查、不确定
-   标签顺序遵循逻辑 DOM 结构

## 常见问题

### @fiscozen/checkbox 是什么？

设计系统复选框和复选框组组件

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

在项目目录运行 npm install @fiscozen/checkbox，或使用 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/checkbox 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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