@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/modules/share/index.d.ts

@@ -13,6 +13,40 @@ export interface MiniProgramShareModule {
     /**
      * 复制当前小程序的通用分享链接，并返回该链接。
      *
+     * @param options - 可选配置；只接受本次链接需要携带的 `extra`。省略 `options` 或
+     * `options.extra` 时生成不带扩展数据的链接。
+     * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
+     * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
+     * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
+     * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+     * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
+     * 对应错误码。
+     *
+     * @remarks
+     * 该方法生成当前小程序的固定通用落地页，不复制当前页面路径或 hash，也不继承启动 URL
+     * 中已有的 `extra`。显式传入的 `extra` 会按 {@link MiniProgramShareExtraValue} 约束编码为
+     * Base64URL 参数；接收方使用 {@link MiniProgramShareModule.getExtra | share.getExtra} 还原值。
+     *
+     * 该调用需要在 `package.json#heybox.permissions` 声明并启用 `share`，但不额外要求
+     * `clipboard` 权限或可信用户手势。它只写入系统剪贴板，不会打开分享面板或自动显示成功
+     * 提示；需要直接打开分享面板时使用
+     * {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const copiedUrl = await hbSDK.share.copyLink({
+     *   extra: { page: 'ranking', season: 12 },
+     * })
+     *
+     * console.log('已复制分享链接', copiedUrl)
+     * ```
+     *
+     * @see {@link MiniProgramShareModule.getExtra | share.getExtra}
+     * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.7.4-alpha.5
      * @hbPlatform android
      * @hbPlatform ios
@@ -29,6 +63,46 @@ export interface MiniProgramShareModule {
     /**
      * 同步获取小程序启动时携带的分享扩展数据；没有有效数据时返回 `undefined`。
      *
+     * @returns 启动 URL 中有效的 `extra` 解码值。`null`、`false`、`0` 和空字符串都是有效
+     * 返回值；只有 URL 或参数缺失、编码/MessagePack 非法、超出限制或值类型不受支持时才返回
+     * `undefined`。所有非法输入都会静默降级，不会抛出异常。
+     *
+     * @remarks
+     * 该方法无参数且同步返回。SDK 实例创建时会捕获一次启动 URL，后续调用始终解析这份快照；
+     * `history.pushState`、`history.replaceState`、hash 变化或页面内路由跳转不会改变结果。需要处理
+     * 新分享链接时，应让宿主以该链接重新启动小程序。
+     *
+     * 解码器只接受启动 URL 查询参数中的无填充 Base64URL `extra`，解码后的 MessagePack 最多
+     * 128 字节；值必须符合 {@link MiniProgramShareExtraValue}，最多嵌套 8 层，单个数组或对象
+     * 最多 64 项。含 `+`、`/` 或填充 `=` 的标准 Base64、JSON 文本的 Base64、损坏的
+     * MessagePack、非有限数字和其他非 JSON-compatible 值均返回 `undefined`。
+     *
+     * `getExtra()` 完全在当前页面本地解析，不等待握手、不发起 bridge/Host 请求、不要求权限
+     * 声明或可信用户手势，即使 SDK 握手失败也可以调用。它不会读取此前调用
+     * {@link MiniProgramShareModule.copyLink | share.copyLink}、
+     * {@link MiniProgramShareModule.showShareMenu | share.showShareMenu} 或
+     * {@link MiniProgramShareModule.screenshot | share.screenshot} 的内存状态：只有本次启动 URL
+     * 中的 `extra` 是数据源。其中 `copyLink` 和 `showShareMenu` 可生成携带 `extra` 的通用分享
+     * 链接，`screenshot` 不会为 `getExtra()` 写入扩展数据。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const extra = hbSDK.share.getExtra()
+     *
+     * if (extra && typeof extra === 'object' && !Array.isArray(extra)) {
+     *   const page = extra.page
+     *   if (page === 'ranking') window.location.hash = '#/ranking'
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramShareExtraValue}
+     * @see {@link MiniProgramShareModule.copyLink | share.copyLink}
+     * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
+     * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share | 社区分享预置}
+     *
      * @since 0.7.4-alpha.5
      * @hbPlatform android
      * @hbPlatform ios
@@ -45,6 +119,76 @@ export interface MiniProgramShareModule {
     /**
      * 展示以当前小程序通用分享页为落地页的基础分享面板。
      *
+     * @param options - 必填标题、描述，以及可选缩略图、渠道、扩展数据和社区发帖预置；每个
+     * 字段的规范化与降级规则见 {@link MiniProgramShowShareMenuOptions}。
+     * @returns Host 分享面板返回的 `unknown` 不透明值。平台和客户端版本可能返回 `undefined`
+     * 或不同对象，不能依赖字段或用真假值判断用户是否完成、取消或成功发布。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS` 表示参数不是对象，`title` / `desc`
+     * trim 后为空，出现自定义 `url`，`imageUrl` 不是 HTTP(S)，`channel` 不在公开枚举内，
+     * `extra` 超出编码限制，缺少 canonical 小程序身份/有效当前 URL，或开发态 `post` 无效、
+     * 超过一个分区、与 `channel` 冲突。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
+     * `share` 权限未声明或未启用；`METHOD_FORBIDDEN` / `METHOD_NOT_FOUND` 表示当前 Host 未开放
+     * 分享面板；`REQUEST_UNSUPPORTED` 表示 Host 不支持当前分享参数或渠道。
+     * @throws {@link HbMiniProgramSDKError} `RUNTIME_DESTROYED` / `RUNTIME_UNAVAILABLE` /
+     * `SDK_DESTROYED` 表示 Runtime、容器或 SDK 已进入终态。SDK 握手失败或 Host 面板调用超时
+     * 时，还会返回对应握手错误码或 `REQUEST_TIMEOUT`；其他 Host 分享错误保留其 SDK 错误码。
+     *
+     * @remarks
+     * Runtime 使用 Host 确认的 canonical 小程序 ID 构造固定通用落地页，并按可用情况附带当前
+     * 小程序版本、启动 URL 的 `h_src` 和本次显式传入的 `extra`。不能传自定义 `url`，也不会
+     * 继承当前启动 URL 中已有的 `extra`。接收方新启动小程序后用
+     * {@link MiniProgramShareModule.getExtra | share.getExtra} 同步读取该值。
+     *
+     * `channel` 用于站外渠道，`post` 用于社区发帖页预置，两者不要同时配置。`post.topicIds`
+     * 会转换为字符串、trim、去重，普通分享最多保留第一项；`post.topics` 会 trim、拒绝首尾
+     * `#` 并去重。开发 Runtime 对任一无效项或冲突返回 `INVALID_PARAMS`；生产 Runtime 会过滤
+     * 无效项，在冲突时保留 `channel`、省略 `post`，继续打开基础面板。社区预置只填充可编辑
+     * 发帖页，用户仍可修改或取消，SDK 不能直接发布内容。
+     *
+     * 该方法需要声明并启用 `share`，但不额外要求 `network`、`clipboard` 权限或可信用户手势；
+     * 分享面板内仍由用户完成最终确认。移动端 Host 支持分享面板；当前新 PC Host 未开放，
+     * Windows/macOS 调用应处理 `METHOD_FORBIDDEN`。Browser Dev Host 的确认弹窗只用于开发模拟。
+     *
+     * `showShareMenu` 不截图，也不会隐藏小程序导航栏或其他 Host chrome。需要把当前画面交给
+     * 分享流程时使用 {@link MiniProgramShareModule.screenshot | share.screenshot}；后者会在
+     * capture 前临时隐藏截图 chrome，并在结束后尽力恢复。只需复制同一固定落地链接时使用
+     * {@link MiniProgramShareModule.copyLink | share.copyLink}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * async function shareToWechat() {
+     *   await hbSDK.share.showShareMenu({
+     *     title: '本周战绩',
+     *     desc: '查看我的最新战绩',
+     *     imageUrl: 'https://cdn.example.com/share/weekly.png',
+     *     channel: 'wechatSession',
+     *     extra: { tab: 'weekly' },
+     *   })
+     * }
+     *
+     * async function shareToCommunity() {
+     *   await hbSDK.share.showShareMenu({
+     *     title: '本周战绩',
+     *     desc: '查看我的最新战绩',
+     *     post: {
+     *       topicIds: [235709],
+     *       topics: ['无畏契约战绩'],
+     *     },
+     *   })
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramShowShareMenuOptions}
+     * @see {@link MiniProgramSharePostOptions}
+     * @see {@link MiniProgramShareModule.copyLink | share.copyLink}
+     * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
+     * @see {@link MiniProgramShareModule.getExtra | share.getExtra}
+     * @see [社区分享预置](/recipes/community-share)
+     * @see [权限声明](/guide/permissions)
+     *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
      * @hbPlatform ios
@@ -61,6 +205,71 @@ export interface MiniProgramShareModule {
     /**
      * 截图并唤起分享。
      *
+     * @param options - 可选截图配置。省略时使用调用时的整个可见窗口；字段约束见
+     * {@link MiniProgramScreenshotOptions}。
+     * @returns Host 截图分享流程返回的 `unknown` 不透明值。不同平台和客户端版本可能返回
+     * `undefined` 或不同对象，不能依赖字段或用真假值判断分享成功。
+     * @throws {@link HbMiniProgramSDKError} `options` 是数组或非对象值（省略值和运行时 `null`
+     * 除外），`rect` 不是对象或其坐标、尺寸经 `Number(...)` 转换后不是有效范围，`delay`
+     * 转换后不是非负有限数，
+     * `saveToAlbum` 不是布尔值，或开发 Runtime 中 `post` 含无效项时以 `INVALID_PARAMS`
+     * 拒绝。未声明或未启用 `share` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放截图能力时以
+     * `METHOD_FORBIDDEN` 拒绝，不支持请求形状时可能以 `REQUEST_UNSUPPORTED` 拒绝。握手失败、
+     * SDK/Runtime 已销毁、bridge 超时或 Host 截图失败时抛出对应 SDK 错误。用户取消由
+     * Host 决定返回不透明结果还是错误，不能依赖统一形态。
+     *
+     * @remarks
+     * `rect` 使用与 {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo}
+     * 相同的当前窗口逻辑像素坐标；省略时 Runtime 在调用时读取窗口，构造从 `(0, 0)` 到
+     * `windowWidth × windowHeight` 的矩形。Runtime 校验有限数和正负范围，但不取整、不按
+     * `pixelRatio` 换算，也不把越界矩形夹取到窗口内。JavaScript 的 coercible 非 number 值可能被
+     * 当前 Runtime 接受，但这不是 TypeScript 公共合同，不应依赖。
+     *
+     * `delay` 省略时由 Host 使用默认延迟；`saveToAlbum` 省略时由 Host 决定是否提供相册
+     * 入口。`post` 会对分区 ID 和话题 trim、规范化及去重。截图分享允许多个分区；开发
+     * Runtime 对任一无效项返回 `INVALID_PARAMS`，生产 Runtime 过滤无效项，并在没有有效项
+     * 时省略 `post` 后继续截图。社区预置只填充可编辑的发帖页，不会自动发布。
+     *
+     * Runtime 在截图前请求隐藏可能进入成图的 Host 顶部视觉外壳（例如开发者入口），并在
+     * Host 成功、失败或 Runtime 终止后都尝试恢复。恢复是 best-effort：非终止场景下的恢复
+     * 失败不会覆盖原始截图结果或错误；具体隐藏范围由 Host 决定，这不代表 Mini-program
+     * 自己的 DOM 会被隐藏。
+     *
+     * 该调用需要在 `package.json#heybox.permissions` 声明并启用 `share`，但不要求可信用户
+     * 手势。Android、iOS、OHOS 的移动 Host 已实现真实截图分享；当前新 PC Host 在 Windows
+     * 和 macOS 上禁用该能力，应处理 `METHOD_FORBIDDEN`。Browser Dev Host 只展示参数确认，
+     * 不读取页面像素，也不能替代真机验收。
+     *
+     * 与 {@link MiniProgramShareModule.showShareMenu | share.showShareMenu} 相比，本方法分享
+     * 截图且不接收标题、描述、`channel` 或 `extra`；需要通用分享落地页或让接收方通过
+     * {@link MiniProgramShareModule.getExtra | share.getExtra} 恢复状态时，应使用
+     * `showShareMenu()`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const { windowWidth, windowHeight } = await hbSDK.viewport.getWindowInfo()
+     *
+     * await hbSDK.share.screenshot({
+     *   rect: { left: 0, top: 0, width: windowWidth, height: windowHeight },
+     *   delay: 100,
+     *   saveToAlbum: true,
+     *   post: {
+     *     topicIds: [235709, '66739'],
+     *     topics: ['无畏契约战绩'],
+     *   },
+     * })
+     * ```
+     *
+     * @see {@link MiniProgramScreenshotOptions}
+     * @see {@link MiniProgramScreenshotRect}
+     * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
+     * @see {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share | 社区分享预置}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
      * @hbPlatform ios
@@ -79,6 +288,7 @@ export interface MiniProgramShareModule {
  * 创建分享模块。
  *
  * @param requester - 底层 bridge 请求能力。
+ * @param launchHref - 可选的小程序启动 URL；`getExtra()` 从这里同步解析分享扩展数据。
  * @returns 面向业务层的分享模块对象。
  */
 export declare function createShareModule(requester: MiniProgramRequester, launchHref?: string): MiniProgramShareModule;

package/types/modules/share/screenshot.d.ts

@@ -1,16 +1,34 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramScreenshotOptions } from './types';
 export { SHARE_SCREENSHOT_METHOD } from '../../protocol/capabilities';
-/** `share.screenshot` 入参。 */
+/**
+ * `share.screenshot` 的可选入参；省略时截取调用时的当前可见窗口。
+ *
+ * @see {@link MiniProgramScreenshotOptions}
+ */
 export type ScreenshotPayload = MiniProgramScreenshotOptions | undefined;
-/** `share.screenshot` 返回值由客户端协议决定。 */
+/**
+ * `share.screenshot` 透传的 Host 截图分享结果。
+ *
+ * @remarks
+ * 结果类型刻意为 `unknown`：不同平台、客户端版本以及用户完成或取消分享时可能返回
+ * `undefined` 或不同对象。调用方不得依赖字段、用真假值判断分享成功，或把该值持久化
+ * 为跨版本协议。
+ */
 export type ScreenshotResult = unknown;
 /**
  * 截图并唤起分享。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 截图区域、延迟与保存相册等配置。
- * @returns 由宿主客户端协议决定的结果。
- * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @param options - 可选截图配置；省略时截取当前可见窗口。
+ * @returns Host 返回的不透明截图分享结果；不要依赖其具体结构。
+ * @throws {@link HbMiniProgramSDKError} 参数、权限、bridge、Runtime 或 Host 截图能力失败时抛出。
+ *
+ * @remarks
+ * 公开业务代码通常通过 {@link MiniProgramShareModule.screenshot | share.screenshot} 调用；
+ * 完整参数、平台和恢复语义见该方法。
+ *
+ * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
+ * @see {@link MiniProgramScreenshotOptions}
  */
 export declare function screenshot(requester: MiniProgramRequester, options?: MiniProgramScreenshotOptions): Promise<ScreenshotResult>;

package/types/modules/share/show-share-menu.d.ts

@@ -1,16 +1,29 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramShowShareMenuOptions } from './types';
 export { SHARE_SHOW_SHARE_MENU_METHOD } from '../../protocol/capabilities';
-/** `share.showShareMenu` 入参。 */
+/**
+ * `share.showShareMenu` 入参；落地页固定为当前小程序的通用分享页。
+ *
+ * @see [share.showShareMenu](/reference/sdk/share/showShareMenu)
+ */
 export type ShowShareMenuPayload = MiniProgramShowShareMenuOptions;
-/** `share.showShareMenu` 返回值由客户端协议决定。 */
+/**
+ * 客户端分享面板返回的不透明值。
+ *
+ * @remarks
+ * Host 可能返回 `undefined` 或任意对象，不同平台和版本没有稳定字段。不能用结构或真假值判断
+ * 用户是否完成、取消或成功发布；只在 Promise rejection 时按公开错误码处理失败。
+ */
 export type ShowShareMenuResult = unknown;
 /**
  * 展示以当前小程序通用分享页为落地页的基础分享面板。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 基础分享参数。
- * @returns 由宿主客户端协议决定的结果。
- * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @param options - 标题、描述，以及可选缩略图、渠道、扩展数据和社区发帖预置。
+ * @returns Host 分享面板返回的 `unknown` 不透明值；不能依赖字段或真假值判断分享结果。
+ * @throws {@link HbMiniProgramSDKError} 参数、固定落地页身份、`extra` 或开发态 `post` 校验失败
+ * 时返回 `INVALID_PARAMS`；权限、Host 能力及生命周期错误见公开模块方法文档。
+ * @remarks 不支持自定义 `url`、宿主回调或直接发布；社区预置仍由用户在客户端修改确认。
+ * @see [share.showShareMenu](/reference/sdk/share/showShareMenu)
  */
 export declare function showShareMenu(requester: MiniProgramRequester, options: ShowShareMenuPayload): Promise<ShowShareMenuResult>;

package/types/modules/share/types.d.ts

@@ -2,59 +2,145 @@
  * 小程序可选分享渠道。
  *
  * @remarks
- * 不同宿主环境可支持的渠道集合可能不同；未传 `channel` 时由客户端自行展示默认分享面板。
+ * `wechatSession` / `wechatTimeline` / `qqFriend` / `qzone` / `weibo` 分别表示微信好友、
+ * 微信朋友圈、QQ 好友、QQ 空间和微博。值区分大小写；Host 可以只支持其中一部分。
+ * `share.showShareMenu()` 省略 `channel` 时由客户端展示默认分享面板；指定 `channel` 时不能
+ * 同时配置有效的社区 `post` 预置。
  */
 export type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
-/** 分享扩展数据支持的 JSON-compatible 类型。 */
+/**
+ * 分享扩展数据支持的 JSON-compatible 类型。
+ *
+ * @remarks
+ * 只允许 `null`、有限数字、字符串、布尔值、数组和普通对象；`undefined`、`NaN`、
+ * `Infinity`、`bigint`、`symbol`、函数、循环引用、`Date`、`Map` 和其他 class 实例均不受支持。
+ * 合法的 `null`、`false`、`0` 与空字符串在 {@link MiniProgramShareModule.getExtra | share.getExtra}
+ * 中会原样返回，不能用真假值判断是否存在分享数据。
+ *
+ * 编码后的 MessagePack 最多 8 层嵌套，单个数组或对象最多 64 项，总容量不超过 128 字节；
+ * 超限时分享 API 返回 `INVALID_PARAMS`，接收端 `getExtra()` 则对非法启动参数返回 `undefined`。
+ * 不要把 token、cookie、个人信息或其他敏感数据放入分享 URL。
+ */
 export type MiniProgramShareExtraValue = null | boolean | number | string | readonly MiniProgramShareExtraValue[] | {
     readonly [key: string]: MiniProgramShareExtraValue;
 };
-/** 复制当前小程序分享链接的配置。 */
+/**
+ * 复制当前小程序通用分享链接的配置。
+ *
+ * @remarks 该配置不能自定义落地 URL；省略整个配置等同于省略 `extra`。
+ */
 export interface MiniProgramCopyLinkOptions {
-    /** 分享扩展数据；最多 8 层、单层最多 64 项、容量不超过 128 字节。 */
+    /**
+     * 随本次分享链接携带、供接收方通过
+     * {@link MiniProgramShareModule.getExtra | share.getExtra} 读取的业务状态。
+     *
+     * @remarks
+     * 值域只允许 `null`、有限数字、字符串、布尔值、数组和普通对象。`undefined`、`NaN`、
+     * `Infinity`、`bigint`、`symbol`、函数、循环引用、`Date`、`Map` 及其他 class 实例都会以
+     * `INVALID_PARAMS` 拒绝。
+     *
+     * 最多嵌套 8 层，每个数组最多 64 项，每个对象最多 64 个字段。容量按 MessagePack
+     * 编码后的字节数计算，必须不超过 128 字节；不是按 `JSON.stringify` 后的字符数计算。
+     * Runtime 会再把字节编码为无填充 Base64URL 参数，调用方不要预先 JSON 序列化、Base64
+     * 编码或拼接 URL。省略该字段时，链接不携带 `extra`，也不会继承当前启动链接中的值。
+     *
+     * 不要在分享 URL 中放入 token、cookie、个人信息或其他敏感数据。
+     *
+     * @see {@link MiniProgramShareExtraValue}
+     * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
+     */
     extra?: MiniProgramShareExtraValue;
 }
-/** 社区发帖预置配置。 */
+/**
+ * 客户端“转发到社区”发帖页的可编辑预置。
+ *
+ * @remarks
+ * 预置只填充客户端发帖页，用户仍可修改或取消，不会由 SDK 直接发布。`showShareMenu` 最多
+ * 保留一个分区，`screenshot` 可保留多个分区；两者都会按首次出现顺序去重。
+ *
+ * 开发 Runtime 对任一无效项返回 `INVALID_PARAMS`，生产 Runtime 则过滤无效项；过滤后没有
+ * 任何有效分区或话题时省略整个 `post`，但继续原分享流程。
+ *
+ * @see [社区分享预置](/recipes/community-share)
+ */
 export interface MiniProgramSharePostOptions {
-    /** 默认发布分区 ID；普通分享只使用第一项，截图分享支持多项。 */
+    /**
+     * 默认发布分区 ID。number 必须是正安全整数并转换为字符串；string 会 trim 且必须非空。
+     * 规范化后按首次出现顺序去重，普通分享最多保留第一项，截图分享可保留多项。
+     */
     topicIds?: (string | number)[];
-    /** 预置话题内容，不包含首尾 `#`。 */
+    /**
+     * 预置话题正文。每项必须是 string，trim 后非空且不能以 `#` 开头或结尾；规范化后按首次
+     * 出现顺序去重。传正文即可，不要自行包裹 `#`。
+     */
     topics?: string[];
 }
 /**
  * 展示基础分享面板的配置。
  *
  * @remarks
- * 分享落地页固定为当前小程序的通用分享页。该配置只暴露基础分享字段，不暴露宿主内部上报、回调、自定义按钮等协议参数。
+ * 分享落地页固定为当前小程序的通用分享页。该配置只暴露基础分享字段，不暴露宿主内部
+ * 上报、回调、自定义按钮、直接发布等协议参数。`url` 即使值为 `undefined` 也不允许出现；
+ * 其他未知字段不会传给 Host。
  */
 export interface MiniProgramShowShareMenuOptions {
-    /** 分享标题。 */
+    /** 分享标题；必须是 trim 后非空的字符串，前后空白不会被 SDK 改写。 */
     title: string;
-    /** 分享描述。 */
+    /** 分享描述；必须是 trim 后非空的字符串，前后空白不会被 SDK 改写。 */
     desc: string;
-    /** 分享扩展数据；最多 8 层、单层最多 64 项、容量不超过 128 字节。 */
+    /**
+     * 写入固定落地页 URL、供接收方 {@link MiniProgramShareModule.getExtra | share.getExtra}
+     * 读取的业务状态；遵守 {@link MiniProgramShareExtraValue} 的类型、深度、项数和 128 字节限制。
+     * 省略时不携带 `extra`，也不会继承当前启动链接中的值。
+     */
     extra?: MiniProgramShareExtraValue;
-    /** 分享缩略图 URL。 */
+    /**
+     * 分享缩略图的绝对 URL；必须是非空字符串、可由 `URL` 解析，且协议严格为 `http:` 或
+     * `https:`。SDK 只校验 URL，不负责下载、裁剪或确认 Host 最终采用该图片。
+     */
     imageUrl?: string;
-    /** 指定分享渠道；不传则由客户端展示默认分享面板。 */
+    /**
+     * 指定站外分享渠道；省略时由客户端展示默认面板。不能与有效 `post` 同时使用，且具体
+     * 渠道是否可用由 Host 决定。
+     */
     channel?: MiniProgramShareChannel;
-    /** 转发到社区时使用的分区与话题预置；`null` 等同于不配置。 */
+    /**
+     * 转发到社区时使用的分区与话题预置；`null` 或省略表示不预置。
+     *
+     * @remarks
+     * 普通分享最多保留一个规范化后的 `topicIds`，但可保留多个去重后的 `topics`。开发态对
+     * 无效项、空预置、多个分区或与 `channel` 的冲突返回 `INVALID_PARAMS`；生产态会过滤无效项、
+     * 截断到首个分区，并在冲突时保留 `channel`、省略 `post`，不会阻断基础分享面板。
+     * 用户进入发帖页后仍可修改或取消，SDK 不会直接发布帖子。
+     */
     post?: MiniProgramSharePostOptions | null;
 }
 /**
  * 截图区域。
  *
  * @remarks
- * 坐标与尺寸单位均为像素，基于当前小程序可见窗口坐标系。
+ * 坐标与尺寸均使用当前小程序可见窗口的逻辑像素，原点是窗口左上角，与
+ * {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo} 返回的
+ * `windowWidth`、`windowHeight` 使用同一坐标系。TypeScript 调用方应传有限 number；当前
+ * Runtime 会先用 `Number(...)` 转换 JavaScript 值再校验范围，因此字符串、boolean、`null`
+ * 等可能被兼容转换，业务不应依赖该宽松行为。Runtime 不会取整，也不会把矩形夹取到窗口边界；调用方应确保
+ * `left + width <= windowWidth`、`top + height <= windowHeight`。
+ *
+ * 省略整个 `rect` 时，Runtime 会在调用时读取当前窗口并构造
+ * `{ left: 0, top: 0, width: windowWidth, height: windowHeight }`。窗口可能在用户拖动、
+ * 旋转设备或 Host 恢复后变化，不要长期缓存旧矩形。
+ *
+ * @see {@link MiniProgramScreenshotOptions.rect}
+ * @see {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo}
  */
 export interface MiniProgramScreenshotRect {
-    /** 截图区域左边距。 */
+    /** 截图区域左边缘距窗口左边缘的逻辑像素数；转换后必须有限且大于等于 `0`。 */
     left: number;
-    /** 截图区域上边距。 */
+    /** 截图区域上边缘距窗口上边缘的逻辑像素数；必须是有限且大于等于 `0` 的数。 */
     top: number;
-    /** 截图区域宽度。 */
+    /** 截图区域宽度，单位逻辑像素；必须是有限且大于 `0` 的数。 */
     width: number;
-    /** 截图区域高度。 */
+    /** 截图区域高度，单位逻辑像素；必须是有限且大于 `0` 的数。 */
     height: number;
 }
 /**
@@ -62,14 +148,53 @@ export interface MiniProgramScreenshotRect {
  *
  * @remarks
  * 该配置只暴露截图与保存相册相关基础字段，不暴露宿主内部上传、回调或样式扩展能力。
+ * 所有字段均可省略；省略整个配置等同于传入空配置，并在调用时截取当前可见窗口。
+ * JavaScript 调用在运行时传入 `null` 也会按空配置处理，但 TypeScript 调用方应直接省略参数。
+ *
+ * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
  */
 export interface MiniProgramScreenshotOptions {
-    /** 指定截图区域；不传则默认截当前可见窗口。 */
+    /**
+     * 指定截图区域；省略时截取调用时的整个可见窗口。
+     *
+     * @remarks
+     * 字段单位、有效范围和窗口边界要求见 {@link MiniProgramScreenshotRect}。Runtime 不会
+     * 自动按设备像素比换算，也不会裁正越界矩形。
+     */
     rect?: MiniProgramScreenshotRect;
-    /** 截图延迟，单位毫秒。 */
+    /**
+     * Host 开始截图前的延迟，单位毫秒；TypeScript 调用应传 number，Runtime 用 `Number(...)`
+     * 转换后要求有限且大于等于 `0`。
+     *
+     * @remarks
+     * Runtime 不要求整数，也不设置上限。省略时不会下发 `delay`，由当前 Host 使用默认值；
+     * Host 仍可按平台能力拒绝过大的值。
+     */
     delay?: number;
-    /** 是否展示保存到相册能力。 */
+    /**
+     * 是否在客户端截图分享流程中提供保存到系统相册的能力。
+     *
+     * @remarks
+     * `true` 明确请求提供，`false` 明确关闭。省略时不会下发该开关，由当前 Host 决定
+     * 默认行为；该字段本身不表示图片已经保存成功。
+     */
     saveToAlbum?: boolean;
-    /** 转发到社区时使用的分区与话题预置；`null` 等同于不配置。 */
+    /**
+     * 转发到社区时使用的分区与话题预置；`null` 或省略表示不预置。
+     *
+     * @remarks
+     * 截图分享支持多个分区。`topicIds` 中的正安全整数会转成字符串，字符串会 trim，
+     * 再按首次出现顺序去重；`topics` 会 trim、拒绝首尾 `#`，再按首次出现顺序去重。
+     * 预置必须至少保留一个有效的 `topicIds` 或 `topics` 项。
+     *
+     * 开发 Runtime 遇到任一无效项会以 `INVALID_PARAMS` 拒绝，生产 Runtime 则过滤无效项，
+     * 将剩余有效项交给客户端；没有有效项时省略整个 `post`，但继续截图。预置只填充
+     * 客户端发帖页，用户仍可修改或取消，不会直接发布内容。
+     * 当前小程序来源由 Runtime 使用 Host 确认的 canonical identity 自动关联，调用方不能
+     * 也无需传入小程序 ID 或其他来源字段。
+     *
+     * @see {@link MiniProgramSharePostOptions}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share | 社区分享预置}
+     */
     post?: MiniProgramSharePostOptions | null;
 }