跳至主要內容
版本：v8

@capacitor/preferences

偏好設定 API 為輕量級資料提供簡單的鍵/值持續性儲存。

行動作業系統可能會定期清除在 window.localStorage 中設定的資料，因此應改用此 API。當作為漸進式 Web 應用程式執行時，此 API 將會回退使用 localStorage。

此外掛程式將會在 iOS 上使用 UserDefaults，在 Android 上使用 SharedPreferences。如果解除安裝應用程式，則會清除儲存的資料。

注意：此 API 並非要作為本機資料庫使用。如果您的應用程式儲存大量資料、具有高讀寫負載或需要複雜的查詢，我們建議您查看基於 SQLite 的解決方案。其中一個解決方案是 Ionic Secure Storage，這是一個具有完整加密支援的基於 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與指定索引鍵相關聯的偏好設定中的值。如果先前未設定或已移除值，則值將會是 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 Preferences 外掛程式中具有值的索引鍵陣列。1.0.0

目錄

編輯此頁面