1/* 2 * Copyright (c) 2021-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 FormKit 19 */ 20 21import formBindingData from './@ohos.app.form.formBindingData'; 22/*** if arkts 1.1 */ 23import formInfo from './@ohos.app.form.formInfo'; 24/*** endif */ 25import FormExtensionContext from './application/FormExtensionContext'; 26import Want from './@ohos.app.ability.Want'; 27/*** if arkts 1.1 */ 28import { Configuration } from './@ohos.app.ability.Configuration'; 29/*** endif */ 30 31/** 32 * Called when this ability breaks the last link, notifying the provider that the provider process is about to stop. 33 * 34 * @typedef { function } 35 * @syscap SystemCapability.Ability.Form 36 * @stagemodelonly 37 * @atomicservice 38 * @since 20 39 * @arkts 1.2 40 */ 41type OnStopFn = () => void; 42 43/** 44 * class of form extension. 45 * 46 * @syscap SystemCapability.Ability.Form 47 * @stagemodelonly 48 * @since 9 49 */ 50/** 51 * class of form extension. 52 * 53 * @syscap SystemCapability.Ability.Form 54 * @stagemodelonly 55 * @atomicservice 56 * @since arkts {'1.1':'11', '1.2':'20'} 57 * @arkts 1.1&1.2 58 */ 59declare class FormExtensionAbility { 60 /** 61 * Indicates form extension context. 62 * 63 * @type { FormExtensionContext } 64 * @syscap SystemCapability.Ability.Form 65 * @stagemodelonly 66 * @since 9 67 */ 68 /** 69 * Indicates form extension context. 70 * 71 * @type { FormExtensionContext } 72 * @syscap SystemCapability.Ability.Form 73 * @stagemodelonly 74 * @atomicservice 75 * @since arkts {'1.1':'11', '1.2':'20'} 76 * @arkts 1.1&1.2 77 */ 78 context: FormExtensionContext; 79 80 /** 81 * Called to return a {@link formBindingData#FormBindingData} object. 82 * 83 * @param { Want } want - Indicates the detailed information for creating a {@link formBindingData#FormBindingData}. 84 * The {@code Want} object must include the form ID, form name, and grid style of the form. 85 * Such form information must be managed as persistent data for further form 86 * acquisition, update, and deletion. 87 * @returns { formBindingData.FormBindingData } Returns the created {@link formBindingData#FormBindingData} object. 88 * @syscap SystemCapability.Ability.Form 89 * @stagemodelonly 90 * @since 9 91 */ 92 /** 93 * Called to return a {@link formBindingData#FormBindingData} object. 94 * 95 * @param { Want } want - Indicates the detailed information for creating a {@link formBindingData#FormBindingData}. 96 * The {@code Want} object must include the form ID, form name, and grid style of the form. 97 * Such form information must be managed as persistent data for further form 98 * acquisition, update, and deletion. 99 * @returns { formBindingData.FormBindingData } Returns the created {@link formBindingData#FormBindingData} object. 100 * @syscap SystemCapability.Ability.Form 101 * @stagemodelonly 102 * @atomicservice 103 * @since arkts {'1.1':'11', '1.2':'20'} 104 * @arkts 1.1&1.2 105 */ 106 onAddForm(want: Want): formBindingData.FormBindingData; 107 108 /** 109 * Called when the form provider is notified that a temporary form is successfully converted to a normal form. 110 * 111 * @param { string } formId - Indicates the ID of the form. 112 * @syscap SystemCapability.Ability.Form 113 * @stagemodelonly 114 * @since 9 115 */ 116 /** 117 * Called when the form provider is notified that a temporary form is successfully converted to a normal form. 118 * 119 * @param { string } formId - Indicates the ID of the form. 120 * @syscap SystemCapability.Ability.Form 121 * @stagemodelonly 122 * @atomicservice 123 * @since arkts {'1.1':'11', '1.2':'20'} 124 * @arkts 1.1&1.2 125 */ 126 onCastToNormalForm(formId: string): void; 127 128 /** 129 * Called to notify the form provider to update a specified form. 130 * 131 * @param { string } formId - Indicates the ID of the form to update. 132 * @syscap SystemCapability.Ability.Form 133 * @stagemodelonly 134 * @since 9 135 */ 136 /** 137 * Called to notify the form provider to update a specified form. 138 * 139 * @param { string } formId - Indicates the ID of the form to update. 140 * @syscap SystemCapability.Ability.Form 141 * @stagemodelonly 142 * @atomicservice 143 * @since 11 144 */ 145 /** 146 * Called to notify the form provider to update a specified form. 147 * 148 * @param { string } formId - Indicates the ID of the form to update. 149 * @param { Record<string, Object> } [wantParams] - Indicates the detailed information for updating the form. 150 * @syscap SystemCapability.Ability.Form 151 * @stagemodelonly 152 * @atomicservice 153 * @since arkts {'1.1':'12', '1.2':'20'} 154 * @arkts 1.1&1.2 155 */ 156 onUpdateForm(formId: string, wantParams?: Record<string, Object>): void; 157 158 /** 159 * Called when the form provider receives form events from the system. 160 * 161 * @param { object } newStatus - Indicates the form events occurred. The key in the {@code Map} 162 * object indicates the form ID, and the value indicates the event 163 * type, which can be either 164 * {@link formInfo#VisibilityType#FORM_VISIBLE} or 165 * {@link formInfo#VisibilityType#FORM_INVISIBLE}. 166 * {@link formInfo#VisibilityType#FORM_VISIBLE} means that the form becomes visible, 167 * {@link formInfo#VisibilityType#FORM_INVISIBLE} means that the form becomes 168 * invisible. 169 * @syscap SystemCapability.Ability.Form 170 * @stagemodelonly 171 * @since 9 172 */ 173 /** 174 * Called when the form provider receives form events from the system. 175 * 176 * @param { Record<string, number> } newStatus - Indicates the form events occurred. The key in the {@code Map} 177 * object indicates the form ID, and the value indicates the event 178 * type, which can be either 179 * {@link formInfo#VisibilityType#FORM_VISIBLE} or 180 * {@link formInfo#VisibilityType#FORM_INVISIBLE}. 181 * {@link formInfo#VisibilityType#FORM_VISIBLE} 182 * means that the form becomes visible, 183 * {@link formInfo#VisibilityType#FORM_INVISIBLE} means that the form 184 * becomes invisible. 185 * @syscap SystemCapability.Ability.Form 186 * @stagemodelonly 187 * @since arkts {'1.1':'11', '1.2':'20'} 188 * @arkts 1.1&1.2 189 */ 190 onChangeFormVisibility(newStatus: Record<string, number>): void; 191 192 /** 193 * Called when a specified message event defined by the form provider is triggered. This method is valid only for 194 * JS forms. 195 * 196 * @param { string } formId - Indicates the ID of the form on which the message event is triggered, which is 197 * provided by the client to the form provider. 198 * @param { string } message - Indicates the value of the {@code params} field of the message event. This parameter 199 * is used to identify the specific component on which the event is triggered. 200 * @syscap SystemCapability.Ability.Form 201 * @stagemodelonly 202 * @since 9 203 */ 204 /** 205 * Called when a specified message event defined by the form provider is triggered. This method is valid only for 206 * JS forms. 207 * 208 * @param { string } formId - Indicates the ID of the form on which the message event is triggered, which is 209 * provided by the client to the form provider. 210 * @param { string } message - Indicates the value of the {@code params} field of the message event. This parameter 211 * is used to identify the specific component on which the event is triggered. 212 * @syscap SystemCapability.Ability.Form 213 * @stagemodelonly 214 * @atomicservice 215 * @since arkts {'1.1':'11', '1.2':'20'} 216 * @arkts 1.1&1.2 217 */ 218 onFormEvent(formId: string, message: string): void; 219 220 /** 221 * Called to notify the form provider that a specified form has been destroyed. Override this method if 222 * you want your application, as the form provider, to be notified of form deletion. 223 * 224 * @param { string } formId - Indicates the ID of the destroyed form. 225 * @syscap SystemCapability.Ability.Form 226 * @stagemodelonly 227 * @since 9 228 */ 229 /** 230 * Called to notify the form provider that a specified form has been destroyed. Override this method if 231 * you want your application, as the form provider, to be notified of form deletion. 232 * 233 * @param { string } formId - Indicates the ID of the destroyed form. 234 * @syscap SystemCapability.Ability.Form 235 * @stagemodelonly 236 * @atomicservice 237 * @since arkts {'1.1':'11', '1.2':'20'} 238 * @arkts 1.1&1.2 239 */ 240 onRemoveForm(formId: string): void; 241 242 /** 243 * Called when the system configuration is updated. 244 * 245 * @param { Configuration } newConfig - Indicates the system configuration, such as language and color mode. 246 * @syscap SystemCapability.Ability.Form 247 * @stagemodelonly 248 * @since 9 249 */ 250 /** 251 * Called when the system configuration is updated. 252 * 253 * @param { Configuration } newConfig - Indicates the system configuration, such as language and color mode. 254 * @syscap SystemCapability.Ability.Form 255 * @stagemodelonly 256 * @atomicservice 257 * @since 11 258 */ 259 onConfigurationUpdate(newConfig: Configuration): void; 260 261 /** 262 * Called to return a {@link FormState} object. 263 * <p>You must override this callback if you want this ability to return the actual form state. Otherwise, 264 * this method returns {@link FormState#DEFAULT} by default.</p> 265 * 266 * @param { Want } want - Indicates the description of the form for which the {@link formInfo#FormState} 267 * is obtained. The description covers the bundle name, ability name, module name, 268 * form name, and form dimensions. 269 * @returns { formInfo.FormState } Returns the {@link formInfo#FormState} object. 270 * @syscap SystemCapability.Ability.Form 271 * @stagemodelonly 272 * @since 9 273 */ 274 /** 275 * Called to return a {@link FormState} object. 276 * <p>You must override this callback if you want this ability to return the actual form state. Otherwise, 277 * this method returns {@link FormState#DEFAULT} by default.</p> 278 * 279 * @param { Want } want - Indicates the description of the form for which the {@link formInfo#FormState} 280 * is obtained. The description covers the bundle name, ability name, module name, 281 * form name, and form dimensions. 282 * @returns { formInfo.FormState } Returns the {@link formInfo#FormState} object. 283 * @syscap SystemCapability.Ability.Form 284 * @stagemodelonly 285 * @atomicservice 286 * @since 11 287 */ 288 onAcquireFormState?(want: Want): formInfo.FormState; 289 290 /** 291 * Called when the system shares the form. 292 * 293 * @param { string } formId - Indicates the ID of the form. 294 * @returns { object } Returns the wantParams object. 295 * @syscap SystemCapability.Ability.Form 296 * @systemapi 297 * @stagemodelonly 298 * @since 9 299 */ 300 /** 301 * Called when the system shares the form. 302 * 303 * @param { string } formId - Indicates the ID of the form. 304 * @returns { Record<string, Object> } Returns the wantParams object. 305 * @syscap SystemCapability.Ability.Form 306 * @systemapi 307 * @stagemodelonly 308 * @since 11 309 */ 310 onShareForm?(formId: string): Record<string, Object>; 311 312 /** 313 * Called when the system acquire the form data. 314 * 315 * @param { string } formId - Indicates the ID of the form. 316 * @returns { object } Returns the wantParams object. 317 * @syscap SystemCapability.Ability.Form 318 * @systemapi 319 * @stagemodelonly 320 * @since 10 321 */ 322 /** 323 * Called when the system acquire the form data. 324 * 325 * @param { string } formId - Indicates the ID of the form. 326 * @returns { Record<string, Object> } Returns the wantParams object. 327 * @syscap SystemCapability.Ability.Form 328 * @systemapi 329 * @stagemodelonly 330 * @since 11 331 */ 332 onAcquireFormData?(formId: string): Record<string, Object>; 333 334 /** 335 * Called when this ability breaks the last link, notifying the provider that the provider process is about to stop. 336 * 337 * @syscap SystemCapability.Ability.Form 338 * @stagemodelonly 339 * @atomicservice 340 * @since 12 341 */ 342 onStop?(): void; 343 344 /** 345 * Called when this ability breaks the last link, notifying the provider that the provider process is about to stop. 346 * 347 * @type { ?OnStopFn } 348 * @syscap SystemCapability.Ability.Form 349 * @stagemodelonly 350 * @atomicservice 351 * @since 20 352 * @arkts 1.2 353 */ 354 onStop?: OnStopFn; 355 356 /** 357 * Called to notify the form provider that the form location of the form has been changed. 358 * 359 * @param { string } formId - Indicates the ID of the form. 360 * @param { formInfo.FormLocation } newFormLocation - Indicates the new form location of the form. 361 * 362 * @syscap SystemCapability.Ability.Form 363 * @stagemodelonly 364 * @atomicservice 365 * @since 20 366 */ 367 onFormLocationChanged(formId: string, newFormLocation: formInfo.FormLocation): void; 368 369 /** 370 * Called to notify the form provider that the size of the form has been changed. Override this method if 371 * you want to know the form size be changed, used for data continuity and layout refresh. 372 * 373 * @param { string } formId - Indicates the ID of the form. 374 * @param { formInfo.FormDimension } newDimension - Indicates the new dimension of the form. 375 * @param { formInfo.Rect } newRect - Indicates the new rect(vp) of the form. 376 * @syscap SystemCapability.Ability.Form 377 * @stagemodelonly 378 * @atomicservice 379 * @since 20 380 */ 381 onSizeChanged(formId: string, newDimension: formInfo.FormDimension, newRect: formInfo.Rect): void; 382} 383export default FormExtensionAbility; 384