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