1# @ohos.arkui.componentSnapshot (组件截图) 2 3本模块提供获取组件截图的能力，包括已加载的组件的截图和没有加载的组件的截图。组件截图只能够截取组件大小的区域，如果组件的绘制超出了它的区域，或子组件的绘制超出了父组件的区域，这些在组件区域外绘制的内容不会在截图中呈现。 4 5> **说明：** 6> 7> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 示例效果请以真机运行为准，当前 IDE 预览器不支持。 10 11 12## 导入模块 13 14```ts 15import componentSnapshot from "@ohos.arkui.componentSnapshot"; 16``` 17 18## componentSnapshot.get 19 20get(id: string, callback: AsyncCallback<image.PixelMap>): void 21 22获取已加载的组件的截图，传入组件的[组件标识](../arkui-ts/ts-universal-attributes-component-id.md#组件标识)，找到对应组件进行截图。通过回调返回结果。 23 24> **说明：** 25> 26> 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 27 28**系统能力：** SystemCapability.ArkUI.ArkUI.Full 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| -------- | ----------------------------------- | ---- | ---------------------------------------- | 34| id | string | 是 | 目标组件的[组件标识](../arkui-ts/ts-universal-attributes-component-id.md#组件标识) | 35| callback | AsyncCallback<image.PixelMap> | 是 | 截图返回结果的回调。 | 36 37**错误码：** 38 39| 错误码ID | 错误信息 | 40| -------- | ------------------- | 41| 100001 | if id is not valid. | 42 43**示例：** 44 45```ts 46import componentSnapshot from '@ohos.arkui.componentSnapshot' 47import image from '@ohos.multimedia.image' 48 49@Entry 50@Component 51struct SnapshotExample { 52 @State pixmap: image.PixelMap|undefined = undefined 53 54 build() { 55 Column() { 56 Image(this.pixmap) 57 .width(300).height(300) 58 // ...Component 59 // ...Component 60 // ...Component 61 Button("click to generate UI snapshot") 62 .onClick(() => { 63 componentSnapshot.get("root", (error: Error, pixmap: image.PixelMap) => { 64 this.pixmap = pixmap 65 // save pixmap to file 66 // .... 67 }) 68 }) 69 } 70 .width('80%') 71 .margin({ left: 10, top: 5, bottom: 5 }) 72 .height(200) 73 .border({ color: '#880606', width: 2 }) 74 .id("root") 75 } 76} 77``` 78 79## componentSnapshot.get 80 81get(id: string): Promise<image.PixelMap> 82 83获取已加载的组件的截图，传入组件的[组件标识](../arkui-ts/ts-universal-attributes-component-id.md#组件标识)，找到对应组件进行截图。通过Promise返回结果。 84 85> **说明：** 86> 87> 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 88 89**系统能力：** SystemCapability.ArkUI.ArkUI.Full 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| ---- | ------ | ---- | ---------------------------------------- | 95| id | string | 是 | 目标组件的[组件标识](../arkui-ts/ts-universal-attributes-component-id.md#组件标识) | 96 97**返回值：** 98 99| 类型 | 说明 | 100| ----------------------------- | -------- | 101| Promise<image.PixelMap> | 截图返回的结果。 | 102 103**错误码：** 104 105| 错误码ID | 错误信息 | 106| ------ | ------------------- | 107| 100001 | if id is not valid. | 108 109**示例：** 110 111```ts 112import componentSnapshot from '@ohos.arkui.componentSnapshot' 113import image from '@ohos.multimedia.image' 114 115@Entry 116@Component 117struct SnapshotExample { 118 @State pixmap: image.PixelMap|undefined = undefined 119 120 build() { 121 Column() { 122 Image(this.pixmap) 123 .width(300).height(300) 124 // ...Component 125 // ...Component 126 // ...Component 127 Button("click to generate UI snapshot") 128 .onClick(() => { 129 componentSnapshot.get("root") 130 .then((pixmap: image.PixelMap) => { 131 this.pixmap = pixmap 132 // save pixmap to file 133 // .... 134 }) 135 }) 136 } 137 .width('80%') 138 .margin({ left: 10, top: 5, bottom: 5 }) 139 .height(200) 140 .border({ color: '#880606', width: 2 }) 141 .id("root") 142 } 143} 144``` 145 146## componentSnapshot.createFromBuilder 147 148createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>): void 149 150在应用后台渲染CustomBuilder自定义组件，并输出其截图。通过回调返回结果并支持在回调中获取离屏组件绘制区域坐标和大小。 151 152> **说明：** 153> 154> 由于需要等待组件构建、渲染成功，离屏截图的回调有500ms以内的延迟。 155> 156> 部分执行耗时任务的组件可能无法及时在截图前加载完成，因此会截取不到加载成功后的图像。例如：加载网络图片的Image组件、Web组件。 157 158 159**系统能力：** SystemCapability.ArkUI.ArkUI.Full 160 161**参数：** 162 163| 参数名 | 类型 | 必填 | 说明 | 164| -------- | ---------------------------------------- | ---- | ---------- | 165| builder | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) | 是 | 自定义组件构建函数。 | 166| callback | AsyncCallback<image.PixelMap> | 是 | 截图返回结果的回调。支持在回调中获取离屏组件绘制区域坐标和大小。 | 167 168**错误码：** 169 170| 错误码ID | 错误信息 | 171| -------- | ----------------------------------------- | 172| 100001 | if builder is not a valid build function. | 173 174**示例：** 175 176```ts 177import componentSnapshot from '@ohos.arkui.componentSnapshot' 178import image from '@ohos.multimedia.image' 179import componentUtils from '@ohos.arkui.componentUtils' 180 181@Entry 182@Component 183struct OffscreenSnapshotExample { 184 @State pixmap: image.PixelMap | undefined = undefined 185 186 @Builder 187 RandomBuilder() { 188 Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 189 Text('Test menu item 1') 190 .fontSize(20) 191 .width(100) 192 .height(50) 193 .textAlign(TextAlign.Center) 194 Divider().height(10) 195 Text('Test menu item 2') 196 .fontSize(20) 197 .width(100) 198 .height(50) 199 .textAlign(TextAlign.Center) 200 } 201 .width(100) 202 .id("builder") 203 } 204 205 build() { 206 Column() { 207 Button("click to generate offscreen UI snapshot") 208 .onClick(() => { 209 componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()}, 210 (error: Error, pixmap: image.PixelMap) => { 211 this.pixmap = pixmap 212 // save pixmap to file 213 // .... 214 // get component size and location 215 let info = componentUtils.getRectangleById("builder") 216 console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y) 217 }) 218 }) 219 }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200) 220 .border({ color: '#880606', width: 2 }) 221 } 222} 223``` 224 225## componentSnapshot.createFromBuilder 226 227createFromBuilder(builder: CustomBuilder): Promise<image.PixelMap> 228 229在应用后台渲染CustomBuilder自定义组件，并输出其截图。通过Promise返回结果并支持获取离屏组件绘制区域坐标和大小。 230 231> **说明：** 232> 233> 由于需要等待组件构建、渲染成功，离屏截图的回调有500ms以内的延迟。 234> 235> 部分执行耗时任务的组件可能无法及时在截图前加载完成，因此会截取不到加载成功后的图像。例如：加载网络图片的Image组件、Web组件。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| ------- | ---------------------------------------- | ---- | ---------- | 243| builder | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) | 是 | 自定义组件构建函数。 | 244 245**返回值：** 246 247| 类型 | 说明 | 248| ----------------------------- | -------- | 249| Promise<image.PixelMap> | 截图返回的结果。 | 250 251**错误码：** 252 253| 错误码ID | 错误信息 | 254| ------ | ---------------------------------------- | 255| 100001 | if builder is not a valid build function. | 256 257**示例：** 258 259```ts 260import componentSnapshot from '@ohos.arkui.componentSnapshot' 261import image from '@ohos.multimedia.image' 262import componentUtils from '@ohos.arkui.componentUtils' 263 264@Entry 265@Component 266struct OffscreenSnapshotExample { 267 @State pixmap: image.PixelMap | undefined = undefined 268 269 @Builder 270 RandomBuilder() { 271 Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 272 Text('Test menu item 1') 273 .fontSize(20) 274 .width(100) 275 .height(50) 276 .textAlign(TextAlign.Center) 277 Divider().height(10) 278 Text('Test menu item 2') 279 .fontSize(20) 280 .width(100) 281 .height(50) 282 .textAlign(TextAlign.Center) 283 } 284 .width(100) 285 .id("builder") 286 } 287 288 build() { 289 Column() { 290 Button("click to generate offscreen UI snapshot") 291 .onClick(() => { 292 componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()}) 293 .then((pixmap: image.PixelMap) => { 294 this.pixmap = pixmap 295 // save pixmap to file 296 // .... 297 // get component size and location 298 let info = componentUtils.getRectangleById("builder") 299 console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y) 300 }) 301 }) 302 }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200) 303 .border({ color: '#880606', width: 2 }) 304 } 305} 306``` 307