@capacitor/preferences

本项目基于 @capacitor/[email protected] 开发。

简介

提供了一个简单的键/值持久化存储，适用于轻量级数据。本插件是 capacitor 生态系统中的核心插件，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境中使用，本文档仅说明在 OpenHarmony 系统中的使用情况。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/preferences

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/preferences

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/preferences",
  "classpath": "Preferences"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 capacitor 模块，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

// ...
add_subdirectory(Preferences)
// ...

// ...
target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Preferences
  // ...
  "-Wl,--no-whole-archive"
);

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并复制到对应的目录：

将源码中 src/main/cpp/Preferences 目录下的 Preferences.h、Preferences.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/Preferences 目录下。

将源码中 src/main/ets/components/Preferences 目录下的 Preferences.ets 文件引入到 capacitor 模块中 src/main/ets/components/Preferences 目录下。

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入拷贝的 ets 文件路径：

"buildOption": {
  // ...
  "arkOptions": {
    "runtimeOnly": [
      // ...
      "./src/main/ets/components/Preferences/Preferences.ets"
      // ...
    ]
  }
}

卸载

# 卸载 preferences 插件
hionic plugin remove @capacitor/preferences

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不需要额外权限。

使用示例

示例 1：基础用法 - 设置和获取键值对

import { Preferences } from '@capacitor/preferences';

// 设置键值对
const setValue = async () => {
  try {
    await Preferences.set({
      key: 'user_name',
      value: '张三'
    });
    console.log('数据已成功保存');
  } catch (error) {
    console.error('保存失败：', error);
  }
};

// 获取键值对
const getValue = async () => {
  try {
    const ret = await Preferences.get({ key: 'user_name' });
    console.log('获取到的数据:', ret.value);
  } catch (error) {
    console.error('获取失败：', error);
  }
};

示例 2：获取所有键名

import { Preferences } from '@capacitor/preferences';

const getAllKeys = async () => {
  try {
    const ret = await Preferences.keys();
    console.log('所有键名:', ret.keys);
  } catch (error) {
    console.error('获取键名失败：', error);
  }
};

示例 3：清除特定键或全部数据

import { Preferences } from '@capacitor/preferences';

// 删除特定键
const removeKey = async () => {
  try {
    await Preferences.remove({ key: 'user_name' });
    console.log('键已成功删除');
  } catch (error) {
    console.error('删除失败：', error);
  }
};

// 清空所有数据
const clearAllData = async () => {
  try {
    await Preferences.clear();
    console.log('所有数据已清空');
  } catch (error) {
    console.error('清空失败：', error);
  }
};

使用说明

接口方法

| 方法名 | 调用方式 | 入参类型 | 功能描述 | | -------------- | ------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ | | configure(...) | Preferences.configure(ConfigureOptions) | ConfigureOptions | 配置 Preferences 存储选项，指定存储组名，使用值 NativeStorage 可提供与 cordova-plugin-nativestorage 的向后兼容性 | | get(...) | Preferences.get(GetOptions) | GetOptions | 根据键获取存储的值 | | set(...) | Preferences.set(SetOptions) | SetOptions | 根据键值对存储数据 | | remove(...) | Preferences.remove(RemoveOptions) | RemoveOptions | 根据键删除对应的存储项 | | clear() | Preferences.clear() | 无入参 | 清空所有存储的数据 | | keys() | Preferences.keys() | 无入参 | 获取所有存储的键名 | | migrate() | Preferences.migrate() | 无入参 | 不支持 | | removeOld() | Preferences.removeOld() | 无入参 | 不支持 |

接口定义

ConfigureOptions

调用 configure 方法时的入参对象

| 参数 | 类型 | 描述 | | ----------- | ---------- | ------------------------------------- | | group | string | 可选参数，指定存储的组名，默认为 CapacitorStorage |

GetOptions

调用 get 方法时的入参对象

| 参数 | 类型 | 描述 | | --------- | ---------- | ------------- | | key | string | 必传参数，要获取的键名 |

SetOptions

调用 set 方法时的入参对象

| 参数 | 类型 | 描述 | | ----------- | ---------- | ------------- | | key | string | 必传参数，要设置的键名 | | value | string | 必传参数，要设置的值 |

RemoveOptions

调用 remove 方法时的入参对象

| 参数 | 类型 | 描述 | | --------- | ---------- | ------------- | | key | string | 必传参数，要删除的键名 |

常见问题（FAQ）

1. 调用 get/set/remove 方法抛出「Must provide key」异常？

• 原因：key 是必传参数，插件原生层会严格校验，未传参、传空字符串、传 "null" 均会触发该异常。
• 解决方案：确保调用时传入合法有效的键名，格式示例：{ key: 'myKey' }。

2. configure 方法的作用是什么？

• 说明：configure 方法用于配置 Preferences 存储选项，可以指定不同的存储组名以实现数据隔离。如果不调用 configure 方法，插件会使用默认的 CapacitorStorage 组名。

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- Preferences   # 插件核心 C++ 实现
|                             |---- Preferences.h
|                             |---- Preferences.cpp
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- Preferences   # 插件核心 ArkTS 实现
|                                   |---- Preferences.ets
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。