@fiscozen/checkbox

中文文档

3.0.19发布于 2026/10/23MITES Module近 30 天下载 2423

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

文档目录28 节

特征
安装
基本用途
单复选框( Boolean 模型)
多个复选框( Arrray 模型)
复选框组
复选框卡
API 参考
Fz 检查框
Fz 检查框组
Fz 检查框卡
高级使用
有错误验证
带有工具提示
强调模式
独立( 只有Icon)
等级复选框组
水平布局
复选框卡——与图像垂直
复选框卡 — 没有复选框图标
残疾状态
带有窗体验证
类型脚本支持
无障碍特性
WCAG 2.1 AA 遵守情况
键盘交互
屏幕阅读器行为
重点指标

@ fiscozen/ 检查框

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

特征

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

安装

npm install @fiscozen/checkbox

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

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

基本用途

单复选框( Boolean 模型)

<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 模型)

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

复选框组

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

复选框卡

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

// 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 型号

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

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

变式布局

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

高级使用

有错误验证

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

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

强调模式

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

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

等级复选框组

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

水平布局

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

复选框卡——与图像垂直

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

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

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

残疾状态

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

带有窗体验证

<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来写,并提供了完整的类型定义.

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 共发布 34 个版本，首次发布于 2024/07/08；过去 12 个月发布了 25 个版本。

版本	发布日期	距今
`3.0.19`latest	2026/10/23	23 天前
`3.0.18`	2026/10/20	26 天前
`3.0.17`	2026/10/07	1 个月前
`3.0.16`	2026/09/29	1 个月前
`3.0.15`	2026/09/14	2 个月前
`3.0.14`	2026/09/07	2 个月前

其他发布通道：next → 1.0.0-next.0。

关于 @fiscozen/checkbox 的常见问题

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

npm install @fiscozen/checkbox

pnpmpnpm add @fiscozen/checkbox
yarnyarn add @fiscozen/checkbox
bunbun add @fiscozen/checkbox

peer 依赖vue ^3.4.13tailwindcss ^3.4.1@fiscozen/icons ^1.0.8

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

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

近 30 天下载

2,423

约 2423 次日均 81 次

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

最新版本3.0.19发布于 23 天前

开源许可MIT宽松许可

包体积420 kB41 个文件 · 解压后

运行依赖4 个另有 3 个 peer 依赖

模块格式ES Module

TypeScript未声明类型可查找 @types/fiscozen__checkbox

发布版本34 个近 12 个月 25 个

首次发布2024/07/082 年前

元数据更新2026/10/23

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

@fiscozen/checkbox

@ fiscozen/ 检查框

特征

安装

基本用途

单复选框( Boolean 模型)

多个复选框( Arrray 模型)

复选框组

复选框卡

API 参考

Fz 检查框

道具

v 型号

活动

槽数

Fz 检查框组

道具

v 型号

槽数

Fz 检查框卡

道具

v 型号

变式布局

高级使用

有错误验证

带有工具提示

强调模式

独立( 只有Icon)

等级复选框组

水平布局

复选框卡——与图像垂直

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

残疾状态

带有窗体验证

类型脚本支持

无障碍特性

WCAG 2.1 AA 遵守情况

键盘交互

屏幕阅读器行为

重点指标

版本与发布记录

关于 @fiscozen/checkbox 的常见问题

@fiscozen/checkbox 是什么？

如何安装 @fiscozen/checkbox？

@fiscozen/checkbox 支持 TypeScript 吗？

@fiscozen/checkbox 支持 ESM 还是 CommonJS？

@fiscozen/checkbox 可以商用吗？

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

@fiscozen/checkbox 还在维护吗？