# @fiscozen/tooltip 中文文档

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

版本：3\.1\.1
npm 元数据更新时间：2026-10-23T08:35:16.817Z
中文译文更新时间：2026-11-14T20:31:30.103Z
软件包许可：ISC

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

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

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

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

## 中文简介

设计系统工具提示组件

## 安装

```sh
npm install @fiscozen/tooltip
```

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

## README

# @fiscozen/ 工具提示

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

## 特征

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

## 安装

```bash
npm install @fiscozen/tooltip
```

## 基本用途

### 简单文本工具提示

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

### 带槽的丰富内容

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

### 基于状态的工具提示

```vue
<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 参考

### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | `undefined` | 工具提示内容文本 。 替代使用 `text` 插槽 |
| `status` | `FzTooltipStatus` | `'neutral'` | 视觉状态 : `'neutral'` | `'informative'` | `'positive'` | `'alert'` | `'error'` |
| `position` | `FzFloatingPosition` | `'auto'` | 相对于触发元素的工具提示定位 |
| `withIcon` | `boolean` | `false` | 在工具提示内容中显示适合状态的图标 |
| `ariaLabel` | `string` | `undefined` | 触发元素的可访问标签 |
| `interactive` | `boolean | 'auto'` | `'auto'` | 控制键盘访问性 : `undefined`编号 :`'auto'` 用于自动检测(FzButton、FzLink), `true` 强制交互, `false` 强制非互动 |
| `truncate` | `boolean` | `false` | 在一行上显示内容,不合适时用椭圆剪接,仅在内容被剪接时打开工具提示. 扳机不设分站也不设 `aria-describedby`:全部内容已收录于DOM. 在灵活布局中,灵活祖先需要 `min-w-0` 要切除的内容 |
| `externalFocus` | `boolean` | `false` | 焦点是否位于一个元素上, 触发符代表但不包含, 例如控制标签名称 。 虽然 `true`,工具提示表现为触发器有焦点:打开(与 `truncate`,只在内容被剪去时,在指针离开时保持开放,并关闭 `Escape`。 。 。 . `FzTruncatedLabel` 帮你摆好 |
| `_forceOpenForDesignReview` | `boolean` | `false` | ⚠️ **仅供设计审查** - 保持可见性. **不使用生产** |

### 槽数

| 槽 | 说明 |
| --- | --- |
| `default` | 触发元素内容( 需要) |
| `text` | 工具提示内容 - 支持丰富的 HTML 内容 |

### FzTrunced 标签

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

```vue
<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 />
```

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | \- 说吧 | 标签的文字( 需要) |
| `labelId` | `string` | \- 说吧 | `id` 会 议 日 程 和 议 程 `<label>` 元素,用于控件 `aria-labelledby` (必须) |
| `controlId` | `string` | \- 说吧 | `id` 作为标签的标签 `for` (必须) |
| `required` | `boolean` | `false` | 在切口外加一个可视星等。 隐藏辅助技术:按要求标出控制本身 |

### 状态类型

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

## 样式和主题

### 状态颜色映射

| 状态 | 使用大小写 | 背景类 | 图标 |
| --- | --- | --- | --- |
| `neutral` | 概况,帮助文本 | `!bg-core-black` | 无 |
| `informative` | 提示, 附加上下文 | `bg-semantic-info` | `circle-info` |
| `positive` | 成功状态、确认 | `bg-semantic-success` | `circle-check` |
| `alert` | 警告,需要注意 | `bg-semantic-warning` | `triangle-exclamation` |
| `error` | 错误, 验证失败 | `bg-semantic-error` | `circle-exclamation` |

## 无障碍特性

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

示例

```typescript
// 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 其他自定义组件( 即使是交互式的)

```vue
<!-- 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}` 删除包装器的分页索引,从而实现有单个分页站的干净键盘导航.

### 键盘交互

| 密钥 | 行动 |
| --- | --- |
| `Tab` | 焦点包装并显示工具提示 |
| `Shift + Tab` | 聚焦上一个元素并隐藏工具提示 |
| `Escape` | 在保持焦点的同时隐藏工具提示 |

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

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

## 故事书中的设计回顾

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

### QQ 重要警告

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

### 故事书中的用法

```vue
<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关于驳回内容的准则
-   仅用作开发/设计工具

## 常见问题

### @fiscozen/tooltip 是什么？

设计系统工具提示组件

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

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

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

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

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

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

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

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

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

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

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