Preferences 本地配置

@capacitor-rydeen/preferences 基于 Capacitor 官方 Preferences 插件，为 Android / iOS / Web / Electron 提供统一的 轻量级键值对存储 能力，适合保存终端配置、用户偏好、简单状态等数据。

典型场景包括：默认门店、默认打印机、主题模式、最近登录账号、本地版本号等。

设计定位

轻量级：仅做 key-value 存储，不负责复杂查询、表结构；复杂业务数据请使用 @rydeen/storage。
跨平台一致：对齐 Capacitor Preferences API，在多端保持一致的行为与序列化规则。
与其它组件配合：@rydeen/hotfix、终端配置中心等都会依赖本插件做本地配置持久化。

与官方 `@capacitor/preferences` 的主要差异

Capacitor 官方的 @capacitor/preferences 所有 key 都保存在同一个存储空间 中，只提供「清空全部」的能力，无法只清理某一类业务的配置数据，这在中大型项目中会带来一些不便：

不同业务模块（如「登录信息」「门店配置」「打印配置」）混在同一个「大桶」里；
需要清理某一类数据时，只能：
- 要么逐个枚举并删除所有相关 key；
- 要么直接 clear() 把所有 Preferences 清空，影响其它模块。

@capacitor-rydeen/preferences 在此基础上做了增强：支持自定义存储命名空间（store）。

可以为不同业务定义不同的 store，例如：
- store = 'auth'：登录与用户信息相关配置；
- store = 'store-config'：门店与终端配置；
- store = 'printer'：打印相关配置。
清理时可以 只清空某一个 store 下的数据，而不会影响其它 store：
- 比如退出登录时，只需要清空 auth 的存储空间，不影响门店/打印等终端级别配置。

具体的 store 字段会在各方法的 options 中以扩展字段形式出现（保持与官方 API 兼容的同时增加命名空间选择），默认行为仍然与官方插件一致（不指定 store 时落在默认命名空间）。

安装与集成

npm install @capacitor-rydeen/preferences
npx cap sync

在应用中导入：

import { Preferences } from '@capacitor-rydeen/preferences'

平台能力矩阵

能力	Android	iOS	Web	Electron
方法
`get`	✅	✅	✅	✅
`set`	✅	✅	✅	✅
`remove`	✅	✅	✅	✅
`clear`	✅	✅	✅	✅
`keys`	✅	✅	✅	✅

存储位置：原生端一般使用 SharedPreferences（Android）/ UserDefaults（iOS）；Web 使用 LocalStorage 或 IndexedDB。
数据统一以 字符串形式 持久化；上层可自行做 JSON 序列化/反序列化。

快速开始

import { Preferences } from '@capacitor-rydeen/preferences'

// 推荐为不同业务定义命名空间（group）
const STORE_CONFIG_GROUP = 'store-config'

// 1. 写入配置
await Preferences.set({
  group: STORE_CONFIG_GROUP,
  key: 'defaultStoreId',
  value: 'store-001',
})

// 2. 读取配置
const { value } = await Preferences.get({
  group: STORE_CONFIG_GROUP,
  key: 'defaultStoreId',
})
console.log('defaultStoreId =', value)

// 3. 删除配置
await Preferences.remove({
  group: STORE_CONFIG_GROUP,
  key: 'defaultStoreId',
})

// 4. 查看某个 group 下已有 key
const { keys } = await Preferences.keys(STORE_CONFIG_GROUP)
console.log('store-config keys =', keys)

// 5. 只清空某个 group（例如退出登录时清理 auth，而不是全部）
await Preferences.clear('auth')

实战示例：终端默认门店与打印机

场景：门店一体机需要记住「默认门店 ID」与「默认打印机配置」，方便下次启动时自动恢复。

import { Preferences } from '@capacitor-rydeen/preferences'

const STORE_CONFIG_GROUP = 'store-config'
const PRINTER_CONFIG_GROUP = 'printer'

const DEFAULT_STORE_KEY = 'defaultStoreId'
const DEFAULT_PRINTER_KEY = 'defaultPrinter'

export async function saveDefaultStore(storeId: string) {
  await Preferences.set({
    group: STORE_CONFIG_GROUP,
    key: DEFAULT_STORE_KEY,
    value: storeId,
  })
}

export async function loadDefaultStore(): Promise<string | null> {
  const { value } = await Preferences.get({
    group: STORE_CONFIG_GROUP,
    key: DEFAULT_STORE_KEY,
  })
  return value ?? null
}

export interface DefaultPrinterConfig {
  type: 'NETWORK' | 'USB'
  ip?: string
  port?: number
  vendorId?: number
  productId?: number
}

export async function saveDefaultPrinter(config: DefaultPrinterConfig) {
  await Preferences.set({
    group: PRINTER_CONFIG_GROUP,
    key: DEFAULT_PRINTER_KEY,
    value: JSON.stringify(config),
  })
}

export async function loadDefaultPrinter(): Promise<DefaultPrinterConfig | null> {
  const { value } = await Preferences.get({
    group: PRINTER_CONFIG_GROUP,
    key: DEFAULT_PRINTER_KEY,
  })
  if (!value) return null
  return JSON.parse(value) as DefaultPrinterConfig
}

API 与类型参考

方法列表

方法	签名	说明
get	`get(options: GetOptions): Promise<GetResult>`	按 key 读取 value，支持按 group（命名空间）区分。
set	`set(options: SetOptions): Promise<void>`	写入 key/value，支持指定 group。
remove	`remove(options: RemoveOptions): Promise<void>`	删除指定 key，可限定在某个 group 中。
clear	`clear(group?: string): Promise<void>`	清空指定 group 下的所有 key/value；未传 group 时清空默认组。
keys	`keys(group?: string): Promise<KeysResult>`	返回指定 group 下的所有 key 列表；未传 group 时列出默认组。

完整类型定义

以下类型定义与 @capacitor-rydeen/preferences 源码中的 src/definitions.ts 保持一致，阅读本小节即可了解所有可用字段与行为：

export interface GetOptions {
  /**
   * 指定要获取的键值对所在的组（命名空间）
   *
   * 如果不指定，则默认为 CapacitorStorage
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  group?: string

  /**
   * 要获取的键值对的键
   *
   * @since 6.0.0
   */
  key: string
}

export interface GetResult {
  /**
   * 与给定键关联的 Preferences 中的值
   *
   * 如果之前未设置或已删除值，则 value 将为 'null'
   *
   * @since 6.0.0
   */
  value: string | null
}

export interface SetOptions {
  /**
   * 指定要存储的键值对所在的组（命名空间）
   *
   * 如果不指定，则默认为 CapacitorStorage
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  group?: string

  /**
   * 要存入 Preferences 中的值关联的键
   *
   * @since 6.0.0
   */
  key: string

  /**
   * 要存入 Preferences 中的值
   *
   * @since 6.0.0
   */
  value: string
}

export interface RemoveOptions {
  /**
   * 指定要删除的键值对所在的组（命名空间）
   *
   * 如果不指定，则默认为 CapacitorStorage
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  group?: string

  /**
   * 要从 Preferences 中删除的键
   *
   * @since 6.0.0
   */
  key: string
}

export interface KeysResult {
  /**
   * 指定组中的键列表
   *
   * @since 6.0.0
   */
  keys: string[]
}

export interface PreferencesPlugin {
  /**
   * 从给定键的 Preferences 中获取值
   * @param options 取值参数选项
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  get(options: GetOptions): Promise<GetResult>

  /**
   * 将指定键值对值存入 Preferences
   * @param options 存值参数选项
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  set(options: SetOptions): Promise<void>

  /**
   * 从给定键的 Preferences 中删除该值（如果有）
   * @param options 删除参数选项
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  remove(options: RemoveOptions): Promise<void>

  /**
   * 清除指定组的 Preferences 中的所有键值对
   * @param group 要清除的组。如果未提供，则清除默认组中的键值对
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  clear(group?: string): Promise<void>

  /**
   * 列出指定组的 Preferences 中的所有键
   * @param group 要列出的组。如果未提供，则列出默认组中的键
   *
   * @default CapacitorStorage
   * @since 6.0.0
   */
  keys(group?: string): Promise<KeysResult>
}

在实际项目中，推荐封装一层 ConfigService / PreferencesService，对上层隐藏具体 key 名称、group 命名空间与序列化细节，仅暴露「获取/设置业务配置」的方法。

设计定位​

与官方 @capacitor/preferences 的主要差异​

安装与集成​

平台能力矩阵​

快速开始​

实战示例：终端默认门店与打印机​

API 与类型参考​

方法列表​

完整类型定义​