@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 截图并唤起分享。

      参数

      返回 Promise<unknown>

      Host 截图分享流程返回的 unknown 不透明值。不同平台和客户端版本可能返回 undefined 或不同对象,不能依赖字段或用真假值判断分享成功。

      HbMiniProgramSDKError options 是数组或非对象值(省略值和运行时 null 除外),rect 不是对象或其坐标、尺寸经 Number(...) 转换后不是有效范围,delay 转换后不是非负有限数, saveToAlbum 不是布尔值,或开发 Runtime 中 post 含无效项时以 INVALID_PARAMS 拒绝。当前运行快照缺少或未启用 share 权限时分别以 PERMISSION_NOT_IN_SNAPSHOT、PERMISSION_DENIED 拒绝;当前 Host 未开放截图能力时以 METHOD_FORBIDDEN 拒绝,不支持请求形状时可能以 REQUEST_UNSUPPORTED 拒绝。握手失败、 SDK/Runtime 已销毁、bridge 超时或 Host 截图失败时抛出对应 SDK 错误。用户取消由 Host 决定返回不透明结果还是错误,不能依赖统一形态。

      rect 使用与 viewport.getWindowInfo 相同的当前窗口逻辑像素坐标;省略时 Runtime 在调用时读取窗口,构造从 (0, 0) 到 windowWidth × windowHeight 的矩形。Runtime 校验有限数和正负范围,但不取整、不按 pixelRatio 换算,也不把越界矩形夹取到窗口内。JavaScript 的 coercible 非 number 值可能被 当前 Runtime 接受,但这不是 TypeScript 公共合同,不应依赖。

      SDK 每次调用都会输出 warning,提醒水印行为变化及布局、配色要求;日志失败不阻断截图。 新 Runtime 按 Version record 中已校验的 SDK 版本启用水印:低于正式版 0.9.1 (包括 0.9.1-alpha.*)或兼容模式下版本缺失时,静默保持无水印截图; 0.9.1 及以上默认添加水印。升级 SDK 前应同步调整截图布局。

      启用水印时,Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊, 下方显示灰色「小黑盒工坊小程序」。开发者应在目标截图区域底部预留至少 57 个逻辑 像素的空白背景,不放置成绩、正文、按钮等重要内容,并保证背景与所选水印配色 有足够对比度;自定义 rect 也按该区域的底部预留。水印不增加图片尺寸,只在本次 SDK 截图期间展示,完成、失败或终止后移除,不常驻业务页面。系统按键截图不属于 此能力;开发者无需自行绘制水印,也不能通过截图参数关闭水印。

      watermarkTheme 按截图背景选择:light 用于浅色背景,显示黑色水印;dark 用于 深色背景,显示白色水印。说明文字分别为 40% 黑色或白色。省略时默认为 dark, 不自动跟随 App 或系统主题。该参数由宿主 Runtime 实现,旧 Runtime 可能忽略此字段。

      截图不受 SDK 普通请求的固定超时限制;排队、延迟和成图等待由 Host 管理, SDK/Runtime 终止时取消尚未投递的截图。Mobile Host 在延迟结束后才投递原生截图, 并从投递时起最多等待 15 秒成图回调。已投递原生的截图无法保证撤回。

      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 只展示参数确认, 不读取页面像素,也不能替代真机验收。

      与 share.showShareMenu 相比,本方法分享 截图且不接收标题、描述、channel 或 extra;需要通用分享落地页或让接收方通过 share.getExtra 恢复状态时,应使用 showShareMenu()。

      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: ['无畏契约战绩'],
      },
      })

      0.3.1

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none