使用設定

「設定」是 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 提供。

用戶端應透過單一連線與每個設定通訊協定進行通訊。 如後續章節所述，持續性通訊必須透過相同的連線進行，以確保回應的一致性和連續性。詳情請參閱後續章節。

閱讀

每個設定通訊協定都會定義一個資料表，用於表示狀態和狀態等相關詳細資料。將資料整理使用單一結構 可讓「設定」以簡潔的方式傳達資訊。這個結構也有助於傳達變更，如後續所述。在無障礙範例中，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 會遵循等待取得模式，並傳回初始呼叫目前的資訊。系統會延後對後續叫用的回應，直到最後一個傳回值進行更新為止。在「設定」中，請務必在這些要求之間使用相同的 Proxy 連線，因為「設定」會根據管道追蹤已傳送的回應。如果發生錯誤，「設定」會以相關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

如要擷取設定通訊協定目前的資訊 (Accessibility 和 VolumePolicy 除外)，您可以用通訊協定名稱做為引數來呼叫 ffx setui。舉例來說，下列指令會擷取隱私權相關資訊：

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) 設為「是」：

ffx setui privacy -u true