Preferences

發行項
01/23/2025

本文說明如何使用 .NET 多平臺應用程式 UI （.NET MAUI） IPreferences 介面。此介面可協助將應用程式喜好設定儲存在索引鍵/值存放區中。

介面的預設實作 IPreferences 可透過 Preferences.Default 屬性取得。 IPreferences介面和Preferences類別都包含在命名空間中Microsoft.Maui.Storage。

儲存體類型

Preferences 會以 String 金鑰儲存。喜好設定的值必須是下列其中一種數據類型：

DateTime 的值會使用 DateTime 類別定義的兩種方法，以 64 位元二進位 (長整數) 格式儲存：

方法 ToBinary 可用來編碼 DateTime 值。
方法會 FromBinary 譯碼值。

請參閱這些方法的檔，以瞭解在儲存不是國際標準時間（UTC）值時 DateTime ，可能會對譯碼值所做的調整。

偏好設定

Preferences 藉由呼叫方法來 Preferences.Set 設定，並提供索引鍵和值：

// Set a string value:
Preferences.Default.Set("first_name", "John");

// Set an numerical value:
Preferences.Default.Set("age", 28);

// Set a boolean value:
Preferences.Default.Set("has_pets", true);

取得喜好設定

若要從喜好設定擷取值，請傳遞喜好設定的索引鍵，接著是不存在索引鍵時的預設值：

string firstName = Preferences.Default.Get("first_name", "Unknown");
int age = Preferences.Default.Get("age", -1);
bool hasPets = Preferences.Default.Get("has_pets", false);

在某些情況下，您可能需要傳遞喜好設定的索引鍵，後面接著預設值及其類型：

long value = Preferences.Get("master_date", (long)0);

檢查金鑰

檢查金鑰是否存在於喜好設定中可能很有用。即使您 Get 在機碼不存在時設定預設值，也可能有索引鍵存在的情況，但索引鍵的值符合預設值。因此，您無法依賴預設值做為索引鍵不存在的指標。 ContainsKey使用方法來判斷索引鍵是否存在：

bool hasKey = Preferences.Default.ContainsKey("my_key");

拿掉一或所有索引鍵

使用 Remove 方法，從喜好設定中移除特定索引鍵：

Preferences.Default.Remove("first_name");

若要移除所有索引鍵，請使用 Clear 方法：

Preferences.Default.Clear();

共用金鑰

您的應用程式所儲存的喜好設定只會對您的應用程式顯示。不過，您也可以建立共用喜好設定，供其他延伸模組或監看應用程式使用。當您設定、移除或擷取喜好設定時，可以提供選擇性字串參數來指定儲存喜好設定的容器名稱。

下列方法會採用名為 sharedName的字串參數：

Preferences.Set
Preferences.Get
Preferences.Remove
Preferences.Clear

重要

請閱讀平台實作的特定細節，因為「共享偏好設定」具有與行為相關的特定實作。

與系統設定整合

Preferences 會以原生方式儲存，可讓您將設定整合到原生系統設定中。請遵循平台檔來與平臺整合：

Apple：實作 iOS 設定套件組合
Android：開始使用設定畫面

平台差異

本節說明與喜好設定 API 的平臺特定差異。

所有數據都會儲存在共用中 Preferences。 sharedName如果未指定，則會使用預設的SharedPreferences。否則，此名稱會用來取得 具有指定名稱的私人共用 Preferences 。

ApplicationDataContainer 用來將值儲存在裝置上。 sharedName如果未指定，LocalSettings則會使用。否則，名稱會用來在內 LocalSettings建立新的容器。

LocalSettings 將喜好設定機碼名稱限制為 255 個字元或更少。每個喜好設定值的大小上限為8K個字節，而且每個複合設定的大小最多可達64 K個字節。

持續性

卸載應用程式會導致移除所有 喜好設定，但應用程式在Android 6.0（API層級 23）或更新版本上執行時，使用自動備份功能時除外。此功能預設為開啟，並保留應用程式數據，包括 共用 Preferences，這是 API 使用 Preferences 的內容。您可以遵循 Google 的自動備份檔來停用此功能。

限制

如果您儲存大量的文字，效能可能會受到影響，因為 API 是設計來儲存少量的文字。

共用方式為