vant-weapp Notify 消息提示组件实战指南函数调用与组件调用双模式详解【免费下载链接】vant-weapp轻量、可靠的小程序 UI 组件库项目地址: https://gitcode.com/gh_mirrors/va/vant-weapp导读Notify 消息提示是 vant-weapp 小程序组件库中用于在页面顶部展示轻量级提示信息的组件它同时支持函数调用与组件调用两种方式适用于表单校验反馈、操作结果提醒、状态变更通知等场景。阅读本文后你将掌握 Notify 的引入与配置、四种通知类型与自定义样式、全局默认参数管理以及其底层基于selectComponent与过渡动画的实现原理并能在实际项目中灵活落地。本文以 packages/notify/README.md 为核心骨架结合仓库内 组件源码、函数入口、模板、样式 及示例与测试展开纵深讲解。组件定位与能力概览Notify 的核心定位是在页面顶部展示消息提示条。与 Dialog、Toast 等弹层组件不同Notify 更轻量它不阻塞页面交互、自动按时长消失非常适合做非打断式的即时反馈。从 packages/notify/README.md 可知该组件支持两大调用范式函数调用通过import Notify from vant/weapp/notify/notify导入后直接以函数形式触发适合在任意业务逻辑中快速弹出提示组件调用在页面 WXML 中放置van-notify idvan-notify /节点作为函数调用的承载目标。两种方式本质上是函数驱动、组件渲染的关系函数负责寻找并驱动组件实例组件负责实际的视觉呈现与动画这在后文源码解析部分会详细展开。快速引入组件与 vant-weapp 其他组件一致Notify 需要在页面的index.json或全局的app.json中声明usingComponents组件完整路径为vant/weapp/notify/indexusingComponents: { van-notify: vant/weapp/notify/index }关于依赖安装、构建 npm 等前置步骤可参考仓库内的快速上手文档该文档详细介绍了npm i vant/weapp、微信开发者工具中构建 npm、以及app.json中usingComponents的标准配置流程。引入组件后还需在当前页面的 WXML 中放置对应的van-notify节点函数调用才有可操作的目标van-notify idvan-notify /基础用法函数调用与页面节点配合README 给出的最小可用示例是import Notify from vant/weapp/notify/notify; Notify(通知内容);!-- 在页面内添加对应的节点 -- van-notify idvan-notify /这里有一个非常关键的细节函数调用时传入的可以是字符串也可以是配置对象。查看函数入口 packages/notify/notify.ts 可以发现Notify内部通过parseOptions对入参做了归一化function parseOptions( message?: NotifyOptions | string ): PartialNotifyOptions { if (message null) { return {}; } return typeof message string ? { message } : message; }也就是说Notify(通知内容)等价于Notify({ message: 通知内容 })二者最终都会合并进默认配置currentOptions后统一处理。底层调用链packages/notify/notify.ts如下将当前默认参数currentOptions与本次调用参数做浅合并通过getContext()获取当前页面栈中最后一个页面实例作为查找上下文调用context.selectComponent(options.selector)找到页面中的van-notify组件实例将展示参数setData注入组件并调用组件实例的show()方法触发展示若未找到节点控制台会输出警告未找到 van-notify 节点请确认 selector 及 context 是否正确。这就是为什么 WXML 中的节点id默认必须是van-notify对应selector默认值#van-notify——否则函数将无法定位组件这也是新手最容易踩的坑。通知类型四种内置视觉风格Notify 支持primary、success、warning、danger四种通知类型默认值为danger// 主要通知 Notify({ type: primary, message: 通知内容 }); // 成功通知 Notify({ type: success, message: 通知内容 }); // 危险通知 Notify({ type: danger, message: 通知内容 }); // 警告通知 Notify({ type: warning, message: 通知内容 });从组件实现 packages/notify/index.ts 可以看到type的默认值正是danger与文档声明一致type: { type: String, value: danger, },各类型的背景色定义在样式文件 packages/notify/index.less 中通过 CSS 变量自定义属性与 less 变量双轨控制--primary { background-color: var( --notify-primary-background-color, notify-primary-background-color ); } --success { background-color: var( --notify-success-background-color, notify-success-background-color ); } --danger { background-color: var( --notify-danger-background-color, notify-danger-background-color ); } --warning { background-color: var( --notify-warning-background-color, notify-warning-background-color ); }对应的 less 默认值位于 packages/common/style/var.lessprimary使用品牌蓝blue、success使用绿色green、danger使用红色red、warning使用橙色orange。模板 packages/notify/index.wxml 通过classvan-notify van-notify--{{ type }}动态切换类型样式。自定义通知颜色与展示时长当内置类型无法满足需求时可通过color、background自定义文字与背景颜色通过duration控制展示时长Notify({ message: 自定义颜色, color: #ad0000, background: #ffe1e1, }); Notify({ message: 自定义时长, duration: 1000, });这些参数最终会通过 packages/notify/index.wxs 中的notifyStyle计算函数注入到消息条内层节点的内联样式中function notifyStyle(data) { return style({ background: data.background, color: data.color, }); }duration 为 0 时不自动关闭README 明确指出duration值为 0 时notify 不会消失。这一行为在组件源码 packages/notify/index.ts 的show()方法中有对应的守卫逻辑show() { const { duration, onOpened } this.data; clearTimeout(this.timer); this.setData({ show: true }); wx.nextTick(onOpened); if (duration 0 duration ! Infinity) { this.timer setTimeout(() { this.hide(); }, duration); } }可以看到只有duration 0且不等于Infinity时才会启动定时器自动隐藏当duration为 0 或Infinity时提示条会持续停留直到手动调用Notify.clear()关闭。这一设计使得 Notify 可以承担常驻提示类需求。自定义选择器多实例与自定义节点在同一个页面存在多个van-notify节点、或需要把节点放在特定位置时可以通过selector指定节点选择器Notify({ message: 自定义节点选择器, duration: 1000, selector: #custom-selector, });!-- 在页面内添加自定义节点 -- van-notify idcustom-selector /selector的默认值为#van-notify见 packages/notify/notify.ts 中defaultOptions的定义。与之配套的还有context参数当需要在自定义组件内部弹出 Notify 时由于getCurrentPages()拿到的是页面而非组件必须显式传入组件自身的this作为查找上下文Notify({ context: this, message: 通知内容, });这一点在示例页面 packages/notify/demo/index.ts 中得到了直接印证所有 demo 调用均传入了context: this。在 packages/notify/notify.ts 中context与selector在完成组件查找后会被delete掉不会作为展示参数污染组件数据。API 详解方法README 中提供的方法表如下方法名说明参数返回值Notify展示提示options \| messagenotify 实例Notify.clear关闭提示optionsvoid除文档列出的两个方法外从源码 packages/notify/notify.ts 中还可以看到两个全局默认参数管理方法可用于统一业务内的通知风格方法名说明参数返回值Notify.setDefaultOptions修改当前默认配置optionsvoidNotify.resetDefaultOptions重置默认配置为初始值无void其实现基于模块内的currentOptions引用Notify.setDefaultOptions (options: NotifyOptions) { Object.assign(currentOptions, options); }; Notify.resetDefaultOptions () { currentOptions { ...defaultOptions }; };例如可在app.js中统一设置默认展示时长import Notify from vant/weapp/notify/notify; Notify.setDefaultOptions({ duration: 1500 });Options以下是 README 中完整的 Options 参数表并补充了源码中确认的默认值与内部行为参数说明类型默认值typev1.0.0类型可选值为primarysuccesswarningstringdangermessagev1.0.0展示文案支持通过\n换行stringduration展示时长(ms)值为 0 时notify 不会消失number3000selector自定义节点选择器stringvan-notifycolor字体颜色string#ffftop顶部距离number0background背景颜色string-context选择器的选择范围可以传入自定义组件的 this 作为上下文object当前页面onClick点击时的回调函数Function-onOpened完全展示后的回调函数Function-onClose关闭时的回调函数Function-safeAreaInsetTop是否留出顶部安全距离状态栏高度booleanfalse需要说明的是上表各默认值均有源码依据type与duration默认值见 packages/notify/index.tsselector: #van-notify、color: WHITE即#fff定义于 packages/common/color.ts、top: 0、safeAreaInsetTop: false等见 packages/notify/notify.ts。此外组件还暴露了一个 README 表格之外的参数zIndex默认110见 packages/notify/index.ts 与 packages/notify/notify.ts用于调整提示条的层叠顺序避免被其他浮层遮挡。回调函数onClick、onOpened、onClose三个回调在组件 packages/notify/index.ts 中作为内部数据存储onOpenedshow()时通过wx.nextTick(onOpened)在展示完成后的下一帧触发onClosehide()时通过wx.nextTick(onClose)触发可借此在关闭后执行后续逻辑onClick消息条被点击时触发事件处理见onTap方法packages/notify/index.ts模板中通过bind:taponTap绑定在过渡容器上。插入状态栏安全距离对于顶部有状态栏的机型如刘海屏可通过safeAreaInsetTop: true让提示条自动避开状态栏Notify({ message: 通知内容, safeAreaInsetTop: true, });其实现细节非常巧妙组件在created生命周期通过getSystemInfoSync()读取statusBarHeight并存入 datapackages/notify/index.ts模板 packages/notify/index.wxml 中当safeAreaInsetTop为真时会在消息条上方渲染一个高度等于状态栏高度的占位 viewview wx:if{{ safeAreaInsetTop }} styleheight: {{ statusBarHeight }}px /示例页面 packages/notify/demo/index.wxml 中对应的按钮文案即为插入状态栏高度。底层实现原理从函数到动画的完整链路组件结构packages/notify/index.json 声明了组件依赖van-transition过渡组件因此消息条的显隐动画复用了 transition 的slide-down下拉动画{ component: true, usingComponents: { van-transition: ../transition/index } }模板 packages/notify/index.wxml 的整体结构为van-transition承载slide-down动画与点击事件→ 内层view.van-notify承载类型背景色与background/color内联样式→ 可选的状态栏占位 view → 文案text。顶部定位与层级rootStyle计算函数packages/notify/index.wxs将zIndex与top组合为容器的内联样式容器本身的position: fixed; top: 0; left: 0; width: 100%由样式文件 packages/notify/index.less 定义保证提示条固定悬浮在页面顶部top参数默认 0可在此基础上继续下移。定时器与手动关闭组件show()内部使用this.timer管理自动关闭定时器并在hide()中clearTimeout避免重复展示时定时器叠加Notify.clear()则通过同样的selectComponent机制找到节点并调用notify.hide()packages/notify/notify.ts因此它同样支持传入selector与context参数以定位非默认节点。样式定制CSS 变量主题化Notify 的样式全部通过 CSS 变量提供覆盖入口可在页面或全局样式中按需覆写CSS 变量默认值less用途--notify-paddingnotify-padding6px 15px内边距--notify-font-sizenotify-font-size14px字号--notify-line-heightnotify-line-height20px行高--notify-primary-background-colorblueprimary 背景色--notify-success-background-colorgreensuccess 背景色--notify-danger-background-colorreddanger 背景色--notify-warning-background-colororangewarning 背景色各变量定义在 packages/notify/index.lessless 默认值集中在 packages/common/style/var.less如notify-padding: 6px 15px; notify-font-size: 14px; notify-line-height: 20px;。实际开发中可直接覆写page { --notify-danger-background-color: #7a1f1f; }测试与示例验证仓库为 Notify 提供了基于miniprogram-simulate的快照测试packages/notify/test/demo.spec.ts通过渲染示例页面并比对快照packages/notify/test/snapshots/demo.spec.ts.snap来保证组件渲染结果稳定防止回归。示例页面 packages/notify/demo/index.wxml 完整覆盖了基础用法、四种类型、自定义颜色/时长、状态栏安全距离四种场景其对应逻辑在 packages/notify/demo/index.ts 中均有实现可作为项目集成的参照样板。实战建议与常见问题务必放置页面节点函数调用本身不渲染任何内容页面 WXML 中必须有van-notify idvan-notify /节点否则控制台会输出未找到 van-notify 节点警告且无任何视觉反馈自定义组件内调用需传context: thisgetCurrentPages()只能拿到页面实例组件内的selectComponent上下文必须手动指定多实例场景使用selector区分同一页面需要多个不同样式/位置的提示条时为每个节点指定不同id并在调用时传入对应selector常驻提示使用duration: 0需要用户主动关闭的提示如强提示将duration设为 0再结合Notify.clear()手动关闭批量统一风格在app.js中通过Notify.setDefaultOptions一次性设置全项目的默认duration、background等参数避免重复传参。至此你已经掌握了 vant-weapp Notify 消息提示从引入、函数调用、类型切换、自定义样式到源码级实现原理的完整链路可以直接在项目中按需接入。【免费下载链接】vant-weapp轻量、可靠的小程序 UI 组件库项目地址: https://gitcode.com/gh_mirrors/va/vant-weapp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考