メインコンテンツへスキップ
バージョン：バージョン 8

@capacitor/preferences

Preferences API は、軽量データ用のシンプルなキー/値永続ストアを提供します。

モバイル OS は window.localStorage で設定されたデータを定期的に消去する可能性があるため、代わりにこの API を使用する必要があります。この API は、プログレッシブ Web アプリとして実行しているときは localStorage の使用にフォールバックします。

このプラグインは、iOS では UserDefaults を、Android では SharedPreferences を使用します。保存データは、アプリがアンインストールされると消去されます。

注意: この API は、ローカルデータベースとして使用すべきものではありません。お使いのアプリが大量のデータを保存していて、読み取り/書き込みの負荷が高いか、複雑なクエリが必要な場合は、SQLite ベースのソリューションを試用することをお勧めします。そのようなソリューションの 1 つは、フル暗号化をサポートする SQLite ベースのエンジンである Ionic Secure Storage です。 Capacitor コミュニティも、他の複数のストレージエンジンを構築しています。

インストール​

npm install @capacitor/preferences
npx cap sync

Apple プライバシーマニフェストの要件​

Apple は、ユーザーのプライバシーを強化するために、アプリ開発者が API 使用の承認された理由を示すことを義務付けています。2024 年 5 月 1 日までに、App Store Connect にアプリを送信する際にこれらの理由を含める必要があります。

この特定のプラグインをアプリで使用する場合、/ios/AppにPrivacyInfo.xcprivacyファイルを作成するか、VSコード拡張機能を使用して使用理由を指定して生成する必要があります。

これを行う方法の詳細な手順については、Capacitor Docsを参照してください。

このプラグインでは、必要なディクショナリのキーはNSPrivacyAccessedAPICategoryUserDefaultsで、推奨される理由はCA92.1です。

Example 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>

Example Plugin Usage​

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' });
};

Working with JSON​

Preferences APIは文字列の値のみをサポートしています。ただし、set()を呼び出す前にJSON.stringifyを使用してオブジェクトを処理し、get()から返される値をJSON.parseする場合、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ストレージプラグインからデータを移行します。

このアクションは破壊的ではありません。古いデータは削除されず、キーが既に設定されていない場合にのみ新しいデータが書き込まれます。移行後に古いデータを削除するには、removeOld()を呼び出します。

返される値: Promise<MigrateResult>

以降 1.0.0

removeOld()​

removeOld() => Promise<void>

Capacitor 2ストレージプラグインから_cap_プレフィックスのある古いデータを削除します。

以降 1.1.0

インターフェイス​

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

内容

このページを編集する