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 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 } 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}