使用设置

设置是 Fuchsia SDK 的一部分，适用于具有适当支持软件包的产品。如果这些产品上的应用具有相应权限，则可以与“设置”进行交互。这种交互遵循通过“设置”协议访问和修改设置的常见模式。

本指南详细介绍了将“设置”整合到应用中以及与“设置”交互的步骤。

前提条件

设置服务支持 Fuchsia 中的“设置”协议。产品定义中必须存在服务的软件包 //src/settings/service:setui_service 及其核心分片之一（例如 //src/settings/service:setui_service_core_shard），才能使用“设置”。以下产品定义包括“设置”：

import("//products/bringup.gni")

base_package_labels += [
  "//src/settings/service:setui_service",
]
core_realm_shards += [
  "//src/settings/service:setui_service_core_shard",
]

如需详细了解 Fuchsia 构建系统，请参阅 Fuchsia 构建系统。

权限

任何访问“设置”的应用都必须通过其组件清单声明使用情况。例如，以下清单声明了对 fuchsia.settings.accessibility 协议的访问权限：

{
    program: {
        runner: "elf",
        binary: "bin/example",
    },
    use: [
        { protocol: "fuchsia.settings.Accessibility" },
    ],
}

如需详细了解 Fuchsia 组件，请参阅组件清单。

正在连接

应用通过 Fuchsia SDK 中的运行时绑定访问“设置”。本指南将使用 Rust 作为示例，但绑定适用于各种其他语言，例如 C++ 和 Dart。

与其他 FIDL 协议一样，访问“设置”的第一步是连接到设置服务。以下示例连接到 fuchsia.settings.accessibility：

let proxy = connect_to_protocol::<AccessibilityMarker>().context("failed to connect to Settings");

在上面的示例中，connect_to_protocol 和 AccessibilityMarker 通过 SDK 提供。

客户端应通过单个连接与每个 Settings 协议进行通信。 持续通信必须通过同一连接进行，以确保响应的一致性和连续性（如后续部分所述）。

阅读

每个 Settings 协议都定义了一个表，用来传达相关详细信息，例如状态和状态。通过将数据整理在一个结构下，“设置”可以简洁地传达信息。该结构还有助于交流更改，如稍后所述。在无障碍功能示例中，AccessibilitySettings 会捕获相关详细信息：

/// Supported accessibility settings.
type AccessibilitySettings = table {
    /// For videos, use an alternative audio track (akin to changing languages)
    /// that explains what is happening visually while there is no dialogue.
    1: audio_description bool;

    /// Read aloud elements of the screen selected by the user.
    2: screen_reader bool;

    /// Invert colors on the screen.
    3: color_inversion bool;

    /// Interpret triple-tap on the touchscreen as a command to zoom in.
    4: enable_magnification bool;

    /// What type of color-blindness, if any, to correct for.
    5: color_correction ColorBlindnessType;

    /// What kind of sources get closed captions, and how they look.
    6: captions_settings CaptionsSettings;
};

每个协议中都有一个名为“Watch”的方法，用于提供对这些信息的访问权限。这是 fuchsia.settings.accessibility 的声明：

Watch() -> (struct {
    settings AccessibilitySettings;
});

Watch 遵循挂起 get 模式，返回初始调用的当前信息。后续调用的响应被延迟到上次返回值有更新为止。在这些请求之间使用相同的代理连接对于此行为至关重要，因为“设置”会根据通道跟踪传送的响应。如果出现错误，“设置”将使用相关 epitaph 来关闭 FIDL 通道。

在无障碍功能示例中，调用 Watch 以确定屏幕阅读器是否已启用：

let settings = proxy.watch().expect("settings retrieved");
let screen_reader_enabled = settings.screen_reader.ok_or(false);

文案

应用可以通过利用为读取数据而找到的相同表结构来影响“设置”。每个可变协议都提供了名为 Set 的 Watch 对应方法，该方法接受 AccessibilitySettings 作为参数：

Set(struct {
    settings AccessibilitySettings;
}) -> () error Error;

通过在表字段中指定所需的最终状态来传达更改。由于每个字段都是可选的，因此只需指定受影响的字段。 通过将更改定义为增量，可以避免来自多个调用方的竞态条件。如果成功，相应更改将持久保存并应用多次。 接着前面的示例来讲，调用方可以使用以下代码启用屏幕阅读器：

let new_settings = AccessibilitySettings::default();
new_settings.screen_reader = Some(true);
proxy.set(new_settings).await.expect("request completed").expect("request succeeded");

调试

“设置”提供了一个 Fuchsia CLI 工具 (ffx setui)，用于与其协议交互。借助此工具，开发者能够实时访问“设置”，了解其应用会如何影响“设置”以及受“设置”影响。ffx setui 工具附带 Fuchsia 源代码和 SDK。如需使用该功能，请先运行以下命令以选择启用：

ffx config set setui true

如需检索 Settings 协议的最新信息（Accessibility 和 VolumePolicy 除外），您可以使用协议名称作为参数调用 ffx setui。例如，以下命令可检索有关 Privacy 的信息：

ffx setui privacy

对于无障碍功能，请在协议名称后面添加关键字 watch：

ffx setui accessibility watch

对于 VolumePolicy，请在协议名称后面添加关键字 get：

ffx setui volume_policy get

ffx setui还可以修改“设置”。该实用程序的 help 命令详细说明了每个协议的具体修改语法：

ffx setui privacy help

以下是将用户数据分享意见征求 (user-data-sharing-consent) 设为 true 的示例：

ffx setui privacy -u true