跳到主要内容
版本：v7

@capacitor/preferences

Preferences API 提供了一个简单的键值对持久化存储，用于存储轻量级数据。

移动操作系统可能会定期清除 window.localStorage 中设置的数据，因此应使用此 API 代替。当作为渐进式 Web 应用 (PWA) 运行时，此 API 将回退到使用 localStorage。

此插件在 iOS 上使用 UserDefaults，在 Android 上使用 SharedPreferences。如果应用被卸载，存储的数据将被清除。

注意：此 API 不适合用作本地数据库。如果你的应用需要存储大量数据、具有高读写负载或需要复杂查询，我们建议你考虑基于 SQLite 的解决方案。其中一个解决方案是 Ionic Secure Storage，这是一个支持完全加密的基于 SQLite 的引擎。Capacitor 社区 也构建了许多其他存储引擎。

安装​

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

Apple 隐私清单要求​

Apple 现在要求应用开发者为 API 的使用指定批准的理由，以增强用户隐私。到 2024 年 5 月 1 日，向 App Store Connect 提交应用时，必须包含这些理由。

在你的应用中使用此特定插件时，你必须在 /ios/App 目录中创建一个 PrivacyInfo.xcprivacy 文件，或使用 VS Code 扩展来生成它，并指定使用理由。

有关如何执行此操作的详细步骤，请参阅 Capacitor 文档。

对于此插件，必需的字典键是 NSPrivacyAccessedAPICategoryUserDefaults，推荐的理由是 CA92.1。

示例 PrivacyInfo.xcprivacy​

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- 如果 PrivacyInfo 文件已存在，请将此 dict 条目添加到数组中 -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

插件使用示例​

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 仅支持字符串值。然而，你可以在调用 set() 之前使用 JSON.stringify 对对象进行序列化，然后在 get() 返回的值上使用 JSON.parse 来使用 JSON。

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

API​

configure(...)​

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

在运行时配置 preferences 插件。

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

参数类型
options
ConfigureOptions

自： 1.0.0

get(...)​

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

根据给定的键获取 preferences 中的值。

参数类型
options
GetOptions

返回： 

Promise<GetResult>

自： 1.0.0

set(...)​

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

为给定的键在 preferences 中设置值。

参数类型
options
SetOptions

自： 1.0.0

remove(...)​

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

从 preferences 中移除给定键对应的值（如果存在）。

参数类型
options
RemoveOptions

自： 1.0.0

clear()​

clear() => Promise<void>

清除 preferences 中的所有键和值。

自： 1.0.0

keys()​

keys() => Promise<KeysResult>

返回 preferences 中已知键的列表。

返回： 

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

接口#### ConfigureOptions​

属性类型说明默认值始于
groupstring设置偏好设置组。偏好设置组用于组织键/值对。使用值 'NativeStorage' 可向后兼容 cordova-plugin-nativestorage。警告：使用 'NativeStorage' 组时，clear() 方法可能会删除意外值。CapacitorStorage1.0.0

GetResult​

属性类型说明始于
valuestring | null与给定键关联的偏好设置值。如果之前未设置值或值已被移除，则 value 将为 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

编辑此页