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 */ 238 function get(id: string, callback: AsyncCallback<image.PixelMap>, options?: SnapshotOptions): void; 239 240 /** 241 * Take a snapshot of the target component. 242 * 243 * @param { string } id - Target component ID, set by developer through .id attribute. 244 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 245 * @throws { BusinessError } 401 - Parameter error. Possible causes: 246 * <br> 1. Mandatory parameters are left unspecified. 247 * <br> 2. Incorrect parameters types. 248 * <br> 3. Parameter verification failed. 249 * @throws { BusinessError } 100001 - Invalid ID. 250 * @syscap SystemCapability.ArkUI.ArkUI.Full 251 * @crossplatform 252 * @since 10 253 */ 254 /** 255 * Take a snapshot of the target component. 256 * 257 * @param { string } id - Target component ID, set by developer through .id attribute. 258 * @param { SnapshotOptions } [options] - Define the snapshot options. 259 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 260 * @throws { BusinessError } 401 - Parameter error. Possible causes: 261 * <br> 1. Mandatory parameters are left unspecified. 262 * <br> 2. Incorrect parameters types. 263 * <br> 3. Parameter verification failed. 264 * @throws { BusinessError } 100001 - Invalid ID. 265 * @syscap SystemCapability.ArkUI.ArkUI.Full 266 * @crossplatform 267 * @atomicservice 268 * @since 12 269 */ 270 function get(id: string, options?: SnapshotOptions): Promise<image.PixelMap>; 271 272 /** 273 * Generate a snapshot from a custom component builder. 274 * 275 * @param { CustomBuilder } builder - Builder function of a custom component. 276 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 277 * @throws { BusinessError } 401 - Parameter error. Possible causes: 278 * <br> 1. Mandatory parameters are left unspecified. 279 * <br> 2. Incorrect parameters types. 280 * <br> 3. Parameter verification failed. 281 * @throws { BusinessError } 100001 - The builder is not a valid build function. 282 * @syscap SystemCapability.ArkUI.ArkUI.Full 283 * @crossplatform 284 * @since 10 285 */ 286 /** 287 * Generate a snapshot from a custom component builder. 288 * 289 * @param { CustomBuilder } builder - Builder function of a custom component. 290 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 291 * @param { number } [delay] - Defines the delay time to render the snapshot. 292 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 293 * @param { SnapshotOptions } [options] - Define the snapshot options. 294 * @throws { BusinessError } 401 - Parameter error. Possible causes: 295 * <br> 1. Mandatory parameters are left unspecified. 296 * <br> 2. Incorrect parameters types. 297 * <br> 3. Parameter verification failed. 298 * @throws { BusinessError } 100001 - The builder is not a valid build function. 299 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 300 * the ready state is required when the checkImageStatus option is enabled. 301 * @syscap SystemCapability.ArkUI.ArkUI.Full 302 * @crossplatform 303 * @atomicservice 304 * @since 12 305 */ 306 function createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>, 307 delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void; 308 309 /** 310 * Generate a snapshot from a custom component builder. 311 * 312 * @param { CustomBuilder } builder - Builder function of a custom component. 313 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 314 * @throws { BusinessError } 401 - Parameter error. Possible causes: 315 * <br> 1. Mandatory parameters are left unspecified. 316 * <br> 2. Incorrect parameters types. 317 * <br> 3. Parameter verification failed. 318 * @throws { BusinessError } 100001 - The builder is not a valid build function. 319 * @syscap SystemCapability.ArkUI.ArkUI.Full 320 * @crossplatform 321 * @since 10 322 */ 323 /** 324 * Generate a snapshot from a custom component builder. 325 * 326 * @param { CustomBuilder } builder - Builder function of a custom component. 327 * @param { number } [delay] - Defines the delay time to render the snapshot. 328 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 329 * @param { SnapshotOptions } [options] - Define the snapshot options. 330 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 331 * @throws { BusinessError } 401 - Parameter error. Possible causes: 332 * <br> 1. Mandatory parameters are left unspecified. 333 * <br> 2. Incorrect parameters types. 334 * <br> 3. Parameter verification failed. 335 * @throws { BusinessError } 100001 - The builder is not a valid build function. 336 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 337 * the ready state is required when the checkImageStatus option is enabled. 338 * @syscap SystemCapability.ArkUI.ArkUI.Full 339 * @crossplatform 340 * @atomicservice 341 * @since 12 342 */ 343 function createFromBuilder(builder: CustomBuilder, delay?: number, 344 checkImageStatus?: boolean, options?: SnapshotOptions): Promise<image.PixelMap>; 345 346 /** 347 * Take a screenshot of the specified component in synchronous mode, 348 * this mode will block the main thread, please use it with caution, the maximum 349 * waiting time of the interface is 3s, if it does not return after 3s, an exception will be thrown. 350 * 351 * @param { string } id - Target component ID, set by developer through .id attribute. 352 * @param { SnapshotOptions } [options] - Define the snapshot options. 353 * @returns { image.PixelMap } The snapshot result in PixelMap format. 354 * @throws { BusinessError } 401 - Parameter error. Possible causes: 355 * <br> 1. Mandatory parameters are left unspecified. 356 * <br> 2. Incorrect parameters types. 357 * <br> 3. Parameter verification failed. 358 * @throws { BusinessError } 100001 - Invalid ID. 359 * @throws { BusinessError } 160002 - Timeout. 360 * @syscap SystemCapability.ArkUI.ArkUI.Full 361 * @crossplatform 362 * @atomicservice 363 * @since 12 364 */ 365 function getSync(id: string, options?: SnapshotOptions): image.PixelMap; 366} 367 368export default componentSnapshot; 369