> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/confirm.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Confirm 确认框

在执行重要操作前征求确认，通过 API 调用并等待用户的选择。

## 入口配置一次

在应用入口使用 `ConfigProvider`，子组件直接调用 `useConfirm()`。确认框沿用调用区域的主题和语言，无需管理显示状态。

```tsx
import { ConfigProvider } from '@ifhover/leaf-ui';

export function Root() {
  return <ConfigProvider><App /></ConfigProvider>;
}
```

## 异步确认


删除项目

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/confirm/basic.tsx"
import { Button, Space, useConfirm, useMessage } from '@ifhover/leaf-ui';

export function ConfirmBasic() {
  const { confirm } = useConfirm();
  const { message } = useMessage();
  return (
    <Space direction="vertical" align="center">
      <Button
        danger
        variant="outline"
        onClick={async () => {
          const accepted = await confirm({
            title: '删除项目',
            children: '删除后无法恢复，请确认是否继续。',
            type: 'danger',
            onConfirm: () => new Promise((resolve) => setTimeout(resolve, 900)),
          });
          if (accepted) message.success('项目已删除');
        }}
      >
        删除项目
      </Button>
    </Space>
  );
}
```

展开代码

## useConfirm API

返回的对象类型是 [`ConfirmApi`](#confirmapi)。

| 属性        | 类型                                                                 | 默认值 | 说明                           |
| --------- | ------------------------------------------------------------------ | --- | ---------------------------- |
| `confirm` | [`(options: ConfirmOptions) => Promise<boolean>`](#confirmoptions) | —   | 确认返回 true；取消或调用区域卸载返回 false。 |

## ConfirmOptions

| 属性                   | 类型                                                                                         | 默认值                     | 说明                                |
| -------------------- | ------------------------------------------------------------------------------------------ | ----------------------- | --------------------------------- |
| `initialFocus`       | `RefObject<HTMLElement \| null> \| (() => HTMLElement \| null)`                            | —                       | 指定打开后的初始焦点。                       |
| `returnFocus`        | `boolean \| RefObject<HTMLElement \| null> \| (() => HTMLElement \| null)`                 | —                       | 关闭后返回原焦点，也可指定目标或设为 false。         |
| `title`              | `ReactNode`                                                                                | —                       | 确认标题。                             |
| `children`           | `ReactNode`                                                                                | —                       | 简短说明本次操作的影响。                      |
| `icon`               | `ReactNode`                                                                                | —                       | 正文左侧的状态图标；传入 null 隐藏图标。           |
| `type`               | `'default' \| 'danger' \| 'success' \| 'warning' \| 'info'`                                | `'default'`             | 状态图标与颜色；仅 danger 改变确定按钮颜色。        |
| `showCancel`         | `boolean`                                                                                  | success 为 false，其余 true | 是否展示取消按钮。                         |
| `confirmText`        | `ReactNode`                                                                                | 语言默认值                   | 确认按钮文字。                           |
| `cancelText`         | `ReactNode`                                                                                | 语言默认值                   | 取消按钮文字。                           |
| `confirmButtonProps` | [`ButtonProps`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/button.md#button-api) | —                       | 确认按钮属性。                           |
| `cancelButtonProps`  | [`ButtonProps`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/button.md#button-api) | —                       | 取消按钮属性。                           |
| `onConfirm`          | `() => void \| Promise<void>`                                                              | —                       | 确认操作；等待 Promise 成功后关闭，失败时保留并显示错误。 |
| `onCancel`           | `() => void`                                                                               | —                       | 取消时调用。                            |
| `width`              | `number \| string`                                                                         | `420`                   | 确认框宽度，数字为像素。                      |
| `closable`           | `boolean`                                                                                  | `false`                 | 是否显示右上角关闭按钮。                      |
| `maskClosable`       | `boolean`                                                                                  | `false`                 | 点击遮罩时取消。                          |
| `keyboard`           | `boolean`                                                                                  | `true`                  | 按 Escape 时取消。                     |
| `className`          | `string`                                                                                   | —                       | 确认框类名。                            |
| `style`              | `CSSProperties`                                                                            | —                       | 确认框样式。                            |

## ConfirmProvider API

未使用 `ConfigProvider` 时，在入口放置 `ConfirmProvider`。显式添加它也可以为某个区域建立独立的确认队列。

```tsx
import { ConfirmProvider } from '@ifhover/leaf-ui';

export function Root() {
  return <ConfirmProvider><App /></ConfirmProvider>;
}
```

| 属性         | 类型          | 默认值 | 说明          |
| ---------- | ----------- | --- | ----------- |
| `children` | `ReactNode` | —   | 共用此确认队列的组件。 |

## ConfirmApi

| 属性        | 类型                                                                     | 默认值 | 说明              |
| --------- | ---------------------------------------------------------------------- | --- | --------------- |
| `confirm` | `(options: `[`ConfirmOptions`](#confirmoptions)`) => Promise<boolean>` | —   | 必需。发起一次确认并等待选择。 |

## 类型

组装配置时可导入相关类型。

```ts
import type { ConfirmOptions, ConfirmApi, ConfirmProviderProps } from '@ifhover/leaf-ui';
```

## 使用说明

`useConfirm()` 返回 `{ confirm }`。同一入口下的请求依次展示，上一个确认框完成关闭后再显示下一个。异步确认期间展示加载状态并阻止重复操作；失败时保留确认框并显示错误，可再次尝试。

default 不展示状态图标；info、warning、success、danger 展示对应图标。图标位于正文左侧，没有背景底座，危险提示使用红色感叹号。success 默认隐藏取消按钮，可通过 `showCancel` 调整。

Confirm 用于简短的确认提示，只通过 API 调用。包含表单、多步骤或复杂内容的操作使用 [Modal](https://ifhover.github.io/leaf-ui/v/0.6.0/components/modal.md)。