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 SnapshotOptions 46 * @syscap SystemCapability.ArkUI.ArkUI.Full 47 * @crossplatform 48 * @atomicservice 49 * @since 12 50 */ 51 interface SnapshotOptions { 52 /** 53 * Defines the scale property to render the snapshot. 54 * 55 * @type {?number} 56 * @syscap SystemCapability.ArkUI.ArkUI.Full 57 * @crossplatform 58 * @atomicservice 59 * @since 12 60 */ 61 scale?: number 62 63 /** 64 * Whether to wait the rendering is finished. 65 * 66 * @type {?boolean} 67 * @syscap SystemCapability.ArkUI.ArkUI.Full 68 * @crossplatform 69 * @atomicservice 70 * @since 12 71 */ 72 waitUntilRenderFinished?: boolean 73 } 74 75 /** 76 * Take a snapshot of the target component. 77 * 78 * @param { string } id - Target component ID, set by developer through .id attribute. 79 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 80 * @throws { BusinessError } 401 - Parameter error. Possible causes: 81 * <br> 1. Mandatory parameters are left unspecified. 82 * <br> 2. Incorrect parameters types. 83 * <br> 3. Parameter verification failed. 84 * @throws { BusinessError } 100001 - Invalid ID. 85 * @syscap SystemCapability.ArkUI.ArkUI.Full 86 * @crossplatform 87 * @since 10 88 */ 89 /** 90 * Take a snapshot of the target component. 91 * 92 * @param { string } id - Target component ID, set by developer through .id attribute. 93 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 94 * @param { SnapshotOptions } [options] - Define the snapshot options. 95 * @throws { BusinessError } 401 - Parameter error. Possible causes: 96 * <br> 1. Mandatory parameters are left unspecified. 97 * <br> 2. Incorrect parameters types. 98 * <br> 3. Parameter verification failed. 99 * @throws { BusinessError } 100001 - Invalid ID. 100 * @syscap SystemCapability.ArkUI.ArkUI.Full 101 * @crossplatform 102 * @atomicservice 103 * @since 12 104 */ 105 function get(id: string, callback: AsyncCallback<image.PixelMap>, options?: SnapshotOptions): void; 106 107 /** 108 * Take a snapshot of the target component. 109 * 110 * @param { string } id - Target component ID, set by developer through .id attribute. 111 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 112 * @throws { BusinessError } 401 - Parameter error. Possible causes: 113 * <br> 1. Mandatory parameters are left unspecified. 114 * <br> 2. Incorrect parameters types. 115 * <br> 3. Parameter verification failed. 116 * @throws { BusinessError } 100001 - Invalid ID. 117 * @syscap SystemCapability.ArkUI.ArkUI.Full 118 * @crossplatform 119 * @since 10 120 */ 121 /** 122 * Take a snapshot of the target component. 123 * 124 * @param { string } id - Target component ID, set by developer through .id attribute. 125 * @param { SnapshotOptions } [options] - Define the snapshot options. 126 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 127 * @throws { BusinessError } 401 - Parameter error. Possible causes: 128 * <br> 1. Mandatory parameters are left unspecified. 129 * <br> 2. Incorrect parameters types. 130 * <br> 3. Parameter verification failed. 131 * @throws { BusinessError } 100001 - Invalid ID. 132 * @syscap SystemCapability.ArkUI.ArkUI.Full 133 * @crossplatform 134 * @atomicservice 135 * @since 12 136 */ 137 function get(id: string, options?: SnapshotOptions): Promise<image.PixelMap>; 138 139 /** 140 * Generate a snapshot from a custom component builder. 141 * 142 * @param { CustomBuilder } builder - Builder function of a custom component. 143 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 144 * @throws { BusinessError } 401 - Parameter error. Possible causes: 145 * <br> 1. Mandatory parameters are left unspecified. 146 * <br> 2. Incorrect parameters types. 147 * <br> 3. Parameter verification failed. 148 * @throws { BusinessError } 100001 - The builder is not a valid build function. 149 * @syscap SystemCapability.ArkUI.ArkUI.Full 150 * @crossplatform 151 * @since 10 152 */ 153 /** 154 * Generate a snapshot from a custom component builder. 155 * 156 * @param { CustomBuilder } builder - Builder function of a custom component. 157 * @param { AsyncCallback<image.PixelMap> } callback - Callback that contains the snapshot in PixelMap format. 158 * @param { number } [delay] - Defines the delay time to render the snapshot. 159 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 160 * @param { SnapshotOptions } [options] - Define the snapshot options. 161 * @throws { BusinessError } 401 - Parameter error. Possible causes: 162 * <br> 1. Mandatory parameters are left unspecified. 163 * <br> 2. Incorrect parameters types. 164 * <br> 3. Parameter verification failed. 165 * @throws { BusinessError } 100001 - The builder is not a valid build function. 166 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 167 * the ready state is required when the checkImageStatus option is enabled. 168 * @syscap SystemCapability.ArkUI.ArkUI.Full 169 * @crossplatform 170 * @atomicservice 171 * @since 12 172 */ 173 function createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>, 174 delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void; 175 176 /** 177 * Generate a snapshot from a custom component builder. 178 * 179 * @param { CustomBuilder } builder - Builder function of a custom component. 180 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 181 * @throws { BusinessError } 401 - Parameter error. Possible causes: 182 * <br> 1. Mandatory parameters are left unspecified. 183 * <br> 2. Incorrect parameters types. 184 * <br> 3. Parameter verification failed. 185 * @throws { BusinessError } 100001 - The builder is not a valid build function. 186 * @syscap SystemCapability.ArkUI.ArkUI.Full 187 * @crossplatform 188 * @since 10 189 */ 190 /** 191 * Generate a snapshot from a custom component builder. 192 * 193 * @param { CustomBuilder } builder - Builder function of a custom component. 194 * @param { number } [delay] - Defines the delay time to render the snapshot. 195 * @param { boolean } [checkImageStatus] - Defines if check the image decoding status before taking snapshot. 196 * @param { SnapshotOptions } [options] - Define the snapshot options. 197 * @returns { Promise<image.PixelMap> } A Promise with the snapshot in PixelMap format. 198 * @throws { BusinessError } 401 - Parameter error. Possible causes: 199 * <br> 1. Mandatory parameters are left unspecified. 200 * <br> 2. Incorrect parameters types. 201 * <br> 3. Parameter verification failed. 202 * @throws { BusinessError } 100001 - The builder is not a valid build function. 203 * @throws { BusinessError } 160001 - An image component in builder is not ready for taking a snapshot. The check for 204 * the ready state is required when the checkImageStatus option is enabled. 205 * @syscap SystemCapability.ArkUI.ArkUI.Full 206 * @crossplatform 207 * @atomicservice 208 * @since 12 209 */ 210 function createFromBuilder(builder: CustomBuilder, delay?: number, 211 checkImageStatus?: boolean, options?: SnapshotOptions): Promise<image.PixelMap>; 212 213 /** 214 * Take a screenshot of the specified component in synchronous mode, 215 * this mode will block the main thread, please use it with caution, the maximum 216 * waiting time of the interface is 3s, if it does not return after 3s, an exception will be thrown. 217 * 218 * @param { string } id - Target component ID, set by developer through .id attribute. 219 * @param { SnapshotOptions } [options] - Define the snapshot options. 220 * @returns { image.PixelMap } The snapshot result in PixelMap format. 221 * @throws { BusinessError } 401 - Parameter error. Possible causes: 222 * <br> 1. Mandatory parameters are left unspecified. 223 * <br> 2. Incorrect parameters types. 224 * <br> 3. Parameter verification failed. 225 * @throws { BusinessError } 100001 - Invalid ID. 226 * @throws { BusinessError } 160002 - Timeout. 227 * @syscap SystemCapability.ArkUI.ArkUI.Full 228 * @crossplatform 229 * @atomicservice 230 * @since 12 231 */ 232 function getSync(id: string, options?: SnapshotOptions): image.PixelMap; 233} 234 235export default componentSnapshot; 236