動態光源

本主題說明您的Windows應用程式如何在實現開放式人機介面裝置（HID）照明與照明標準的連網裝置間提供動態光照效果。 特別是適用於具有一個或多個燈（燈光、LED、燈泡等）的裝置之 LampArray 規格。

• 重要 API：Windows.Devices.Lights

Note

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

Overview

動態光影讓 Windows 應用程式開發者與終端使用者都能控制並同步相容周邊設備及其他連網裝置間的光影效果。 這些功能可以用來提供連貫的體驗，娛樂使用者、提升生產力，甚至讓他們在 Windows 上的體驗更易取得。

支援的應用程式類型與平台

• Windows 10 版本 1809（2018 年 10 月）及之後。
  • 適用於在前景執行的 UWP 和 Win32 應用程式。
• Windows 11 版本 23466（預覽版）及更新版本。
  • 適用於前景和背景（環境）UWP 和 Win32 應用程式。
• Xbox GDK 2023 年 3 月 Update 1 及之後版本。
  • 請參閱遊戲開發套件（GDK）中的燈光 API。

支援的裝置與裝置類型

• 鍵盤或數字鍵盤
• Mouse
• 遊戲控制器（手把、飛行搖桿、方向盤等等）。
• 周邊設備（一般裝置如喇叭、滑鼠墊、麥克風、網路攝影機等）。
• 場景（房間/舞台/區域裝置，如燈泡、聚光燈、頻閃燈、廣告看板、閃光燈等）。
• 通知（使用者注意力裝置如鬧鐘、語音助理等）。
• 機箱（電腦內部零件，如記憶體、主機板、風扇等）。
• 可穿戴配件（配件如耳機、手錶、健身追蹤器、鞋子等等）。
• 家具（例如椅子、書桌、書櫃等）。
• 藝術（例如繪畫或雕塑）。
• 耳機（專為頭部設計的配件，如耳機或麥克風）。

Windows 應用程式可在應用程式於前景執行時（自 Windows 10 起）以及於背景執行時（亦稱為 ambient lighting，自 Windows 11 起）控制 HID LampArray 裝置。

裝置優先順序

Windows 會根據應用程式狀態優先設定動態光照。 預設情況下，前景應用程式總是被分配控制 LampArray 裝置，除非使用者在設定中另有指定。 當兩個或以上的環境背景應用程式試圖控制 LampArray 裝置時，系統會將控制權分配給設定中優先的應用程式。

背景（環境）照明

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

應用程式可接收 LampArray.AvailabilityChanged 事件，視使用者設定而定。 結合 DeviceWatcher 類別，應用程式可以追蹤並管理所有已連接或斷開的 LampArray 裝置，並查看使用者期望應用程式控制哪一個裝置。 一個例子是介面會為每個連接裝置渲染圖示，無法使用的裝置則變灰，並連結到 動態光影 設定頁面，讓使用者可以調整前景/背景應用程式偏好設定。

使用者設定

使用者可透過 設定 -> 個人化 -> 動態燈光 畫面自訂 LampArray 裝置體驗（前景與背景）。

1. 連接後，相容裝置會顯示在頁面頂端的裝置卡中，使用者可在那裡更改個別裝置設定。

2. 全域動態光影設定位於裝置卡下方（這些設定的變更會影響所有連接的裝置）。

   1. 「在我的裝置上使用動態光影」開關可以讓使用者開啟或關閉動態光影。 當動態光影關閉時，裝置應該會以預設的非動態光影行為運作。 動態光影包含一組內建的基本效果。
   2. 前景中的相容應用程式始終控制光影，讓使用者能開啟或關閉預設的動態光照應用程式行為。 當此功能關閉時，即使想要取得控制權的前景應用程式正在執行，背景應用程式仍可控制其所關聯的裝置。
   3. 背景燈控制區塊允許使用者優先排序已註冊為環境背景控制器的已安裝應用程式。 將應用程式拖曳到清單頂端，會優先排序它，並確保它能控制裝置而非清單中其他應用程式。 環境背景設定是綁定在裝置和它連接的埠口上。 如果你將 LampArray 拔除後，再插入另一個 USB 連接埠，它會被辨識為不同的裝置。
   4. 亮度滑桿讓使用者能設定裝置上的 LED 亮度。
   5. 效果 下拉 選單讓使用者為裝置選擇顏色和效果。

   

Note

當裝置未被選擇背景 光控制時，會以「自主模式」運作。

HID 規範中定義此模式，硬體會退回到韌體定義的預設行為。 例如，裝置可能具有一種預先編程的視覺效果，當作業系統未主動控制該裝置時，或當使用者選擇不讓作業系統介入該裝置時，該效果會作為預設效果。 裝置必須回應 HID 指令，從自主模式返回，以確保與使用者期望的順暢互動。

包裝與應用程式識別

環境背景應用程式必須在應用程式清單中宣告「com.microsoft.windows.lighting」的應用程式擴充功能（更多細節請參見 建立並架設應用程式擴充功能）。 此要求由 AmbientLightingServer 強制執行，該伺服器僅接受來自位於具有套件身分（封裝應用程式）的處理程序中，且支援該擴充功能之 AmbientLightingClient 所發起的連線。 此要求是為了讓使用者能為已安裝應用程式定義政策，並在執行時將該政策相關聯。

應用程式身份對於環境應用程式來說是必要的，以便在執行時能判斷使用者偏好。 一旦應用程式安裝完成，若使用環境 API，系統需要將執行中的應用程式實例與使用者偏好做對應。 此外，要在設定中讓使用者使用應用程式，需要安裝後的產物，向系統顯示你的應用程式是環境光 API 的合法使用者。

此身份要求透過MSIX 封裝（一種Microsoft部署與封裝技術，前稱 APPX）來實現。

如果您已經使用 MSIX 封裝進行封裝與安裝，則無需額外要求。

如果你使用的是未包裝的應用程式，取得應用程式身份還需要額外步驟。 你可以將安裝遷移到完整的 MSIX，或是使用 MSIX 簡化的 Sparse Packaging 與 External Location 功能。 採用外部位置的稀疏封裝，其設計目的是讓現有的應用程式安裝享有應用程式識別的優點，而無需將安裝程式/安裝程序完整轉換為 MSIX。 這是你設定/安裝中的一個新步驟，利用工具建立一個 MSIX 套件來代表你正在安裝的應用程式。

您必須定義一份 AppXManifest.xml 包裝清單 ，描述您的安裝內容。 MSIX 套件是使用 MakeAppXPackage 工具建立的。 安裝時，你會使用 封裝管理員 API 安裝 MSIX 套件，該 API 會指定你安裝的執行檔位置。 為了方便起見， add-appxpackage PowerShell 腳本 也會封裝這個 API 行為。 另外，安裝時也可使用 AddPackageByUriAsync 來安裝 MSIX 套件。

對於未封裝的應用程式安裝，您的可執行檔也必須符合 並存應用程式資訊清單 的要求。

請參閱 部署總覽 ，了解打包與非打包應用程式的更深入說明。

Examples

LampArray 樣本

示範如何使用 Windows.Devices.Lights 和 Windows.Devices.Lights.Effects API 來控制周邊裝置的 RGB 照明。

AutoRGB 範例

示範如何從桌面螢幕提取單一具代表性的顏色，並用它來點亮連接的 RGB 裝置上的 LED 燈。

另請參閱

• Windows.Devices.Lights
• Windows。裝置。燈光。效果
• 照明與照明（www.usb.org）