社区分享预置

share.showShareMenu() 和 share.screenshot() 可以给客户端的“转发到社区”流程预置分区与话题。预置内容进入发帖页后仍可由用户修改，SDK 不会直接发布内容。

普通分享

普通分享的落地页固定为当前小程序的 common_share，不接受自定义 url。普通分享只支持一个默认分区，并且配置 post 时不要同时指定站外 channel。

import { share } from '@heybox/hb-sdk'

await share.showShareMenu({
  title: '本局战绩',
  desc: '查看我的完整战绩',
  post: {
    topicIds: [235709],
    topics: ['无畏契约战绩'],
  },
})

截图分享

截图分享可以预置多个分区，客户端发帖页负责最终选择与确认。进入社区发帖流程后，客户端会自动把帖子关联到当前小程序，开发者无需配置额外来源字段。

SDK 在每次调用截图时输出行为变更 warning，提醒版本门槛、底部预留区域和明暗配色。这是 SDK 侧的升级提示，日志输出失败不影响截图调用；Runtime 只负责按版本选择水印行为，不输出兼容警告。

升级注意：正式 SDK 0.9.1 起默认添加截图水印。 新 Runtime 使用已校验的 SDK 版本记录判断：低于 0.9.1（包括 0.9.1-alpha.*）时，Runtime 静默跳过水印，产物不加水印；版本记录缺失的兼容模式同样不加水印。0.9.1 及以上保持默认水印行为。升级 SDK 时必须同时检查下述预留区域与配色要求。

启用水印后，调用 share.screenshot() 时，Runtime 自动在目标截图区域底部居中添加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，下方为灰色「小黑盒工坊小程序」。水印进入截图后随图片用于预览、保存、站外分享及社区发帖，开发者无需自行绘制。

布局要求：在目标截图区域底部预留至少 57 个逻辑像素的空白背景，不要放置成绩、正文、按钮等重要内容；背景应与所选水印配色保持足够对比度。使用自定义 rect 时，预留区域以该矩形底部为准。水印叠加在区域内，不会额外增加图片高度；正常浏览时不常驻，仅在 SDK 截图期间展示，完成或失败后移除。系统按键截图暂不支持添加此水印。

可通过 watermarkTheme 按截图背景选择配色：light 适合浅色背景，使用黑色图标、边框和名称；dark 适合深色背景，使用白色图标、边框和名称。说明文字分别为 40% 黑色或白色。默认 dark，保持现有白色水印效果，不自动跟随 App 或系统主题；旧 Runtime 可能忽略此字段。

await share.screenshot({
  watermarkTheme: 'light', // 浅色截图背景使用黑色水印
  delay: 100,
  saveToAlbum: true,
  post: {
    topicIds: [235709, 66739],
    topics: ['无畏契约战绩'],
  },
})

截图等待不受 SDK 普通请求的固定超时限制。排队和 delay 期间会响应会话终止；移动端从投递原生截图起最多等待 15 秒成图回调，已投递的截图无法保证撤回。结果为不透明值，不要根据返回值的真假判断用户是否分享成功。

调用前需声明并启用 share 权限。Android、iOS、OHOS 的移动 Host 提供真实截图分享；当前新 PC 的 Windows/macOS Host 未开放，应处理 METHOD_FORBIDDEN。Browser Dev Host 仅展示参数确认，仍需真机验收。完整参数与平台边界见 share.screenshot()。

恢复分享页面状态

通过固定通用分享链接分享时，可以使用 extra 携带由小程序自行定义的页面状态。分享方只负责写入状态，接收方负责决定如何使用：

await share.showShareMenu({
  title: '排行榜',
  desc: '查看当前排名',
  extra: { page: 'ranking', options: [1, 2, 3] },
})

需要由业务按钮复制链接时，传入同样的状态即可：

const shareUrl = await share.copyLink({
  extra: { page: 'ranking', options: [1, 2, 3] },
})

copyLink() 完成时链接已写入系统剪贴板，并返回同一个完整链接。它不会自动弹出提示，建议在用户点击后调用并自行展示成功反馈。

小程序被分享链接打开后，用同步的 getExtra() 读取状态，再交给自己的路由：

const sharedState = share.getExtra()
const routeMap = { ranking: '#/ranking', profile: '#/profile' } as const

if (sharedState && typeof sharedState === 'object' && !Array.isArray(sharedState)) {
  const page = sharedState.page
  const target = typeof page === 'string' ? routeMap[page as keyof typeof routeMap] : undefined
  if (target) window.location.hash = target
}

getExtra() 不依赖异步请求；没有有效数据时返回 undefined，业务应回退到默认首页。extra 只支持 JSON-compatible 数据，最多 8 层，单个数组或对象最多 64 项，内容不超过 128 字节，也不要存放 token、个人信息等敏感数据。copyLink() 不会继承当前启动链接中的 extra，只携带本次显式传入的数据。

参数边界

topicIds 接受正整数或非空字符串，按首次出现顺序去重。
topics 只传话题内容，不要添加首尾 #；字符串会先 trim 再去重。
post: null 等同于不配置社区发帖预置，post: {} 是无效配置。
本地 Mock、App Dev Shell 和开发 Runtime 会对无效配置返回 INVALID_PARAMS。
生产 Runtime 会过滤无效项；普通分享只使用第一个有效分区，配置冲突时保留站外 channel，不会阻断原分享流程。

调用方不能通过该 API 传客户端协议、回调、自定义按钮或发布指令。

社区分享预置 ​

普通分享 ​

截图分享 ​

恢复分享页面状态 ​

参数边界 ​

社区分享预置

普通分享

截图分享

恢复分享页面状态

参数边界