@yeez-tech/sharing-component

一款开箱即用的 Web 分享按钮组件（含悬浮分享面板、烟花动效、渠道跳转与回退策略）。

✨ 特性

• 🎨 边框跑马灯动画、按钮点击波纹
• 🎆 烟花粒子效果（可配置/默认间隔发射）
• 🖱️ Hover 交互：按钮上方显示悬浮分享面板
• 🧩 6 个分享渠道：QQ、QQ 空间、微博、微信、生成海报、复制链接
• 🧱 完整产品卡片（标题/价格/大小/图片）与推广横幅
• 🎯 智能二维码生成：支持传入 URL 自动生成二维码（内置算法，无需额外依赖）
• 🧰 API 简单、支持多实例与回调钩子
• 🔄 自动资源管理：包内资源自动加载，无需手动配置路径

📦 安装

npm i @yeez-tech/sharing-component

🚀 快速开始

A. 在 Vue (Vite) 中使用（推荐）

无需单独引入 CSS，样式已在 ESM 入口自动加载。包内资源（二维码、推广图片）会自动加载，无需手动导入。

<script setup>
import { onMounted } from "vue";
import ShareButtonComponent, { ShareMedia } from "@yeez-tech/sharing-component";

// 可选：从包内导入资源文件（Vite 会返回可用 URL）
// 如果不传入，组件会自动使用包内默认资源
import cardPng from "@yeez-tech/sharing-component/asset/transparent.png";

onMounted(() => {
  ShareButtonComponent.init({
    shareMedia: [
      ShareMedia.QQ,
      ShareMedia.QZone,
      ShareMedia.XiaoHongShu,
      ShareMedia.WeiBo,
      ShareMedia.TieBa,
      ShareMedia.Link,
    ],
    shareTitle: "分享标题",
    cardTitle: "卡片标题",
    cardSize: "45.2 GB",
    cardPrice: "￥18.88",
    cardImageUrl: cardPng, // 可选：不传则使用默认
    // qrCodeUrl 支持两种方式：
    // 1) 传入 URL 链接，组件会自动生成二维码图片
    qrCodeUrl: "https://example.com/share?ref=abc123",
    // 2) 传入图片 URL，直接显示该图片
    // qrCodeUrl: "https://cdn.example.com/qrcode.png",
    showPromo: true,
    // 点击推广按钮后自动关闭分享弹窗（默认 true）
    closeOnPromoClick: true,
    onPromo: function () {
      console.log("推广按钮被点击");
    },
    debug: true, // 开启调试日志
  });
});
</script>

<template>
  <button class="share-button" id="shareBtn">分享</button>
</template>

<style scoped>
/* 取消拉伸并设定本地尺寸 */
.share-button {
  flex: 0 0 auto !important;
  padding: 10px 18px !important; /* 调整大小 */
  font-size: 13px !important;
  border-radius: 6px !important;
  width: auto !important;
  display: inline-flex !important;
}
</style>

### B. 纯 HTML 引用（无构建） ```html
<link
  rel="stylesheet"
  href="node_modules/@yeez-tech/sharing-component/dist/share-button.css"
/>
<script src="node_modules/@yeez-tech/sharing-component/dist/share_media.js"></script>
<script src="node_modules/@yeez-tech/sharing-component/dist/share-button.js"></script>

<!-- 按钮 -->
<button class="share-button" id="shareBtn">分享</button>

<script>
ShareButtonComponent.init({
  shareTitle: "分享标题",
  cardTitle: "卡片标题",
  cardSize: "45.2 GB",
  cardPrice: "￥18.88",
  // cardImageUrl: 可选，不传则使用包内默认资源
  // qrCodeUrl: 支持两种方式
  // 1) 传入 URL 链接，组件会自动生成二维码
  qrCodeUrl: "https://example.com/share?ref=abc123",
  // 2) 传入图片 URL 或相对路径
  // qrCodeUrl: "asset/qrcode.png",
  showPromo: true,
  closeOnPromoClick: true, // 点击推广按钮后自动关闭分享弹窗
  onPromo: function () {
    alert("申请成为数据经纪人");
  },
});
</script>

注意：在纯 HTML 环境中，二维码生成能力已内置，无需额外引入第三方库。

🧭 API 概览

ShareButtonComponent.init(options)

| 参数 | 类型 | 默认值 | 说明 | | ----------------- | -------- | -------------------------- | ----------------------------------------------------------------------------------------------------- | | instanceId | string | '' | 多实例标识。自动查找 shareBtn{instanceId} 与 shareTooltip{instanceId} | | shareMedia | array | 全部渠道 | 渠道列表，来自 ShareMedia 枚举 | | showPromo | boolean | true | 是否显示底部推广横幅 | | shareTitle | string | '分享内容' | 分享标题/文案（用于分享页或系统分享） | | cardTitle | string | '...' | 悬浮卡片标题（仅 UI 展示） | | cardSize | string | '64.76 GB' | 悬浮卡片文件大小 | | cardPrice | string | '￥ 21.55' | 悬浮卡片价格 | | cardImageUrl | string | '' | 悬浮卡片图片 URL（可选，不传则使用默认） | | qrCodeUrl | string | 'asset/qrcode.png' | 二维码 URL。支持两种方式：1) URL 链接字符串（自动生成二维码）；2) 图片 URL（直接显示） | | qrCodeSize | number | 140 | 二维码尺寸（32-512 像素） | | promoImageUrl | string | '' | 推广横幅图片 URL（可选，不传则使用包内默认资源） | | promoTitle | string | '分享链接，躺赚丰厚佣金！' | 底部推广横幅文案 | | promoButtonText | string | '了解数据经纪人' | 推广按钮文案 | | promoButtonUrl | string | '' | 推广按钮跳转链接（如果提供了 onPromo 回调，则不会自动跳转；否则如果提供了此 URL，点击按钮会直接跳转） | | closeOnPromoClick | boolean | true | 点击推广按钮后是否自动关闭分享弹窗 | | debug | boolean | false | 是否开启调试日志（输出到 console） | | zIndex | object | - | 图层层级配置对象，见下方说明 | | onShare | function | - | 渠道点击回调 (channel, title, url)。返回 false（或 Promise<false>）可触发默认回退逻辑 | | onPromo | function | - | 推广按钮点击回调（在弹窗关闭后触发）。如果提供了此回调，则优先执行回调，不会自动跳转到 promoButtonUrl | | onButtonClick | function | - | 分享按钮点击回调 | | afterCopy | function | - | 复制海报成功后的回调。如果提供了此回调，则优先执行回调；否则使用默认回退逻辑（按钮变绿显示"已复制"） | | posterData | object | - | 海报数据对象（用于生成海报功能，见下方说明） |

返回值：{ destroy() } 用于销毁定时器等副作用。在 SPA 路由切换时建议调用 destroy() 清理资源。

qrCodeUrl 使用说明：

• 传入 URL 链接（如 https://example.com/share?ref=abc）：组件会自动生成二维码图片
• 传入图片 URL 或相对路径（如 https://cdn.example.com/qr.png 或 asset/qrcode.png）：直接显示该图片
• 在所有环境（ESM、纯 HTML、SSR）中均内置二维码算法，无需额外加载第三方库

zIndex 配置说明：

用于自定义组件的图层层级（z-index），避免与其他弹窗层级冲突。默认值如下：

zIndex: {
  tooltip: 10000,      // 分享弹窗（.share-tooltip）
  wechatModal: 20000,  // 微信二维码弹窗（.wechat-qr-modal）
  posterModal: 20000   // 海报预览弹窗（.poster-preview-modal）
}

示例：

ShareButtonComponent.init({
  // ... 其他配置
  zIndex: {
    tooltip: 15000, // 自定义分享弹窗层级
    wechatModal: 25000, // 自定义微信二维码弹窗层级
    posterModal: 25000, // 自定义海报预览弹窗层级
  },
});

如果某个层级未配置，将使用默认值。例如只配置 tooltip，则 wechatModal 和 posterModal 仍使用默认值 20000。

ShareMedia 枚举

ShareMedia.WeChat; // 微信（引导/二维码）
ShareMedia.QQ; // QQ 好友
ShareMedia.QZone; // QQ 空间
ShareMedia.XiaoHongShu; // 小红书（提示）
ShareMedia.WeiBo; // 微博
ShareMedia.TieBa; // 百度贴吧
ShareMedia.Poster; // 生成海报（点击后生成海报图片供下载分享）
ShareMedia.Link; // 复制链接

生成海报功能

组件支持生成精美的海报图片供用户下载分享。需要在 shareMedia 中包含 ShareMedia.Poster，并配置 posterData 对象。

posterData 数据结构

{
  userAvatarUrl: string,      // 用户头像图片 URL（支持 http/https/data URL）
  userName: string,           // 用户名（显示在头像右侧）
  recommendationText: string, // 推荐语（显示在用户名下方）
  productTitle: string,       // 商品标题（最多显示 5 行，超出部分用省略号）
  productPrice: number,       // 商品价格（数字，如 109.9）
  productImageUrl: string,    // 商品主图 URL（支持 http/https/data URL）
  logoUrl?: string,          // Logo 图片 URL（显示在底部，可选）
  shareUrl?: string          // 分享链接（用于生成二维码，可选，默认使用 dataUrl）
}

使用示例

ShareButtonComponent.init({
  dataUrl: "https://example.com/product/123", // 用于生成二维码
  shareMedia: [ShareMedia.Poster, ShareMedia.WeChat, ShareMedia.Link],
  posterData: {
    userAvatarUrl: "https://example.com/avatar.jpg",
    userName: "马毓一",
    recommendationText: "快来看看这个高质量的数据产品，别错过～",
    productTitle: "南京方言数据集｜300小时高质量自然对话音频｜专业录音棚采集",
    productPrice: 1,
    productImageUrl: "https://example.com/product.jpg",
    logoUrl: "https://example.com/logo.png", // 可选
  },
});

海报功能说明

• 生成方式：点击"生成海报"按钮后，组件会使用 Canvas 绘制海报图片
• 图片格式：生成 PNG 格式的高清图片（分辨率约 4K 级别）
• 二维码：自动根据 dataUrl 生成二维码（如未提供 shareUrl）
• 图片加载：支持跨域图片（需要服务端设置 CORS），加载失败时使用灰色占位图
• 文本处理：商品标题自动换行，最多显示 5 行，超出部分显示省略号
• 弹窗预览：生成后会在弹窗中预览，支持下载

onShare 回调示例

onShare 回调支持自定义分享逻辑，并可返回 false 触发默认回退行为：

ShareButtonComponent.init({
  // ... 其他配置
  onShare: async function (channel, title, url) {
    // channel: 分享渠道（如 'wechat', 'qq' 等）
    // title: 分享标题
    // url: 当前页面 URL（可通过 window.location.href 获取）

    // 示例：从后端获取自定义分享 URL
    try {
      const customUrl = await fetch("/api/getShareUrl?channel=" + channel)
        .then((res) => res.json())
        .then((data) => data.url);

      if (customUrl) {
        // 使用自定义 URL 进行分享
        ShareMediaConfig[channel].share(title, customUrl);
        return; // 不返回 false，不触发默认逻辑
      }
    } catch (e) {
      console.error("获取分享 URL 失败:", e);
    }

    // 返回 false 触发默认分享逻辑（Web Share API 或渠道默认行为）
    return false;
  },
});

afterCopy 回调示例

afterCopy 回调在复制海报成功后触发，可用于显示自定义提示（如 toast）：

ShareButtonComponent.init({
  // ... 其他配置
  posterData: {
    // ... 海报数据
  },
  afterCopy: function () {
    // 复制海报成功后的自定义逻辑
    // 例如：显示 toast 提示、发送埋点、更新 UI 等

    // 示例：显示自定义 toast
    showToast("海报已复制到剪贴板");

    // 示例：发送埋点
    // trackEvent('poster_copied');

    // 如果没有提供 afterCopy 回调，会使用默认回退逻辑：
    // 按钮变绿显示"已复制" 2 秒
  },
});

⚠️ 注意事项

资源加载

• ESM 环境（Vite/Webpack）：包内资源（二维码、推广图片）会自动加载，无需手动配置。如需自定义，可传入 cardImageUrl、qrCodeUrl、promoImageUrl 选项。
• 纯 HTML 环境：建议传入完整的资源 URL 路径，或确保资源文件可访问。

二维码生成

• ESM 环境：组件会自动加载 qrcode 库，支持直接传入 URL 链接生成二维码。
• 纯 HTML 环境：如需使用 URL 生成二维码功能，需确保 qrcode 库可用（通过 CDN 引入或全局变量）。

分享行为

• 移动端优先尝试系统分享（Web Share API，需 HTTPS/localhost）；不支持时回退到渠道分享/复制链接。
• 微信内想"拉起好友选择"需接入微信 JS‑SDK（内置浏览器，需服务端签名与域名白名单）。
• onShare 回调返回 false（或 Promise<false>）可触发默认回退逻辑。

SPA 路由切换

在 Vue/React 等 SPA 框架中，建议在路由切换时调用 destroy() 方法清理资源：

import { onBeforeUnmount } from "vue";

const instance = ShareButtonComponent.init({
  /* ... */
});

onBeforeUnmount(() => {
  instance.destroy();
});

SSR 环境

组件依赖浏览器环境（window、document），在 SSR 环境中需使用动态导入：

// Vue
import { onMounted } from "vue";

onMounted(async () => {
  const ShareButtonComponent = (await import("@yeez-tech/sharing-component"))
    .default;
  ShareButtonComponent.init({
    /* ... */
  });
});

📦 打包文件说明

发布包包含以下文件：

• dist/share-button.js - UMD/IIFE 格式的主文件
• dist/index.esm.js - ESM 入口文件（自动加载样式和资源）
• dist/share-button.css - 样式文件
• dist/share_media.js - 分享渠道定义
• asset/qrcode.png - 默认二维码图片
• asset/transparent.png - 默认推广图片
• example.html - 纯 HTML 使用示例
• App.vue - Vue (Vite) 使用示例

📁 项目结构 & 设计文件说明

核心运行时代码

这些是 真正随 npm 包发布、在业务页面里运行的代码：

• dist/share-button.js：分享按钮 + 悬浮弹窗 + 渠道跳转 +（当前正在对接中的）“生成海报”逻辑，全部打包在这里
• dist/share-button.css：分享按钮和分享弹窗的样式
• dist/share_media.js：ShareMedia 枚举以及每个渠道的图标、名称、跳转逻辑
• example.html：用于本地调试的纯 HTML 示例（不会随线上业务一起改样式，只是 demo）
• App.vue：在 Vue/Vite 中使用组件的示例（同样只是 demo）

当你在业务里通过 @yeez-tech/sharing-component 使用组件时，真正起作用的是 dist 目录里的这些打包文件。

「海报设计与样式调整」文件夹是干什么的？

路径：webui-component/sharing-component/海报设计与样式调整/

这个文件夹不是运行时代码，而是 专门用于海报设计与样式对齐的“设计沙箱”，主要作用：

• 存放 Figma 导出的 React/HTML/CSS 实现，用于还原海报视觉稿
• 为 Canvas 版海报生成提供 像素级对照标准（尺寸、间距、阴影、字体等）
• 不直接参与 npm 包打包，不会影响现有分享弹窗和产品卡片样式

目录关键内容：

• preview.html
  纯 HTML + CSS 版本的海报页面，用来在浏览器里预览最终视觉效果。这里的样式是海报的“真标准”，Canvas 版会尽量 1:1 复刻这份布局。

• src/imports/Frame36791.tsx
  同一张海报的 React 组件实现，使用 Tailwind + JSX 描述布局。主要给设计/前端参考结构，不直接被打包使用。

• src/imports/svg-pfp9ulgp78.ts
  导出人民币符号的 SVG 路径（p34e56900），Canvas 版会复用这段路径来绘制 ￥ 图形，而不是随便画一个符号。

• src/assets/*.png

  • 80ec...png：用户头像示例图
  • 9cff...png：产品主图示例图
  • 1aed...png：二维码示例图
  • f65d...png：底部「典枢」Logo 示例图
    这些都是设计稿里的示例资源，方便本地预览；业务环境下会被接口返回的真实数据替换。

• README_FOR_AI.md
  给「写代码的 AI」看的说明文档，详细列出了海报组件的布局结构、尺寸、颜色、阴影、字体等规范，用来指导 Canvas 版实现 严格对齐设计。

总结：

• 你在 Figma / React / HTML 里调样式 → 改的是 海报设计与样式调整 文件夹
• 真正生成海报图片、给用户下载分享的逻辑 → 在 dist/share-button.js 里用 Canvas 实现，并“照抄”上面这份设计

未来如果你或其他模型实现了一个独立的海报渲染模块（例如 海报设计与样式调整/poster-canvas.js），我们会在这里补充说明：
它会以 window.PosterRenderer.renderPosterToCanvas(posterData) 这样的方式暴露出来，然后在 dist/share-button.js 里仅负责“调用”，而不再重新设计样式。

📝 更新日志

v1.0.1

• ✨ 新增：支持传入 URL 链接自动生成二维码图片
• ✨ 新增：添加百度贴吧分享渠道
• ✨ 新增：closeOnPromoClick 选项，控制点击推广按钮后是否自动关闭弹窗
• ✨ 新增：promoImageUrl 选项，支持自定义推广横幅图片
• ✨ 新增：qrCodeSize 选项，支持自定义二维码尺寸
• ✨ 新增：debug 选项，支持开启调试日志
• ✨ 新增：afterCopy 回调，支持自定义复制海报成功后的提示逻辑
• ✨ 新增：海报生成时显示 loading 动画，提升用户体验
• ✨ 新增：海报弹窗支持"复制海报"功能（主要按钮）和"下载海报"功能（次要按钮）
• 🐛 修复：ESM 环境下包内资源自动加载问题
• 🐛 修复：onShare 回调支持返回 false 触发默认回退逻辑
• 📚 优化：完善文档和使用示例

v1.0.0

• 🎉 首次发布
• ✨ 基础分享功能：QQ、QQ 空间、微博、微信、生成海报、复制链接
• ✨ Hover 交互与悬浮分享面板
• ✨ 产品卡片与推广横幅
• ✨ 边框跑马灯与烟花粒子效果

📄 License

MIT