1/* 2 * Copyright (C) 2024 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 State management API file 18 * @kit ArkUI 19 */ 20 21import contextConstant from '@ohos.app.ability.contextConstant'; 22 23/** 24 * Function that returns default creator. 25 * 26 * @typedef { function } StorageDefaultCreator<T> 27 * @returns { T } default creator 28 * @syscap SystemCapability.ArkUI.ArkUI.Full 29 * @crossplatform 30 * @atomicservice 31 * @since 12 32 */ 33export declare type StorageDefaultCreator<T> = () => T; 34 35/** 36 * Define class constructor with arbitrary parameters. 37 * @interface TypeConstructorWithArgs<T> 38 * @syscap SystemCapability.ArkUI.ArkUI.Full 39 * @crossplatform 40 * @atomicservice 41 * @since 12 42 */ 43export interface TypeConstructorWithArgs<T> { 44 /** 45 * @param { any } args the arguments of the constructor. 46 * @returns { T } return class instance. 47 * @syscap SystemCapability.ArkUI.ArkUI.Full 48 * @crossplatform 49 * @atomicservice 50 * @since 12 51 */ 52 new(...args: any): T; 53} 54 55/** 56 * Define ConnectOptions class. 57 * @syscap SystemCapability.ArkUI.ArkUI.Full 58 * @atomicservice 59 * @since 18 60 */ 61export class ConnectOptions<T extends object> { 62 /** 63 * @type { TypeConstructorWithArgs<T> } type class type of the stored value. 64 * @syscap SystemCapability.ArkUI.ArkUI.Full 65 * @atomicservice 66 * @since 18 67 */ 68 type: TypeConstructorWithArgs<T>; 69 70 /** 71 * Defines alias name of the key, or the function generating the default value. 72 * @type { ?string } 73 * @syscap SystemCapability.ArkUI.ArkUI.Full 74 * @atomicservice 75 * @since 18 76 */ 77 key?: string; 78 79 /** 80 * Define the function generating the default value. 81 * @type { ?StorageDefaultCreator<T>} 82 * @syscap SystemCapability.ArkUI.ArkUI.Full 83 * @atomicservice 84 * @since 18 85 */ 86 defaultCreator?: StorageDefaultCreator<T>; 87 88 /** 89 * Define encrypted partition for data storage. 90 * if not passed in, the defaule value is El2 91 * 92 * @type { ?contextConstant.AreaMode} 93 * @syscap SystemCapability.ArkUI.ArkUI.Full 94 * @atomicservice 95 * @since 18 96 */ 97 areaMode?: contextConstant.AreaMode; 98} 99 100/** 101 * AppStorageV2 is for UI state of app-wide access, has same life cycle as the app, 102 * and saves database content only in memory. 103 * 104 * @syscap SystemCapability.ArkUI.ArkUI.Full 105 * @crossplatform 106 * @atomicservice 107 * @since 12 108 */ 109export declare class AppStorageV2 { 110 /** 111 * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. 112 * If the value for the given key is already available, return the value. 113 * If not, add the key with value generated by calling defaultFunc and return it to caller. 114 * 115 * @param { TypeConstructorWithArgs<T> } type class type of the stored value. 116 * @param { string | StorageDefaultCreator<T> } [keyOrDefaultCreator] alias name of the key, or the function generating the default value. 117 * @param { StorageDefaultCreator<T> } [defaultCreator] the function generating the default value 118 * @returns { T | undefined } the value of the existed key or the default value 119 * @syscap SystemCapability.ArkUI.ArkUI.Full 120 * @crossplatform 121 * @atomicservice 122 * @since 12 123 */ 124 static connect<T extends object>( 125 type: TypeConstructorWithArgs<T>, 126 keyOrDefaultCreator?: string | StorageDefaultCreator<T>, 127 defaultCreator?: StorageDefaultCreator<T> 128 ): T | undefined; 129 130 /** 131 * Removes data with the given key or given class type. 132 * 133 * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type removing 134 * @syscap SystemCapability.ArkUI.ArkUI.Full 135 * @crossplatform 136 * @atomicservice 137 * @since 12 138 */ 139 static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void; 140 141 /** 142 * Return the array of all keys. 143 * 144 * @returns { Array<string> } the array of all keys 145 * @syscap SystemCapability.ArkUI.ArkUI.Full 146 * @crossplatform 147 * @atomicservice 148 * @since 12 149 */ 150 static keys(): Array<string>; 151} 152 153/** 154 * Function that returns reason type when error. 155 * 156 * @typedef { function } PersistenceErrorCallback 157 * @param { string } key persisted key when error 158 * @param { 'quota' | 'serialization' | 'unknown' } reason reason type when error 159 * @param { string } message more message when error 160 * @syscap SystemCapability.ArkUI.ArkUI.Full 161 * @crossplatform 162 * @atomicservice 163 * @since 12 164 */ 165export declare type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void; 166 167/** 168 * PersistenceV2 is for UI state of app-wide access, available on app re-start, 169 * and saves database content in disk. 170 * 171 * @extends AppStorageV2 172 * @syscap SystemCapability.ArkUI.ArkUI.Full 173 * @crossplatform 174 * @atomicservice 175 * @since 12 176 */ 177export declare class PersistenceV2 extends AppStorageV2 { 178 /** 179 * Application-level storage path, sharing a storage path for all modules under the application. 180 * If the value for the given key is already available, return the value. 181 * If not, add the key with value generated by calling defaultFunc and return it to caller. 182 * 183 * @param { ConnectOptions<T> } type Application level storage parameters. 184 * @returns { T | undefined } the value of the existed key or the default value 185 * @syscap SystemCapability.ArkUI.ArkUI.Full 186 * @atomicservice 187 * @since 18 188 */ 189 static globalConnect<T extends object>( 190 type: ConnectOptions<T> 191 ): T | undefined; 192 193 /** 194 * Used to manually persist data changes to disks. 195 * 196 * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type need to persist. 197 * @syscap SystemCapability.ArkUI.ArkUI.Full 198 * @crossplatform 199 * @atomicservice 200 * @since 12 201 */ 202 static save<T>(keyOrType: string | TypeConstructorWithArgs<T>): void; 203 204 /** 205 * Be called when persisting has encountered an error. 206 * 207 * @param { PersistenceErrorCallback | undefined } callback called when error 208 * @syscap SystemCapability.ArkUI.ArkUI.Full 209 * @crossplatform 210 * @atomicservice 211 * @since 12 212 */ 213 static notifyOnError(callback: PersistenceErrorCallback | undefined): void; 214} 215 216/** 217 * Define TypeConstructor type. 218 * 219 * @interface TypeConstructor<T> 220 * @syscap SystemCapability.ArkUI.ArkUI.Full 221 * @crossplatform 222 * @atomicservice 223 * @since 12 224 */ 225export interface TypeConstructor<T> { 226 /** 227 * @returns { T } 228 * @syscap SystemCapability.ArkUI.ArkUI.Full 229 * @crossplatform 230 * @atomicservice 231 * @since 12 232 */ 233 new(): T; 234} 235 236/** 237 * Function that returns PropertyDecorator. 238 * 239 * @typedef { function } TypeDecorator 240 * @param { TypeConstructor<T> } type type info 241 * @returns { PropertyDecorator } Type decorator 242 * @syscap SystemCapability.ArkUI.ArkUI.Full 243 * @crossplatform 244 * @atomicservice 245 * @since 12 246 */ 247export declare type TypeDecorator = <T>(type: TypeConstructor<T>) => PropertyDecorator; 248 249/** 250 * Define Type PropertyDecorator, adds type information to an object. 251 * 252 * @syscap SystemCapability.ArkUI.ArkUI.Full 253 * @crossplatform 254 * @atomicservice 255 * @since 12 256 */ 257export declare const Type: TypeDecorator; 258 259/** 260 * UIUtils is a state management tool class for operating the observed data. 261 * 262 * @syscap SystemCapability.ArkUI.ArkUI.Full 263 * @crossplatform 264 * @atomicservice 265 * @since 12 266 */ 267export declare class UIUtils { 268 /** 269 * Get raw object from the Object wrapped with an ObservedObject. 270 * If input parameter is a regular Object without ObservedObject, return Object itself. 271 * 272 * @param { T } source input source Object data. 273 * @returns { T } raw object from the Object wrapped with an ObservedObject. 274 * @syscap SystemCapability.ArkUI.ArkUI.Full 275 * @crossplatform 276 * @atomicservice 277 * @since 12 278 */ 279 static getTarget<T extends object>(source: T): T; 280 281 /** 282 * Make non-observed data into V2 observed data. 283 * Support non-observed class, JSON.parse Object and Sendable class. 284 * 285 * @param { T } source input source object data. 286 * @returns { T } V2 proxy object from the source object data. 287 * @syscap SystemCapability.ArkUI.ArkUI.Full 288 * @crossplatform 289 * @atomicservice 290 * @since 12 291 */ 292 static makeObserved<T extends object>(source: T): T; 293 294 /** 295 * Make non-observed data into V1 observed data. 296 * Support JS object, interface, class (non-@Observed, non-ObservedV2). 297 * 298 * @param { T } source input source object data. 299 * @returns { T } V1 proxy object from the source object data. 300 * @static 301 * @syscap SystemCapability.ArkUI.ArkUI.Full 302 * @crossplatform 303 * @atomicservice 304 * @since 19 305 */ 306 static makeV1Observed<T extends object>(source: T): T; 307 308 /** 309 * Enables V2 compatibility on given viewmodel object or nested viewmodels, which are V1 observed object already. 310 * 311 * @param {T} source - The object to be made V2-compatible. 312 * @returns {T} The processed object with V2 compatibility enabled. 313 * @static 314 * @syscap SystemCapability.ArkUI.ArkUI.Full 315 * @crossplatform 316 * @atomicservice 317 * @since 19 318 */ 319 static enableV2Compatibility<T extends object>(source: T): T; 320 321 /** 322 * Dynamically add monitor for state variable change. 323 * 324 * @param { object } target class instance or custom component instance. 325 * @param { string | string[] } path monitored change for state variable. 326 * @param { MonitorCallback } monitorCallback the function that triggers the callback when state variable change. 327 * @param { MonitorOptions} [options] the monitor configuration parameter. 328 * @throws { BusinessError } 130000 - The target is not a custom component instance or V2 class instance. 329 * @throws { BusinessError } 130001 - The path is invalid. 330 * @throws { BusinessError } 130002 - monitorCallback is not a function or an anonymous function. 331 * @static 332 * @syscap SystemCapability.ArkUI.ArkUI.Full 333 * @crossplatform 334 * @atomicservice 335 * @since 20 336 */ 337 static addMonitor(target: object, path: string | string[], monitorCallback: MonitorCallback, options?: MonitorOptions): void; 338 339 /** 340 * Dynamically clear monitor callback for state variable change. 341 * 342 * @param { object } target class instance or custom component instance. 343 * @param { string | string[] } path monitored change for state variable. 344 * @param { MonitorCallback } [monitorCallback] the function that triggers the callback when state variable change. 345 * @throws { BusinessError } 130000 - The target is not a custom component instance or V2 class instance. 346 * @throws { BusinessError } 130001 - The path is invalid. 347 * @throws { BusinessError } 130002 - monitorCallback is not a function or an anonymous function. 348 * @static 349 * @syscap SystemCapability.ArkUI.ArkUI.Full 350 * @crossplatform 351 * @atomicservice 352 * @since 20 353 */ 354 static clearMonitor(target: object, path: string | string[], monitorCallback?: MonitorCallback) : void; 355 356 /** 357 * Creates read-only data binding. 358 * Example. UIUtils.makeBinding<number>(()=>this.num); 359 * 360 * Supports simple getters for read-only data. 361 * Intended for primitive value parameters when calling a @Builder function where arguments are of type Binding. 362 * 363 * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T. 364 * @returns { Binding<T> } read-only data binding value 365 * @static 366 * @syscap SystemCapability.ArkUI.ArkUI.Full 367 * @crossplatform 368 * @atomicservice 369 * @since 20 370 */ 371 static makeBinding<T>(getter: GetterCallback<T>): Binding<T>; 372 373 /** 374 * Creates a mutable data binding. 375 * 376 * Two functions to implement function overloading. 377 * 378 * Example. UIUtils.makeBinding<number>(()=>this.num, val => this.num = val); 379 * 380 * Supports getter-setter pairs for mutable data. 381 * Intended for primitive value parameters when calling a @Builder 382 * function where arguments are of type MutableBinding. 383 * 384 * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T. 385 * @param { SetterCallback<T> } setter - A function to set a new value of type T. 386 * If provided, a MutableBinding is created. 387 * @returns { MutableBinding<T> } mutable data binding value 388 * @static 389 * @syscap SystemCapability.ArkUI.ArkUI.Full 390 * @crossplatform 391 * @atomicservice 392 * @since 20 393 */ 394 static makeBinding<T>(getter: GetterCallback<T>, setter: SetterCallback<T>): MutableBinding<T>; 395} 396 397/** 398 * Function that returns monitor instance value when state variable is changed. 399 * 400 * @typedef { function } MonitorCallback 401 * @param { IMonitor} monitorValue monitor instance value when state variable is changed. 402 * @syscap SystemCapability.ArkUI.ArkUI.Full 403 * @crossplatform 404 * @atomicservice 405 * @since 20 406 */ 407export declare type MonitorCallback = (monitorValue: IMonitor) => void; 408 409/** 410 * Define Monitor options. 411 * 412 * @interface MonitorOptions 413 * @syscap SystemCapability.ArkUI.ArkUI.Full 414 * @crossplatform 415 * @atomicservice 416 * @since 20 417 */ 418export interface MonitorOptions { 419 /** 420 * Used to determine whether the state variable change is 421 * triggered synchronously or asynchronously. The default value is false. 422 * 423 * @type { ?boolean } isSynchronous parameter 424 * @default false 425 * @syscap SystemCapability.ArkUI.ArkUI.Full 426 * @crossplatform 427 * @atomicservice 428 * @since 20 429 */ 430 isSynchronous?: boolean; 431} 432 433/** 434 * Getter callback type. It is used to get value. 435 * 436 * @typedef { function } GetterCallback 437 * @returns { T } 438 * @syscap SystemCapability.ArkUI.ArkUI.Full 439 * @crossplatform 440 * @atomicservice 441 * @since 20 442 */ 443export declare type GetterCallback<T> = () => T; 444 445/** 446 * Setter callback type. It is used to assign a new value. 447 * 448 * @typedef { function } SetterCallback 449 * @param { T } newValue - update the value with newValue. 450 * @syscap SystemCapability.ArkUI.ArkUI.Full 451 * @crossplatform 452 * @atomicservice 453 * @since 20 454 */ 455export declare type SetterCallback<T> = (newValue: T) => void; 456 457/** 458 * Represents a read-only data binding. 459 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function. 460 * @syscap SystemCapability.ArkUI.ArkUI.Full 461 * @crossplatform 462 * @atomicservice 463 * @since 20 464 */ 465export declare class Binding<T> { 466 /** 467 * Get function that can acquire the value. 468 * @returns T 469 * @syscap SystemCapability.ArkUI.ArkUI.Full 470 * @crossplatform 471 * @atomicservice 472 * @since 20 473 */ 474 get value(): T; 475} 476 477/** 478 * Represents a mutable data binding allowing both read and write operations. 479 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function. 480 * @syscap SystemCapability.ArkUI.ArkUI.Full 481 * @crossplatform 482 * @atomicservice 483 * @since 20 484 */ 485export declare class MutableBinding<T> { 486 /** 487 * Get function that can acquire the value. 488 * @returns T 489 * @syscap SystemCapability.ArkUI.ArkUI.Full 490 * @crossplatform 491 * @atomicservice 492 * @since 20 493 */ 494 get value(): T; 495 /** 496 * Set function that can set the new value. 497 * @syscap SystemCapability.ArkUI.ArkUI.Full 498 * @crossplatform 499 * @atomicservice 500 * @since 20 501 */ 502 set value(newValue: T); 503}