動態光源

本主題描述您的 Windows 應用程式如何跨連線裝置提供動態光源效果，以實作開放式 Human Interface Devices （HID）光源和照明標準。 特別是具有一個或多個燈 (燈、LED、燈泡等) 的裝置的 LampArray 規格。

重要 API

• Windows.Devices.Lights

  注意

  Lamp 類別不適用於 HID LampArray 功能，且與本主題無關。

概觀

動態光源可讓 Windows 應用程式開發人員和終端使用者控制及同步處理相容周邊和其他連線裝置的光源效果。 這些功能可用來提供可娛樂使用者、使其更具生產力的凝聚力體驗，甚至讓 Windows 體驗更容易存取。

支援的應用程式類型和平臺

• Win10 版本 1809 (2018 年 10 月) 及更高版本。
  • 適用於前景 UWP 和 Win32 應用程式。
• Windows 11 Build 23466 (預覽版) 及更高版本。
  • 適用於前景和背景 (環境) UWP 和 Win32 應用程式。
• Xbox GDK 2023 年 3 月 Update 1 和更新版本。
  • 請參閱遊戲開發工具組 (GDK) 中的 光源 API。

支援的裝置和裝置類型

• 鍵盤或鍵盤
• 滑鼠
• 遊戲控制器 (遊戲手把、飛行桿、方向盤等)。
• 周邊裝置 (如喇叭、滑鼠墊、麥克風、網路攝影機等)。
• 場景 (會議室/舞臺/區域裝置，例如燈泡、聚光燈、閃閃燈、看板、相機閃爍等)。
• 通知 (使用者註意裝置，例如警報、語音助理等)。
• 底座 (RAM、主機板、風扇等內部計算機元件)。
• 可穿戴式裝置 (耳機、手錶、健身跟蹤器、鞋子等配件)。
• 傢俱 (如椅子、辦公桌、書櫃等)。
• 藝術 (如繪畫或雕塑)。
• 耳機 (專為頭部設計的配件，例如耳機或麥克風)。

當應用程式位於前景時，Windows 應用程式可以控制 HID LampArray 裝置 (從 Windows 10 開始)，以及當它位於背景時 (也稱為 環境光源，從 Windows 11 開始)。

裝置優先順序

Windows 會根據應用程式狀態設定動態光源的優先順序。 預設情況下，除非使用者在「設定」中另有指定，否則始終為前景應用程式指派 LampArray 裝置的控制權。 如果兩個或多個環境背景應用程式嘗試控制 LampArray 裝置，系統會將控制權指派給「設定」中優先考慮的應用程式。

背景 (環境) 照明

Windows.Devices.Lights 中的「環境」API 可讓背景應用程式控制 LampArray 裝置，而使用者在前景與不相關的應用程式互動時 (例如驅動同步光源效果的音樂應用程式)。

視使用者設定而定，應用程式可以接收 LampArray.AvailabilityChanged 事件。 搭配 DeviceWatcher 類別，應用程式可以追蹤及管理所有已連線/中斷連線的 LampArray 裝置，並查看使用者預期應用程式要控制哪些專案。 其中一個使用範例是使用者介面，會為每個連線裝置呈現圖示，無法使用的裝置會呈現灰色，並有到 動態光源 設定頁面的超連結，提供用戶變更前景和背景應用偏好設定的選項。

使用者設定

用戶可以透過 [設定-> 個人化 -> 動態光源 畫面，自定義其 LampArray 裝置體驗（前景和背景）。

1. 連接後，相容裝置將顯示在頁面頂端的裝置卡中，使用者可以在其中更改各個裝置設定。

2. 全域動態照明設定位於裝置卡下方 (對這些設定的變更會影響所有連接的裝置)。

   1. 在我的裝置上使用動態光源切換可讓使用者開啟或關閉動態光源。 當動態光源關閉時，裝置應該使用其預設的非動態光源行為運作。 動態光源包含一組內建的基本效果。
   2. 前景中的相容應用程式一律控制光源，可讓使用者開啟或關閉預設的動態光源應用程式行為。 關閉此功能後，即使需要控制的前景應用程式處於活動狀態，背景應用程式也可以控制其關聯裝置。
   3. 背景光控制項區段可讓使用者排定已自行註冊為環境背景控制器的已安裝應用程式優先順序。 將應用程式拖曳到清單頂端將優先考慮該應用程式，並確保它可以控制清單中其他應用程式的裝置。 環境背景設定與裝置及其連接的連接埠相關聯。 如果將 LampArray 拔下然後插入不同的 (USB) 端口，它將顯示為不同的裝置。
   4. 亮度滑桿可讓使用者在其裝置上設定 LED 亮度。
   5. 效果下拉式清單可讓使用者選取其裝置的色彩和效果。

   

封包和應用程式身分識別

環境背景應用程式必須在應用程式清單中聲明「com.microsoft.windows.lighting」AppExtension (有關如何執行此操作的更多詳細資訊，請參閱建立和託管應用程式擴充功能)。 EnvironmentLightingServer 會強制執行這項需求，此需求只會在支援擴充功能的套件身分識別 (已封存應用程式) 程式中接受 AmbientLightingClient 的連線。 為了使使用者能夠為已安裝的應用程式定義策略並在執行階段關聯該策略，此要求是必需的。

環境應用程式需要應用程式標識，以便在執行階段確定使用者偏好。 安裝應用程式之後，如果使用環境 API，系統就必須將應用程式的執行執行個體與使用者的喜好設定相互關聯。 此外，讓應用程式可供設定中的使用者使用，需要安裝後成品，以向系統指出您的應用程式是環境光源 API 的合法使用者。

此身分識別需求是透過 MSIX 封裝技術（即先前稱為 APPX 的 Microsoft 部署和封裝技術） 達成。

如果您已經使用 MSIX 封裝進行封裝和安裝，則沒有任何進一步的需求。

如果您有未封裝的應用程式，則需要額外的步驟來取得應用程式身分識別。 你可以將安裝移轉到完整的 MSIX，也可以使用 MSIX 的簡化稀疏打包和外部位置功能。 具有外部位置的稀疏打包旨在讓現有應用安裝獲得應用標識的優勢，而無需將設定/安裝完全轉換為 MSIX。 這是設定/安裝中的一個新步驟，它使用工具建立 MSIX 套件來表示您正在安裝的應用程式。

您必須定義描述安裝 AppXManifest.xml 封裝指令清單。 MSIX 套件是使用 MakeAppXPackage 工具建立的。 在安裝期間，您會使用指定已安裝可執行檔案位置的 封裝管理員 API 來安裝 MSIX 套件。 為了方便起見，add-appxpackage PowerShell 指令碼也會封裝此 API 行為。 或者， AddPackageByUriAsync 可以在安裝期間用來安裝 MSIX 套件。

針對未封裝的應用程式安裝，可執行檔也有並存應用程式指令清單需求。

如需已封裝和未封裝應用程式的更深入說明，請參閱部署概觀。

範例

另請參閱

• Windows.Devices.Lights
• Windows.Devices.Lights.Effects
• 燈光和照明 (www.usb.org)