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 * @file State management API file 17 * @kit ArkUI 18 */ 19/** 20 * Function that returns default creator. 21 * 22 * @typedef { function } StorageDefaultCreator<T> 23 * @returns { T } default creator 24 * @syscap SystemCapability.ArkUI.ArkUI.Full 25 * @crossplatform 26 * @atomicservice 27 * @since 12 28 */ 29export declare type StorageDefaultCreator<T> = () => T; 30/** 31 * Define class constructor with arbitrary parameters. 32 * @interface TypeConstructorWithArgs<T> 33 * @syscap SystemCapability.ArkUI.ArkUI.Full 34 * @crossplatform 35 * @atomicservice 36 * @since 12 37 */ 38export interface TypeConstructorWithArgs<T> { 39 /** 40 * @param { any } args the arguments of the constructor. 41 * @returns { T } return class instance. 42 * @syscap SystemCapability.ArkUI.ArkUI.Full 43 * @crossplatform 44 * @atomicservice 45 * @since 12 46 */ 47 new (...args: any): T; 48} 49/** 50 * AppStorageV2 is for UI state of app-wide access, has same life cycle as the app, 51 * and saves database content only in memory. 52 * 53 * @syscap SystemCapability.ArkUI.ArkUI.Full 54 * @crossplatform 55 * @atomicservice 56 * @since 12 57 */ 58export declare class AppStorageV2 { 59 /** 60 * If the value for the given key is already available, return the value. 61 * If not, add the key with value generated by calling defaultFunc and return it to caller. 62 * 63 * @param { TypeConstructorWithArgs<T> } type class type of the stored value. 64 * @param { string | StorageDefaultCreator<T> } [keyOrDefaultCreator] alias name of the key, or the function generating the default value. 65 * @param { StorageDefaultCreator<T> } [defaultCreator] the function generating the default value 66 * @returns { T | undefined } the value of the existed key or the default value 67 * @syscap SystemCapability.ArkUI.ArkUI.Full 68 * @crossplatform 69 * @atomicservice 70 * @since 12 71 */ 72 static connect<T extends object>(type: TypeConstructorWithArgs<T>, keyOrDefaultCreator?: string | StorageDefaultCreator<T>, defaultCreator?: StorageDefaultCreator<T>): T | undefined; 73 /** 74 * Removes data with the given key or given class type. 75 * 76 * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type removing 77 * @syscap SystemCapability.ArkUI.ArkUI.Full 78 * @crossplatform 79 * @atomicservice 80 * @since 12 81 */ 82 static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void; 83 /** 84 * Return the array of all keys. 85 * 86 * @returns { Array<string> } the array of all keys 87 * @syscap SystemCapability.ArkUI.ArkUI.Full 88 * @crossplatform 89 * @atomicservice 90 * @since 12 91 */ 92 static keys(): Array<string>; 93} 94/** 95 * Function that returns reason type when error. 96 * 97 * @typedef { function } PersistenceErrorCallback 98 * @param { string } key persisted key when error 99 * @param { 'quota' | 'serialization' | 'unknown' } reason reason type when error 100 * @param { string } message more message when error 101 * @syscap SystemCapability.ArkUI.ArkUI.Full 102 * @crossplatform 103 * @atomicservice 104 * @since 12 105 */ 106export declare type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void; 107/** 108 * PersistenceV2 is for UI state of app-wide access, available on app re-start, 109 * and saves database content in disk. 110 * 111 * @extends AppStorageV2 112 * @syscap SystemCapability.ArkUI.ArkUI.Full 113 * @crossplatform 114 * @atomicservice 115 * @since 12 116 */ 117export declare class PersistenceV2 extends AppStorageV2 { 118 /** 119 * Used to manually persist data changes to disks. 120 * 121 * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type need to persist. 122 * @syscap SystemCapability.ArkUI.ArkUI.Full 123 * @crossplatform 124 * @atomicservice 125 * @since 12 126 */ 127 static save<T>(keyOrType: string | TypeConstructorWithArgs<T>): void; 128 /** 129 * Be called when persisting has encountered an error. 130 * 131 * @param { PersistenceErrorCallback | undefined } callback called when error 132 * @syscap SystemCapability.ArkUI.ArkUI.Full 133 * @crossplatform 134 * @atomicservice 135 * @since 12 136 */ 137 static notifyOnError(callback: PersistenceErrorCallback | undefined): void; 138} 139/** 140 * Define TypeConstructor type. 141 * 142 * @interface TypeConstructor<T> 143 * @syscap SystemCapability.ArkUI.ArkUI.Full 144 * @crossplatform 145 * @atomicservice 146 * @since 12 147 */ 148export interface TypeConstructor<T> { 149 /** 150 * @returns { T } 151 * @syscap SystemCapability.ArkUI.ArkUI.Full 152 * @crossplatform 153 * @atomicservice 154 * @since 12 155 */ 156 new (): T; 157} 158/** 159 * Function that returns PropertyDecorator. 160 * 161 * @typedef { function } TypeDecorator 162 * @param { TypeConstructor<T> } type type info 163 * @returns { PropertyDecorator } Type decorator 164 * @syscap SystemCapability.ArkUI.ArkUI.Full 165 * @crossplatform 166 * @atomicservice 167 * @since 12 168 */ 169export declare type TypeDecorator = <T>(type: TypeConstructor<T>) => PropertyDecorator; 170/** 171 * Define Type PropertyDecorator, adds type information to an object. 172 * 173 * @syscap SystemCapability.ArkUI.ArkUI.Full 174 * @crossplatform 175 * @atomicservice 176 * @since 12 177 */ 178export declare const Type: TypeDecorator; 179/** 180 * UIUtils is a state management tool class for operating the observed data. 181 * 182 * @syscap SystemCapability.ArkUI.ArkUI.Full 183 * @crossplatform 184 * @atomicservice 185 * @since 12 186 */ 187export declare class UIUtils { 188 /** 189 * Get raw object from the Object wrapped with an ObservedObject. 190 * If input parameter is a regular Object without ObservedObject, return Object itself. 191 * 192 * @param { T } source input source Object data. 193 * @returns { T } raw object from the Object wrapped with an ObservedObject. 194 * @syscap SystemCapability.ArkUI.ArkUI.Full 195 * @crossplatform 196 * @atomicservice 197 * @since 12 198 */ 199 static getTarget<T extends object>(source: T): T; 200 /** 201 * Make non-observed data into observed data. 202 * Support non-observed class, JSON.parse Object and Sendable class. 203 * 204 * @param { T } source input source object data. 205 * @returns { T } proxy object from the source object data. 206 * @syscap SystemCapability.ArkUI.ArkUI.Full 207 * @crossplatform 208 * @atomicservice 209 * @since 12 210 */ 211 static makeObserved<T extends object>(source: T): T; 212 /** 213 * Make non-observed data into V1 observed data. 214 * Support JS object, interface, class (non-@Observed, non-ObservedV2). 215 * 216 * @param { T } source input source object data. 217 * @returns { T } V1 proxy object from the source object data. 218 * @static 219 * @syscap SystemCapability.ArkUI.ArkUI.Full 220 * @crossplatform 221 * @atomicservice 222 * @since 19 223 */ 224 static makeV1Observed<T extends object>(source: T): T; 225 226 /** 227 * Enables V2 compatibility on given viewmodel object or nested viewmodels, which are V1 observed object already. 228 * 229 * @param {T} source - The object to be made V2-compatible. 230 * @returns {T} The processed object with V2 compatibility enabled. 231 * @static 232 * @syscap SystemCapability.ArkUI.ArkUI.Full 233 * @crossplatform 234 * @atomicservice 235 * @since 19 236 */ 237 static enableV2Compatibility<T extends object>(source: T): T; 238 239 /** 240 * Creates read-only data binding. 241 * 242 * 243 * Example. UIUtils.makeBinding<number>(()=>this.num); 244 * 245 * Supports simple getters for read-only data. 246 * Intended for primitive value parameters when calling a @Builder function where arguments are of type Binding. 247 * 248 * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T. 249 * @returns { Binding<T> } read-only data binding value 250 * @static 251 * @syscap SystemCapability.ArkUI.ArkUI.Full 252 * @crossplatform 253 * @atomicservice 254 * @since 20 255 */ 256 static makeBinding<T>(getter: GetterCallback<T>): Binding<T>; 257 258 /** 259 * Creates a mutable data binding. 260 * 261 * Two functions to implement function overloading. 262 * 263 * Example. UIUtils.makeBinding<number>(()=>this.num, val => this.num = val); 264 * 265 * Supports getter-setter pairs for mutable data. 266 * Intended for primitive value parameters when calling a @Builder 267 * function where arguments are of type MutableBinding. 268 * 269 * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T. 270 * @param { SetterCallback<T> } setter - A function to set a new value of type T. 271 * If provided, a MutableBinding is created. 272 * @returns { MutableBinding<T> } mutable data binding value 273 * @static 274 * @syscap SystemCapability.ArkUI.ArkUI.Full 275 * @crossplatform 276 * @atomicservice 277 * @since 20 278 */ 279 static makeBinding<T>(getter: GetterCallback<T>, setter: SetterCallback<T>): MutableBinding<T>; 280} 281/** 282 * Getter callback type. It is used to get value. 283 * 284 * @typedef { function } GetterCallback 285 * @returns { T } 286 * @syscap SystemCapability.ArkUI.ArkUI.Full 287 * @crossplatform 288 * @atomicservice 289 * @since 20 290 */ 291export declare type GetterCallback<T> = () => T; 292 293/** 294 * Setter callback type. It is used to assign a new value. 295 * 296 * @typedef { function } SetterCallback 297 * @param { T } newValue - update the value with newValue. 298 * @syscap SystemCapability.ArkUI.ArkUI.Full 299 * @crossplatform 300 * @atomicservice 301 * @since 20 302 */ 303export declare type SetterCallback<T> = (newValue: T) => void; 304 305/** 306 * Represents a read-only data binding. 307 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function. 308 * @syscap SystemCapability.ArkUI.ArkUI.Full 309 * @crossplatform 310 * @atomicservice 311 * @since 20 312 */ 313export declare class Binding<T> { 314 /** 315 * Get function that can acquire the value. 316 * @returns T 317 * @syscap SystemCapability.ArkUI.ArkUI.Full 318 * @crossplatform 319 * @atomicservice 320 * @since 20 321 */ 322 get value(): T; 323} 324 325/** 326 * Represents a mutable data binding allowing both read and write operations. 327 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function. 328 * @syscap SystemCapability.ArkUI.ArkUI.Full 329 * @crossplatform 330 * @atomicservice 331 * @since 20 332 */ 333export declare class MutableBinding<T> { 334 /** 335 * Get function that can acquire the value. 336 * @returns T 337 * @syscap SystemCapability.ArkUI.ArkUI.Full 338 * @crossplatform 339 * @atomicservice 340 * @since 20 341 */ 342 get value(): T; 343 /** 344 * Set function that can set the new value. 345 * @syscap SystemCapability.ArkUI.ArkUI.Full 346 * @crossplatform 347 * @atomicservice 348 * @since 20 349 */ 350 set value(newValue: T): void; 351} 352