> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/message.html

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

# Message 消息提示

以短暂提示反馈操作结果。需要标题、详细说明或后续操作时使用 [Notification](https://ifhover.github.io/leaf-ui/components/notification.md)。


## 基础用法

在应用入口放置 [ConfigProvider](https://ifhover.github.io/leaf-ui/components/config-provider.md)，再在子组件中调用 `useMessage()`。已有该配置时无需重复添加。

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

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


显示消息

basic.tsx

复制代码

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

export function MessageBasic() {
  const { message } = useMessage();
  return <Button onClick={() => message.info('更改已保存')}>显示消息</Button>;
}
```

展开代码


## 示例

### 状态提示

通过快捷方法显示成功、信息、警告和危险提示。


信息成功警告失败

states.tsx

复制代码

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

export function MessageStates() {
  const { message } = useMessage();
  return (
    <Space wrap>
      <Button onClick={() => message.info('有一条新的评论')}>信息</Button>
      <Button onClick={() => message.success('更改已保存')}>成功</Button>
      <Button onClick={() => message.warning('还有未保存的更改')}>警告</Button>
      <Button onClick={() => message.danger('保存失败，请重试')}>失败</Button>
    </Space>
  );
}
```

展开代码

### 手动关闭

设置 `duration: 0` 持续显示，配合 `closable: true` 提供关闭按钮。


显示持续消息

manual.tsx

复制代码

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

export function MessageManual() {
  const { message } = useMessage();
  return (
    <Button
      onClick={() =>
        message.open({ content: '此消息会保留到手动关闭', duration: 0, closable: true })
      }
    >
      显示持续消息
    </Button>
  );
}
```

展开代码

[](#)
### 异步更新

使用 `loading()` 返回的 `key`，将加载消息替换为操作结果。相同 `key` 会替换整组配置，而不是合并旧配置，并按新的时长重新计时。


异步保存

async.tsx

复制代码

```tsx lineNumbers file="../../src/examples/message/async.tsx"
import { Button, useMessage } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function MessageAsync() {
  const { message } = useMessage();
  const [saving, setSaving] = useState(false);
  async function save() {
    setSaving(true);
    const key = message.loading('正在保存');
    await new Promise((resolve) => setTimeout(resolve, 1200));
    message.open({ key, type: 'success', content: '保存成功' });
    setSaving(false);
  }
  return (
    <Button loading={saving} onClick={save}>
      异步保存
    </Button>
  );
}
```

展开代码

### 跨组件共享

下面两个按钮来自不同子组件。同一入口下的组件共享消息队列，可以用相同 `key` 更新消息。嵌套的 `ConfigProvider` 沿用同一队列，每条消息使用调用组件所在区域的主题和语言。


开始处理更新结果

shared.tsx

复制代码

```tsx lineNumbers file="../../src/examples/message/shared.tsx"
import { Button, Space, useMessage } from '@ifhover/leaf-ui';
import { useId } from 'react';

function StartAction({ messageKey }: { messageKey: string }) {
  const { message } = useMessage();
  return (
    <Button onClick={() => message.open({ key: messageKey, type: 'loading', content: '正在处理' })}>
      开始处理
    </Button>
  );
}

function ResultAction({ messageKey }: { messageKey: string }) {
  const { message } = useMessage();
  return (
    <Button onClick={() => message.open({ key: messageKey, type: 'success', content: '处理完成' })}>
      更新结果
    </Button>
  );
}

export function MessageShared() {
  const messageKey = useId();
  return (
    <Space wrap>
      <StartAction messageKey={messageKey} />
      <ResultAction messageKey={messageKey} />
    </Space>
  );
}
```

展开代码

调用组件卸载后，已有消息继续保留，异步任务仍可更新结果；入口 provider 卸载后，其消息和计时器一起清理。


## API

### Message API

直接渲染时，由应用响应 `onClose` 并设置 `open=false`；`afterClose` 在离场动画结束后触发。

| 属性           | 类型                                     | 默认值                | 说明                                       |
| ------------ | -------------------------------------- | ------------------ | ---------------------------------------- |
| `open`       | `boolean`                              | 必填                 | 受控显示状态                                   |
| `content`    | `ReactNode`                            | 必填                 | 消息内容                                     |
| `type`       | `FeedbackType \| 'error' \| 'loading'` | `'info'`           | 消息类型；`error` 为兼容别名                       |
| `duration`   | `number`                               | 普通消息 3；loading 为 0 | 自动关闭的秒数；0 或负数不自动关闭。悬停或焦点进入时暂停，离开后继续剩余时间。 |
| `closable`   | `boolean`                              | `false`            | 关闭按钮                                     |
| `onClose`    | `() => void`                           | —                  | 关闭请求时调用；声明式 Message 须由应用将 open 设为 false。 |
| `afterClose` | `() => void`                           | —                  | 关闭动画结束、内容卸载后调用，不代替 onClose 更新受控值。        |

### useMessage API

获取当前入口托管的消息队列。

| 属性        | 类型                          | 默认值 | 说明          |
| --------- | --------------------------- | --- | ----------- |
| `message` | [`MessageApi`](#messageapi) | —   | 调用入口托管的消息队列 |

### MessageApi

`close(key)` 仅关闭指定消息；`close()` 关闭共享队列中的全部消息。

| 属性        | 类型                                                           | 默认值 | 说明                                               |
| --------- | ------------------------------------------------------------ | --- | ------------------------------------------------ |
| `open`    | `(options: `[`MessageOptions`](#messageoptions)`) => string` | 必填  | 打开或按 key 替换消息，返回该消息的 key。                        |
| `success` | `(content: ReactNode, duration?: number) => string`          | 必填  | 快捷显示对应类型；`error` 保留为兼容方法                         |
| `info`    | `(content: ReactNode, duration?: number) => string`          | 必填  | 快捷显示对应类型；`error` 保留为兼容方法                         |
| `warning` | `(content: ReactNode, duration?: number) => string`          | 必填  | 快捷显示对应类型；`error` 保留为兼容方法                         |
| `danger`  | `(content: ReactNode, duration?: number) => string`          | 必填  | 快捷显示对应类型；`error` 保留为兼容方法                         |
| `error`   | `(content: ReactNode, duration?: number) => string`          | 必填  | 请求失败时显示的内容，替代数据行。                                |
| `loading` | `(content: ReactNode) => string`                             | 必填  | 显示不自动关闭的加载消息，返回 key；应用负责更新或关闭。                   |
| `close`   | `(key?: string) => void`                                     | 必填  | 关闭指定 key；不传 key 会关闭同一 Provider 内的全部消息，不限于当前调用组件。 |

### MessageOptions

鼠标停留或焦点进入消息时暂停计时，恢复后按剩余时长继续。

| 属性         | 类型                                     | 默认值                | 说明                                                |
| ---------- | -------------------------------------- | ------------------ | ------------------------------------------------- |
| `content`  | `ReactNode`                            | 必填                 | 消息内容                                              |
| `type`     | `FeedbackType \| 'error' \| 'loading'` | `'info'`           | 消息类型；`error` 为兼容别名                                |
| `duration` | `number`                               | 普通消息 3；loading 为 0 | 自动关闭的秒数；0 或负数不自动关闭。悬停或焦点进入时暂停，离开后继续剩余时间。          |
| `closable` | `boolean`                              | `false`            | 展示关闭按钮                                            |
| `key`      | `string`                               | 自动生成               | 同一 Provider 内的唯一标识；重复 open 会替换该条消息并重启关闭计时，不追加新消息。 |
| `onClose`  | `() => void`                           | —                  | 关闭请求时调用；声明式 Message 须由应用将 open 设为 false。          |

### MessageProvider API

单独使用消息时，可用 `MessageProvider` 代替 `ConfigProvider`；显式添加它也可建立独立队列。不同 React 应用及 SSR 请求各自拥有队列。

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

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

| 属性         | 类型          | 默认值 | 说明                                                          |
| ---------- | ----------- | --- | ----------------------------------------------------------- |
| `children` | `ReactNode` | —   | 共享此独立消息队列的内容；ConfigProvider 已提供队列，嵌套 ConfigProvider 复用上层队列。 |
