跳到主要内容
版本：v5

@capacitor/preferences

Preferences API 为轻量级数据提供了简单的键/值持久化存储方案。

由于移动操作系统可能会定期清除 window.localStorage 中的数据，因此推荐使用本 API。在渐进式 Web 应用（PWA）模式下运行时，本 API 会自动回退到使用 localStorage。

该插件在 iOS 上使用 UserDefaults，在 Android 上使用 SharedPreferences。当应用被卸载时，存储的数据会被清除。

注意：本 API 不 适合作为本地数据库使用。如果您的应用需要存储大量数据、高频读写或复杂查询，建议考虑基于 SQLite 的解决方案，例如支持全加密的 Ionic Secure Storage。Capacitor 社区 也提供了多种其他存储引擎。

安装​

npm install @capacitor/preferences@latest-5
npx cap sync

示例​

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

const setName = async () => {
  await Preferences.set({
    key: 'name',
    value: 'Max',
  });
};

const checkName = async () => {
  const { value } = await Preferences.get({ key: 'name' });

  console.log(`Hello ${value}!`);
};

const removeName = async () => {
  await Preferences.remove({ key: 'name' });
};

处理 JSON 数据​

Preferences API 仅支持字符串值。但您可以通过 JSON.stringify 将对象转换为字符串后调用 set()，再通过 JSON.parse 解析 get() 返回值的方式来存储 JSON 数据。

此方法也可用于存储非字符串值，例如数字和布尔值。

API​

configure(...)​

configure(options: ConfigureOptions) => Promise<void>

运行时配置 Preferences 插件。

值为 undefined 的选项将不会被使用。

参数类型
options
ConfigureOptions

自版本: 1.0.0

get(...)​

get(options: GetOptions) => Promise<GetResult>

获取指定键对应的偏好设置值。

参数类型
options
GetOptions

返回值: 

Promise<GetResult>

自版本: 1.0.0

set(...)​

set(options: SetOptions) => Promise<void>

设置指定键对应的偏好设置值。

参数类型
options
SetOptions

自版本: 1.0.0

remove(...)​

remove(options: RemoveOptions) => Promise<void>

移除指定键对应的偏好设置值（如果存在）。

参数类型
options
RemoveOptions

自版本: 1.0.0

clear()​

clear() => Promise<void>

清除所有偏好设置键值对。

自版本: 1.0.0

keys()​

keys() => Promise<KeysResult>

返回已知的所有偏好设置键名列表。

返回值: 

Promise<KeysResult>

自版本: 1.0.0

migrate()​

migrate() => Promise<MigrateResult>

从 Capacitor 2 Storage 插件迁移数据。

此操作是非破坏性的，不会删除旧数据，仅当键名未被设置时才写入新数据。 迁移完成后如需删除旧数据，请调用 removeOld()。

返回值: 

Promise<MigrateResult>

自版本: 1.0.0

removeOld()​

removeOld() => Promise<void>

移除 Capacitor 2 Storage 插件中以 _cap_ 为前缀的旧数据。

自版本: 1.1.0

Interfaces​

ConfigureOptions​

属性类型描述默认值自版本
groupstring设置偏好设置分组。分组用于组织键值对。使用值 'NativeStorage' 可保持与 cordova-plugin-nativestorage 的兼容性。警告：当使用 'NativeStorage' 分组时，clear() 方法可能会意外删除某些值。CapacitorStorage1.0.0

GetResult​

属性类型描述自版本
valuestring | null与给定键关联的偏好设置值。如果该键从未被设置或已被移除，则返回 null。1.0.0

GetOptions​

属性类型描述自版本
keystring要检索的偏好设置键名。1.0.0

SetOptions​

属性类型描述自版本
keystring要设置的偏好设置键名。1.0.0
valuestring要与键名关联的偏好设置值。1.0.0

RemoveOptions​

属性类型描述自版本
keystring要从偏好设置中移除的键名。1.0.0

KeysResult​

属性类型描述自版本
keysstring[]已知的所有偏好设置键名。1.0.0

MigrateResult​

属性类型描述自版本
migratedstring[]已迁移的键名数组。1.0.0
existingstring[]已存在或已在 Capacitor 2 Preferences 插件中有值的键名数组。1.0.0

Contents

编辑此页