Vant 4 ShareSheet 分享面板组件完全指南从用法、API 到源码原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantShareSheet 是 Vant 4 中一个底部弹起的分享面板组件用于展示各分享渠道对应的操作按钮微信、微博、复制链接、二维码等组件本身不包含任何具体的分享逻辑。在移动端 H5 业务中它是承接分享给好友 / 分享海报 / 生成小程序码等入口的标准 UI 方案。读完本文你将掌握 ShareSheet 的完整配置options数据结构、17 个 Props、7 个事件、3 个插槽、14 个主题变量并了解其基于 Popup 组件的底层实现原理与测试验证方式。组件定位与设计思想ShareSheet 的设计理念很明确只负责展示分享面板不负责执行分享动作。正如 README 开头所述它是一个 pop-up sharing panel at the bottom for displaying the action buttons corresponding to each sharing channel, without specific sharing logic。这是因为移动端分享场景极度碎片化微信内没有公开的分享 API只能引导用户点击右上角菜单各 App 内需要通过 JSBridge 调用原生 SDK海报、二维码类分享则往往需要配合弹层组件展示图片。因此 Vant 将面板 UI与分享逻辑解耦开发者只需提供options数组定义分享渠道并在select事件中自行对接业务分享能力。从源码结构看ShareSheet 目录下也只有 ShareSheet.tsx组件实现、index.less样式、types.ts主题变量类型与 index.ts导出没有依赖任何分享 SDK。快速引入ShareSheet 支持按需引入与全局注册。通过app.use全局注册import { createApp } from vue; import { ShareSheet } from vant; const app createApp(); app.use(ShareSheet);从 index.ts 可以看到组件通过withInstall包装后同时支持默认导出与命名导出并注册了全局组件名VanShareSheet。更多组件注册方式如 Vite/RSC 按需自动引入可参考文档 组件注册。基础用法ShareSheet 通过options属性定义分享选项数组的每一项是一个对象对象格式见下文Option 数据结构一节。面板显隐由v-model:show双向绑定控制点击某个选项触发select事件van-cell title显示分享面板 clickshowShare true / van-share-sheet v-model:showshowShare title立即分享给好友 :optionsoptions selectonSelect /import { ref } from vue; import { showToast } from vant; export default { setup() { const showShare ref(false); const options [ { name: 微信, icon: wechat }, { name: 微博, icon: weibo }, { name: 复制链接, icon: link }, { name: 分享海报, icon: poster }, { name: 二维码, icon: qrcode }, ]; const onSelect (option) { showToast(option.name); showShare.value false; }; return { options, onSelect, showShare, }; }, };select事件的回调参数为(option: Option, index: number)即被点击的选项对象及其在数组中的索引。在 test/index.spec.ts 的测试用例中可以验证点击选项后组件确实以[{ icon: wechat, name: wechat }, 0]的形式派发select事件。展示多行选项当分享选项较多时可以把options定义为数组嵌套的格式每个子数组会作为一行选项展示行与行之间自动绘制顶部细分割线van-share-sheet v-model:showshowShare title立即分享给好友 :optionsoptions /import { ref } from vue; export default { setup() { const showShare ref(false); const options [ [ { name: 微信, icon: wechat }, { name: 朋友圈, icon: wechat-moments }, { name: 微博, icon: weibo }, { name: QQ, icon: qq }, ], [ { name: 复制链接, icon: link }, { name: 分享海报, icon: poster }, { name: 二维码, icon: qrcode }, { name: 小程序码, icon: weapp-qrcode }, ], ]; return { options, showShare, }; }, };从 ShareSheet.tsx 的实现可以看到renderRows通过Array.isArray(options[0])判断是否为多行结构多行时逐行调用renderOptions且除第一行外其余行都会加上--border修饰类对应 index.less 中基于hairline混合宏绘制的 1px 顶部边框视觉上区分每组分享渠道。自定义图标除了内置的 8 种分享图标外可以直接在icon字段中传入图片 URL来使用任意自定义图标van-share-sheet v-model:showshowShare :optionsoptions /import { ref } from vue; export default { setup() { const showShare ref(false); const options [ { name: 名称, icon: https://fastly.jsdelivr.net/npm/vant/assets/custom-icon-fire.png, }, { name: 名称, icon: https://fastly.jsdelivr.net/npm/vant/assets/custom-icon-light.png, }, { name: 名称, icon: https://fastly.jsdelivr.net/npm/vant/assets/custom-icon-water.png, }, ]; return { options, showShare, }; }, };判断逻辑在 ShareSheet.tsx 的isImage函数中只要icon字符串包含/字符就按图片 URL 处理渲染为img标签class 为van-share-sheet__image-icon否则按内置图标名处理通过iconMap映射后交给van-icon渲染。这个斜杠即图片的约定非常轻量也意味着只要 URL 合法含路径分隔符即可生效。仓库自带 Demo demo/index.vue 中除 CDN 图片外还混合使用了内置图标label验证了两种模式可以并存。展示描述信息通过description属性可以设置标题下方的整体描述文字在某个options项内部设置description字段则可为该分享选项单独添加一行描述van-share-sheet v-model:showshowShare :optionsoptions title立即分享给好友 description描述信息 /import { ref } from vue; export default { setup() { const showShare ref(false); const options [ { name: 微信, icon: wechat }, { name: 微博, icon: weibo }, { name: 复制链接, icon: link, description: 描述信息 }, { name: 分享海报, icon: poster }, { name: 二维码, icon: qrcode }, ]; return { options, showShare, }; }, };渲染细节标题与描述共用.van-share-sheet__header头部区域只有title或description非空时才渲染该区域见 ShareSheet.tsx选项级描述渲染在选项名下方样式类为van-share-sheet__option-description。测试 test/index.spec.ts 也覆盖了 description 渲染与清空后的隐藏行为。Props 完整说明参数说明类型默认值v-model:show是否显示分享面板booleanfalseoptions分享选项Option[][]title顶部标题string-cancel-text取消按钮文字传入空字符串可以隐藏按钮string取消description标题下方的辅助描述文字string-duration动画时长单位秒设置为 0 可以禁用动画number | string0.3z-index将面板的 z-index 层级设置为一个固定值number | string2000round是否显示圆角booleantrueoverlay是否显示遮罩层booleantrueoverlay-class自定义遮罩层类名string | Array | object-overlay-style自定义遮罩层样式object-lock-scroll是否锁定背景滚动booleantruelazy-render是否在显示弹层时才渲染内容booleantrueclose-on-popstate是否在页面回退时自动关闭booleantrueclose-on-click-overlay是否在点击遮罩层后关闭booleantruesafe-area-inset-bottom是否开启底部安全区适配booleantrueteleport指定挂载的节点等同于 Teleport 组件的 to 属性string | Element-before-close关闭前的回调函数返回false可阻止关闭支持返回 Promise(action: string) boolean | Promiseboolean-Props 的底层来源从源码角度看这 17 个 Props 中大部分并非 ShareSheet 自行定义而是继承自 Popup 弹层组件。在 ShareSheet.tsx 中shareSheetProps通过extend({}, popupSharedProps, {...})合并了 popup/shared.ts 中声明的共享属性show、zIndex、overlay、duration、teleport、lockScroll、lazyRender、beforeClose、overlayStyle、overlayClass、closeOnClickOverlay等再叠加round、closeOnPopstate、safeAreaInsetBottom三个truthProp默认为 true 的布尔属性以及title、options、cancelText、description四个自有属性。options使用makeArrayProp工厂函数生成默认值为[]其类型为ShareSheetOption[] | ShareSheetOption[][]即支持单行与多行两种形态见 ShareSheet.tsx 的ShareSheetOptions类型。最终渲染时整个面板结构被包裹在positionbottom的Popup内因此 ShareSheet 天然获得 Popup 的动画、遮罩、锁定滚动、Teleport 等全部能力——这也是其 Props 如此丰富的原因。Option 数据结构options属性为一个对象数组数组中的每个对象配置一个分享选项可包含以下字段键名说明类型name分享渠道名称stringdescription分享选项描述stringicon图标可选值为wechatweiboqqlinkqrcodeposterweapp-qrcodewechat-moments支持传入图片 URLstringclassName分享选项类名会设置到分享项根元素上string对应的 TypeScript 定义在 ShareSheet.tsxexport type ShareSheetOption { name: string; icon: string; className?: string; description?: string; };其中className字段用于给单个选项追加自定义类名。测试 test/index.spec.ts 验证了className: foo会被正确挂到.van-share-sheet__option元素上可用于对特定渠道做差异化样式。内置图标与颜色映射icon的 8 个内置值在 ShareSheet.tsx 的iconMap中映射为对应的 Vant 图标名分享 icon 值实际渲染的图标wechatwechatwechat-momentswechat-momentsweiboweiboqqqqlinklink-oqrcodeqrposterphoto-oweapp-qrcodeminiprogram-o同时 index.less 为品牌渠道预设了圆形底与品牌色微信绿色#0bc15f、微博红色#ee575e、QQ 蓝色#38b9fa、朋友圈绿色#7bc845未映射的图标名会直接透传给van-icon渲染。Events 事件事件名说明回调参数select点击分享选项时触发option: Option, index: numbercancel点击取消按钮时触发-open打开面板时触发-close关闭面板时触发-opened打开面板且动画结束后触发-closed关闭面板且动画结束后触发-click-overlay点击遮罩层时触发event: MouseEvent其中select、cancel由 ShareSheet 自身声明见 ShareSheet.tsx 的emits: [cancel, select, update:show]其余open/close/opened/closed/click-overlay事件由内部 Popup 透传而来。取消按钮的点击行为是先派发update:show(false)关闭面板再派发cancel事件ShareSheet.tsx测试用例 test/index.spec.ts 对这一顺序有明确断言。Slots 插槽名称说明title自定义顶部标题description自定义描述文字cancel自定义取消按钮内容插槽优先级高于对应属性传入title插槽时插槽内容会覆盖title属性见 ShareSheet.tsx 与 #L140-L149 的 cancel 插槽逻辑。特别地cancel插槽与cancel-text属性二选一渲染取消按钮当两者都为空时取消按钮整体不渲染——测试 test/index.spec.ts 验证了cancelText: 时按钮会被隐藏。类型定义组件从vant包中导出以下类型供 TypeScript 项目使用import type { ShareSheetProps, ShareSheetOption, ShareSheetOptions, } from vant;此外还可导入ShareSheetThemeVars主题变量类型见 types.ts它声明了 14 个shareSheetXxx可选字段与下方 CSS 变量一一对应便于在ConfigProvider主题定制时获得类型提示。主题定制CSS 变量ShareSheet 提供了以下 CSS 变量可直接在根节点覆盖或通过 ConfigProvider 组件 统一注入主题名称默认值描述--van-share-sheet-header-paddingvar(--van-padding-sm) var(--van-padding-md) var(--van-padding-base)头部内边距--van-share-sheet-title-colorvar(--van-text-color)标题颜色--van-share-sheet-title-font-sizevar(--van-font-size-md)标题字号--van-share-sheet-title-line-heightvar(--van-line-height-md)标题行高--van-share-sheet-description-colorvar(--van-text-color-2)描述文字颜色--van-share-sheet-description-font-sizevar(--van-font-size-sm)描述文字字号--van-share-sheet-description-line-height16px描述文字行高--van-share-sheet-icon-size48px图标尺寸--van-share-sheet-option-name-colorvar(--van-gray-7)选项名称颜色--van-share-sheet-option-name-font-sizevar(--van-font-size-sm)选项名称字号--van-share-sheet-option-description-colorvar(--van-text-color-3)选项描述颜色--van-share-sheet-option-description-font-sizevar(--van-font-size-sm)选项描述字号--van-share-sheet-cancel-button-font-sizevar(--van-font-size-lg)取消按钮字号--van-share-sheet-cancel-button-height48px取消按钮高度--van-share-sheet-cancel-button-backgroundvar(--van-background-2)取消按钮背景色这些变量的默认值全部定义在 index.less 的:root, :host选择器中绝大多数引用 Vant 设计令牌如--van-padding-md、--van-font-size-sm、--van-text-color修改全局设计变量即可联动生效。例如把图标放大:root { --van-share-sheet-icon-size: 56px; }常见问题如何实现分享逻辑ShareSheet 刻意不内置分享逻辑。在不同 App 或浏览器中分享接口与方式差异很大需要开发者根据业务场景自行在select事件回调中对接微信内分享微信未提供公开的分享 API通常的做法是引导用户点击右上角菜单进行分享分享面板仅作为引导入口。App 内分享在 App 内可以通过 JSBridge 调用原生应用的 SDK 完成分享ShareSheet 的select回调中拿到option后按渠道名分发到对应的桥接方法即可。分享海报或二维码海报、二维码类分享本质上不是分享 API 调用而是内容展示。可以配合 Popup 组件 以弹层形式展示图片再引导用户长按保存图片进行分享。源码级要点小结基于 Popup 的复合组件ShareSheet Popuppositionbottom 头部 选项网格 取消按钮共享属性通过popupSharedProps合并popup/shared.ts这也是它拥有遮罩、动画、锁滚动、Teleport 等能力的原因。图标双模式icon含/渲染img否则走iconMap映射到 Vant 图标ShareSheet.tsx。多行渲染Array.isArray(options[0])判定多行结构首行外自动加细分隔线ShareSheet.tsx。取消按钮可隐藏cancel-text传空字符串即不渲染取消按钮且有对应测试用例保障test/index.spec.ts。可访问性细节每个分享选项渲染为rolebuttontabindex{0}并附带HAPTICS_FEEDBACK触摸反馈类兼顾键盘操作与移动端按压反馈。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考