1# Persisting Preferences Data 2 3 4## When to Use 5 6The **Preferences** module provides APIs for processing data in the form of key-value (KV) pairs, including querying, modifying, and persisting KV pairs. You can use **Preferences** when you want a unique storage for global data. <br>**Preferences** caches data in the memory, which allows fast access when the data is required. If you want to persist data, you can use **flush()** to save the data to a file. **Preferences** is recommended for storing small amount of data, such as personalized settings (font size and whether to enable the night mode) of applications. 7 8 9## Working Principles 10 11User applications call **Preference** through the ArkTS interface to read and write data files. You can load the data of a **Preferences** persistence file to a **Preferences** instance. Each file uniquely corresponds to an instance. The system stores the instance in memory through a static container until the instance is removed from the memory or the file is deleted. The following figure illustrates how **Preference** works. 12 13The preference persistent file of an application is stored in the application sandbox. You can use **context** to obtain the file path. For details, see [Obtaining Application File Paths](../application-models/application-context-stage.md#obtaining-application-file-paths). 14 15**Figure 1** Preferences working mechanism 16 17 18 19 20## Constraints 21 22- The key in a KV pair must be a string and cannot be empty or exceed 80 bytes. 23 24- If the value is of the string type, use the UTF-8 encoding format. It can be empty or a string not longer than 8192 bytes. 25 26- The memory usage increases with the amount of **Preferences** data. The maximum number of data records recommended is 10,000. Otherwise, high memory overheads will be caused. 27 28 29## Available APIs 30 31The following table lists the APIs used for persisting user preference data. For more information about the APIs, see [User Preferences](../reference/apis-arkdata/js-apis-data-preferences.md). 32 33| API | Description | 34| ------------------------------------------------------------ | ------------------------------------------------------------ | 35| getPreferencesSync(context: Context, options: Options): Preferences | Obtains a **Preferences** instance. This API returns the result synchronously.<br/> An asynchronous API is also provided. | 36| putSync(key: string, value: ValueType): void | Writes data to the **Preferences** instance. This API returns the result synchronously. An asynchronous API is also provided.<br/>You can use **flush()** to persist the **Preferences** instance data. | 37| hasSync(key: string): void | Checks whether the **Preferences** instance contains a KV pair with the given key. The key cannot be empty. This API returns the result synchronously.<br/> An asynchronous API is also provided.| 38| getSync(key: string, defValue: ValueType): void | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned. This API returns the result synchronously.<br/> An asynchronous API is also provided.| 39| deleteSync(key: string): void | Deletes a KV pair with the given key from the **Preferences** instance. This API returns the result synchronously.<br/> An asynchronous API is also provided.| 40| flush(callback: AsyncCallback<void>): void | Flushes the data of this **Preferences** instance to a file for data persistence.| 41| on(type: 'change', callback: Callback<string>): void | Subscribes to data changes of the specified key. When the value of the specified key is changed and saved by **flush()**, a callback will be invoked to return the new data.| 42| off(type: 'change', callback?: Callback<string>): void | Unsubscribes from data changes. | 43| deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void | Deletes a **Preferences** instance from memory. If the **Preferences** instance has a persistent file, this API also deletes the persistent file.| 44 45 46## How to Develop 47 481. Import the **@ohos.data.preferences** module. 49 50 ```ts 51 import dataPreferences from '@ohos.data.preferences'; 52 ``` 53 542. Obtain a **Preferences** instance. Read data from a file and load the data to a **Preferences** instance for data operations. 55 56 Stage model: 57 58 59 ```ts 60 import UIAbility from '@ohos.app.ability.UIAbility'; 61 import { BusinessError } from '@ohos.base'; 62 import window from '@ohos.window'; 63 64 let preferences: dataPreferences.Preferences | null = null; 65 66 class EntryAbility extends UIAbility { 67 onWindowStageCreate(windowStage: window.WindowStage) { 68 let options: dataPreferences.Options = { name: 'myStore' }; 69 preferences = dataPreferences.getPreferencesSync(this.context, options); 70 } 71 } 72 ``` 73 74 FA model: 75 76 77 ```ts 78 // Obtain the context. 79 import featureAbility from '@ohos.ability.featureAbility'; 80 import { BusinessError } from '@ohos.base'; 81 82 let context = featureAbility.getContext(); 83 let options: dataPreferences.Options = { name: 'myStore' }; 84 let preferences: dataPreferences.Preferences = dataPreferences.getPreferencesSync(context, options); 85 ``` 86 873. Write data. 88 89 Use **putSync()** to save data to the cached **Preferences** instance. After data is written, you can use **flush()** to persist the **Preferences** instance data to a file if necessary. 90 91 > **NOTE** 92 > 93 > If the specified key already exists, the **putSync()** method changes the value. You can use **hasSync()** to check whether the KV pair exists. 94 95 Example: 96 97 ```ts 98 import util from '@ohos.util'; 99 if (preferences.hasSync('startup')) { 100 console.info("The key 'startup' is contained."); 101 } else { 102 console.info("The key 'startup' does not contain."); 103 // Add a KV pair. 104 preferences.putSync('startup', 'auto'); 105 // If the string contains special characters, convert the string into a Uint8Array before storing it. 106 let uInt8Array = new util.TextEncoder().encodeInto("~! @#￥%......&* () --+? "); 107 preferences.putSync('uInt8', uInt8Array); 108 } 109 ``` 110 1113. Read data. 112 113 Use **getSync()** to obtain the value of the specified key. If the value is null or is not of the default value type, the default data is returned. 114 115 Example: 116 117 ```ts 118 import util from '@ohos.util'; 119 let val = preferences.getSync('startup', 'default'); 120 console.info("The 'startup' value is " + val); 121 // If the value is a string containing special characters, it is stored in the Uint8Array format. Conver the obtained Uint8Array into a string. 122 let uInt8Array : dataPreferences.ValueType = preferences.getSync('uInt8', new Uint8Array(0)); 123 let textDecoder = util.TextDecoder.create('utf-8'); 124 val = textDecoder.decodeWithStream(uInt8Array as Uint8Array); 125 console.info("The 'uInt8' value is " + val); 126 ``` 127 1284. Delete data. 129 130 Use **deleteSync()** to delete a KV pair.<br>Example: 131 132 133 ```ts 134 preferences.deleteSync('startup'); 135 ``` 136 1376. Persist data. 138 139 You can use **flush()** to persist the data held in a **Preferences** instance to a file.<br>Example: 140 141 ```ts 142 preferences.flush((err: BusinessError) => { 143 if (err) { 144 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 145 return; 146 } 147 console.info('Succeeded in flushing.'); 148 }) 149 ``` 150 1517. Subscribe to data changes. 152 153 Specify an observer as the callback to return the data changes for an application. When the value of the subscribed key is changed and saved by **flush()**, the observer callback will be invoked to return the new data.<br>Example: 154 155 ```ts 156 let observer = (key: string) => { 157 console.info('The key' + key + 'changed.'); 158 } 159 preferences.on('change', observer); 160 // The data is changed from 'auto' to 'manual'. 161 preferences.put('startup', 'manual', (err: BusinessError) => { 162 if (err) { 163 console.error(`Failed to put the value of 'startup'. Code:${err.code},message:${err.message}`); 164 return; 165 } 166 console.info("Succeeded in putting the value of 'startup'."); 167 if (preferences !== null) { 168 preferences.flush((err: BusinessError) => { 169 if (err) { 170 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 171 return; 172 } 173 console.info('Succeeded in flushing.'); 174 }) 175 } 176 }) 177 ``` 178 1798. Delete a **Preferences** instance from the memory. 180 181 Use **deletePreferences()** to delete a **Preferences** instance from the memory. If the **Preferences** instance has a persistent file, the persistent file and its backup and corrupted files will also be deleted. 182 183 > **NOTE** 184 > 185 > - The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused. 186 > 187 > - The deleted data and files cannot be restored. 188 189 Example: 190 191 ```ts 192 let options: dataPreferences.Options = { name: 'myStore' }; 193 dataPreferences.deletePreferences(this.context, options, (err: BusinessError) => { 194 if (err) { 195 console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`); 196 return; 197 } 198 console.info('Succeeded in deleting preferences.'); 199 }) 200 ``` 201 202 203
