Preferences

  • 项目

Browse sample. 浏览示例

本文介绍如何使用 .NET Multi-platform App UI (.NET MAUI) IPreferences 接口。 此接口有助于将应用首选项存储在密钥/值存储中。

IPreferences 接口的默认实现通过 Preferences.Default 属性提供。 IPreferences 接口和 Preferences 类都包含在 Microsoft.Maui.Storage 命名空间中。

存储类型

Preferences 使用 String 密钥存储。 首选项的值必须是下列数据类型之一：

DateTime 的值采用 DateTime 类定义的两种方法按 64 位二进制（长整型）格式进行存储：

  • ToBinary 方法用于对 DateTime 值进行编码。
  • FromBinary 方法对值进行解码。

请参阅这些方法的文档，了解当存储的 DateTime 为非协调世界时 (UTC) 值时可能对解码值进行的调整。

设置首选项

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

检查密钥

在检查一个密钥是否存在于首选项中时可能很有用。 尽管 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 以本机方式存储，这样便可将设置集成到本机系统设置。 按照平台文档和示例说明与平台进行集成：

平台差异

本部分介绍特定于平台的首选项 API 差异。

所有数据均存储在共享 Preferences 中。 如果未指定 sharedName，则使用默认共享 Preferences。 否则，该名称用于获取具有指定名称的专用共享 Preferences。

持久性

卸载应用会导致删除所有首选项，除非应用在 Android 6.0 (API 级别 23) 或更高版本上运行，同时使用自动备份功能。 此功能默认启用并且会保留应用数据，包括共享 Preferences (即 API 使用的 Preferences)。 可以遵循 Google 的自动备份文档禁用此功能。

限制

如果存储大量文本，性能可能会受到影响，因为 API 旨在存储少量文本。