可选options: MiniProgramScreenshotOptions可选截图配置。省略时使用调用时的整个可见窗口;字段约束见 MiniProgramScreenshotOptions。
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: ['无畏契约战绩'],
},
})
截图并唤起分享。