メインコンテンツまでスキップ
Version: v4

@capacitor/preferences

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

モバイル OS は定期的に window.localStorage に保存されたデータを消去することがあるので、 代わりにこの API を使用する必要があります。 この API は Progressive Web App として動作している場合、localStorage を使用するようにフォールバックします。

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

注意: このAPIは、ローカルデータベースとして使用することは想定していません。アプリが多くのデータを アプリが大量のデータを保存する場合、読み取り/書き込みの負荷が高い場合、または複雑なクエリを必要とする場合。 SQLiteベースのソリューションを検討することをお勧めします。そのようなソリューションの1つが、完全な暗号化をサポートするSQLiteベースのエンジンであるIonic Secure Storageです。Capacitor Community](https://github.com/capacitor-community/) は、他にも多くのストレージエンジンを構築しています。

Install

npm install @capacitor/preferences
npx cap sync

Example

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

The Preferences API only supports string values. You can, however, use JSON if you JSON.stringify the object before calling set(), then JSON.parse the value returned from get().

This method can also be used to store non-string values, such as numbers and booleans.

API

configure(...)

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

Configure the preferences plugin at runtime.

Options that are undefined will not be used.

ParamType
optionsConfigureOptions

Since: 1.0.0


get(...)

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

Get the value from preferences of a given key.

ParamType
optionsGetOptions

Returns: Promise<GetResult>

Since: 1.0.0


set(...)

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

Set the value in preferences for a given key.

ParamType
optionsSetOptions

Since: 1.0.0


remove(...)

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

Remove the value from preferences for a given key, if any.

ParamType
optionsRemoveOptions

Since: 1.0.0


clear()

clear() => Promise<void>

Clear keys and values from preferences.

Since: 1.0.0


keys()

keys() => Promise<KeysResult>

Return the list of known keys in preferences.

Returns: Promise<KeysResult>

Since: 1.0.0


migrate()

migrate() => Promise<MigrateResult>

Migrate data from the Capacitor 2 Storage plugin.

This action is non-destructive. It will not remove old data and will only write new data if they key was not already set. To remove the old data after being migrated, call removeOld().

Returns: Promise<MigrateResult>

Since: 1.0.0


removeOld()

removeOld() => Promise<void>

Removes old data with _cap_ prefix from the Capacitor 2 Storage plugin.

Since: 1.1.0


Interfaces

ConfigureOptions

PropTypeDescriptionDefaultSince
groupstringSet the preferences group. Preferences groups are used to organize key/value pairs. Using the value 'NativeStorage' provides backwards-compatibility with cordova-plugin-nativestorage. WARNING: The clear() method can delete unintended values when using the 'NativeStorage' group.CapacitorStorage1.0.0

GetResult

PropTypeDescriptionSince
valuestring | nullThe value from preferences associated with the given key. If a value was not previously set or was removed, value will be null.1.0.0

GetOptions

PropTypeDescriptionSince
keystringThe key whose value to retrieve from preferences.1.0.0

SetOptions

PropTypeDescriptionSince
keystringThe key to associate with the value being set in preferences.1.0.0
valuestringThe value to set in preferences with the associated key.1.0.0

RemoveOptions

PropTypeDescriptionSince
keystringThe key whose value to remove from preferences.1.0.0

KeysResult

PropTypeDescriptionSince
keysstring[]The known keys in preferences.1.0.0

MigrateResult

PropTypeDescriptionSince
migratedstring[]An array of keys that were migrated.1.0.0
existingstring[]An array of keys that were already migrated or otherwise exist in preferences that had a value in the Capacitor 2 Preferences plugin.1.0.0