bxs-tools-ui 3.1.2 → 3.2.0-0

package/packages/share-sheet/readme.md

@@ -1,27 +1,34 @@
 ## 分享面板（ShareSheet）
-通过底部弹窗提供分享渠道/功能入口，并支持分享有效期、分享后提示与复制文案。  
-  
-**内容**：
-- introduceImage：顶部说明图（可选）
-- expireData：分享有效期（可选）
-- explainData：分享说明（可选）
-- shareActions：分享渠道入口（可选）
-- featureActions：功能入口（可选）
-- 底部取消按钮：关闭弹窗
 
+通过底部全屏弹窗（`van-popup`，挂载到 `body`，底部安全区）提供分享渠道/功能入口，并支持分享说明、分享有效期与复制文案。
+
+**自上而下展示顺序**：
+
+1. `introduceImage`：顶部说明图（可选）
+2. `explainData`：分享说明标题与正文（可选）
+3. `expireData`：分享有效期（可选）
+4. `header` 插槽：自定义内容（可选）
+5. `shareActions`：分享渠道入口（可选）
+6. `featureActions`：功能入口（可选）
+7. 底部「取消」：关闭弹窗
+
+---
 
 ### 模块引用（import）
+
 ```javascript
 import { ShareSheet } from 'bxs-tools-ui';
 export default {
   components: {
     ShareSheet
   }
-}
-```  
+};
+```
 
+---
 
 ### 示例（example）
+
 ```html
 <template>
   <ShareSheet
@@ -55,6 +62,7 @@ export default {
         urlAfterExpire: 'https://pbf.winbaoxian.cn/planBook/projectGroup/feedback/index.html'
       },
       explainData: {
+        title: '分享说明',
         text: '分享后推广费及奖励将不可见，请放心分享，用户投保成功，推广费及奖励可拿。',
         copy: true
       },
@@ -96,7 +104,9 @@ export default {
     };
   },
   methods: {
-    onExpire(o) { console.log(o); },
+    onExpire(o) {
+      console.log(o);
+    },
     onAction(item) {
       if (item.customActionHandler) {
         // 自定义行为（由调用方处理）
@@ -107,66 +117,85 @@ export default {
 };
 </script>
 ```
-  
+
+---
+
 ### Attributes
-| 参数| 说明 | 类型 | 默认值 |
+
+根级 props 控制弹窗与各区块是否出现；对象/数组的字段见下方分表。
+
+
+#### 根级 props
+
+| 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| value / v-model | 控制弹窗显示/隐藏 | Boolean | false |
-| closeOnClickOverlay | 是否点击外层区域关闭 | Boolean | false |
-| introduceImage | 顶部说明图地址 | String | '' |
-| expireData | 分享有效期配置（是否展示由该对象是否存在决定） | Object | {} |
-| explainData | 分享后说明配置（仅当 `explainData.text` 存在时展示） | Object | {} |
-| shareActions | 分享渠道入口列表 | Array | [] |
-| featureActions | 功能入口列表 | Array | [] |
-
-#### expireData 对象
-| 参数| 说明 | 类型 | 默认值 |
+| `value` / `v-model` | Boolean | `false` | 弹窗显示/隐藏 |
+| `closeOnClickOverlay` | Boolean | `false` | 是否允许通过点击遮罩层关闭（不包括说明图与内容区） |
+| `introduceImage` | String | — | 顶部说明图地址 |
+| `expireData` | Object | — | 传入则展示「分享有效期」模块 |
+| `explainData` | Object | — | `title` 或 `text` 有值则展示说明区 |
+| `shareActions` | Array | `[]` | 分享渠道入口列表 |
+| `featureActions` | Array | `[]` | 功能入口列表 |
+
+
+#### expireData
+
+| 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| value | 默认/当前选中的有效期值（用于计算 `expireTimestamp` 并在分享链接上追加 `wy_expire`） | String | - |
-| options | 可选，覆盖有效期单选项列表（仅用于展示；`value` 仍建议使用组件内枚举值以便计算 `expireTimestamp`） | Array | - |
-| urlAfterExpire | 点击“链接失效后客户看到什么？”的跳转地址 | String | - |
+| `value` | String | — | 当前选中的有效期；参与 `expireTimestamp` 与 `shareUrl` 上的 `wy_expire`；`NEVER` 不生成时间戳 |
+| `options` | Array | 有 | 可选，数组元素的 key，建议使用：NEVER、24h、72h、7d、15d、30d |
+| `urlAfterExpire` | String | — | 「链接失效后客户看到什么？」的跳转地址 |
+
 
-说明：组件内有效期枚举由 `constant.js` 定义，`value` 建议使用下列任意值：`NEVER`、`24h`、`72h`、`7d`、`15d`、`30d`。
+#### explainData
 
-#### explainData 对象
-| 参数| 说明 | 类型 | 默认值 |
+| 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| text | 分享后说明文案 | String | - |
-| copy | 点击文案时是否复制 `text`（会调用 `appBridge.copyString`） | Boolean | false |
+| `title` | String | — | 说明区标题（带下边框样式） |
+| `text` | String | — | 说明正文 |
+| `copy` | Boolean | — | 为 `true` 且有 `text` 时，点击正文调用 `appBridge.copyString(text)` |
+
+
+#### shareActions（单项）
 
-#### shareActions 数组（shareAction 对象）
-每一项至少需要 `action` 字段。点击分享项后会触发 `action` 事件；并且会尝试调用原生 `appBridge.share` / `appBridge.gotoNativeView`（或调用自定义 `customActionHandler`）。
+若 `action` 属于 `SHARE_ENUM` 且未提供 `customActionHandler`，会尝试调用 `appBridge.share` 或 `appBridge.gotoNativeView`（小程序）。
 
-| 参数| 说明 | 类型 | 默认值 |
+| 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| action | 分享渠道类型；组件从 `ACTION_ENUM` 读取对应的默认 `actionName`/`actionIcon`，并由 `SHARE_ENUM` 决定是否触发原生分享能力 | String | - |
-| actionName | 覆盖展示文案（可选） | String | - |
-| actionIcon | 覆盖展示图标（可选） | String | - |
-| customActionHandler | 自定义分享处理函数：存在时将调用 `customActionHandler(newItem)`，并跳过默认原生分享逻辑 | Function | - |
+| `action` | String | — | 必传，渠道类型；默认文案/图标来自 `ACTION_ENUM`；是否走内置原生分享由 `SHARE_ENUM` 决定 |
+| `actionName` | String | — | 可选，覆盖展示文案 |
+| `actionIcon` | String | — | 可选，覆盖展示图标 |
+| `customActionHandler` | Function | — | 存在时执行 `customActionHandler(newItem)`，并跳过内置原生分享 |
+
+**SHARE_ENUM**（内置原生分享）：
+* `wechat_friends`
+* `wechat_timeline`
+* `qq_friends`
+* `shareMiniProgram`
+* `system_share`。
+
+
+**透传字段**（按渠道自行传入，组件透传给原生）：
 
-触发原生分享（`SHARE_ENUM`）的 action 值：`wechat_friends`、`wechat_timeline`、`qq_friends`、`shareMiniProgram`、`system_share`。不在此列表中的 action 仅触发 `action` 事件，不会调用原生能力（除非提供 `customActionHandler`）。
+- 非小程序：`title`、`content`、`imgUrl`、`shareUrl`；可选 `introduction`、`imageData`、`type`
+- 小程序：`webPageUrl`、`userName`、`path`、`title`、`description`、`imageUrl`
 
-分享数据字段（由调用方按 action 自行提供；组件内部透传给原生能力）：
-- 非 `shareMiniProgram`：常用字段包括 `title`、`content`、`imgUrl`、`shareUrl`（组件内部会额外读取 `introduction`、`imageData`、`type`，若你们业务需要可一并传入）
-- `shareMiniProgram`：常用字段包括 `webPageUrl`、`userName`、`path`、`title`、`description`、`imageUrl`
+**链接过期**：当能算出 `expireTimestamp` 且该项有 `shareUrl` 时，会追加 `wy_expire=<expireTimestamp>`。
 
-有效期追加逻辑：
-- 当选择了有效期会计算出 `expireTimestamp`，并且该分享项存在 `shareUrl` 时，会在 `shareUrl` 上追加查询参数：`wy_expire=<expireTimestamp>`。
 
-#### featureActions 数组（featureAction 对象）
-每一项至少需要 `action` 字段。点击后触发 `action` 事件；组件本身不会在这里直接调用原生分享能力，仅会在满足有效期时给事件回参补充 `expireTimestamp`（若命中组件内枚举可计算）。
+#### featureActions（单项）
 
-| 参数| 说明 | 类型 | 默认值 |
+| 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| action | 功能类型；组件从 `ACTION_ENUM` 读取对应的默认 `actionName`/`actionIcon` | String | - |
-| actionName | 覆盖展示文案（可选） | String | - |
-| actionIcon | 覆盖展示图标（可选） | String | - |
-| customActionHandler | 可选字段：组件只会原样透传；是否调用由调用方在 `@action` 里自行处理 | Function | - |
+| `action` | String | — | 功能类型；默认文案/图标来自 `ACTION_ENUM` |
+| `actionName` | String | — | 可选，覆盖展示文案 |
+| `actionIcon` | String | — | 可选，覆盖展示图标 |
+| `customActionHandler` | Function | — | 可选，原样透传；是否在业务里调用由 `@action` 自行处理 |
 
-#### 内置 action 枚举（ACTION_ENUM）
-`ACTION_ENUM` 仅提供默认的 `actionName` 和 `actionIcon`。未在枚举中定义的 `action` 值也可正常传入，仅需自行提供 `actionName`/`actionIcon`。
 
-| action | 默认文案 |
+#### 内置 action 文案（ACTION_ENUM）
+
+| `action` | 默认文案 |
 | --- | --- |
 | `wechat_friends` | 微信好友 |
 | `wechat_timeline` | 朋友圈 |
@@ -188,15 +217,24 @@ export default {
 | `h5_cancel_frequently_used` | 取消常用 |
 | `h5_feedback` | 反馈 |
 
+---
+
 ### Methods
-无内置方法（当前组件仅通过属性/事件交互）。
+
+-
+
+---
 
 ### Events
-| 方法名 | 说明 | 参数 | 备注 |
+
+| 事件名 | 说明 | 参数 | 备注 |
 | --- | --- | --- | --- |
-| input | `v-model` 对应的值更新 | Boolean | 通过组件内部 `visible` 的 setter 触发 |
-| expire | 切换有效期单选项时触发 | Object | 单选项对象（包含 `value`/`name`/`millisecond`） |
-| action | 点击分享/功能入口时触发 | Object | shareActions：为 `shareHandler` 处理后的结果；featureActions：为克隆后的结果并可能附加 `expireTimestamp` |
+| `input` | `v-model` 同步 | Boolean | 弹窗显隐变化时触发 |
+| `expire` | 切换有效期单选项 | Object | 含 `value`、`name`、`millisecond` 等 |
+| `action` | 点击分享或功能入口 | Object | 分享项：经 `shareHandler` 处理；功能项：深拷贝，可能含 `expireTimestamp` |
+
+---
 
 ### Slot
-- `header`：顶部内容插槽（会插在有效期/说明区域之后、分享列表之前）
+
+- `header`：位于**有效期模块之后**、**分享渠道列表之前**。