@ fiscozen/ 按钮

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

特征

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

安装

npm install @fiscozen/button

构成部分

此套件输出三个组件:

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

基本用途

Fz 按钮

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

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

有备选案文

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

带有图标

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

环境( 小)

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

大小道具( 已过期)

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

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

残疾状态

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

使用槽

<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按钮道具

槽数

行为和概念

标签对 Slot 优先级

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

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

图标显示逻辑

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

集装箱类自定义

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

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

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

2. 完全覆盖数字 :

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

实例

窗体动作

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

经确认的破坏行动

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

带有图标的导航

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

装入状态( 海关执行)

<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%宽度
• 无需道具

基本用途

<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按钮组示例

动作按钮组

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

两个按钮( 前沿办公室)

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

两个按钮( 后台)

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

三键 (前沿办公室)

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

三键 (后台)

<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接触区域
• 通知徽章覆盖支持
• 自定义图标变体
• 全面无障碍支持
• 类型脚本支持

基本用途

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

备选案文

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

环境

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

带有通知徽章

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

压缩

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

<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 开始.

带有工具提示( 建议)

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

FzIcon 按钮道具

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 按钮示例

工具栏动作

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

窗体动作

<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 按钮组: 用于组合具有一致间隔的相关按钮