在 UWP 应用中保存和加载设置Save and load settings in a UWP app

本主题介绍开始在通用 Windows 平台 (UWP) 应用中加载和保存设置需要了解的内容。This topic covers what you need to know to get started loading, and saving, settings in a Universal Windows Platform (UWP) app. 介绍了主要 API,并提供了可帮助你了解详细信息的链接。The main APIs are introduced, and links are provided to help you learn more.

使用设置可以记住应用中用户可自定义的方面。Use settings to remember the user-customizable aspects of your app. 例如,新闻阅读器可以使用应用设置来保存要显示的新闻源以及用于阅读文章的字体。For example, a news reader could use app settings to save which news sources to display and what font to use for reading articles.

我们将了解一下用来保存和加载应用设置的代码,包括本地和漫游设置。We’ll look at code to save and load app settings, including local and roaming settings.

需要了解哪些内容What do you need to know

使用应用设置存储配置数据,如用户首选项和应用状态。Use app settings to store configuration data such as user preferences and app state. 设备特定的设置存储在本地。Settings that are specific to the device are stored locally. 在安装应用的设备上应用的设置存储在漫游数据存储中。Settings that apply on whichever device your app is installed on are stored in the roaming data store. 设置在用户使用同一个 Microsoft 帐户登录并安装了相同应用版本的设备之间漫游。Settings are roamed between devices on which the user is signed in with the same Microsoft Account and have the same version of the app installed.

设置可以使用以下数据类型:整数、加倍、浮点、字符、字符串、点、DateTimes,等等。The following data types can be used with settings: integers, doubles, floats, chars, strings, Points, DateTimes, and more. 还可以存储 ApplicationDataCompositeValue 类的实例,当存在应被视为单元的多个设置时这很有用。You can also store instances of the ApplicationDataCompositeValue class which is useful when there are multiple settings that should be treated as a unit. 例如,用于在应用的阅读面板中显示文本的字体名称和点大小应该作为单个单元保存/还原。For example, a font name and point size for displaying text in the reading pane of your app should be saved/restored as a single unit. 当由于在一个设置之前漫游另一个设置而出现延时,这将防止一个设置与另一个设置不同步。This prevents one setting from getting out of sync with the other due to delays in roaming one setting before the other.

下面是你需要了解的用于保存或加载应用设置的主要 API:Here are the main APIs you need to know about to save or load app settings:

保存应用设置Save app settings

在此说明中,我们将着重介绍两个简单的场景:本地保存和加载应用设置,在设备之间漫游组合字体/字体大小设置。For this introduction, we will focus on two simple scenarios: saving and loading an app setting locally, and roaming a composite font/font size setting between devices.

// Save a setting locally on the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting that will be roamed between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
roamingSettings.Values["RoamingFontInfo"] = composite;

将设置保存到本地设备:通过使用 首先为本地设置数据存储获取ApplicationDataContainerWindows.Storage.ApplicationData.Current.LocalSettingsSave a setting to the local device, by first getting an ApplicationDataContainer for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. 分配到此实例的键/值字典对在本地设备设置数据存储中保存。Key/value dictionary pairs that you assign to this instance are saved in the local device setting data store.

使用类似的模式保存漫游设置。Save a roaming setting using a similar pattern. 首先通过 为漫游设置数据存储获取ApplicationDataContainerWindows.Storage.ApplicationData.Current.RoamingSettingsFirst get an ApplicationDataContainer for the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. 然后将键/值对分配到此实例。Then assign key/value pairs to this instance. 这些键/值对将在设备之间自动漫游。Those key/value pairs will automatically roam between devices.

在上述代码片段中,ApplicationDataCompositeValue 存储多个键/值对。In the code snippet above, a ApplicationDataCompositeValue stores multiple key/value pairs. 如果你有多个不应彼此脱离同步的设置,复合值非常有用。Composite values are useful when you have multiple settings that shouldn't get out of sync with each other. 保存 ApplicationDataCompositeValue 时,值作为一个单元保存和加载或自动完成。When you save a ApplicationDataCompositeValue, the values are saved and loaded as a unit, or atomically. 通过这种方式,相关的设置不会脱离同步,因为它们作为一个单元而不是单独漫游。This way settings that are related won't get out of sync because they are roamed as a unit instead of individually.

加载应用设置Load app settings

// load a setting that is local to the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting that roams between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)roamingSettings.Values["RoamingFontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

从本地设备加载设置:通过使用 首先为本地设置数据存储获取ApplicationDataContainerWindows.Storage.ApplicationData.Current.LocalSettings 实例。Load a setting from the local device, by first getting an ApplicationDataContainer instance for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. 然后使用它来检索键/值对。Then use it to retrieve key/value pairs.

按照类似的模式加载漫游设置。Load a roaming setting by following a similar pattern. 首先通过 从漫游设置数据存储获取ApplicationDataContainerWindows.Storage.ApplicationData.Current.RoamingSettings 实例。First get an ApplicationDataContainer instance from the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. 从该实例访问键/值对。Access key/value pairs from that instance. 如果数据尚未漫游到你从其访问设置的设备,你将获得一个空 ApplicationDataContainerIf the data hasn't roamed yet to the device that you are accessing the settings from, you'll get a null ApplicationDataContainer. 这就是上面的示例代码中有一个 if (composite != null) 检查的原因。That's why there is a if (composite != null) check in the example code above.

有用的 API 和文档Useful APIs and docs

以下是 API 和其他有用文档的核心摘要,可帮助你开始保存和加载应用设置。Here is a quick summary of APIs, and other useful documentation, to help get you started saving and loading app settings.

有用的 APIUseful APIs

APIAPI 说明Description
ApplicationData.LocalSettingsApplicationData.LocalSettings 从本地应用数据存储获取应用程序设置容器。Gets the application settings container from the local app data store.
ApplicationData.RoamingSettingsApplicationData.RoamingSettings 从漫游应用数据存储获取应用程序设置容器。Gets the application settings container from the roaming app data store.
ApplicationDataContainerApplicationDataContainer 支持创建、删除、枚举和遍历容器层次结构的应用设置的容器。A container for app settings that supports creating, deleting, enumerating, and traversing the container hierarchy.
Windows.UI.ApplicationSettings 命名空间Windows.UI.ApplicationSettings Namespace 提供用于定义显示在 Windows shell 的设置窗格中的应用设置的类。Provides classes that you'll use to define the app settings that appear in the settings pane of the Windows shell.

有用的文档Useful docs

主题Topic 说明Description
应用设置指南Guidelines for app settings 介绍有关创建和显示应用设置的最佳做法。Describes best practices for creating and displaying app settings.
存储和检索设置以及其他应用数据Store and retrieve settings and other app data 保存和检索设置(包括漫游设置)演练。Walk-through for saving and retrieving settings, including roaming settings.

有用的代码示例Useful code samples

代码示例Code sample 说明Description
应用程序数据示例Application data sample 场景 2-4 重点介绍设置Scenarios 2-4 focus on settings