1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ArkUI 19 */ 20 21/*** if arkts 1.2 */ 22import { CustomBuilder } from './arkui/component/builder'; 23/*** endif */ 24 25import { AsyncCallback } from './@ohos.base'; 26import image from './@ohos.multimedia.image'; 27 28/** 29 * This module allows developers to export snapshot image from a component or a custom builder. 30 * 31 * @namespace componentSnapshot 32 * @syscap SystemCapability.ArkUI.ArkUI.Full 33 * @crossplatform 34 * @since 10 35 */ 36/** 37 * This module allows developers to export snapshot image from a component or a custom builder. 38 * 39 * @namespace componentSnapshot 40 * @syscap SystemCapability.ArkUI.ArkUI.Full 41 * @crossplatform 42 * @atomicservice 43 * @since arkts {'1.1':'12','1.2':'20'} 44 * @arkts 1.1&1.2 45 */ 46declare namespace componentSnapshot { 47 /** 48 * Defines the extra options for snapshot taking. 49 * 50 * @typedef SnapshotRegion 51 * @syscap SystemCapability.ArkUI.ArkUI.Full 52 * @crossplatform 53 * @atomicservice 54 * @since arkts {'1.1':'15','1.2':'20'} 55 * @arkts 1.1&1.2 56 */ 57 export interface SnapshotRegion { 58 /** 59 * Left side position of rectangle, in PX. 60 * 61 * @type { number } 62 * @syscap SystemCapability.ArkUI.ArkUI.Full 63 * @crossplatform 64 * @atomicservice 65 * @since arkts {'1.1':'15','1.2':'20'} 66 * @arkts 1.1&1.2 67 */ 68 left: number; 69 70 /** 71 * Right side position of Rectangle, in PX. 72 * 73 * @type { number } 74 * @syscap SystemCapability.ArkUI.ArkUI.Full 75 * @crossplatform 76 * @atomicservice 77 * @since arkts {'1.1':'15','1.2':'20'} 78 * @arkts 1.1&1.2 79 */ 80 right: number; 81 82 /** 83 * Top side position of Rectangle, in PX. 84 * 85 * @type { number } 86 * @syscap SystemCapability.ArkUI.ArkUI.Full 87 * @crossplatform 88 * @atomicservice 89 * @since arkts {'1.1':'15','1.2':'20'} 90 * @arkts 1.1&1.2 91 */ 92 top: number; 93 94 /** 95 * Bottom side position of Rectangle, in PX. 96 * 97 * @type { number } 98 * @syscap SystemCapability.ArkUI.ArkUI.Full 99 * @crossplatform 100 * @atomicservice 101 * @since arkts {'1.1':'15','1.2':'20'} 102 * @arkts 1.1&1.2 103 */ 104 bottom: number; 105 } 106 107 /** 108 * Defines the extra options for snapshot taking, if this is used, the start and end will 109 * be assigned to left and right value according to the layout direction of node automaticlly. 110 * 111 * @typedef LocalizedSnapshotRegion 112 * @syscap SystemCapability.ArkUI.ArkUI.Full 113 * @crossplatform 114 * @atomicservice 115 * @since arkts {'1.1':'15','1.2':'20'} 116 * @arkts 1.1&1.2 117 */ 118 export interface LocalizedSnapshotRegion { 119 /** 120 * Left/Right side position of rectangle, in PX 121 * 122 * @type { number } 123 * @syscap SystemCapability.ArkUI.ArkUI.Full 124 * @crossplatform 125 * @atomicservice 126 * @since arkts {'1.1':'15','1.2':'20'} 127 * @arkts 1.1&1.2 128 */ 129 start: number; 130 131 /** 132 * End side position of Rectangle, in PX. 133 * 134 * @type { number } 135 * @syscap SystemCapability.ArkUI.ArkUI.Full 136 * @crossplatform 137 * @atomicservice 138 * @since arkts {'1.1':'15','1.2':'20'} 139 * @arkts 1.1&1.2 140 */ 141 end: number; 142 143 /** 144 * Left/Right side position of rectangle, in PX 145 * 146 * @type { number } 147 * @syscap SystemCapability.ArkUI.ArkUI.Full 148 * @crossplatform 149 * @atomicservice 150 * @since arkts {'1.1':'15','1.2':'20'} 151 * @arkts 1.1&1.2 152 */ 153 top: number; 154 155 /** 156 * Bottom side position of Rectangle, in PX. 157 * 158 * @type { number } 159 * @syscap SystemCapability.ArkUI.ArkUI.Full 160 * @crossplatform 161 * @atomicservice 162 * @since arkts {'1.1':'15','1.2':'20'} 163 * @arkts 1.1&1.2 164 */ 165 bottom: number; 166 } 167 168 /** 169 * Defines the snapshot region rect type. 170 * 171 * @typedef { SnapshotRegion | LocalizedSnapshotRegion } SnapshotRegionType 172 * @syscap SystemCapability.ArkUI.ArkUI.Full 173 * @crossplatform 174 * @atomicservice 175 * @since arkts {'1.1':'15','1.2':'20'} 176 * @arkts 1.1&1.2 177 */ 178 export type SnapshotRegionType = SnapshotRegion | LocalizedSnapshotRegion; 179 180 /** 181 * Defines the extra options for snapshot taking. 182 * 183 * @typedef SnapshotOptions 184 * @syscap SystemCapability.ArkUI.ArkUI.Full 185 * @crossplatform 186 * @atomicservice 187 * @since arkts {'1.1':'12','1.2':'20'} 188 * @arkts 1.1&1.2 189 */ 190 export interface SnapshotOptions { 191 /** 192 * Defines the scale property to render the snapshot. 193 * 194 * @type {?number} 195 * @syscap SystemCapability.ArkUI.ArkUI.Full 196 * @crossplatform 197 * @atomicservice 198 * @since arkts {'1.1':'12','1.2':'20'} 199 * @arkts 1.1&1.2 200 */ 201 scale?: number 202 203 /** 204 * Whether to wait the rendering is finished. 205 * 206 * @type {?boolean} 207 * @syscap SystemCapability.ArkUI.ArkUI.Full 208 * @crossplatform 209 * @atomicservice 210 * @since arkts {'1.1':'12','1.2':'20'} 211 * @arkts 1.1&1.2 212 */ 213 waitUntilRenderFinished?: boolean 214 215 /** 216 * Defines the rect reigon type of the snapshot. 217 * 218 * @type {?SnapshotRegionType} 219 * @syscap SystemCapability.ArkUI.ArkUI.Full 220 * @crossplatform 221 * @atomicservice 222 * @since arkts {'1.1':'15','1.2':'20'} 223 * @arkts 1.1&1.2 224 */ 225 region?: SnapshotRegionType 226 } 227 228 /** 229 * Take a snapshot of the target component. 230 * 231 * @param { string } id - Target component ID, set by developer through .id attribute. 232 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 233 * @throws { BusinessError } 401 - Parameter error. Possible causes: 234 * <br> 1. Mandatory parameters are left unspecified. 235 * <br> 2. Incorrect parameters types. 236 * <br> 3. Parameter verification failed. 237 * @throws { BusinessError } 100001 - Invalid ID. 238 * @syscap SystemCapability.ArkUI.ArkUI.Full 239 * @crossplatform 240 * @since 10 241 */ 242 /** 243 * Take a snapshot of the target component. 244 * 245 * @param { string } id - Target component ID, set by developer through .id attribute. 246 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 247 * @param { SnapshotOptions } [options] - Define the snapshot options. 248 * @throws { BusinessError } 401 - Parameter error. Possible causes: 249 * <br> 1. Mandatory parameters are left unspecified. 250 * <br> 2. Incorrect parameters types. 251 * <br> 3. Parameter verification failed. 252 * @throws { BusinessError } 100001 - Invalid ID. 253 * @syscap SystemCapability.ArkUI.ArkUI.Full 254 * @crossplatform 255 * @atomicservice 256 * @since arkts {'1.1':'12','1.2':'20'} 257 * @deprecated since 18 258 * @useinstead ohos.arkui.UIContext.ComponentSnapshot#get 259 * @arkts 1.1&1.2 260 */ 261 function get(id: string, callback: AsyncCallback<image.PixelMap>, options?: SnapshotOptions): void; 262 263 /** 264 * Take a snapshot of the target component. 265 * 266 * @param { string } id - Target component ID, set by developer through .id attribute. 267 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 268 * @throws { BusinessError } 401 - Parameter error. Possible causes: 269 * <br> 1. Mandatory parameters are left unspecified. 270 * <br> 2. Incorrect parameters types. 271 * <br> 3. Parameter verification failed. 272 * @throws { BusinessError } 100001 - Invalid ID. 273 * @syscap SystemCapability.ArkUI.ArkUI.Full 274 * @crossplatform 275 * @since 10 276 */ 277 /** 278 * Take a snapshot of the target component. 279 * 280 * @param { string } id - Target component ID, set by developer through .id attribute. 281 * @param { SnapshotOptions } [options] - Define the snapshot options. 282 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 283 * @throws { BusinessError } 401 - Parameter error. Possible causes: 284 * <br> 1. Mandatory parameters are left unspecified. 285 * <br> 2. Incorrect parameters types. 286 * <br> 3. Parameter verification failed. 287 * @throws { BusinessError } 100001 - Invalid ID. 288 * @syscap SystemCapability.ArkUI.ArkUI.Full 289 * @crossplatform 290 * @atomicservice 291 * @since arkts {'1.1':'12','1.2':'20'} 292 * @deprecated since 18 293 * @useinstead ohos.arkui.UIContext.ComponentSnapshot#get 294 * @arkts 1.1&1.2 295 */ 296 function get(id: string, options?: SnapshotOptions): Promise<image.PixelMap>; 297 298 /** 299 * Generate a snapshot from a custom component builder. 300 * 301 * @param { CustomBuilder } builder - Builder function of a custom component. 302 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 303 * @throws { BusinessError } 401 - Parameter error. Possible causes: 304 * <br> 1. Mandatory parameters are left unspecified. 305 * <br> 2. Incorrect parameters types. 306 * <br> 3. Parameter verification failed. 307 * @throws { BusinessError } 100001 - The builder is not a valid build function. 308 * @syscap SystemCapability.ArkUI.ArkUI.Full 309 * @crossplatform 310 * @since 10 311 */ 312 /** 313 * Generate a snapshot from a custom component builder. 314 * 315 * @param { CustomBuilder } builder - Builder function of a custom component. 316 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 317 * @param { number } [delay] - Defines the delay time to render the snapshot. 318 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 319 * @param { SnapshotOptions } [options] - Define the snapshot options. 320 * @throws { BusinessError } 401 - Parameter error. Possible causes: 321 * <br> 1. Mandatory parameters are left unspecified. 322 * <br> 2. Incorrect parameters types. 323 * <br> 3. Parameter verification failed. 324 * @throws { BusinessError } 100001 - The builder is not a valid build function. 325 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 326 * the ready state is required when the checkImageStatus option is enabled. 327 * @syscap SystemCapability.ArkUI.ArkUI.Full 328 * @crossplatform 329 * @atomicservice 330 * @since arkts {'1.1':'12','1.2':'20'} 331 * @deprecated since 18 332 * @useinstead ohos.arkui.UIContext.ComponentSnapshot#createFromBuilder 333 * @arkts 1.1&1.2 334 */ 335 function createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>, 336 delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void; 337 338 /** 339 * Generate a snapshot from a custom component builder. 340 * 341 * @param { CustomBuilder } builder - Builder function of a custom component. 342 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 343 * @throws { BusinessError } 401 - Parameter error. Possible causes: 344 * <br> 1. Mandatory parameters are left unspecified. 345 * <br> 2. Incorrect parameters types. 346 * <br> 3. Parameter verification failed. 347 * @throws { BusinessError } 100001 - The builder is not a valid build function. 348 * @syscap SystemCapability.ArkUI.ArkUI.Full 349 * @crossplatform 350 * @since 10 351 */ 352 /** 353 * Generate a snapshot from a custom component builder. 354 * 355 * @param { CustomBuilder } builder - Builder function of a custom component. 356 * @param { number } [delay] - Defines the delay time to render the snapshot. 357 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 358 * @param { SnapshotOptions } [options] - Define the snapshot options. 359 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 360 * @throws { BusinessError } 401 - Parameter error. Possible causes: 361 * <br> 1. Mandatory parameters are left unspecified. 362 * <br> 2. Incorrect parameters types. 363 * <br> 3. Parameter verification failed. 364 * @throws { BusinessError } 100001 - The builder is not a valid build function. 365 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 366 * the ready state is required when the checkImageStatus option is enabled. 367 * @syscap SystemCapability.ArkUI.ArkUI.Full 368 * @crossplatform 369 * @atomicservice 370 * @since arkts {'1.1':'12','1.2':'20'} 371 * @deprecated since 18 372 * @useinstead ohos.arkui.UIContext.ComponentSnapshot#createFromBuilder 373 * @arkts 1.1&1.2 374 */ 375 function createFromBuilder(builder: CustomBuilder, delay?: number, 376 checkImageStatus?: boolean, options?: SnapshotOptions): Promise<image.PixelMap>; 377 378 /** 379 * Take a screenshot of the specified component in synchronous mode, 380 * this mode will block the main thread, please use it with caution, the maximum 381 * waiting time of the interface is 3s, if it does not return after 3s, an exception will be thrown. 382 * 383 * @param { string } id - Target component ID, set by developer through .id attribute. 384 * @param { SnapshotOptions } [options] - Define the snapshot options. 385 * @returns { image.PixelMap } The snapshot result in PixelMap format. 386 * @throws { BusinessError } 401 - Parameter error. Possible causes: 387 * <br> 1. Mandatory parameters are left unspecified. 388 * <br> 2. Incorrect parameters types. 389 * <br> 3. Parameter verification failed. 390 * @throws { BusinessError } 100001 - Invalid ID. 391 * @throws { BusinessError } 160002 - Timeout. 392 * @syscap SystemCapability.ArkUI.ArkUI.Full 393 * @crossplatform 394 * @atomicservice 395 * @since arkts {'1.1':'12','1.2':'20'} 396 * @arkts 1.1&1.2 397 */ 398 export function getSync(id: string, options?: SnapshotOptions): image.PixelMap; 399} 400 401export default componentSnapshot; 402