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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/message.md.

Message 消息提示

以短暂提示反馈操作结果。需要标题、详细说明或后续操作时使用 Notification。

基础用法

在应用入口放置 ConfigProvider,再在子组件中调用 useMessage()。已有该配置时无需重复添加。

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

export function Root() {
  return <ConfigProvider><App /></ConfigProvider>;
}
basic.tsx
import { Button, useMessage } from '@ifhover/leaf-ui';

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

示例

状态提示

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

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
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
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
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 在离场动画结束后触发。

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

useMessage API

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

属性类型默认值说明
messageMessageApi—调用入口托管的消息队列

MessageApi

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

属性类型默认值说明
open(options: 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

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

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

MessageProvider API

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

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

export function Root() {
  return <MessageProvider><App /></MessageProvider>;
}
属性类型默认值说明
childrenReactNode—共享此独立消息队列的内容;ConfigProvider 已提供队列,嵌套 ConfigProvider 复用上层队列。