前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载Naive UI 的 Message轻提示组件用于在浏览器顶部或用户指定的其他位置向用户弹出短暂停留的操作反馈信息是表单提交成功、接口报错、异步加载等场景中最常用的反馈组件之一。本文以 src/message/demos/enUS/index.demo-entry.md 为核心脉络结合 MessageProvider 源码 与官方示例完整讲解 Provider 的挂载前置条件、全部 Props 与注入 API 的用法、MessageReactive的响应式更新能力以及两种在setup之外调用 Message 的实战方案帮助你直接在项目中落地一套可复用的消息提示机制。使用前置条件useMessage必须在n-message-provider内部调用Message 的 API 不是全局静态函数而是通过 Vue 的provide / inject机制注入到组件树中的。因此在调用useMessage()之前必须先把对应的组件放在n-message-provider内部这是官方文档在开篇就强调的两条规则想要用useMessage使用 Message需要把调用其方法的组件放在n-message-provider内部并通过useMessage获取 API想在setup之外使用 Message 的用法请参考本文末尾的 Q A 章节。官方给出的最小挂载结构如下!-- App.vue -- n-message-provider content / /n-message-providerimport { useMessage } from naive-ui import { defineComponent } from vue // content export default defineComponent({ setup() { const message useMessage() return { warning() { message.warning(...) } } } })从源码层面看这条规则是强制的而不是约定俗成。use-message.ts 的实现如下export function useMessage(): MessageApiInjection { const api inject(messageApiInjectionKey, null) if (api null) { throwError( use-message, No outer n-message-provider / founded. See prerequisite in ... ) } return api }也就是说useMessage本质上是inject(messageApiInjectionKey)的一层封装如果组件树中不存在n-message-providerinject拿到的是null会直接抛出 No outern-message-provider /founded 的错误。注入的 key 定义在 context.ts 中export const messageApiInjectionKey createInjectionKeyMessageApiInjection(n-message-api) export const messageProviderInjectionKey createInjectionKey{ props: MessageProviderSetupProps mergedClsPrefixRef: Refstring }(n-message-provider)值得注意Provider 同时向子树注入了两个 key——n-message-api供useMessage取用与n-message-provider内部传递 props 与合并后的类名前缀mergedClsPrefix供渲染层使用。MessageProvider Props 全解析n-message-provider承担着「统一管理消息列表、定义全局默认行为」的职责。下表是官方文档列出的全部 Props注意这些配置是作用于该 Provider 下所有消息的默认值单条消息仍可通过第二个参数options覆盖NameTypeDefaultDescriptionVersionclosablebooleanfalse是否在所有消息上显示关闭图标。container-classstringundefined消息容器的类名。2.36.0container-stylestring \| CSSPropertiesundefined消息容器的样式。durationnumber3000所有消息的默认持续时间毫秒。keep-alive-on-hoverbooleanfalse鼠标悬停时是否暂停计时保留所有消息。maxnumberundefined限制显示的消息数量上限。placementtop \| top-left \| top-right \| bottom \| bottom-left \| bottom-righttop所有消息的弹出位置。tostring \| HTMLElementbody消息容器的挂载节点。这些 Props 在 MessageProvider.tsx 中有完全对应的定义例如duration默认3000、placement默认topexport const messageProviderProps { ...(useTheme.props as ThemePropsMessageTheme, MessageThemeOverrides), to: [String, Object] as PropTypestring | HTMLElement, duration: { type: Number, default: 3000 }, keepAliveOnHover: Boolean, max: Number, placement: { type: String as PropType | top | top-left | top-right | bottom | bottom-left | bottom-right , default: top }, closable: Boolean, containerClass: String, containerStyle: [String, Object] as PropTypestring | CSSProperties }其中...useTheme.props说明 Provider 还继承了 Naive UI 主题体系的theme/theme-overrides等主题相关 Props因此你可以通过n-config-provider或直接传theme让消息组件跟随全局明暗主题切换对应官方 Demo 中的 about-theme.vue。关键 Props 的底层行为placement与to在 Provider 的render中消息容器通过Teleport to{this.to ?? body}被传送到body默认或其他节点并给容器 div 追加${mergedClsPrefix}-message-container--${placement}类来控制六个方位的定位样式。默认弹出位置是浏览器顶部top这也是官方对 Message 的定位描述 Oracle from the top (always) of the browser。max队列上限在create内部当已有消息数达到max时会先messageListRef.value.shift()移除最旧的一条再push新消息——即超出上限时最老的消息被顶掉这与部分组件库「丢弃新消息」的策略不同使用前需留意。keepAliveOnHover其实现位于 MessageEnvironment.tsx鼠标移入消息时clearTimeout暂停销毁计时移出时重新setHideTimeout。只有当该值为true时才会把onMouseenter/onMouseleave事件绑到消息 DOM 上。动态切换 placement 的官方示例placement.demo.vue 演示了如何用ref动态切换消息位置——把placement绑到一个响应式变量上点击不同按钮时既改变 Provider 的placement又同时弹出一条消息以直观预览效果n-message-provider :placementplacementRef Buttons change-placementchangePlacement / /n-message-provider使用container-class/container-style定制容器从 2.36.0 开始container-class可以给消息容器追加自定义类名container-style则支持传入string或CSSProperties对象直接覆盖容器样式。两者最终都会应用到 MessageProvider.tsx 中渲染的容器 div 上可用于调整容器整体宽度、层级或边距而不必逐条修改消息样式。命令式 API六种消息类型与destroyAll通过useMessage()拿到的 API 是MessageApiInjection对外导出类型名为MessageApi官方文档的注入方法表如下NameTypeDescriptionVersiondestroyAll() void销毁所有弹窗消息。create(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 default 类型消息。2.25.7error(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 error 类型消息。info(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 info 类型消息。loading(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 loading 类型消息。success(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 success 类型消息。warning(content: string \| (() VNodeChild), option?: MessageOption) MessageReactive创建 warning 类型消息。content既可以是普通字符串也可以传一个返回VNodeChild的函数从而渲染自定义内容。create方法比较特殊它需要配合options.type指定类型默认是default——这一点在 MessageProvider.tsx 的 API 实现中可以看到create会先给 options 补上type: default而info/success/warning/error/loading则是把对应 type 合并进 options 后统一调用内部的create。destroyAll的实现则遍历当前存活的messageRefs逐一调用每个消息实例的hide()触发渐隐离开动画后由handleAfterLeave从列表中移除MessageProvider.tsx。五种消息类型的完整示例basic.demo.vue 一次性演示了info / error / warning / success / loading五种类型的用法其中 info 消息还传入了keepAliveOnHover: trueconst message useMessage() function info() { message.info(I don\t know why nobody told you how to unfold your love, { keepAliveOnHover: true }) } function error() { message.error(Once upon a time you dressed so fine) } function warning() { message.warning(How many roads must a man walk down) } function success() { message.success(\Cause you walked hand in hand With another man in my place) } function loading() { message.loading(If I were you, I will realize that I love you more than any other guy) }注意message.info(...)这类调用每次都会新建一条消息如果希望多次点击只保留一条需要借助MessageReactive的响应式能力见下文或先destroy()旧消息。MessageOption单条消息的可选配置MessageOption即MessageOptions用于控制单条消息的行为官方文档的属性表如下NameTypeDescriptionVersionclosableboolean是否显示关闭图标。durationnumber消息持续时间毫秒。icon() VNodeChild消息图标。keepAliveOnHoverboolean鼠标悬停时是否保留消息。renderMessageRenderMessage整个消息的渲染函数。2.24.0showIconboolean是否显示图标。2.25.7spinProps{ strokeWidth?: number, stroke?: string, scale?: number, radius?: number }Loading 图标属性。2.44.0typeinfo \| success \| warning \| error \| loading \| default消息类型默认default。2.25.7onAfterLeave() void消息消失后的回调。onClose() void点击关闭图标时的回调。onLeave() void消息开始消失时的回调。以上字段在 types.ts 的MessageOptions接口中一一对应。几个典型用法duration官方 timing.demo.vue 展示了单条覆盖默认时长——message.info(..., { duration: 5000 })会让该消息停留 5 秒。传入duration: 0时消息不会自动消失只能手动关闭见 MessageEnvironment.tsx只有duration为真值时才setTimeout。closableclosable.demo.vue 演示closable: true配合duration: 5000让用户点击右上角关闭按钮提前关闭消息点击关闭会依次触发onClose回调与内部的hide()。icon / showIcon / spinPropsicon用渲染函数替换默认图标showIcon: false隐藏图标对应 no-icon.demo.vueloading类型的旋转图标从 2.44.0 起可通过spinProps微调描边宽度strokeWidth、颜色stroke、缩放scale与圆角半径radius。render用自定义渲染函数完全接管整条消息的展示详见下文「自定义渲染」。MessageRenderMessage用 render 完全自定义消息外观从 2.24.0 开始MessageOption.render支持完全接管消息的渲染官方给出的类型定义如下type MessageRenderMessage (props: { content?: string | number | (() VNodeChild) icon?: () VNodeChild closable: boolean type: info | success | warning | error | loading onClose?: () void }) VNodeChildcustomize-message.demo.vue 提供了一个经典场景用户希望用n-alert的形态来展示消息。实现方式是把NAlert渲染进render函数同时保持原有消息的类型、可关闭性与关闭回调import type { MessageRenderMessage } from naive-ui import { NAlert, useMessage } from naive-ui import { h } from vue const renderMessage: MessageRenderMessage (props) { const { type } props return h( NAlert, { closable: props.closable, onClose: props.onClose, type: type loading ? default : type, title: Lorem ipsum dolor sit amet, style: { boxShadow: var(--n-box-shadow), maxWidth: calc(100vw - 32px), width: 480px } }, { default: () props.content } ) } const { error } useMessage() function handleClick() { error(Lorem ipsum dolor sit amet, consectetur adipiscing elit, { render: renderMessage, closable: true }) }技巧点由于NAlert没有loading类型示例把type loading映射为default同时通过var(--n-box-shadow)复用了 Naive UI 主题变量保证自定义消息与主题风格统一。render会把closable、onClose等由 Provider 管理的行为一并传入因此关闭按钮、自动关闭的联动依然有效。MessageReactive响应式消息对象与手动控制useMessage()的每个方法都会返回一个MessageReactive对象官方文档定义的属性与方法如下MessageReactive PropertiesNameTypeDescriptionVersionclosableboolean是否显示关闭图标。contentstring \| (() VNodeChild)消息内容。destroy() void消息销毁方法。icon() VNodeChild消息图标。keepAliveOnHoverboolean鼠标悬停时是否保留消息。showIconboolean是否显示图标。2.25.7typeinfo \| success \| warning \| error \| loading \| default消息类型默认default。2.25.7onAfterLeave() void消息消失后回调。onLeave() void消息开始消失时回调。MessageReactive MethodsNameTypeDescriptiondestroy()消息销毁方法。MessageReactive是一个reactive对象在 MessageProvider.tsx 的create中它由reactive({ ...options, content, key, destroy })创建其中destroy会调用对应内部消息实例的hide()。由于它是响应式的修改它的属性可以实时反映到正在展示的消息上。场景一手动关闭消息manually-close.demo.vue 用duration: 0让消息永久停留再通过destroy()手动销毁let messageReactive: MessageReactive | null null function removeMessage() { if (messageReactive) { messageReactive.destroy() messageReactive null } } function createMessage() { if (!messageReactive) { messageReactive message.info(3 * 3 * 4 * 4 * ?, { duration: 0 }) } } onBeforeUnmount(removeMessage)示例还在onBeforeUnmount中调用removeMessage避免组件卸载后残留常驻消息——这是使用duration: 0常驻消息时必须养成的清理习惯。场景二动态修改已存在消息的内容与类型modify-content.demo.vue 充分利用了MessageReactive的响应式特性创建消息后直接改写msgReactive.content实现内容更新改写msgReactive.type实现类型切换如从success切到loadingconst types: MessageType[] [success, info, warning, error, loading] let msgReactive: MessageReactive | null null function plus() { if (msgReactive) { countRef.value msgReactive.content ${countRef.value} } } function changeType() { if (msgReactive) { typeIndex (typeIndex 1) % types.length msgReactive.type types[typeIndex] } } function createMessage() { msgReactive message.create(${countRef.value}, { type: types[typeIndex], duration: 10000 }) }这个模式非常适合「上传进度」「轮询状态」等需要原地更新反馈的场景——不必销毁重建界面不会闪烁动画连续。Q A如何在 setup 之外使用 Message官方文档给出了两种在setup之外调用 Message 的方案两者有明显取舍。Option 1使用createDiscreteApi官方推荐方案是使用离散 APIcreateDiscreteApi。它会独立于组件树创建一个可控的 Provider 实例让你在任何模块路由守卫、工具函数、普通 JS 文件中直接调用message.success(...)。用法上需注意其注意事项caveat并且官方特别提醒最好不要在同一个应用里同时混用useMessage与createDiscreteApi因为两者是两套独立的实例体系混用可能导致 API 行为不一致。createDiscreteApi的选项接口定义在 src/discrete/src/interface.ts 中messageProviderProps作为独立选项传入说明离散 API 完整支持n-message-provider的全部 Propsplacement、max、duration等export interface DiscreteApiOptions { configProviderProps?: MaybeRefConfigProviderProps messageProviderProps?: MaybeRefMessageProviderProps dialogProviderProps?: MaybeRefDialogProviderProps notificationProviderProps?: MaybeRefNotificationProviderProps loadingBarProviderProps?: MaybeRefLoadingBarProviderProps modalProviderProps?: MaybeRefModalProviderProps }Option 2把useMessage返回值挂到 window 上第二种方式无需引入离散 API在顶层组件的setup中把useMessage()的返回值挂载到window之后在任何 JS 模块中通过window.$message调用。官方给出的完整示例!-- App.vue -- n-message-provider content / /n-message-provider!-- content.vue -- template.../template script import { useMessage } from naive-ui import { defineComponent } from vue // content export default defineComponent({ setup() { window.$message useMessage() } }) /script// xxx.js export function handler() { // You need to ensure that window.$message message has been executed in setup window.$message.success( Cause you walked hand in hand With another man in my place ) }官方对这种方式给出了两条硬性约束用 warning 强调必须在顶层 setup中执行挂载在调用window.$message之前必须确保message已经挂载成功即 Provider 已完成渲染注入。否则window.$message为undefined调用时会直接报错。相比 Option 1这种方式更轻量、与现有主题完全一致但对「挂载时序」有严格要求适合在应用启动阶段固定挂载一次的架构而createDiscreteApi则更独立、时序更可控。其他官方 Demo 速览index.demo-entry.md的 Demos 区还列出了一系列专项示例均可在 src/message/demos/enUS 下找到对应文件Demo 文件主题icon.demo.vue自定义消息图标multiple-line.demo.vue多行文本消息no-icon.demo.vue通过showIcon: false隐藏图标about-theme.demo.vue消息跟随主题明暗模式变化modify-content.demo.vue修改已存在消息的内容与类型customize-message.demo.vue用render把消息渲染成 Alert总结Message 的使用要点前置条件任何使用useMessage的组件都必须位于n-message-provider内部否则会在运行时抛出异常use-message.ts 中通过injectthrowError保证。Provider 负责全局默认值duration默认 3000ms、placement默认 top、max、closable、keepAliveOnHover、to、container-class/style等均可由 Provider 统一下发单条消息通过MessageOption覆盖。六类注入方法create / info / success / warning / error / loading / destroyAll返回MessageReactive后者是响应式对象支持原地修改content、type并手动destroy()。自定义渲染render函数MessageRenderMessage可完全接管消息外观官方示例展示了如何复用NAlert实现「Alert 形态的消息」。setup 之外调用优先考虑createDiscreteApi或把useMessage的返回值挂载到window注意挂载时序同一应用中不建议混用两套体系。以上所有 Props 与方法的类型定义、默认值与版本信息均可继续在 src/message/src/MessageProvider.tsx、src/message/src/types.ts 以及 src/message/index.ts 的导出声明中逐一核对。赞分享前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载相关推荐Naive UI Message 信息提示组件完全指南从 useMessage 到 setup 外调用Naive UI Message 信息提示组件完全指南从 useMessage 到 setup 外调用 导读 Message 是 Naive UI 中最常用的前端UI组件naive-ui Discrete API 完全指南在 setup 外使用 Message、Dialog、Notification、LoadingBar 与 Modalnaive ui Discrete API 完全指南在 setup 外使用 Message、Dialog、Notification、LoadingBar 与前端UI组件Naive UI Notification 通知组件完全指南Provider 注入、命令式 API 与全参数详解Naive UI Notification 通知组件完全指南Provider 注入、命令式 API 与全参数详解 通知Notification是 Naiv前端UI组件上一篇ET10 从零打造 MMO 技能框架33 节实战课程体系与技术全景解析下一篇深入理解Spring Framework声明式事务实现原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考