Element Plus Notification 通知组件完全指南全局调用、类型体系与源码级原理剖析【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusNotification 是 Element Plus 提供的一款全局消息通知组件用于在页面四角弹出轻量级的提示卡片适合承载操作结果、系统消息等非阻塞性反馈。本文以 notification.md 官方文档为主线结合 notification 组件源码 与官方示例系统讲解其调用方式、全部配置项、版本演进能力如 VNode 消息、倒计时进度条、hover 暂停等并深入到实例队列管理、定时器与 zIndex 分配的底层实现帮助你从会调用进阶到知其所以然。基础用法第一个 NotificationElement Plus 已将$notify方法注册到app.config.globalProperties因此在任意 Vue 组件内部可以直接通过this.$notify调用在script setup组合式 API 中更推荐按需导入ElNotification后直接调用函数式 API。最简单的场景只需提供title标题和message正文两个字段import { ElNotification } from element-plus ElNotification({ title: Title, message: This is a reminder, })参考官方示例 notification/basic.vue其默认行为是在 4500ms 后自动关闭你可以在创建时传入h(i, ...)渲染的 VNode 作为消息体import { h } from vue import { ElNotification } from element-plus const open1 () { ElNotification({ title: Title, message: h(i, { style: color: teal }, This is a reminder), }) }若希望通知永不自动关闭将duration设置为0即可const open2 () { ElNotification({ title: Prompt, message: This is a message that does not automatically close, duration: 0, }) }注意duration接收的是毫秒单位的 Number。在源码层面notification.ts 中duration的默认值即为4500而 notification.vue 的startTimer()会先判断props.duration 0并直接返回——这正是duration: 0不自动关闭的实现依据。五种通知类型primary / success / warning / info / errorNotification 通过type字段指定语义类型组件会据此渲染对应的图标与状态色。官方文档明确列出四种基础类型而primary类型在 ^(2.9.11) 版本中新增因此当前共有五种type语义说明primary主色^(2.9.11) 新增无状态色success成功绿色、对勾图标warning警告橙色、感叹号图标info信息蓝色、信息图标error错误红色、叉号图标除了在ElNotification({ type: success })中显式传参Element Plus 还为每种类型注册了独立方法可以直接调用而无需传入typeElNotification.success({ title: Success, message: This is a success message }) ElNotification.warning({ title: Warning, message: This is a warning message }) ElNotification.info({ title: Info, message: This is an info message }) ElNotification.error({ title: Error, message: This is an error message }) ElNotification.primary({ title: Primary, message: This is a primary message })完整示例见 notification/different-types.vue。源码佐证在 notification.ts 中类型数组被定义为[primary, success, info, warning, error]而 notify.ts 遍历该数组为notify函数动态挂载了notify[type]方法内部实现等价于notify({ ...options, type })。同时notification.vue 中的iconComponent计算属性遵循有type用类型图标否则回退到自定义icon的优先级规则印证了文档中icon会被type覆盖的说明。自定义弹出位置四个角落任选Notification 可以从页面四个角落中的任意一个滑入通过position字段控制可选值为top-right、top-left、bottom-right、bottom-left默认值为top-right。ElNotification({ title: Custom Position, message: Im at the bottom right corner, position: bottom-right, })参考官方示例 notification/positioning.vue其中依次演示了右上默认、右下、左下、左上四种定位。从源码看位置不仅决定视觉坐标还决定了实例队列的归属。notify.ts 内部维护了一个以四个位置为键的队列对象const notifications: RecordNotificationPosition, NotificationQueue { top-left: [], top-right: [], bottom-left: [], bottom-right: [], }同位置的多个实例会按顺序纵向堆叠彼此之间保持固定的 16px 间距GAP_SIZE见 notify.ts。调整屏幕边缘偏移offset通过offset属性可以控制 Notification 距屏幕边缘的偏移量。文档特别强调同一时刻的每一个 Notification 实例应使用相同的 offset否则会出现视觉错乱。ElNotification.success({ title: Success, message: This is a success message, offset: 100, })示例见 notification/offsetting.vue。这里有必要解释offset的真实语义notify.ts 在创建实例时并非直接使用用户传入的offset而是把它作为基础偏移再叠加同位置队列中所有已存在实例的高度与间距从而得到每个实例实际的纵向位置let verticalOffset options.offset || 0 notifications[position].forEach(({ vm }) { verticalOffset (vm.el?.offsetHeight || 0) GAP_SIZE }) verticalOffset GAP_SIZE因此offset更像第一个实例距屏幕边缘的距离后续实例会自动向下或向上排开无需手动计算。使用 HTML 字符串与 XSS 安全警告message默认按纯文本渲染若需渲染富文本可将dangerouslyUseHTMLString设为trueElNotification({ title: HTML String, dangerouslyUseHTMLString: true, message: strongThis is iHTML/i string/strong, })示例见 notification/raw-html.vue。必须重视的安全警告动态渲染任意 HTML 极易导致 XSS跨站脚本攻击。因此开启dangerouslyUseHTMLString后请务必确保message内容可信绝不要将用户输入直接作为message赋值。该行为的实现位于 notification.vue组件通过v-if!dangerouslyUseHTMLString走插值渲染否则走v-htmlmessage源码注释中也明确标注了never use users input as message。消息即函数VNode 与动态渲染 ^(2.9.0)从 ^(2.9.0) 版本起message除了支持字符串和 VNode 之外还支持返回 VNode 的函数。函数形式的最大价值在于当 VNode 中包含响应式动态属性时只有函数形式才能保证内容跟随状态更新。普通 VNode 写法import { h } from vue ElNotification({ title: Use Vnode, message: h(p, null, [ h(span, null, Message can be ), h(i, { style: color: teal }, VNode), ]), })包含动态 props如开关组件时必须使用函数形式import { h, ref } from vue import { ElNotification, ElSwitch } from element-plus const open1 () { const checked refboolean | string | number(false) ElNotification({ title: Use Vnode, // Should pass a function if VNode contains dynamic props message: () h(ElSwitch, { modelValue: checked.value, onUpdate:modelValue: (val: boolean | string | number) { checked.value val }, }), }) }完整示例见 notification/use-vnode.vue。其底层逻辑在 notify.tscreateVNode时会判断message是函数则直接作为插槽函数、是 VNode 则包一层箭头函数从而把任意形式的message统一为可渲染的插槽内容。这也解释了为什么函数形式能保留动态响应能力——它本质上是作为作用域插槽被渲染的。倒计时进度条与悬停暂停 ^(2.14.4)从 ^(2.14.4) 起Notification 支持显示一条与自动关闭计时同步的进度条直观展示剩余展示时间。传入progress: true显示默认进度条其颜色跟随type的状态色传入对象可深度定制进度条支持 Progress 组件 的全部选项如color但percentage、type、duration、indeterminate、width五个字段被排除——因为该进度条永远由倒计时驱动percentage会自动计算当pauseOnHover为true默认值时鼠标悬停在通知上会同时暂停计时器与进度条。ElNotification({ title: Default progress, message: Hover to pause the timer and progress bar, duration: 6000, progress: true, }) ElNotification({ title: Custom color, message: Custom progress bar color overrides the default, duration: 6000, progress: { color: [ { color: #f56c6c, percentage: 20 }, { color: #e6a23c, percentage: 40 }, { color: #5cb87a, percentage: 60 }, { color: #1989fa, percentage: 80 }, { color: #6f7ad3, percentage: 100 }, ], }, }) // 悬停不暂停 ElNotification({ title: No pause on hover, message: Timer and progress bar keep running even when hovering, duration: 6000, progress: true, pauseOnHover: false, })示例见 notification/progress-bar.vue。源码层面的实现非常精巧值得展开notification.ts 中NotificationProgress类型通过OmitPartialProgressProps, percentage | type | duration | indeterminate | width显式排除上述字段与文档说明完全一致notification.vue 使用useIntervalFn以 100ms 为间隔更新percentage计算公式为100 - ((elapsed Date.now() - startedAt) / duration) * 100即从 100 线性递减到 0悬停暂停通过onMouseEnter/onMouseLeave配合clearTimer()/startTimer()实现见 notification.vue且clearTimer()会累计已流逝时间elapsed恢复时用remaining duration - elapsed重新计时并让进度条从当前位置继续而不是粗暴归零键盘交互同样周到按下Esc关闭当前通知按下Delete/Backspace则仅暂停计时见 notification.vue。隐藏关闭按钮showClose默认情况下 Notification 右上角有关闭按钮将其设为false后用户将无法手动关闭只能等待自动关闭或通过代码调用closeElNotification({ title: Title, message: This is a message, showClose: false, })对应示例见 notification/no-close.vue。组件模板中关闭按钮通过v-ifshowClose条件渲染notification.vue并使用了.stop修饰符阻止点击事件冒泡到通知卡片本身。全局方法与局部引入全局方法 $notifyElement Plus 将$notify注册到了app.config.globalProperties因此任何 Vue 实例内部都可以直接调用this.$notify({ title: Title, message: This is a message, })局部引入在按需引入的场景下推荐从element-plus显式导入ElNotificationimport { ElNotification } from element-plus import { CloseBold } from element-plus/icons-vue ElNotification({ title: Title, message: This is a message, closeIcon: CloseBold, })同样支持类型化方法ElNotification.success(options)以及primary、warning、info、error。此外还提供两个批量控制方法ElNotification.closeAll()手动关闭当前所有通知实例。源码实现见 notify.ts它遍历四个方向的队列并逐一调用实例暴露的close()ElNotification.updateOffsets(position)^(2.10.5) 新增手动更新指定方向下所有实例的偏移量。源码见 notify.ts它会以队列中首个实例的偏移为基准重新按高度 16px 间距依次排布后续实例。App 上下文继承Notification 的构造函数接受第二个参数context用于注入当前应用的上下文app context从而使通知内的组件可以继承当前应用的全部属性如全局组件、provide/inject 数据等。import { getCurrentInstance } from vue import { ElNotification } from element-plus // in your setup method const { appContext } getCurrentInstance()! ElNotification({}, appContext)两点补充说明若你通过app.use(ElementPlus)全局注册了ElNotification它会自动继承应用上下文无需手动传参源码中 notify.ts 通过vm.appContext isUndefined(context) ? notify._context : context完成注入而notify._context正是全局注册时被赋值的应用上下文notify.ts。API 参考Options 完整配置表下表为ElNotification(options)支持的全部配置项字段、类型与默认值均与官方文档一致并结合源码补充了版本与取值说明。名称说明类型默认值title标题stringmessage正文内容string/VNode/() VNode函数形式 ^(2.9.0)dangerouslyUseHTMLString是否将message作为 HTML 字符串渲染开启需防范 XSSbooleanfalsetype通知类型primary^(2.9.11)|success|warning|info|error|enumicon自定义图标组件会被type覆盖string/Component—customClass自定义类名stringduration自动关闭前的时长毫秒设为0则不自动关闭number4500position弹出位置top-right|top-left|bottom-right|bottom-leftenumtop-rightshowClose是否显示关闭按钮booleantrueonClose关闭时的回调() void—onClick点击通知时的回调() void—offset距屏幕边缘的偏移同刻所有实例应保持一致number0appendTo通知挂载的根元素默认document.bodyCSSSelector/HTMLElement—zIndex初始 zIndexnumber0closeIcon ^(2.9.8)自定义关闭图标string/ComponentCloseprogress ^(2.14.4)自动关闭倒计时进度条true显示默认条传对象可定制percentage、type、duration、indeterminate、width被排除boolean/objectProgress 选项falsepauseOnHover ^(2.14.4)悬停时是否暂停计时booleantrue源码佐证notification.ts 中的notificationProps完整定义了上述字段其中position与type通过values做了枚举约束closeIcon默认值为Close图标源自element-plus/icons-vueprogress使用definePropType([Boolean, Object])同时接受布尔与对象两种形态。API 参考实例方法ElNotification(...)与this.$notify(...)都会返回当前 Notification 的实例句柄可在任意时刻手动关闭名称说明类型close关闭该条 Notification() voidconst notification ElNotification({ title: Title, message: ... }) // 手动关闭 notification.close()该方法的内部实现值得留意返回句柄的close并非直接隐藏 DOM而是调用组件实例exposed中暴露的close()见 notify.ts。组件内部的close()会先置visible false触发离场过渡再执行clearTimer()停止进度条与关闭计时器notification.vue确保完整的生命周期不会被跳过。深入原理实例队列、内存清理与 zIndex实例队列与自动排布如前所述notify.ts 用四个方向的数组维护所有存活实例。关闭某条通知时close()notify.ts会做三件事调用用户传入的onClose回调在transition的before-leave阶段读取被移除实例的offsetHeight此时 DOM 尚未卸载可正常取高将该实例从队列中splice移除并把其后方所有实例的偏移统一减去被移除高度 16px 间距实现后续通知平滑上移补位。内存释放每个通知创建时会生成一个独立的div容器并通过render(vm, container)渲染notify.ts。组件在离场动画结束后触发destroy事件对应onDestroy钩子执行render(null, container)卸载虚拟节点防止内存泄漏。层级管理通知的zIndex默认并非固定的0组件通过useGlobalComponentSettings获取全局 zIndex 管理器在onMounted时调用nextZIndex()自增获取当前最高层级notification.vue确保新通知始终覆盖在旧通知之上若显式传入zIndex则优先生效。小结Element Plus Notification 以函数式调用 可配置化选项为核心设计从基础的标题/正文、四种语义类型到定位偏移、VNode 消息、倒计时进度条、悬停暂停等进阶能力一应俱全。配合源码中精心设计的实例队列、过渡生命周期、zIndex 分配与内存清理机制它在易用性与工程稳健性之间取得了很好的平衡。掌握本文所述的选项语义与底层行为你便能在项目中正确、安全、优雅地使用通知能力。如需继续了解与 Notification 同族的轻提示组件可查阅 Message 组件文档 与 MessageBox 组件文档 进行对比选型。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
