跳至主要内容
版本：v8

@capacitor/preferences

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

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

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

**注意**：此 API 不 作为本地数据库使用。如果您的应用程序存储大量数据、具有高读写负载或需要复杂的查询，我们建议您查看基于 SQLite 的解决方案。其中一个解决方案是 Ionic 安全存储，它是一个基于 SQLite 的引擎，具有完整的加密支持。Capacitor 社区 还构建了其他一些存储引擎。

安装​

npm install @capacitor/preferences
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>
      
      <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​

首选项 API 仅支持字符串值。但是，如果在调用 set() 之前使用 JSON.stringify 对对象进行字符串化，然后使用 JSON.parse 对从 get() 返回的值进行解析，则可以使用 JSON。

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

API​

configure(...)​

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

在运行时配置首选项插件。

undefined 的选项将不被使用。

参数类型
optionsConfigureOptions

自 1.0.0

get(...)​

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

从给定键的首选项中获取值。

参数类型
optionsGetOptions

**返回值：** Promise<GetResult>

自 1.0.0

set(...)​

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

为给定键设置首选项中的值。

参数类型
optionsSetOptions

自 1.0.0

remove(...)​

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

从首选项中删除给定键的值（如果存在）。

参数类型
optionsRemoveOptions

自 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

接口​

ConfigureOptions​

属性类型描述默认值自
group字符串设置首选项组。首选项组用于组织键值对。使用值 'NativeStorage' 提供了与 cordova-plugin-nativestorage 的向后兼容性。警告：使用 'NativeStorage' 组时，clear() 方法可能会删除意外的值。CapacitorStorage1.0.0

GetResult​

属性类型描述自
value字符串 | null与给定键关联的首选项中的值。如果先前未设置值或已将其删除，则 value 将为 null。1.0.0

GetOptions​

属性类型描述自
key字符串要从首选项中检索其值的键。1.0.0

SetOptions​

属性类型描述自
key字符串要与正在首选项中设置的值关联的键。1.0.0
value字符串要与关联键一起在首选项中设置的值。1.0.0

RemoveOptions​

属性类型描述自
key字符串要从首选项中删除其值的键。1.0.0

KeysResult​

属性类型描述自
keys字符串[]首选项中已知的键。1.0.0

MigrateResult​

属性类型描述自
migrated字符串[]已迁移的键数组。1.0.0
existing字符串[]已迁移或在 Capacitor 2 首选项插件中存在值的已迁移或其他存在的键数组。1.0.0

内容

编辑此页