nz-tooltip 官方名称和作用

官方名称

Tooltip（文字提示）

这是 NG-ZORRO（Ant Design of Angular）组件库中的一个基础组件。

组件定位

• 英文名: Tooltip
• 中文名: 文字提示 / 工具提示
• 组件库: NG-ZORRO (Ant Design of Angular)
• 对应 React 版本: antd 的 Tooltip 组件
• UI 设计体系: Ant Design

核心作用

1. 主要功能

简单的文字提示气泡框，用于在用户鼠标悬停、聚焦或点击元素时，显示额外的说明信息。

2. 使用场景

信息补充

<!-- 解释专业术语 -->
<span nz-tooltip nzTooltipTitle="Software as a Service，软件即服务">
  SaaS
</span>

<!-- 说明字段含义 -->
<th>
  库存
  <span nz-icon nz-tooltip nzTooltipTitle="当前仓库的实时库存数量" nzType="question-circle"></span>
</th>

内容截断显示

<!-- 表格单元格文本过长时显示完整内容 -->
<td>
  <div 
    class="text-ellipsis" 
    nz-tooltip 
    [nzTooltipTitle]="item.fullDescription"
  >
    {{ item.description }}
  </div>
</td>

操作说明

<!-- 图标按钮的功能说明 -->
<button 
  nz-button 
  nzType="text" 
  nz-tooltip 
  nzTooltipTitle="删除"
>
  <span nz-icon nzType="delete"></span>
</button>

状态提示

<!-- 禁用状态的原因说明 -->
<button 
  nz-button 
  [disabled]="!hasPermission" 
  nz-tooltip 
  [nzTooltipTitle]="hasPermission ? '' : '您没有该操作权限'"
>
  提交
</button>

数据详情

<!-- 显示统计数据的详细信息 -->
<span 
  nz-tooltip 
  [nzTooltipTitle]="'总计: ' + total + '\n成功: ' + success + '\n失败: ' + failed"
>
  {{ total }} 条记录
</span>

3. 设计理念

轻量级提示

• 不打断用户操作流程
• 信息即时显示，即时消失
• 不占用页面空间

渐进式信息披露

• 主要信息直接展示
• 次要信息通过 Tooltip 按需查看
• 避免界面过于拥挤

提升可用性

• 帮助用户理解界面元素
• 减少用户的认知负担
• 提供操作指引

4. 与其他组件的区别

选择建议：

• 简单文字说明 → 用 Tooltip
• 需要标题和内容结构 → 用 Popover
• 需要用户确认操作 → 用 Popconfirm
• 复杂表单或重要操作 → 用 Modal

5. 实际应用示例

表单字段说明

<nz-form-item>
  <nz-form-label>
    API密钥
    <span 
      nz-icon 
      nz-tooltip 
      nzTooltipTitle="用于系统间接口调用的身份认证，请妥善保管"
      nzType="question-circle"
      style="margin-left: 4px; color: rgba(0,0,0,0.45);"
    ></span>
  </nz-form-label>
  <nz-form-control>
    <input nz-input [(ngModel)]="apiKey" />
  </nz-form-control>
</nz-form-item>

数据状态指示

<nz-tag 
  [nzColor]="item.status === 'success' ? 'green' : 'red'"
  nz-tooltip
  [nzTooltipTitle]="item.statusMessage"
>
  {{ item.statusText }}
</nz-tag>

计算公式说明

<th>
  可用库存
  <span 
    nz-icon 
    nz-tooltip 
    nzTooltipTitle="可用库存 = 总库存 - 待发货 - 锁定库存"
    nzType="info-circle"
  ></span>
</th>

6. 最佳实践

内容建议

• ✅ 保持简短，一般不超过 2-3 行
• ✅ 使用清晰的语言，避免专业术语
• ✅ 提供有价值的补充信息
• ❌ 不要重复已显示的内容
• ❌ 避免过长的段落

交互建议

• ✅ 默认使用 hover 触发
• ✅ 移动端考虑使用 click 触发
• ✅ 重要提示可以增加延迟显示
• ❌ 不要在 Tooltip 内放置可点击元素（用 Popover）
• ❌ 避免嵌套使用 Tooltip

性能建议

• ✅ 大量元素时考虑按需加载内容
• ✅ 使用条件渲染避免不必要的 Tooltip
• ❌ 避免在循环中创建过多 Tooltip 实例

总结

nz-tooltip 是一个轻量级的文字提示组件，主要用于：

1. 补充说明 - 解释界面元素的含义
2. 操作指引 - 提示用户如何操作
3. 信息展示 - 显示被截断或隐藏的完整内容
4. 状态说明 - 解释当前状态或禁用原因

它是提升用户体验的重要工具，能在不增加界面复杂度的前提下，提供必要的信息支持。

nz-tooltip 用法

1. 基础用法 - 图标提示

<!-- 表头问号提示 -->
<span
  class="header-tooltip-icon"
  nz-icon
  nz-tooltip
  nzTheme="outline"
  nzTooltipTitle="可用=库存-待发-锁库"
  nzType="question-circle"
></span>

属性说明：

• nz-tooltip: 指令，将元素标记为提示触发器
• nzTooltipTitle: 提示框显示的文本内容，支持字符串或模板引用
• nz-icon: ng-zorro 图标组件指令
• nzType: 图标类型，这里使用 question-circle 问号圆圈图标
• nzTheme: 图标主题，outline 为线框风格，还有 fill(填充) 和 twotone(双色)

2. 文本提示

<!-- 在任意元素上添加提示 -->
<span nz-tooltip nzTooltipTitle="这是提示内容">
  鼠标悬停显示提示
</span>

属性说明：

• nz-tooltip: 最简单的用法，只需添加指令和标题即可
• nzTooltipTitle: 必填属性，定义提示内容
• 默认触发方式为 hover（鼠标悬停）
• 默认位置为 top（顶部）

3. 设置提示位置

<!-- 12个方向可选 -->
<button 
  nz-button 
  nz-tooltip 
  nzTooltipTitle="提示内容"
  nzTooltipPlacement="top"
>
  顶部提示
</button>

<!-- 可选位置：
  top, topLeft, topRight
  bottom, bottomLeft, bottomRight
  left, leftTop, leftBottom
  right, rightTop, rightBottom
-->

属性说明：

• nzTooltipPlacement: 控制提示框相对于触发元素的位置
  • top: 正上方居中
  • topLeft: 上方左对齐
  • topRight: 上方右对齐
  • bottom: 正下方居中
  • bottomLeft: 下方左对齐
  • bottomRight: 下方右对齐
  • left: 正左侧居中
  • leftTop: 左侧上对齐
  • leftBottom: 左侧下对齐
  • right: 正右侧居中
  • rightTop: 右侧上对齐
  • rightBottom: 右侧下对齐
• 类型: string
• 默认值: 'top'

4. 触发方式

<!-- 默认 hover 触发 -->
<span nz-tooltip nzTooltipTitle="悬停显示">Hover</span>

<!-- 点击触发 -->
<span 
  nz-tooltip 
  nzTooltipTitle="点击显示"
  nzTooltipTrigger="click"
>
  Click
</span>

<!-- 聚焦触发 -->
<input 
  nz-input 
  nz-tooltip 
  nzTooltipTitle="聚焦显示"
  nzTooltipTrigger="focus"
/>

<!-- 手动控制 -->
<span 
  nz-tooltip 
  nzTooltipTitle="手动控制"
  nzTooltipTrigger="null"
  [(nzTooltipVisible)]="visible"
>
  Manual
</span>

属性说明：

• nzTooltipTrigger: 控制提示框的触发方式
  • 'hover': 鼠标悬停时显示（默认）
  • 'click': 点击时显示，再次点击或点击外部关闭
  • 'focus': 元素获得焦点时显示，失去焦点时隐藏（常用于输入框）
  • null: 不自动触发，需要通过 nzTooltipVisible 手动控制
• 类型: 'hover' | 'focus' | 'click' | null
• 默认值: 'hover'
• nzTooltipVisible: 手动控制提示框显示/隐藏状态，类型为 boolean
• [(nzTooltipVisible)]: 双向绑定，可以在组件中控制和监听状态变化

5. 模板内容提示

<!-- 使用模板作为提示内容 -->
<span 
  nz-tooltip 
  [nzTooltipTitle]="tooltipTemplate"
>
  复杂提示
</span>

<ng-template #tooltipTemplate>
  <div>
    <p>标题</p>
    <ul>
      <li>项目1</li>
      <li>项目2</li>
    </ul>
  </div>
</ng-template>

属性说明：

• [nzTooltipTitle]: 使用方括号进行属性绑定，可以传入模板引用
• TemplateRef: Angular 模板引用类型，通过 #templateName 定义
• 支持在模板中使用任意 HTML 结构、样式和 Angular 指令
• 适用场景：需要显示复杂内容，如列表、表格、图片等
• 注意：模板内容过多会影响用户体验，建议保持简洁

6. 动态内容

<!-- 绑定变量 -->
<span 
  nz-tooltip 
  [nzTooltipTitle]="dynamicContent"
>
  动态提示
</span>

<!-- TypeScript -->
dynamicContent = '动态内容';

属性说明：

• [nzTooltipTitle]: 使用方括号绑定组件属性
• 内容会随着组件属性的变化而自动更新
• 可以绑定字符串、数字、模板引用等
• 适用场景：
  • 根据数据状态显示不同提示
  • 国际化文本
  • 计算属性
  • 异步加载的内容
• 示例：[nzTooltipTitle]="item.status === 'error' ? '错误：' + item.message : '正常'"

7. 自定义样式

<!-- 自定义背景色 -->
<span 
  nz-tooltip 
  nzTooltipTitle="自定义颜色"
  nzTooltipColor="#f50"
>
  红色提示
</span>

<!-- 自定义类名 -->
<span 
  nz-tooltip 
  nzTooltipTitle="自定义样式"
  nzTooltipOverlayClassName="custom-tooltip"
>
  自定义样式
</span>

属性说明：

• nzTooltipColor: 设置提示框的背景颜色

  • 类型: string
  • 支持任何有效的 CSS 颜色值：十六进制 #f50、RGB rgb(255, 85, 0)、颜色名 red
  • 会自动调整文字颜色以保证可读性

• nzTooltipOverlayClassName: 为提示框容器添加自定义 CSS 类名

  • 类型: string
  • 可以通过全局样式或组件样式定义该类的样式
  • 注意：组件样式需要使用 ::ng-deep 或设置 encapsulation: ViewEncapsulation.None
  • 示例 CSS：

    ::ng-deep .custom-tooltip {
    .ant-tooltip-inner {
    font-size: 16px;
    padding: 12px;
    }
    }

• nzTooltipOverlayStyle: 直接设置提示框的内联样式对象

  • 类型: object
  • 示例: [nzTooltipOverlayStyle]="{ 'max-width': '500px' }"

8. 延迟显示/隐藏

<span 
  nz-tooltip 
  nzTooltipTitle="延迟显示"
  [nzTooltipMouseEnterDelay]="0.5"
  [nzTooltipMouseLeaveDelay]="0.1"
>
  延迟提示
</span>

属性说明：

• nzTooltipMouseEnterDelay: 鼠标移入后延迟多少秒显示提示框

  • 类型: number
  • 单位: 秒（不是毫秒）
  • 默认值: 0.1 秒
  • 用途: 避免鼠标快速划过时频繁显示提示，提升用户体验
  • 示例: 0.5 表示鼠标移入后等待 0.5 秒才显示
  • 建议值: 0.3-0.5 秒适合大多数场景

• nzTooltipMouseLeaveDelay: 鼠标移出后延迟多少秒隐藏提示框

  • 类型: number
  • 单位: 秒
  • 默认值: 0.1 秒
  • 用途: 给用户一点时间将鼠标移到提示框上（如果提示框内有可交互内容）
  • 示例: 0.1 表示鼠标移出后等待 0.1 秒才隐藏
  • 建议值: 通常保持默认的 0.1 秒即可

• 使用场景：

  • 密集的列表或表格，避免提示频繁闪烁
  • 需要用户仔细阅读的重要提示
  • 提示框内包含可点击的链接或按钮

9. 条件显示

<!-- 根据条件显示提示 -->
<span 
  nz-tooltip 
  [nzTooltipTitle]="hasError ? '错误信息' : null"
>
  条件提示
</span>

<!-- 或使用 ng-template -->
<span 
  nz-tooltip 
  [nzTooltipTitle]="showTooltip ? tooltipContent : ''"
>
  条件提示2
</span>

属性说明：

• [nzTooltipTitle]: 当值为 null、undefined 或空字符串时，提示框不会显示
• 三元表达式: condition ? trueValue : falseValue
  • 根据条件动态决定是否显示提示
  • null 或 '' 都可以禁用提示
• 适用场景：
  • 只在出错时显示错误提示
  • 根据权限显示不同提示
  • 数据加载完成后才显示提示
  • 文本过长时才显示完整内容

• 示例：

  // 文本截断时显示完整内容
  [nzTooltipTitle]="text.length > 20 ? text : null"
  
  // 根据状态显示
  [nzTooltipTitle]="item.disabled ? '该功能已禁用' : null"

10. 表格中的用法（本页面实际案例）

<!-- 表头提示 -->
<th nzAlign="center">
  可用
  <span
    class="header-tooltip-icon"
    nz-icon
    nz-tooltip
    nzTheme="outline"
    nzTooltipTitle="可用=库存-待发-锁库"
    nzType="question-circle"
  ></span>
</th>

<!-- 单元格内容提示 -->
<td>
  <span 
    nz-tooltip 
    [nzTooltipTitle]="item.fullDescription"
  >
    {{ item.shortName }}
  </span>
</td>

属性说明：

• 表头提示：

  • 通常使用问号图标 question-circle 提供字段说明
  • 放在表头文字后面，用户可以快速了解字段含义
  • 建议使用简短的说明文字或计算公式

• 单元格提示：

  • 用于显示被截断的完整内容
  • 显示详细信息而不占用表格空间
  • 可以显示格式化后的数据（如完整时间、详细地址等）

• 最佳实践：

  • 表头提示使用静态文本
  • 单元格提示绑定数据项属性
  • 避免在每个单元格都加提示，只在必要时使用
  • 考虑使用 nzTooltipPlacement 避免提示框超出视口

11. 禁用状态

<!-- 禁用提示 -->
<button 
  nz-button 
  nz-tooltip 
  nzTooltipTitle="按钮被禁用"
  [disabled]="true"
>
  禁用按钮
</button>

属性说明：

• 禁用元素上的提示框行为：

  • 在某些浏览器中，禁用的元素（如 disabled 按钮）不会触发鼠标事件
  • 提示框可能无法正常显示

• 解决方案：

  <!-- 方案1: 用容器包裹 -->
  <span 
  nz-tooltip 
  nzTooltipTitle="按钮被禁用的原因"
  >
  <button nz-button [disabled]="true">
    禁用按钮
  </button>
  </span>
  
  <!-- 方案2: 使用 pointer-events -->
  <button 
  nz-button 
  nz-tooltip 
  nzTooltipTitle="按钮被禁用"
  [disabled]="true"
  style="pointer-events: auto"
  >
  禁用按钮
  </button>

• 使用场景：

  • 解释为什么功能被禁用
  • 提示用户如何启用该功能
  • 显示权限不足的原因

12. 箭头显示控制

<!-- 箭头指向中心 -->
<span 
  nz-tooltip 
  nzTooltipTitle="箭头指向中心"
  [nzTooltipArrowPointAtCenter]="true"
>
  居中箭头
</span>

属性说明：

• nzTooltipArrowPointAtCenter: 控制提示框箭头是否指向触发元素的中心

  • 类型: boolean
  • 默认值: false
  • true: 箭头始终指向元素中心，提示框可能会偏移
  • false: 箭头位置根据提示框位置自动调整

• 使用场景：

  • 触发元素较大时，希望箭头指向中心更美观
  • 需要精确指示关联关系

• 注意事项：

  • 设置为 true 时，提示框可能会超出视口边界
  • 小元素上使用效果不明显

13. 可见性控制和事件监听

<div
  nz-tooltip
  nzTooltipTitle="完整配置"
  [(nzTooltipVisible)]="tooltipVisible"
  (nzTooltipVisibleChange)="onTooltipVisibleChange($event)"
>
  完整示例
</div>

属性说明：

• nzTooltipVisible: 控制提示框的显示/隐藏状态

  • 类型: boolean
  • 可以单向绑定 [nzTooltipVisible]="visible" 或双向绑定 [(nzTooltipVisible)]="visible"
  • 配合 nzTooltipTrigger="null" 实现完全手动控制

• nzTooltipVisibleChange: 提示框显示状态变化时触发的事件

  • 类型: EventEmitter<boolean>
  • 参数: $event 为 true（显示）或 false（隐藏）
  • 用途：
  • 记录用户查看提示的行为
  • 在显示时加载动态内容
  • 实现复杂的交互逻辑

• 示例：

  // TypeScript
  tooltipVisible = false;
  
  onTooltipVisibleChange(visible: boolean) {
  console.log('提示框状态:', visible);
  if (visible) {
    // 提示框显示时的逻辑
    this.loadTooltipData();
  }
  }
  
  showTooltip() {
  this.tooltipVisible = true;
  }
  
  hideTooltip() {
  this.tooltipVisible = false;
  }

14. 完整配置示例

<div
  nz-tooltip
  nzTooltipTitle="完整配置"
  nzTooltipPlacement="topLeft"
  nzTooltipTrigger="hover"
  nzTooltipColor="#108ee9"
  nzTooltipOverlayClassName="custom-class"
  [nzTooltipMouseEnterDelay]="0.3"
  [nzTooltipMouseLeaveDelay]="0.1"
  [nzTooltipVisible]="tooltipVisible"
  (nzTooltipVisibleChange)="onTooltipVisibleChange($event)"
>
  完整示例
</div>

综合说明：
这个示例展示了如何组合使用多个属性来实现复杂的提示框需求：

1. 基础配置：

   • nzTooltipTitle: 提示内容
   • nzTooltipPlacement: 位置在左上方

2. 交互配置：

   • nzTooltipTrigger: 悬停触发
   • nzTooltipMouseEnterDelay: 0.3秒后显示
   • nzTooltipMouseLeaveDelay: 0.1秒后隐藏

3. 样式配置：

   • nzTooltipColor: 蓝色背景
   • nzTooltipOverlayClassName: 自定义类名用于更多样式控制

4. 状态控制：

   • nzTooltipVisible: 双向绑定显示状态
   • nzTooltipVisibleChange: 监听状态变化

常用属性速查表