From 589c78b00f002b807172cfc2d53d8ba7766046a4 Mon Sep 17 00:00:00 2001 From: s10021109 Date: Tue, 8 Jul 2025 11:10:52 +0800 Subject: [PATCH 1/2] =?UTF-8?q?Environment=E5=92=8CpersistStorage=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: s10021109 --- .../stateManagement/storage/environment.d.ets | 91 ++++++++++ .../storage/persistentStorage.d.ets | 155 ++++++++++++++++++ 2 files changed, 246 insertions(+) create mode 100644 api/arkui/stateManagement/storage/environment.d.ets create mode 100644 api/arkui/stateManagement/storage/persistentStorage.d.ets diff --git a/api/arkui/stateManagement/storage/environment.d.ets b/api/arkui/stateManagement/storage/environment.d.ets new file mode 100644 index 0000000000..adec7aeb40 --- /dev/null +++ b/api/arkui/stateManagement/storage/environment.d.ets @@ -0,0 +1,91 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"), + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +/** + * EnvProps object + * + * @interface EnvPropsOptions + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface EnvPropsOptions { + + /** + * Property name of Environment variable + * + * @type { string } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + key: string; + + /** + * DefaultValue is the default value if cannot get the environment property value + * + * @type { number | string | boolean } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + defaultValue: number | string | boolean; +} + +/** + * Defines the Environment interface. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare class Environment { + /** + * Creates a new property in AppStorage. The UI framework implementation takes care of updating + * its value whenever the named device environment property changes. Recommended use is at app startup. + * The function call fails and returns false if a property with given name exists in AppStorage already. + * It is wrong API use to access a property with given name in AppStorage before calling Environment.envProp. + * + * @param { string } key - environment property + * @param { T } value - is the default value if cannot get the environment property value + * @returns { boolean } false if method failed + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static envProp(key: string, value: T): boolean; + + /** + * Called when multiple property values are added to Environment. + * + * @param { EnvPropsOptions[] } props environment parameter + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static envProps(props: EnvPropsOptions[]): void; + + /** + * returns an Array of all environment property keys + * + * @returns { Array } all environment property keys + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static keys(): Array; +} \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/persistentStorage.d.ets b/api/arkui/stateManagement/storage/persistentStorage.d.ets new file mode 100644 index 0000000000..195df40337 --- /dev/null +++ b/api/arkui/stateManagement/storage/persistentStorage.d.ets @@ -0,0 +1,155 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"), + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +/** + * EnvProps object + * + * @interface PersistPropsOptions + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +declare interface PersistPropsOptions { + + /** + * Property name + * + * @type { string } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + key: string; + + /** + * If AppStorage does not include this property it will be initialized with this value + * + * @type { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + defaultValue: T; + + /** + * Property value type + * + * @type { Type } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + ttype: Type; + + /** + * Used to serialize data + * + * @type { ?ToJSONType } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + toJson?: ToJSONType; + + /** + * Used to deserialize data + * + * @type { ?FromJSONType } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + fromJson?: FromJSONType; +} + +/** + * Defines the PersistentStorage interface. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare class PersistentStorage { + /** + * Add property 'key' to AppStorage properties whose current value will be + * persistent. + * If AppStorage does not include this property it will be added and initializes + * with given value + * + * @param { string } key - property name + * @param { Type } ttype - persist value type + * @param { T } defaultValue - If AppStorage does not include this property it will be initialized with this value + * @param { ToJSONType } [toJson] - serialization function + * @param { FromJSONType } [fromJson] - deserialization function + * @returns { boolean } + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static persistProp(key: string, ttype: Type, defaultValue: T, toJson?: ToJSONType, fromJson?: FromJSONType): boolean; + + /** + * Reverse of @see persistProp + * + * @param { string } key - no longer persist the property named key + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static deleteProp(key: string): void; + + /** + * Persist given AppStorage properties with given names. + * If a property does not exist in AppStorage, add it and initialize it with given value + * works as @see persistProp for multiple properties. + * + * @param { PersistPropsOptions[] } props persistent parameter + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static persistProps(props: PersistPropsOptions[]): void; + + /** + * Inform persisted AppStorage property names + * + * @returns { Array } array of AppStorage keys + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static keys(): Array; +} + +/** + * Define toJson type function. + * + * @typedef { function } ToJSONType + * @param { T } value toJson value + * @returns { jsonx.JsonElement } Json stringify element object + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare type ToJSONType = (value: T) => jsonx.JsonElement; + +/** + * Define fromJson type function. + * + * @typedef { function } FromJSONType + * @param { jsonx.JsonElement } element json element + * @returns { T } deserialization result + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare type FromJSONType = (element: jsonx.JsonElement) => T; \ No newline at end of file -- Gitee From be165730d6d4b1b88b5d483122d9d4ddcb08264a Mon Sep 17 00:00:00 2001 From: s10021109 Date: Wed, 9 Jul 2025 14:30:21 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E5=BC=BA=E5=9F=BA=E7=8A=B6=E6=80=81?= =?UTF-8?q?=E7=AE=A1=E7=90=86API(4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: s10021109 --- api/@ohos.arkui.stateManagement.d.ets | 60 +- api/arkui/stateManagement/decorator.d.ets | 794 ++++++++++++++++++ .../stateManagement/storage/appStorage.d.ets | 31 + .../storage/appStorageV2.d.ets | 85 ++ .../stateManagement/storage/environment.d.ets | 4 +- .../storage/localStorage.d.ets | 188 +++++ .../storage/persistenceV2.d.ets | 252 ++++++ .../storage/storageProperty.d.ets | 63 ++ 8 files changed, 1440 insertions(+), 37 deletions(-) create mode 100644 api/arkui/stateManagement/decorator.d.ets create mode 100644 api/arkui/stateManagement/storage/appStorage.d.ets create mode 100644 api/arkui/stateManagement/storage/appStorageV2.d.ets create mode 100644 api/arkui/stateManagement/storage/localStorage.d.ets create mode 100644 api/arkui/stateManagement/storage/persistenceV2.d.ets create mode 100644 api/arkui/stateManagement/storage/storageProperty.d.ets diff --git a/api/@ohos.arkui.stateManagement.d.ets b/api/@ohos.arkui.stateManagement.d.ets index f29f2f0d28..a91aa3b533 100644 --- a/api/@ohos.arkui.stateManagement.d.ets +++ b/api/@ohos.arkui.stateManagement.d.ets @@ -1,34 +1,26 @@ -/* - * Copyright (C) 2025 Huawei Device Co., Ltd. - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** - * @file State management API file - * @kit ArkUI - * @arkts 1.2 - */ - -export * from './arkui/stateManagement/common'; -export * from './arkui/stateManagement/runtime'; -export * from './arkui/stateManagement/storage'; -export * from './arkui/stateManagement/base/decoratorBase'; -export * from './arkui/stateManagement/base/iObservedObject'; -export * from './arkui/stateManagement/decorators/decoratorState'; -export * from './arkui/stateManagement/decorators/decoratorLink'; -export * from './arkui/stateManagement/decorators/decoratorProp'; -export * from './arkui/stateManagement/decorators/decoratorStorageLink'; -export * from './arkui/stateManagement/decorators/decoratorStorageProp'; -export * from './arkui/stateManagement/decorators/decoratorWatch'; -export * from './arkui/stateManagement/storages/appStorage'; -export * from './arkui/stateManagement/storages/localStorage'; \ No newline at end of file +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file State management API file + * @kit ArkUI + * @arkts 1.2 + */ + +export * from './arkui/stateManagement/decorator'; +export * from './arkui/stateManagement/runtime'; +export * from './arkui/stateManagement/storage'; +export * from './arkui/stateManagement/utils'; +export * from './arkui/stateManagement/storage/storageProperty'; \ No newline at end of file diff --git a/api/arkui/stateManagement/decorator.d.ets b/api/arkui/stateManagement/decorator.d.ets new file mode 100644 index 0000000000..26a631f790 --- /dev/null +++ b/api/arkui/stateManagement/decorator.d.ets @@ -0,0 +1,794 @@ +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +import { ExtendableComponent } from '../component/extendableComponent'; + +/** + * Define decorated variable interface. + * + * @interface IDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IDecoratedVariable { + /** + * Decorated variable name. + * + * @type { string } + * @readonly + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + readonly varName: string; +} + +/** + * Define V1 decorated variable interface. + * + * @extends IDecoratedVariable + * @interface IDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IDecoratedV1Variable extends IDecoratedVariable { + /** + * Registers the watch callback function with the data source. + * + * @param { IDecoratedV1Variable } decoratedVar + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + registerWatchToSource(decoratedVar: IDecoratedV1Variable): void; +} + +/** + * Define decorated immutable variable interface. + * + * @interface IDecoratedImmutableVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IDecoratedImmutableVariable { + /** + * Get the state variable. + * + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + get(): T; +} + +/** + * Define decorated mutable variable interface. + * + * @interface IDecoratedMutableVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IDecoratedMutableVariable { + /** + * Get the state variable. + * + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + get(): T; + /** + * Set the state variable with a new Value. + * + * @param { T } newValue + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + set(newValue: T): void; +} + +/** + * Define decorated updatable variable interface. + * + * @interface IDecoratedUpdatableVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IDecoratedUpdatableVariable { + /** + * Update the state variable with a new Value. + * + * @param { T } newValue + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + update(newValue: T): void; +} + +/** + * Define state decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface IStateDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IStateDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define PropRef decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedUpdatableVariable, IDecoratedV1Variable + * @interface IPropRefDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IPropRefDecoratedVariable extends IDecoratedMutableVariable, + IDecoratedUpdatableVariable, IDecoratedV1Variable {} + +/** + * Define Link decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface ILinkDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface ILinkDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define Provide decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface IProvideDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IProvideDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define Consume decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface IConsumeDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IConsumeDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define ObjectLink decoration variable interface. + * + * @extends IDecoratedImmutableVariable, IDecoratedUpdatableVariable, IDecoratedV1Variable + * @interface IObjectLinkDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IObjectLinkDecoratedVariable extends IDecoratedImmutableVariable, + IDecoratedUpdatableVariable, IDecoratedV1Variable {} + +/** + * Define StorageLink decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface IStorageLinkDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IStorageLinkDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define StoragePropRef decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface IStoragePropRefDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IStoragePropRefDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define Local decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV2Variable + * @interface ILocalDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface ILocalDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV2Variable {} + +/** + * Define mutable state meta interface. + * + * @interface IMutableStateMeta + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IMutableStateMeta { + /** + * Collect the dependancy for UI component with state variable + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + addRef(): void; + /** + * Notify UI component to update when state variable is changed + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + fireChange(): void; +} + +/** + * Define V2 decorated variable interface. + * + * @extends IDecoratedVariable + * @interface IDecoratedV2Variable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export interface IDecoratedV2Variable extends IDecoratedVariable {} + +/** + * Define LocalStorageLink decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface ILocalStorageLinkDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface ILocalStorageLinkDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define mutable state meta interface with key. + * + * @interface IMutableKeyedStateMeta + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IMutableKeyedStateMeta { + /** + * Collect the dependancy for UI component with state variable based on given key + * + * @param { string } key + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + addRef(key: string): void; + /** + * Collect the dependancy for UI component with state variable based on given key + * + * @param { int } index + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + addRef(index: int): void; + /** + * Notify UI component with given key to update when state variable is changed + * + * @param { string } key + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + fireChange(key: string): void; + /** + * Notify UI component with given key to update when state variable is changed + * + * @param { int } index + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + fireChange(index: int): void; +} + +/** + * Define IObserve interface. + * + * @interface IObserve + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IObserve { + /** + * Rendering component. + * + * @type { number } + * @readonly + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + readonly renderingComponent: number; + /** + * Rendering component id. + * + * @type { RenderIdType } + * @readonly + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + readonly renderingId: RenderIdType; + /** + * Collect the dependancy for UI component with state variable + * + * @param { RenderIdType } iObjectsRenderId + * @returns { boolean } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + shouldAddRef(iObjectsRenderId: RenderIdType): boolean; +} + +/** + * Define OBSERVED. + * + * @type { IObserve } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare const OBSERVE: IObserve; + +/** + * Define Provider decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV2Variable + * @interface IProviderDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IProviderDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV2Variable {} + +/** + * Define int alias. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export type RenderIdType = int; + +/** + * Define Consumer decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV2Variable + * @interface IConsumerDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IConsumerDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV2Variable {} + +/** + * Define IObservedObject interface. + * + * @extends IWatchSubscriberRegister + * @interface IObservedObject + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IObservedObject extends IWatchSubscriberRegister { + /** + * Set V1 renderId + * + * @param { RenderIdType } renderId + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + setV1RenderId(renderId: RenderIdType): void; +} + +/** + * Define STATE_MGMT_FACTORY. + * + * @type { IStateMgmtFactory } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare const STATE_MGMT_FACTORY: IStateMgmtFactory; + +/** + * Define IStateMgmtFactory interface. + * + * @interface IStateMgmtFactory + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IStateMgmtFactory { + /** + * get mutable state meta + * + * @returns { IMutableStateMeta } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeMutableStateMeta(): IMutableStateMeta; + /** + * get subscribed watches + * + * @returns { ISubscribedWatches } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeSubscribedWatches(): ISubscribedWatches; + /** + * Create a State variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } initValue - state variable initValue. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IStateDecoratedVariable } State instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeState(owningView: ExtendableComponent, varName: string, initValue: T, + watchFunc?: WatchFuncType): IStateDecoratedVariable; + /** + * Create a PropRef variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } initValue - state variable initValue. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IPropRefDecoratedVariable } PropRef instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makePropRef(owningView: ExtendableComponent, varName: string, initValue: T, + watchFunc?: WatchFuncType): IPropRefDecoratedVariable; + + /** + * Create a Link variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { LinkSourceType } source - state variable sync source. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { ILinkDecoratedVariable } PropRef instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeLink(owningView: ExtendableComponent, varName: string, source: LinkSourceType, + watchFunc?: WatchFuncType): ILinkDecoratedVariable; + + /** + * Create a Provide variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { string } provideAlias - provide alias. + * @param { T } initValue - init value. + * @param { boolean } allowOverride - Override the @Provide of any parent + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IProvideDecoratedVariable } Provide instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeProvide(owningView: ExtendableComponent, varName: string, provideAlias: string, initValue: T, + allowOverride: boolean, watchFunc?: WatchFuncType): IProvideDecoratedVariable; + + /** + * Create a Consume variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { string } provideAlias - provide alias. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IConsumeDecoratedVariable } Consume instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeConsume(owningView: ExtendableComponent, varName: string, + provideAlias: string, watchFunc?: WatchFuncType): IConsumeDecoratedVariable; + + /** + * Create a ObjectLink variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } initValue - init value. + * @param { WatchFuncType } [wathcFunc] - watch type + * @returns { IObjectLinkDecoratedVariable } ObjectLink instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeObjectLink(owningView: ExtendableComponent, varName: string, + initValue: T, wathcFunc?: WatchFuncType): IObjectLinkDecoratedVariable; + + /** + * Create a StorageLink variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } propName - property name. + * @param { string } varName - state variable name. + * @param { T } initValue - init value. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IStorageLinkDecoratedVariable } StorageLink instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeStorageLink(owningView: ExtendableComponent, propName: string, + varName: string, initValue: T, watchFunc?: WatchFuncType): IStorageLinkDecoratedVariable; + + /** + * Create a StoragePropRef variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } propName - property name. + * @param { string } varName - state variable name. + * @param { T } initValue - init value. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { IStoragePropRefDecoratedVariable } StoragePropRef instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeStoragePropRef(owningView: ExtendableComponent, propName: string, + varName: string, initValue: T, watchFunc?: WatchFuncType): IStoragePropRefDecoratedVariable; + + /** + * Create a Local variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } localInitValue - state variable initValue. + * @returns { ILocalDecoratedVariable } Local instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeLocal(owningView: ExtendableComponent, varName: string, localInitValue: T): ILocalDecoratedVariable; + + /** + * Create a LocalStorageLink variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } propName - property name. + * @param { string } varName - state variable name. + * @param { T } initValue - init value. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { ILocalStorageLinkDecoratedVariable } LocalStorageLink instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeLocalStorageLink(owningView: ExtendableComponent, propName: string, + varName: string, initValue: T, watchFunc?: WatchFuncType): ILocalStorageLinkDecoratedVariable; + + /** + * Create a Param variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } initValue - param variable initValue. + * @returns { IParamDecoratedVariable } Param instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeParam(owningView: ExtendableComponent, varName: string, initValue: T): IParamDecoratedVariable; + + /** + * Create a provider variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - provider variable name. + * @param { string } providerAlias - provider alias. + * @param { T } localInitValue - provider local variable value. + * @returns { IProviderDecoratedVariable } Provider instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeProvider(owningView: ExtendableComponent, varName: string, providerAlias: string, localInitValue: T ): IProviderDecoratedVariable; + + /** + * Create a consumer variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - consumer variable name. + * @param { string } providerAlias - consumer alias. + * @param { T } defaultValue - consumer default value. + * @returns { IConsumerDecoratedVariable } Consumer instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeConsumer(owningView: ExtendableComponent, varName: string, providerAlias: string, defaultValue: T): IConsumerDecoratedVariable; + /** + * Create a LocalStoragePropRef variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } propName - property name. + * @param { string } varName - state variable name. + * @param { T } initValue - init value. + * @param { WatchFuncType } [watchFunc] - watch type + * @returns { ILocalStoragePropRefDecoratedVariable } LocalStoragePropRef instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeLocalStoragePropRef(owningView: ExtendableComponent, propName: string, varName: string, initValue: T, watchFunc?: WatchFuncType): ILocalStoragePropRefDecoratedVariable; + + /** + * Create a param once variable instance. + * + * @param { ExtendableComponent } owningView - custom component. + * @param { string } varName - state variable name. + * @param { T } initValue - param once variable initValue. + * @returns { IParamOnceDecoratedVariable } Param Once instance + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + makeParamOnce(owningView: ExtendableComponent, varName: string, initValue: T): IParamOnceDecoratedVariable; +} + +/** + * Defines the callback that is called when state variable is change + * @typedef { function } WatchFuncType + * @param {string} propertyName - property name + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export type WatchFuncType = (propertyName: string) => void; + +/** + * Define int alias. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export type WatchIdType = int; + +/** + * Define IWatchSubscriberRegister interface. + * + * @interface IWatchSubscriberRegister + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IWatchSubscriberRegister { + /** + * Registers the watch function callback. + * + * @param { WatchIdType } watchId - the watch function id + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + addWatchSubscriber(watchId: WatchIdType): void; + /** + * UnRegister the watch function callback. + * + * @param { WatchIdType } watchId - the watch function id + * @returns { boolean } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + removeWatchSubscriber(watchId: WatchIdType): boolean; +} + +/** + * Define ISubscribedWatches interface. + * + * @extends IWatchSubscriberRegister + * @interface ISubscribedWatches + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface ISubscribedWatches extends IWatchSubscriberRegister { + /** + * Execute the watch function callback. + * + * @param { string } propertyName - property name + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + executeOnSubscribingWatches(propertyName: string): void; +} + +/** + * Define AbstractProperty interface. + * + * AbstractProperty can be understood as a handler or an alias + * to a property inside LocalStorage / AppStorage singleton + * allows to read the value with @see get and to change the + * value with @see set. + * + * @extends IDecoratedMutableVariable + * @interface AbstractProperty + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface AbstractProperty extends IDecoratedMutableVariable { + /** + * returns the name of the referenced property + * + * @returns { string } name of the referenced property + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + info(): string; +} + +/** + * Define LocalStoragePropRef decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV1Variable + * @interface ILocalStoragePropRefDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface ILocalStoragePropRefDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV1Variable {} + +/** + * Define Param decoration variable interface. + * + * @extends IDecoratedImmutableVariable, IDecoratedUpdatableVariable, IDecoratedV2Variable + * @interface IParamDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IParamDecoratedVariable extends IDecoratedImmutableVariable, IDecoratedUpdatableVariable, IDecoratedV2Variable {} + +/** + * Define Param Once decoration variable interface. + * + * @extends IDecoratedMutableVariable, IDecoratedV2Variable + * @interface IParamOnceDecoratedVariable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface IParamOnceDecoratedVariable extends IDecoratedMutableVariable, IDecoratedV2Variable {} + +/** + * Define Link source type. + * + * @typedef { IStateDecoratedVariable | ILinkDecoratedVariable + * | IPropRefDecoratedVariable | IObjectLinkDecoratedVariable | IStorageLinkDecoratedVariable + * | IProvideDecoratedVariable | IConsumeDecoratedVariable | IStoragePropRefDecoratedVariable + * | ILocalStorageLinkDecoratedVariable | ILocalStoragePropRefDecoratedVariable } LinkSourceType + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +type LinkSourcesType = IStateDecoratedVariable | ILinkDecoratedVariable + | IPropRefDecoratedVariable | IObjectLinkDecoratedVariable | IStorageLinkDecoratedVariable + | IProvideDecoratedVariable | IConsumeDecoratedVariable | IStoragePropRefDecoratedVariable + | ILocalStorageLinkDecoratedVariable | ILocalStoragePropRefDecoratedVariable; + +/** + * SubscribedAbstractProperty is the return value of + * - AppStorage static functions Link(), Prop(), SetAndLink(), and SetAndProp() + * - LocalStorage member methods link(), prop(), setAndLink(), and setAndProp() + * 'T' can be boolean, string, number or custom class. + * Main functions + * see get() reads the linked AppStorage/LocalStorage property value, + * see set(newValue) write a new value to the synched AppStorage/LocalStorage property + * see aboutToBeDeleted() ends the sync relationship with the AppStorage/LocalStorage property + * The app must call this function before the SubscribedAbstractProperty object + * goes out of scope. + * + * @extends AbstractProperty + * @interface SubscribedAbstractProperty + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare interface SubscribedAbstractProperty extends AbstractProperty { + /** + * An app needs to call this function before the instance of SubscribedAbstractProperty + * goes out of scope / is subject to garbage collection. Its purpose is to unregister the + * variable from the two-way/one-way sync relationship that AppStorage/LocalStorage.link()/prop() + * and related functions create. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + aboutToBeDeleted(): void; +} \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/appStorage.d.ets b/api/arkui/stateManagement/storage/appStorage.d.ets new file mode 100644 index 0000000000..578ad4bc2e --- /dev/null +++ b/api/arkui/stateManagement/storage/appStorage.d.ets @@ -0,0 +1,31 @@ +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +import { LocalStorage } from './localStorage'; + +/** + * AppStorage singleton is sub-class of see LocalStorage for + * UI state of app-wide access and same life cycle as the app. + * @type { LocalStorage } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare const AppStorage: LocalStorage; \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/appStorageV2.d.ets b/api/arkui/stateManagement/storage/appStorageV2.d.ets new file mode 100644 index 0000000000..2306a64c15 --- /dev/null +++ b/api/arkui/stateManagement/storage/appStorageV2.d.ets @@ -0,0 +1,85 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"), + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +/** + * AppStorageV2 is for UI state of app-wide access, has same life cycle as the app, + * and saves database content only in memory. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare class AppStorageV2 { + /** + * Return the array of all keys. + * + * @returns { Array } the array of all keys + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static keys(): Array; + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { string } key alias name of the key + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect( + ttype: Type, + key: string, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect( + ttype: Type, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + + /** + * Removes data with the given key or given class type. + * + * @param { string | Type } keyOrType key or class type removing + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static remove(keyOrType: string | Type): void; +} \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/environment.d.ets b/api/arkui/stateManagement/storage/environment.d.ets index adec7aeb40..de2794377c 100644 --- a/api/arkui/stateManagement/storage/environment.d.ets +++ b/api/arkui/stateManagement/storage/environment.d.ets @@ -27,7 +27,6 @@ * @since 20 */ export declare interface EnvPropsOptions { - /** * Property name of Environment variable * @@ -36,7 +35,6 @@ export declare interface EnvPropsOptions { * @since 20 */ key: string; - /** * DefaultValue is the default value if cannot get the environment property value * @@ -67,7 +65,7 @@ export declare class Environment { * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 20 */ - static envProp(key: string, value: T): boolean; + static envProp(key: string, value: T): boolean; /** * Called when multiple property values are added to Environment. diff --git a/api/arkui/stateManagement/storage/localStorage.d.ets b/api/arkui/stateManagement/storage/localStorage.d.ets new file mode 100644 index 0000000000..5b4bc5105a --- /dev/null +++ b/api/arkui/stateManagement/storage/localStorage.d.ets @@ -0,0 +1,188 @@ +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +import { AbstractProperty, SubscribedAbstractProperty } from './storageProperty'; + +/** + * LocalStorage + * Class implements a Map of ObservableObjectBase UI state variables. + * Instances can be created to manage UI state within a limited "local" + * access, and life cycle as defined by the app. + * AppStorage singleton is sub-class of LocalStorage for + * UI state of app-wide access and same life cycle as the app. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare class LocalStorage { + /** + * Construct new instance of LocalStorage + * initialize with all properties and their values that Object.keys(params) returns + * Property values must not be undefined. + * + * @param { Record } [initializingProperties] - initializing Properties + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public constructor(initializingProperties?: Record); + /** + * Obtain a handler or an alias to LocalStorage property with given name. + * + * @param { string } propName LocalStorage property name + * @returns { AbstractProperty | undefined } AbstractProperty object if property with given name exists + * return undefined otherwise. + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public ref(propName: string): AbstractProperty | undefined; + /** + * Obtain a handler or an alias to LocalStorage property with given name. + * + * If property does not exist in LocalStorage, create it with given default value. + * + * @param { string } propName LocalStorage property name + * @param { T } defaultValue If property does not exist in LocalStorage, create it with given default value. + * @returns { AbstractProperty } AbstractProperty object + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public setAndRef(propName: string, defaultValue: T): AbstractProperty; + + /** + * Create and return a two-way sync "(link") to named property + * + * @param { string } propName - name of source property in LocalStorage + * @returns { SubscribedAbstractProperty | undefined } instance of SubscribedAbstractProperty, return undefined + * if named property does not already exist in LocalStorage + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public link(propName: string): SubscribedAbstractProperty | undefined; + + /** + * Like see link(), but will create and initialize a new source property in LocalStorage if missing + * + * @param { string } propName - name of source property in LocalStorage + * @param { T } defaultValue - value to be used for initializing new property in LocalStorage + * default value must be of type T, can be undefined or null. + * @returns { SubscribedAbstractProperty } instance of SubscribedAbstractProperty + * Apps can use SDK functions of base class SubscribedAbstractProperty + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public setAndLink(propName: string, defaultValue: T): SubscribedAbstractProperty; + + /** + * Check if LocalStorage has a property with given name + * return true if property with given name exists + * same as ES6 Map.prototype.has() + * + * @param { string } propName - searched property + * @returns { boolean } true if property with such name exists in LocalStorage + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public has(propName: string): boolean; + + /** + * Returns value of given property + * return undefined if no property with this name + * + * @param { string } propName - property name + * @returns { T | undefined } property value if found or undefined + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public get(propName: string): T | undefined; + /** + * Set value of given property in LocalStorage + * Method sets nothing and returns false if property with this name does not exist in LocalStorage + * newValue can be undefined or null from API 20. + * + * @param { string } propName + * @param { T } newValue - must be of type T, can be undefined or null + * @returns { boolean } true on success, i.e. when above conditions are satisfied, otherwise false + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public set(propName: string, newValue: T): boolean; + /** + * Set value of given property, if it exists, see set() . + * Add property if no property with given name and initialize with given value. + * newValue can be undefined or null from API 12 + * + * @param { string } propName + * @param { T } newValue - must be of type T, can be undefined or null + * @returns { boolean } true on success, i.e. when above conditions are satisfied, otherwise false + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public setOrCreate(propName: string, newValue: T): boolean; + /** + * Provide names of all properties in LocalStorage + * same as ES6 Map.prototype.keys() + * + * @returns { IterableIterator } return a Map Iterator + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public keys(): IterableIterator; + /** + * Returns number of properties in LocalStorage + * same as Map.prototype.size() + * + * @returns { number } return number of properties + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public size(): number; + /** + * Delete property from StorageBase + * Use with caution: + * Before deleting a prop from LocalStorage all its subscribers need to + * unsubscribe from the property. + * This method fails and returns false if given property still has subscribers + * Another reason for failing is unknown property. + * Developer advise: + * Subscribers are created with see link(), see prop() + * and also via @LocalStorageLink and @LocalStorageProp state variable decorators. + * That means as long as their is a @Component instance that uses such decorated variable + * or a sync relationship with a SubscribedAbstractProperty variable the property can nit + * (and also should not!) be deleted from LocalStorage. + * + * @param { string } propName + * @returns { boolean } false if method failed + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public delete(propName: string): boolean; + /** + * Delete all properties from the LocalStorage instance + * Precondition is that there are no subscribers. + * method returns false and deletes no properties if there is any property + * that still has subscribers + * + * @returns { boolean } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + public clear(): boolean; +} \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/persistenceV2.d.ets b/api/arkui/stateManagement/storage/persistenceV2.d.ets new file mode 100644 index 0000000000..28afeabde0 --- /dev/null +++ b/api/arkui/stateManagement/storage/persistenceV2.d.ets @@ -0,0 +1,252 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"), + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +import contextConstant from '@ohos.app.ability.contextConstant'; +import {ToJSONType, FromJSONType } from './persistentStorage'; + +/** + * Function that returns default creator. + * + * @typedef { function } StorageDefaultCreator + * @returns { T } default creator + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare type StorageDefaultCreator = () => T; + +/** + * Define ConnectOptions class. + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export class ConnectOptions { + /** + * Define class constructor + * @type { Type } type class type of the stored value. + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + type: Type; + /** + * Defines alias name of the key, or the function generating the default value. + * @type { ?string } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + key?: string; + /** + * Define the function generating the default value. + * @type { ?StorageDefaultCreator} + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + defaultCreator?: StorageDefaultCreator; + /** + * Define encrypted partition for data storage. + * if not passed in, the defaule value is El2 + * + * @type { ?contextConstant.AreaMode} + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + areaMode?: contextConstant.AreaMode; +} + +/** + * Function that returns reason type when error. + * + * @typedef { function } PersistenceErrorCallback + * @param { string } key persisted key when error + * @param { 'quota' | 'serialization' | 'unknown' } reason reason type when error + * @param { string } message more message when error + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void; + +/** + * Defines Serializable object + * + * @extends JsonElementSerializable, JsonElementDeserializable + * @interface SerializableObject + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export interface SerializableObject extends JsonElementSerializable, JsonElementDeserializable {} + + +/** + * PersistenceV2 is for UI state of app-wide access, available on app re-start, + * and saves database content in disk. + * + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export declare class PersistenceV2 { + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { ToJSONType } toJson to Json function. + * @param { FromJSONType } fromJson serializable function. + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect( + ttype: Type, + toJson: ToJSONType, + fromJson: FromJSONType, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { string } key - alias name of the key. + * @param { ToJSONType } toJson to Json function. + * @param { FromJSONType } fromJson serializable function. + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect( + ttype: Type, + key: string, + toJson: ToJSONType, + fromJson: FromJSONType, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + /** + * Application-level storage path, sharing a storage path for all modules under the application. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { ConnectOptions } connectOptions Application level storage parameters. + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static globalConnect>(connectOptions: ConnectOptions): T | undefined; + + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value. + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect>( + ttype: Type, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + /** + * Application-level storage path, sharing a storage path for all modules under the application. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { ConnectOptions } connectOptions Application level storage parameters. + * @param { ToJSONType } toJson to Json function. + * @param { FromJSONType } fromJson serializable function. + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static globalConnect(connectOptions: ConnectOptions, + toJson: ToJSONType, fromJson: FromJSONType): T | undefined; + + /** + * If used by persistenceV2, module-level storage path, different modules will have their own storage paths. + * If the value for the given key is already available, return the value. + * If not, add the key with value generated by calling defaultFunc and return it to caller. + * + * @param { Type } ttype class type of the stored value. + * @param { string } key - alias name of the key. + * @param { StorageDefaultCreator } [defaultCreator] the function generating the default value + * @returns { T | undefined } the value of the existed key or the default value + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static connect>( + ttype: Type, + key: string, + defaultCreator?: StorageDefaultCreator + ): T | undefined; + + /** + * Be called when persisting has encountered an error. + * + * @param { PersistenceErrorCallback | undefined } callback called when error + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static notifyOnError(callback: PersistenceErrorCallback | undefined): void; + + /** + * Used to manually persist data changes to disks. + * + * @param { string | Type } keyOrType key or class type need to persist. + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static save(keyOrType: string | Type): void; + + /** + * Return the array of all keys. + * + * @returns { Array } the array of all keys + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static keys(): Array; + + /** + * Removes data with the given key or given class type. + * + * @param { string | Type } keyOrType key or class type removing + * @static + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ + static remove(keyOrType: string | Type): void; +} \ No newline at end of file diff --git a/api/arkui/stateManagement/storage/storageProperty.d.ets b/api/arkui/stateManagement/storage/storageProperty.d.ets new file mode 100644 index 0000000000..9d00841cfe --- /dev/null +++ b/api/arkui/stateManagement/storage/storageProperty.d.ets @@ -0,0 +1,63 @@ +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file + * @kit ArkUI + * @arkts 1.2 + */ + +/** + * Defines the callback that is called when state variable with value is change + * @typedef { function } OnChangeType + * @param { string } propertyName - property name + * @param { T } newValue - the new value of state variable + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export type OnChangeType = (propertyName: string, newValue: T) => void; + +/** + * Define AbstractProperty interface. + * + * AbstractProperty can be understood as a handler or an alias + * to a property inside LocalStorage / AppStorage singleton + * allows to read the value with @see get and to change the + * value with @see set. + * + * @interface AbstractProperty + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export interface AbstractProperty {} + +/** + * SubscribedAbstractProperty is the return value of + * - AppStorage static functions Link(), Prop(), SetAndLink(), and SetAndProp() + * - LocalStorage member methods link(), prop(), setAndLink(), and setAndProp() + * 'T' can be boolean, string, number or custom class. + * Main functions + * see get() reads the linked AppStorage/LocalStorage property value, + * see set(newValue) write a new value to the synched AppStorage/LocalStorage property + * see aboutToBeDeleted() ends the sync relationship with the AppStorage/LocalStorage property + * The app must call this function before the SubscribedAbstractProperty object + * goes out of scope. + * + * @extends AbstractProperty + * @interface SubscribedAbstractProperty + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 20 + */ +export interface SubscribedAbstractProperty extends AbstractProperty {} \ No newline at end of file -- Gitee