From dacb9c2d8cd24c91e21ce4106db7ec2899b9a568 Mon Sep 17 00:00:00 2001 From: liwenzhen Date: Sun, 29 Jan 2023 15:20:22 +0800 Subject: [PATCH] update stateMgmt api9 Signed-off-by: liwenzhen Change-Id: Ic4b0b12e8c9e61d50c63b77c2d68473013f8ff8a --- .../component/ets/common_ts_ets_api.d.ts | 158 ++++++++++++++---- .../plugin/dictionaries_supplementary.txt | 2 + 2 files changed, 124 insertions(+), 36 deletions(-) diff --git a/api/@internal/component/ets/common_ts_ets_api.d.ts b/api/@internal/component/ets/common_ts_ets_api.d.ts index 340a574e2b..ac76dc12e0 100644 --- a/api/@internal/component/ets/common_ts_ets_api.d.ts +++ b/api/@internal/component/ets/common_ts_ets_api.d.ts @@ -87,7 +87,12 @@ declare class AppStorage { static staticClear(): boolean; /** - * Called when a cleanup occurs. + * Delete all properties from the AppStorage. + * + * Precondition is that there are no subscribers. + * @returns false and deletes no properties if there is any property + * that still has subscribers. + * * @since 9 */ static Clear(): boolean; @@ -141,18 +146,18 @@ declare abstract class SubscribedAbstractProperty { * @systemapi */ constructor( - /** - * Subscriber IPropertySubscriber. - * @since 7 - * @systemapi - */ - subscribeMe?: IPropertySubscriber, - /** - * Subscriber info. - * @since 7 - * @systemapi - */ - info?: string, + /** + * Subscriber IPropertySubscriber. + * @since 7 + * @systemapi + */ + subscribeMe?: IPropertySubscriber, + /** + * Subscriber info. + * @since 7 + * @systemapi + */ + info?: string, ); /** @@ -511,12 +516,24 @@ declare class PersistentStorage { declare const appStorage: AppStorage; /** - * Define LocalStorage. + * + * 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. + * * @since 9 */ - declare class LocalStorage { +declare class LocalStorage { /** - * Constructor. + * Construct new instance of LocalStorage + * initialize with all properties and their values that Object.keys(params) returns + * Property values must not be undefined. + * @param initializingProperties Object containing keys and values. see set() for valid values + * * @since 9 */ constructor(initializingProperties?: Object); @@ -529,74 +546,143 @@ declare const appStorage: AppStorage; static GetShared(): LocalStorage; /** - * Return true if property with given name exists + * Check if LocalStorage has a property with given name + * return true if property with given name exists + * same as ES6 Map.prototype.has() + * @param propName searched property + * @returns true if property with such name exists in LocalStorage + * * @since 9 */ has(propName: string): boolean; /** - * Return a Map Iterator + * Provide names of all properties in LocalStorage + * same as ES6 Map.prototype.keys() + * @returns return a Map Iterator + * * @since 9 */ keys(): IterableIterator; /** - * Return number of properties + * Returns number of properties in LocalStorage + * same as Map.prototype.size() + * @returns return number of properties + * * @since 9 */ size(): number; /** - * Return value of given property + * Returns value of given property + * return undefined if no property with this name + * @param propName + * @returns property value if found or undefined + * * @since 9 */ - get(propName: string): T; + get(propName: string): T | undefined; /** - * Set value of given property + * Set value of given property in LocalStorage + * Method sets nothing and returns false if property with this name does not exist + * or if newValue is `undefined` or `null` (`undefined`, `null` value are not allowed for state variables). + * @param propName + * @param newValue must be of type T and must not be undefined or null + * @returns true on success, i.e. when above conditions are satisfied, otherwise false + * * @since 9 */ set(propName: string, newValue: T): boolean; /** - * Add property if not property with given name + * Set value of given property, if it exists, see set() . + * Add property if no property with given name and initialize with given value. + * Do nothing and return false if newValue is undefined or null + * (undefined, null value is not allowed for state variables) + * @param propName + * @param newValue must be of type T and must not be undefined or null + * @returns true on success, i.e. when above conditions are satisfied, otherwise false + * * @since 9 */ - setOrCreate(propName: string, newValue?: T): boolean; + setOrCreate(propName: string, newValue: T): boolean; /** - * Create and return a 'link' (two-way sync) to named property + * Create and return a two-way sync "(link") to named property + * @param propName name of source property in LocalStorage + * @returns instance of SubscribedAbstractProperty + * return undefined if named property does not already exist in LocalStorage + * Apps can use SDK functions of base class SubscribedPropertyAbstract + * * @since 9 */ - link(propName: string, linkUser?: T, subscribersName?: string): T; + link(propName: string): SubscribedAbstractProperty; /** - * Like link(), will create and initialize a new source property in LocalStorge if missing + * Like see link(), but will create and initialize a new source property in LocalStorage if missing + * @param propName name of source property in LocalStorage + * @param defaultValue value to be used for initializing if new creating new property in LocalStorage + * default value must be of type S, must not be undefined or null. + * @returns instance of SubscribedAbstractProperty + * Apps can use SDK functions of base class SubscribedAbstractProperty + * * @since 9 */ - setAndLink(propName: string, defaultValue: T, linkUser?: T, subscribersName?: string): T; + setAndLink(propName: string, defaultValue: T): SubscribedAbstractProperty; /** - * Create and return a 'prop' (one-way sync) to named property + * Create and return a one-way sync ('prop') to named property + * @param propName name of source property in LocalStorage + * @returns instance of SubscribedAbstractProperty + * return undefined if named property does not already exist in LocalStorage + * Apps can use SDK functions of base class SubscribedAbstractProperty + * * @since 9 */ - prop(propName: string, propUser?: T, subscribersName?: string): T; + prop(propName: string): SubscribedAbstractProperty; /** - * Like prop(), will create and initialize a new source property in LocalStorage if missing + * Like see prop(), will create and initialize a new source property in LocalStorage if missing + * @param propName name of source property in LocalStorage + * @param defaultValue value to be used for initializing if new creating new property in LocalStorage. + * default value must be of type S, must not be undefined or null. + * @returns instance of SubscribedAbstractProperty + * Apps can use SDK functions of base class SubscribedAbstractProperty + * * @since 9 */ - setAndProp(propName: string, defaultValue: T, propUser?: T, subscribersName?: string): T; - + setAndProp(propName: string, defaultValue: S): SubscribedAbstractProperty; + /** * Delete property from StorageBase - * @since 9 + * 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 propName * @returns false if method failed - */ + * + * @since 9 + */ delete(propName: string): boolean; /** - * Delete all properties from the StorageBase + * 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 + * * @since 9 */ clear(): boolean; diff --git a/build-tools/api_check_plugin/plugin/dictionaries_supplementary.txt b/build-tools/api_check_plugin/plugin/dictionaries_supplementary.txt index 1fcf2bc1a3..22a67fd99d 100644 --- a/build-tools/api_check_plugin/plugin/dictionaries_supplementary.txt +++ b/build-tools/api_check_plugin/plugin/dictionaries_supplementary.txt @@ -599,6 +599,7 @@ subassembies subcomponents subnode subpixel +suscriber subscrbers subscribale subscribes @@ -607,6 +608,7 @@ superimposed suscribes suspends switchvideomode +synched synchronizes synchronizing synth -- Gitee