@fiscozen/ 工具提示

用于Vue 3应用程序的完全无障碍WCAG 2.1 AA兼容工具提示组件. 以企业级无障碍功能,键盘导航支持为主,并优化了屏幕阅读器.

特征

• 自动检测 - 自动检测交互式组件(FzButton、FzLink),以防止双重制表站
• 基于状态的样式 - 有语义色彩编码的视觉变体
• 灵活内容 - 支持文本道具和丰富的槽内容
• WCAG 2.1 AA 公司 - 充分提供无障碍支助,包括非洲建筑协会的作用和特性
• 屏幕阅读器优化 - 适当的语义标记和屏幕阅读器公告
• 键盘导航 - 完成重点管理的键盘存取
• 坚持不懈 - WCAG 1.4.13 为改进UX而遵循的徘徊行为

安装

npm install @fiscozen/tooltip

基本用途

简单文本工具提示

<script setup>
import { FzTooltip } from '@fiscozen/tooltip'
import { FzButton } from '@fiscozen/button'
</script>

<template>
  <!-- Non-interactive element (wrapper gets tabindex="0") -->
  <FzTooltip text="User profile settings">
    Settings
  </FzTooltip>
  
  <!-- Interactive component - auto-detected (no wrapper tabindex) -->
  <FzTooltip text="Save your changes">
    <FzButton>Save</FzButton>
  </FzTooltip>
  
  <!-- Native HTML element (not auto-detected, wrapper gets tabindex="0") -->
  <FzTooltip text="Submit form">
    <span @click="someAction">Submit</span>
  </FzTooltip>
  
  <!-- Native HTML element with manual override (no wrapper tabindex) -->
  <FzTooltip text="Submit form" :interactive="true">
    <span @click="someAction">Submit</span>
  </FzTooltip>
</template>

带槽的丰富内容

<template>
  <FzTooltip aria-label="Account information">
    <img src="/avatar.jpg" alt="User avatar" class="avatar" />
    
    <template #text>
      <strong>John Doe</strong><br>
      <span>Premium Member</span><br>
      <small>Last active: 2 hours ago</small>
    </template>
  </FzTooltip>
</template>

基于状态的工具提示

<template>
  <div class="dashboard-actions">
    <!-- Error state -->
    <FzTooltip 
      status="error" 
      :with-icon="true"
      text="Action failed: Insufficient permissions"
      aria-label="Delete operation status"
    >
      <button disabled>Delete Item</button>
    </FzTooltip>
    
    <!-- Success state -->
    <FzTooltip 
      status="positive" 
      :with-icon="true"
      text="Backup completed successfully at 14:32"
    >
      <span class="status-badge success">Backup Complete</span>
    </FzTooltip>
    
    <!-- Alert/Warning state -->
    <FzTooltip 
      status="alert" 
      :with-icon="true"
      text="System maintenance scheduled for tonight"
      aria-label="Maintenance warning"
    >
      <strong class="warning-text">Maintenance Notice</strong>
    </FzTooltip>
    
    <!-- Informative state -->
    <FzTooltip 
      status="informative" 
      :with-icon="true"
      text="This feature is currently in beta testing"
    >
      <div class="feature-card">
        <span class="beta-label">BETA</span>
        <p>New Analytics Dashboard</p>
      </div>
    </FzTooltip>
  </div>
</template>

API 参考

道具

槽数

FzTrunced 标签

在一行上保留着一个字段的标签,用于同时铺设形式组件. 标签被剪去后有椭圆形,当它比球场更宽,并在悬浮上用工具提示完整显示,而被标注的控件有焦点. 这个 <label> 保留全文,所以控制器保留它作为无障碍名称. 未剪接的标签永远不会拓宽字段 。 文本样式在组件上走:标签,椭圆和星号继承.

<FzTruncatedLabel
  class="text-base text-grey-500"
  label="Data di versamento dell’imposta sostitutiva"
  labelId="payment-date-label"
  controlId="payment-date"
  required
/>
<input id="payment-date" aria-labelledby="payment-date-label" required />

状态类型

type FzTooltipStatus = 
  | 'neutral'     // Default dark background
  | 'informative' // Blue semantic info color
  | 'positive'    // Green semantic success color  
  | 'alert'       // Orange semantic warning color
  | 'error'       // Red semantic error color

样式和主题

状态颜色映射

无障碍特性

WCAG 2.1 AA 遵守情况

本部分执行全面的无障碍功能:

• 键盘导航: 支持标签、 焦点和逃逸密钥
• 屏幕阅读器支持: 适当阿里亚的作用和说明
• 重点管理: 可用的焦点指标和逻辑分页顺序
• 坚持不懈1.4.13 符合要求的徘徊行为
• 高对比度: 符合 WCAG AA 对比比的颜色组合

交互式元素和自动检测

工具提示通过在运行时直接比较组件类型,自动检测交互式组件来防止双制表站.

自动检测组件 :

• ✅ FzButton - 自动确认为互动
• ✅ FzIconButton - 自动确认为互动
• ✅ FzLink - 自动确认为互动

如何运作: 自动检测使用直接组件类型比较,这种比较是生产安全的,不管建筑配置或细化设置如何,都是可行的. 当你包裹一个 FzButton, (中文(简体) ), FzIconButton,或 FzLink 在工具提示中,包裹会自动省略 tabindex="0" 属性来防止双标签站.

正在扩展自动检测 : 为增加支持新的互动部分:

1. 导入组件为 FzTooltip.vue
2. 把它加进 INTERACTIVE_COMPONENTS 数组
3. 把它添加为对等依赖性 package.json

示例

// In FzTooltip.vue
import { FzNewComponent } from '@fiscozen/newComponent'

const INTERACTIVE_COMPONENTS = [FzButton, FzLink, FzNewComponent] as const;

未自动检测( 需要时需要手动覆盖) :

• QQ 本地 HTML 元素 : <button>, (中文(简体) ), <a>, (中文(简体) ), <input>, (中文(简体) ), <select>, (中文(简体) ), <textarea>
• 自定义交互式元素 @click 处理者
• QQ 其他自定义组件( 即使是交互式的)

<!-- Auto-detection (recommended) - no prop needed -->
<FzTooltip text="Save your changes">
  <FzButton>Save</FzButton>
</FzTooltip>

<!-- Span with @click - not auto-detected, creates double tab stop -->
<FzTooltip text="Submit form">
  <span @click="someAction">Submit</span>
</FzTooltip>

<!-- Manual override - prevents double tab stop -->
<FzTooltip text="Submit form" :interactive="true">
  <span @click="someAction">Submit</span>
</FzTooltip>

<!-- Force non-interactive (e.g., disabled button) -->
<FzTooltip text="Action disabled" :interactive="false">
  <FzButton disabled>Save</FzButton>
</FzTooltip>

这个 interactive 道具 :

• undefined 或者说 'auto' (默认):自动检测 FzButton 和 FzLink
• true: 强制交互行为(删除包装标签索引)
• false: 强制非交互行为(添加包式标签索引="0")

为什么这很重要: 没有适当的交互处理, 工具提示包会添加 tabindex="0" 用于键盘访问,创建两个相接的制表站(Wrapper + 内元素)。 自动检测或明确 interactive={true} 删除包装器的分页索引,从而实现有单个分页站的干净键盘导航.

键盘交互

说明:当被包裹的元素是交互式的(按钮/链接)时,其本土键盘行为(Enter/Space活化)继续正常工作.

说明页:1 externalFocus,焦点坐落在触发器外: Escape 在任何地方按下隐藏工具提示 externalFocus 实值 true。 。 。 .

故事书中的设计回顾

为了进行设计检查和审查,工具提示部分提供一种特殊功能 _forceOpenForDesignReview 保持工具提示可见度的道具,无论徘徊状态或焦点状态.

QQ 重要警告

这道道具只用于在"故事书"中进行设计审查,绝不应在生产代码中使用. 下划线前缀表示这是一个内部/只发展功能.

故事书中的用法

<template>
  <!-- Force tooltip to remain visible for design inspection -->
  <FzTooltip 
    text="Review this tooltip styling" 
    status="informative"
    :withIcon="true"
    _forceOpenForDesignReview
  >
    <FzButton>Inspect Me</FzButton>
  </FzTooltip>
</template>

何时使用

• 设计审查:检查工具提示颜色、打字、间隔和布局
• 视觉QA: 并行比较工具提示变体
• 截图文档: 用于设计系统文档的工具提示状态
• 无障碍审计:审查工具提示内容和ARIA属性

故事书故事

该部分包括了故事书中一个专门的"设计评论"故事,以演示所有工具提示的变体 _forceOpenForDesignReview 启用 。 使用控制面板来切换道具打开/关闭并看到效果.

为什么不用于生产?

• 绕行所有普通工具提示能见度逻辑( 绕行、 聚焦、 键盘)
• 用总是可见的工具提示创建不良的用户体验
• 违反WCAG关于驳回内容的准则
• 仅用作开发/设计工具