场景介绍
用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。当用户希望有一个全局唯一存储的地方，可以采用用户首选项来进行存储。Preferences会将该数据缓存在内存中，当用户读取的时候，能够快速从内存中获取数据，当需要持久化时可以使用flush接口将内存中的数据写入持久化文件中。Preferences会随着存放的数据量越多而导致应用占用的内存越大，因此，Preferences不适合存放过多的数据，也不支持通过配置加密，适用的场景一般为应用保存用户的个性化设置（字体大小，是否开启夜间模式）等。
运作机制
如图所示，用户程序通过ArkTS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。
应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见获取应用文件路径。
图1 用户首选项运作机制
约束限制
-
首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。
-
Key键为string类型，要求非空且长度不超过1024个字节。
-
如果Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16 * 1024 * 1024个字节。
-
内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销。
接口说明
以下是用户首选项持久化功能的相关接口，更多接口及使用方式请见用户首选项。
| 接口名称 | 描述 |
|---|---|
| getPreferencesSync(context: Context, options: Options): Preferences | 获取Preferences实例。该接口存在异步接口。 |
| putSync(key: string, value: ValueType): void | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。该接口存在异步接口。 |
| hasSync(key: string): boolean | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。该接口存在异步接口。 |
| getSync(key: string, defValue: ValueType): ValueType | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。该接口存在异步接口。 |
| deleteSync(key: string): void | 从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。 |
| flush(callback: AsyncCallback<void>): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 |
| on(type: 'change', callback: Callback<string>): void | 订阅数据变更，订阅的数据发生变更后，在执行flush方法后，触发callback回调。 |
| off(type: 'change', callback?: Callback<string>): void | 取消订阅数据变更。 |
| deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。 |
开发步骤
新增/修改数据
import { preferences } from '@kit.ArkData'
@Entry
@Component
struct Index {build() {Row() {Column() {// 1.0 利用首选项api对store这个文件做一个新增数据：["鸿蒙","HTML5"]Button('新增/修改数据').onClick(() => {// 1.0 获取store文件的操作对象const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })
// 2.0 调用操作对象上的putSync方法完成数据的新增 (这是将数据保存到内存中)pre.putSync('keyword', ["鸿蒙Next", "huawei"])pre.putSync('keyword2', ["HTML5", "JavaScript"])
pre.flush() //将内存数据写入到磁盘
AlertDialog.show({ message: '首选项数据写入成功' })})}.width('100%')}
}
}
结果查询：
修改数据就还是用key值把之前数据修改成需要的就行
查询数据
代码：
Button('获取数据').onClick(() => {const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })AlertDialog.show({ message: JSON.stringify(pre.getAllSync()) })
})
删除数据
Button('删除数据').onClick(() => {const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })pre.deleteSync('keyword')pre.flush()AlertDialog.show({ message: '首选项数据删除成功' })})
实例
通过一个搜索框实例进行系统组合起来
静态结构
@Entry
@Component
struct SearchPage {@State keyword: string = ''@State isdel: boolean = falseaboutToAppear(): void {
}
@BuilderitemBuilder(text: string) {Row({ space: 20 }) {Text(text)if (this.isdel) {Text('x').height(30).onClick(() => {AlertDialog.show({ message: '删除' + text })})}}.margin({ right: 10, top: 10 }).padding({left: 15,right: 15,top: 5,bottom: 5}).backgroundColor('rgba(0,0,0,0.05)').borderRadius(20)}
build() {Navigation() {Column({ space: 15 }) {// 1. 搜索关键字TextInput({ placeholder: '输入回车保存数据', text: $$this.keyword }).onSubmit(() => {AlertDialog.show({ message: this.keyword })})
// 2. 关键字列表Row() {Text('搜索记录').fontSize(20).fontWeight(800)
Row() {if (this.isdel) {Text('全部删除').onClick(()=>{AlertDialog.show({ message: '补上全部删除逻辑' })})Text(' | ')Text('取消删除').onClick(()=>{this.isdel = false})} else {Text('X').height(28).onClick(()=>{this.isdel = true})}}}.width('100%').justifyContent(FlexAlign.SpaceBetween)
// 3. 关键字列表Flex({ wrap: FlexWrap.Wrap }) {ForEach([1, 2, 3, 4], (item: number) => {this.itemBuilder('文本' + item)})}}.padding(15)}.padding({ top: 20 }).titleMode(NavigationTitleMode.Mini).title('搜索页面')}
}
实现历史搜索记录
保存关键字数组
import { preferences } from '@kit.ArkData'
@Entry
@Component
struct SearchPage {@State keyword: string = ''@State isdel: boolean = false@State keywords: string[] = []aboutToAppear(): void {this.getData()}// 1.0 新增方法async saveData(text: string) {// 非空验证if(!text){return}// 1.0 获取首选项对象实例const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })// 2.0 调用putsync方法保存数组// 2.0.1 先从首选项中获取老数据let dataArr = pre.getSync('keyword', []) as string[]// 判断如果首选项中已经有了该关键词，不再保存if(dataArr.includes(text)){// 该关键字已经存在了，不保存return}
dataArr.push(text)// 2.0.2 存数据pre.putSync('keyword', dataArr)
// 3.0 调用flush写入到磁盘await pre.flush()}// 2.0 获取首选项数据async getData() {const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })this.keywords = pre.getSync('keyword', []) as string[]}
@BuilderitemBuilder(text: string) {Row({ space: 20 }) {Text(text)if (this.isdel) {Text('x').height(30).onClick(() => {AlertDialog.show({ message: '删除' + text })})}}.margin({ right: 10, top: 10 }).padding({left: 15,right: 15,top: 5,bottom: 5}).backgroundColor('rgba(0,0,0,0.05)').borderRadius(20)}
build() {Navigation() {Column({ space: 15 }) {// 1. 搜索关键字TextInput({ placeholder: '输入回车保存数据', text: $$this.keyword }).onSubmit(async () => {
AlertDialog.show({ message: this.keyword })// 将关键词数据保存到首选项中await this.saveData(this.keyword)await this.getData()})
// 2. 关键字列表Row() {Text('搜索记录').fontSize(20).fontWeight(800)
Row() {if (this.isdel) {Text('全部删除').onClick(()=>{AlertDialog.show({ message: '补上全部删除逻辑' })})Text(' | ')Text('取消删除').onClick(()=>{this.isdel = false})} else {Text('X').height(28).onClick(()=>{this.isdel = true})}}}.width('100%').justifyContent(FlexAlign.SpaceBetween)
// 3. 关键字列表Flex({ wrap: FlexWrap.Wrap }) {ForEach(this.keywords, (item: string) => {this.itemBuilder(item)})}}.padding(15)}.padding({ top: 20 }).titleMode(NavigationTitleMode.Mini).title('搜索页面')}
}
删除指定关键字/全部关键字
async delData(text?: string) {const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })// 1.0 删除全部关键if (!text) {pre.deleteSync('keyword')} else {// 2.0 删除指定关键字 获取 -> 删除内存数组的关键字 -> 写回let datas = pre.getSync('keyword', []) as string[]let cindex = datas.findIndex(item => item === text)// 当关键字索引为-1的时候，表示没有找到if (cindex < 0) {return}// 如果有删除datas.splice(cindex, 1) // 返回值表示删除的元素// 保存回去pre.putSync('keyword', datas)}// 写回磁盘pre.flush()}
// 删除指定关键字await this.delData(text)await this.getData()})
// 删除全局数据await this.delData()await this.getData()})
完整代码
import { preferences } from '@kit.ArkData'@Entry
@Component
struct SearchPage {@State keyword: string = ''@State isdel: boolean = false@State keywords: string[] = []aboutToAppear(): void {this.getData()}// 1.0 新增方法async saveData(text: string) {// 非空验证if(!text){return}// 1.0 获取首选项对象实例const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })// 2.0 调用putsync方法保存数组// 2.0.1 先从首选项中获取老数据let dataArr = pre.getSync('keyword', []) as string[]// 判断如果首选项中已经有了该关键词，不再保存if(dataArr.includes(text)){// 该关键字已经存在了，不保存return}dataArr.push(text)// 2.0.2 存数据pre.putSync('keyword', dataArr)// 3.0 调用flush写入到磁盘await pre.flush()}// 2.0 获取首选项数据async getData() {const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })this.keywords = pre.getSync('keyword', []) as string[]}// 3.0 删除指定关键字和全部关键字async delData(text?: string) {const pre = preferences.getPreferencesSync(getContext(), { name: 'store1' })// 1.0 删除全部关键if (!text) {pre.deleteSync('keyword')} else {// 2.0 删除指定关键字 获取 -> 删除内存数组的关键字 -> 写回let datas = pre.getSync('keyword', []) as string[]let cindex = datas.findIndex(item => item === text)// 当关键字索引为-1的时候，表示没有找到if (cindex < 0) {return}// 如果有删除datas.splice(cindex, 1) // 返回值表示删除的元素// 保存回去pre.putSync('keyword', datas)}// 写回磁盘pre.flush()}@BuilderitemBuilder(text: string) {Row({ space: 20 }) {Text(text)if (this.isdel) {Text('x').height(30).onClick(async () => {// 删除指定关键字await this.delData(text)await this.getData()AlertDialog.show({ message: '删除' + text })})}}.margin({ right: 10, top: 10 }).padding({left: 15,right: 15,top: 5,bottom: 5}).backgroundColor('rgba(0,0,0,0.05)').borderRadius(20)}build() {Navigation() {Column({ space: 15 }) {// 1. 搜索关键字TextInput({ placeholder: '输入回车保存数据', text: $$this.keyword }).onSubmit(async () => {AlertDialog.show({ message: this.keyword })// 将关键词数据保存到首选项中await this.saveData(this.keyword)await this.getData()})// 2. 关键字列表Row() {Text('搜索记录').fontSize(20).fontWeight(800)Row() {if (this.isdel) {Text('全部删除').onClick(async ()=>{// 删除全局数据await this.delData()await this.getData()})Text(' | ')Text('取消删除').onClick(()=>{this.isdel = false})} else {Text('X').height(28).onClick(()=>{this.isdel = true})}}}.width('100%').justifyContent(FlexAlign.SpaceBetween)// 3. 关键字列表Flex({ wrap: FlexWrap.Wrap }) {ForEach(this.keywords, (item: string) => {this.itemBuilder(item)})}}.padding(15)}.padding({ top: 20 }).titleMode(NavigationTitleMode.Mini).title('搜索页面')}
}
总结
-
该文档介绍了用户首选项数据持久化的概念、约束和接口，并通过一个搜索页面的实例展示了如何使用用户首选项存储、查询、修改和删除数据。
-
开发者在使用时需注意数据量的控制和进程安全问题，合理利用接口实现数据的持久化操作，确保应用的正常运行和数据的一致性。
![[数据结构]排序之 归并排序（有详细的递归图解）](https://i-blog.csdnimg.cn/direct/6b5fec2a539d45adbd53451e5705fed9.png)
![[贪心算法]买卖股票的最佳时机 买卖股票的最佳时机Ⅱ K次取反后最大化的数组和 按身高排序 优势洗牌（田忌赛马）](https://i-blog.csdnimg.cn/direct/df8b476b697e433f8778c2d7ea1ea0c6.png)
