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