nz-popconfirm（气泡确认框）

nz-popconfirm 官方名称和作用

官方名称

Popconfirm（气泡确认框）

这是 NG-ZORRO（Ant Design of Angular）组件库中的确认类组件。

组件定位

• 英文名: Popconfirm
• 中文名: 气泡确认框 / 弹出确认
• 组件库: NG-ZORRO (Ant Design of Angular)
• 对应 React 版本: antd 的 Popconfirm 组件
• UI 设计体系: Ant Design

核心作用

1. 主要功能

点击元素时弹出气泡式的确认框，用于对用户的操作进行二次确认，避免误操作导致的不可逆后果。

2. 使用场景

删除操作确认

<!-- 删除按钮 -->
<a
  nz-popconfirm
  nzPopconfirmTitle="确定要删除这条记录吗？"
  (nzOnConfirm)="deleteRecord(item.id)"
>
  <span nz-icon nzType="delete"></span>
  删除
</a>

批量操作确认

<!-- 批量删除 -->
<button
  nz-button
  nzDanger
  nz-popconfirm
  nzPopconfirmTitle="确定要删除选中的 {{selectedCount}} 条记录吗？此操作不可恢复！"
  (nzOnConfirm)="batchDelete()"
>
  批量删除
</button>

状态变更确认

<!-- 启用/禁用 -->
<nz-switch
  [(ngModel)]="item.enabled"
  nz-popconfirm
  [nzPopconfirmTitle]="item.enabled ? '确定要禁用吗？' : '确定要启用吗？'"
  (nzOnConfirm)="toggleStatus(item)"
>
</nz-switch>

提交前确认

<!-- 表单提交 -->
<button
  nz-button
  nzType="primary"
  nz-popconfirm
  nzPopconfirmTitle="确认提交订单？提交后将无法修改"
  (nzOnConfirm)="submitOrder()"
>
  提交订单
</button>

危险操作警告

<!-- 清空数据 -->
<button
  nz-button
  nzDanger
  nz-popconfirm
  nzPopconfirmTitle="此操作将清空所有数据，是否继续？"
  nzOkText="确定清空"
  nzCancelText="取消"
  nzOkDanger
  (nzOnConfirm)="clearAllData()"
  (nzOnCancel)="handleCancel()"
>
  清空数据
</button>

3. 设计理念

轻量级确认

• 比 Modal 对话框更轻量
• 不打断用户的操作流程
• 就近显示，上下文关联性强

防止误操作

• 对危险操作进行二次确认
• 给用户反悔的机会
• 降低操作失误的风险

快速决策

• 简单的确认/取消选择
• 无需复杂的表单填写
• 适合快速操作场景

4. 与其他组件的区别

选择建议：

• 简单的删除、禁用等操作 → 用 Popconfirm
• 需要填写原因或备注 → 用 Modal
• 仅提示信息无需确认 → 用 Tooltip 或 Popover
• 非常重要的操作（如支付） → 用 Modal

5. 实际应用示例

表格行删除

<nz-table [nzData]="dataList">
  <tbody>
    <tr *ngFor="let item of dataList">
      <td>{{ item.name }}</td>
      <td>
        <a
          nz-popconfirm
          nzPopconfirmTitle="确认移除该微仓吗？"
          (nzOnConfirm)="deleteItem(item.id)"
        >
          <span nz-icon nzType="delete"></span>
        </a>
      </td>
    </tr>
  </tbody>
</nz-table>

带图标的确认框

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="删除后数据无法恢复，确定继续吗？"
  nzIcon="exclamation-circle"
  nzOkDanger
  (nzOnConfirm)="permanentDelete()"
>
  永久删除
</button>

条件确认

<button
  nz-button
  nz-popconfirm
  [nzPopconfirmTitle]="getConfirmMessage(item)"
  [nzCondition]="item.canDirectDelete"
  (nzOnConfirm)="deleteItem(item)"
>
  删除
</button>

<!-- TypeScript -->
getConfirmMessage(item: any): string {
  return item.hasChildren 
    ? '该项包含子项，删除后子项也会被删除，确定继续吗？'
    : '确定删除吗？';
}

6. 最佳实践

文案建议

• ✅ 使用疑问句，如"确定要删除吗？"
• ✅ 说明操作后果，如"删除后无法恢复"
• ✅ 重要操作使用感叹号强调
• ❌ 避免使用命令式语气
• ❌ 不要过于冗长

交互建议

• ✅ 危险操作使用红色确认按钮（nzOkDanger）
• ✅ 自定义按钮文字使其更明确
• ✅ 提供取消回调处理用户放弃操作
• ❌ 不要在确认框内放置复杂表单
• ❌ 避免嵌套使用

性能建议

• ✅ 使用 nzCondition 跳过不必要的确认
• ✅ 确认后及时给予反馈（loading 或 message）
• ❌ 避免在循环中创建过多实例

详细属性说明

1. 基础用法

<a
  nz-popconfirm
  nzPopconfirmTitle="确定要删除吗？"
  (nzOnConfirm)="handleConfirm()"
>
  删除
</a>

属性说明：

• nz-popconfirm: 指令，将元素标记为确认框触发器
• nzPopconfirmTitle: 确认框显示的标题文本，必填属性
• nzOnConfirm: 点击确认按钮时触发的事件
• 默认触发方式为 click（点击）
• 默认位置为 top（顶部）

2. 自定义按钮文字

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要删除这条记录吗？"
  nzOkText="确定删除"
  nzCancelText="我再想想"
  (nzOnConfirm)="deleteRecord()"
>
  删除
</button>

属性说明：

• nzOkText: 确认按钮的文字

  • 类型: string
  • 默认值: '确定'
  • 建议使用动词，如"确定删除"、"立即提交"

• nzCancelText: 取消按钮的文字

  • 类型: string
  • 默认值: '取消'
  • 可以使用"我再想想"、"暂不操作"等更人性化的文字

3. 危险操作样式

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="此操作不可恢复，确定继续吗？"
  nzOkText="确定"
  nzOkDanger
  (nzOnConfirm)="dangerousAction()"
>
  危险操作
</button>

属性说明：

• nzOkDanger: 将确认按钮设置为危险样式（红色）
  • 类型: boolean
  • 默认值: false
  • 用于删除、清空等不可逆的危险操作
  • 视觉上警示用户操作的严重性

4. 设置位置

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要执行此操作吗？"
  nzPopconfirmPlacement="topLeft"
  (nzOnConfirm)="handleAction()"
>
  操作
</button>

属性说明：

• nzPopconfirmPlacement: 控制确认框相对于触发元素的位置
  • 类型: string
  • 默认值: 'top'
  • 可选值（12个方向）：
  • top, topLeft, topRight
  • bottom, bottomLeft, bottomRight
  • left, leftTop, leftBottom
  • right, rightTop, rightBottom
  • 建议：根据触发元素在页面中的位置选择，避免超出视口

5. 添加图标

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="删除后无法恢复，确定继续吗？"
  nzIcon="exclamation-circle"
  nzOkDanger
  (nzOnConfirm)="deleteData()"
>
  删除
</button>

属性说明：

• nzIcon: 在确认框标题前显示的图标
  • 类型: string | TemplateRef<void>
  • 常用图标：
  • exclamation-circle: 警告图标（黄色）
  • question-circle: 疑问图标（蓝色）
  • info-circle: 信息图标
  • close-circle: 错误图标（红色）
  • 可以传入图标名称或自定义模板

6. 取消事件处理

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要保存修改吗？"
  (nzOnConfirm)="saveChanges()"
  (nzOnCancel)="handleCancel()"
>
  保存
</button>

属性说明：

• nzOnCancel: 点击取消按钮或点击外部区域时触发的事件
  • 类型: EventEmitter<void>
  • 用途：
  • 记录用户取消操作的行为
  • 恢复某些状态
  • 显示提示信息
  • 示例：

    handleCancel() {
    console.log('用户取消了操作');
    this.message.info('已取消操作');
    }

7. 条件确认

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要删除吗？"
  [nzCondition]="item.canDirectDelete"
  (nzOnConfirm)="deleteItem(item)"
>
  删除
</button>

属性说明：

• nzCondition: 是否直接执行确认操作，跳过确认框
  • 类型: boolean
  • 默认值: false
  • true: 直接触发 nzOnConfirm，不显示确认框
  • false: 显示确认框，等待用户确认
  • 使用场景：
  • 某些情况下不需要确认（如已经确认过）
  • 根据权限或配置决定是否需要确认
  • 简化重复操作的流程
  • 示例：

    // 如果是草稿状态，直接删除无需确认
    item.canDirectDelete = item.status === 'draft';

8. 动态标题

<button
  nz-button
  nz-popconfirm
  [nzPopconfirmTitle]="getConfirmTitle(item)"
  (nzOnConfirm)="handleDelete(item)"
>
  删除
</button>

<!-- TypeScript -->
getConfirmTitle(item: any): string {
  if (item.hasChildren) {
    return `确定删除"${item.name}"及其 ${item.childrenCount} 个子项吗？`;
  }
  return `确定删除"${item.name}"吗？`;
}

属性说明：

• [nzPopconfirmTitle]: 使用方括号进行属性绑定
  • 可以绑定组件属性或方法返回值
  • 支持动态内容、插值表达式
  • 可以根据数据状态显示不同的确认文字
  • 适用场景：
  • 显示要删除的项目名称
  • 根据数据状态调整提示文字
  • 显示操作影响的数量

9. 模板内容

<button
  nz-button
  nz-popconfirm
  [nzPopconfirmTitle]="titleTemplate"
  (nzOnConfirm)="batchDelete()"
>
  批量删除
</button>

<ng-template #titleTemplate>
  <div>
    <p style="margin-bottom: 8px;">即将删除以下项目：</p>
    <ul style="margin: 0; padding-left: 20px;">
      <li *ngFor="let item of selectedItems">{{ item.name }}</li>
    </ul>
    <p style="margin-top: 8px; color: #ff4d4f;">此操作不可恢复！</p>
  </div>
</ng-template>

属性说明：

• [nzPopconfirmTitle]: 可以传入 TemplateRef 模板引用
  • 支持复杂的 HTML 结构
  • 可以使用 Angular 指令（ngFor, ngIf 等）
  • 可以添加样式和格式
  • 适用场景：
  • 显示列表信息
  • 多段文字说明
  • 需要特殊格式的内容
  • 注意：内容不宜过于复杂，否则建议使用 Modal

10. 显示状态控制

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要执行吗？"
  [(nzPopconfirmVisible)]="confirmVisible"
  (nzPopconfirmVisibleChange)="onVisibleChange($event)"
  (nzOnConfirm)="handleConfirm()"
>
  操作
</button>

<!-- TypeScript -->
confirmVisible = false;

onVisibleChange(visible: boolean) {
  console.log('确认框状态:', visible);
  if (visible) {
    // 确认框打开时的逻辑
    this.loadConfirmData();
  }
}

showConfirm() {
  this.confirmVisible = true;
}

hideConfirm() {
  this.confirmVisible = false;
}

属性说明：

• nzPopconfirmVisible: 控制确认框的显示/隐藏状态

  • 类型: boolean
  • 可以单向绑定 [nzPopconfirmVisible] 或双向绑定 [(nzPopconfirmVisible)]
  • 用于手动控制确认框的显示

• nzPopconfirmVisibleChange: 确认框显示状态变化时触发的事件

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

11. 自定义样式

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要删除吗？"
  nzPopconfirmOverlayClassName="custom-popconfirm"
  (nzOnConfirm)="deleteItem()"
>
  删除
</button>

<!-- SCSS -->
::ng-deep .custom-popconfirm {
  .ant-popover-inner {
    background: #fff1f0;
    border: 1px solid #ffccc7;
  }

  .ant-popover-message-title {
    color: #cf1322;
    font-weight: 500;
  }

  .ant-btn-primary {
    background: #ff4d4f;
  }
}

属性说明：

• nzPopconfirmOverlayClassName: 为确认框容器添加自定义 CSS 类名

  • 类型: string
  • 可以通过全局样式或组件样式定义该类的样式
  • 需要使用 ::ng-deep 穿透组件样式封装
  • 可自定义：
  • 背景颜色
  • 边框样式
  • 文字颜色和大小
  • 按钮样式
  • 阴影效果

• nzPopconfirmOverlayStyle: 直接设置确认框的内联样式对象

  • 类型: object
  • 示例: [nzPopconfirmOverlayStyle]="{ width: '300px' }"

12. 按钮加载状态

<button
  nz-button
  nz-popconfirm
  nzPopconfirmTitle="确定要提交吗？"
  [nzOkLoading]="isSubmitting"
  (nzOnConfirm)="handleSubmit()"
>
  提交
</button>

<!-- TypeScript -->
isSubmitting = false;

handleSubmirm() {
  this.isSubmitting = true;
  this.service.submit().subscribe({
    next: () => {
      this.message.success('提交成功');
      this.isSubmitting = false;
    },
    error: () => {
      this.message.error('提交失败');
      this.isSubmitting = false;
    }
  });
}

属性说明：

• nzOkLoading: 确认按钮的加载状态
  • 类型: boolean
  • 默认值: false
  • true: 确认按钮显示加载动画，且不可点击
  • 用途：
  • 防止重复提交
  • 显示操作正在进行中
  • 提升用户体验
  • 最佳实践：
  • 异步操作开始时设为 true
  • 操作完成（成功或失败）后设为 false
  • 配合消息提示告知用户结果

13. 完整配置示例

<button
  nz-button
  nzDanger
  nz-popconfirm
  nzPopconfirmTitle="删除后数据将无法恢复，确定要删除吗？"
  nzPopconfirmPlacement="topRight"
  nzOkText="确定删除"
  nzCancelText="取消"
  nzOkDanger
  nzIcon="exclamation-circle"
  [nzCondition]="false"
  [nzOkLoading]="isDeleting"
  nzPopconfirmOverlayClassName="danger-confirm"
  [(nzPopconfirmVisible)]="deleteConfirmVisible"
  (nzPopconfirmVisibleChange)="onDeleteConfirmChange($event)"
  (nzOnConfirm)="handleDelete()"
  (nzOnCancel)="handleDeleteCancel()"
>
  删除数据
</button>

综合说明：
这个示例展示了如何组合使用多个属性来实现完整的确认框功能：

1. 基础配置：

   • nzPopconfirmTitle: 确认提示文字
   • nzPopconfirmPlacement: 位置在右上方

2. 按钮配置：

   • nzOkText / nzCancelText: 自定义按钮文字
   • nzOkDanger: 危险样式的确认按钮
   • nzOkLoading: 加载状态

3. 视觉配置：

   • nzIcon: 警告图标
   • nzPopconfirmOverlayClassName: 自定义样式类

4. 行为配置：

   • nzCondition: 是否跳过确认
   • nzPopconfirmVisible: 显示状态控制

5. 事件处理：

   • nzOnConfirm: 确认回调
   • nzOnCancel: 取消回调
   • nzPopconfirmVisibleChange: 状态变化回调

常用属性速查表

总结

nz-popconfirm 是一个轻量级的确认组件，主要用于：

1. 防止误操作 - 对危险操作进行二次确认
2. 快速决策 - 提供简单的确认/取消选择
3. 上下文关联 - 就近显示，不打断操作流程
4. 用户友好 - 给用户反悔的机会

它适合用于删除、禁用、清空等需要确认但不需要复杂交互的操作场景。