xiaoye-components

Appearance

Message 消息提示 ​

Message 提供函数式消息提示体验，适合承接"操作已完成""同步中""保存失败"这类短反馈。它不是页面内常驻内容，也不像 Dialog 那样阻断流程，而是在任意位置直接调用即可出现。

当前实现导出的是函数式入口 XyMessage，完整安装组件库后也会自动注入 $message。如果你希望统一消息位置、关闭按钮、暂停策略或数量上限，可以在 Config Provider 全局配置 上配置 message 默认值。

基础用法 ​

最简单的调用方式就是直接传字符串，它会使用默认 info 类型和顶部居中 placement。

基础用法全局提示

点击按钮触发操作，点击后会在页面顶部显示消息提示。

不同类型 ​

XyMessage.success()、warning()、error() 这类快捷方法适合在业务代码里直接表达语义，不需要额外再传 type。

手动关闭 ​

把 duration 设为 0 可以让消息保持常驻，再通过 showClose 交给用户主动关闭。

不同位置 ​

placement 支持六个值，适合根据页面布局和工作台壳子决定提示从哪里进入。

render 富内容与 groupKey ​

render 适合承接更复杂的提示结构，groupKey 可以让富内容消息也具备稳定的合并键。

同 groupKey 会合并为一条消息

点击行为与关闭原因 ​

现在支持 onClick、onClose、closeOnClick 和 closeOnPressEscape，方便把消息反馈接回业务链路。

外观细化 ​

plain、自定义 icon、关闭按钮和移动端宽度都补了一轮，提供完整的消息提示体验。

关闭前拦截 ​

beforeClose(done, ctx) 适合在关闭前补异步校验、埋点或额外确认。

句柄与状态快照 ​

handle.update() 适合实时更新消息内容；getState() 和过滤版 closeAll() 适合消息中心、工作台壳子或联动调试。

App Context 与 withContext ​

当你需要把消息能力继续传给 composable、store 或 service 时，可以用 withContext(appContext) 固定当前 app 的调用入口。通过插件注入拿到的 $message.withContext() 则会默认继承当前 app。

单个 ConfigProvider 下两种方式都会继承同一套默认消息配置；多 app 并存时建议显式绑定。
withContext(appContext) 适合把消息能力继续传给 composable、store 或 service 层。
$message.withContext() 会默认继承当前 app，可继续向业务模块透传。

上下文说明 ​

如果你通过全量安装拿到的是 $message，它会自动继承当前 app 的上下文。
如果你是局部按需导入 XyMessage，并且页面里存在多套 app 或你希望显式继承某个 app 的 ConfigProvider.message，推荐使用 withContext(appContext)；也可以继续把 appContext 作为第二个参数传入：

ts
import { getCurrentInstance } from "vue";
import { XyMessage } from "xiaoye-components";

const instance = getCurrentInstance();
const scopedMessage = XyMessage.withContext(instance?.appContext ?? null);

scopedMessage({
  message: "局部导入时也能继承当前 app 上下文"
});

你也可以直接继续透传 $message.withContext()，让业务模块在不知道组件实例的情况下，仍然显式复用当前 app 的消息上下文。

如果同一页面里存在多套 ConfigProvider.message，但你又直接调用顶层 XyMessage(...) 且没有传 appContext，当前实现会告警并回退到默认配置，而不是猜测应该继承哪一套上下文。

HTML 内容 ​

dangerouslyUseHTMLString 只适合受信任的静态内容，不要直接拼接用户输入。

行为说明 ​

  • XyMessage 支持 string、VNode、() => VNode、render 渲染函数和完整配置对象。
  • 默认自动关闭时长为 3000ms，默认支持悬停暂停；也可以进一步打开 pauseOnFocus 和 pauseOnPageHidden。
  • grouping 当前会优先使用 groupKey 做合并；如果没有 groupKey，则只对字符串或数字消息做内容合并。
  • closeOnClick、closeOnPressEscape 和 beforeClose 共同构成消息关闭策略，onClose 会带上最终关闭原因。
  • appendTo 支持 HTMLElement 或选择器字符串，适合微前端壳子和局部宿主。
  • max / ConfigProvider.message.max 控制单个宿主内同一 placement 的并发消息数量；maxByPlacement 可给不同位置设置独立上限。
  • $message 会自动继承当前 app 的默认配置；$message.withContext() 默认继续绑定当前 app。
  • XyMessage.withContext(appContext) 适合在多 app、局部按需导入或 service 层桥接调用时显式指定配置来源。
  • getState() 返回的是当前消息实例快照，不包含回调和复杂渲染函数本体。

命名对照 ​

  • Message 当前没有模板组件入口，公开合同主要就是 XyMessage() / $message() 这一套函数式 API。
  • 因此这里看到的 customClass、showClose、groupKey、closeOnPressEscape 都是 service / options 层的 camelCase 字段，不存在对应的模板 kebab-case 属性表。
  • 如果你在迁移页面样式或封装通知层时，同时处理 Notification 和 Message，要注意两者虽然都能定制 class，但 Message 只存在函数式参数，Notification 则同时有模板属性和 service options 两套命名。

API ​

基础签名 ​

ts
import { XyMessage } from "xiaoye-components";

const handle = XyMessage({
  message: "保存成功",
  type: "success",
  placement: "top-right",
  showClose: true,
  onClose(ctx) {
    console.log(ctx.reason);
  }
});

handle.update({
  message: "已同步到草稿箱",
  type: "primary",
  icon: "mdi:check-decagram-outline"
});

handle.close("programmatic");

const snapshot = XyMessage.getState({
  placement: "top-right"
});

XyMessage.closeAll({
  placement: "top-right",
  type: "success"
});

XyMessageService 是 XyMessage 的别名，函数签名和快捷方法完全一致。

Message Options ​

字段说明类型默认值
message消息内容，支持字符串、VNode 或渲染函数MessageContent''
render自定义渲染函数，优先级高于 messageMessageOptions["render"]undefined
type消息类型MessageType'info'
plain是否使用更轻的外观booleanfalse
icon自定义图标名string按 type 自动推导
showIcon是否显示图标booleantrue
dangerouslyUseHTMLString是否把字符串按 HTML 渲染booleanfalse
customClass自定义 classstring''
duration自动关闭时长，单位毫秒，0 表示不自动关闭number3000
showClose是否显示关闭按钮booleanfalse
offset第一条消息距视口的偏移number16
placement消息出现位置MessagePlacement'top'
appendTo自定义挂载容器string | HTMLElementdocument.body
grouping是否启用消息合并booleanfalse
groupKey显式指定合并键，适合 VNode / render 消息stringundefined
repeatNum当前重复次数，通常由内部合并逻辑维护number1
max当前宿主下该 placement 的并发消息上限numberundefined
zIndex自定义层级number自动递增
closeOnClick点击消息主体时是否关闭booleanfalse
closeOnPressEscape按 Esc 时是否关闭booleantrue
pauseOnHover悬停时是否暂停自动关闭booleantrue
pauseOnFocus聚焦消息内部元素时是否暂停自动关闭booleanfalse
pauseOnPageHidden页面隐藏时是否暂停自动关闭booleanfalse
resetOnRepeat合并重复消息时是否重置自动关闭计时booleantrue
transition自定义过渡名称string'xy-message-fade'
beforeClose关闭前拦截MessageBeforeCloseFnundefined
onClick点击消息时触发MessageClickHandlerundefined
onClose消息开始关闭时触发，带关闭原因MessageLifecycleHandlerundefined
onClosed消息完全关闭后触发，带关闭原因MessageLifecycleHandlerundefined

Message Close Reason ​

值说明
manual点击关闭按钮
auto自动关闭计时器触发
programmatic通过句柄主动关闭
click点击消息主体关闭
escape按 Esc 关闭
close-all通过批量关闭 API 关闭

Message Handle ​

字段说明类型
id当前消息实例 idstring
close(reason?)主动关闭当前消息，可显式指定关闭原因MessageHandler["close"]
update(patch)更新当前消息的文案、类型、位置、交互策略等配置MessageHandler["update"]

Message Snapshot ​

消息状态快照类型为 MessageSnapshot。

Message Close Filter ​

批量关闭和状态过滤条件类型为 MessageCloseFilter。

快捷方法 ​

方法说明类型
XyMessage.primary(options)打开 primary 类型消息Message["primary"]
XyMessage.success(options)打开 success 类型消息Message["success"]
XyMessage.info(options)打开 info 类型消息Message["info"]
XyMessage.warning(options)打开 warning 类型消息Message["warning"]
XyMessage.error(options)打开 error 类型消息Message["error"]
XyMessage.withContext(appContext?)返回绑定指定 appContext 的消息 API；对 $message.withContext() 来说，缺省参数会继承当前 appMessage["withContext"]
XyMessage.closeAll(typeOrFilter?)关闭全部消息，支持按类型或过滤对象批量关闭Message["closeAll"]
XyMessage.closeAllByPlacement(placement)按 placement 批量关闭消息Message["closeAllByPlacement"]
XyMessage.getState(filter?)获取当前消息实例快照Message["getState"]

ConfigProvider.message ​

ConfigProvider.message 的类型为 MessageGlobalConfig。