動態光源
本主題描述您的 Windows 應用程式如何跨連線裝置提供動態光源效果，以實作開放式 Human Interface Devices （HID） 光源和照明標準。 特別是具有一個或多個燈 (燈、LED、燈泡等) 的裝置的 LampArray 規格。
重要 API
概觀
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 開始)。
使用者可以透過設定 -> 個人化 -> 動態光源畫面來自訂其 LampArray 裝置體驗（包括前景和背景），讓他們同步處理來自不同製造商的裝置、控制所選裝置和尺寸的亮度和效果，以及依環境背景應用程式優先存取裝置。 這些功能使您的應用程式能夠娛樂使用者，提高他們的工作效率，使他們在 Windows 上的體驗更容易訪問，並在一組動態照明相容的裝置上提供有凝聚力的體驗。
裝置優先順序
Windows 會根據應用程式狀態設定動態光源的優先順序。 預設情況下，除非使用者在「設定」中另有指定，否則始終為前景應用程式指派 LampArray 裝置的控制權。 如果兩個或多個環境背景應用程式嘗試控制 LampArray 裝置，系統會將控制權指派給「設定」中優先考慮的應用程式。
背景 (環境) 照明
Windows.Devices.Lights 中的「環境」API 可讓背景應用程式控制 LampArray 裝置，而使用者在前景與不相關的應用程式互動時 (例如驅動同步光源效果的音樂應用程式)。
視使用者設定而定，應用程式可以接收 LampArray.AvailabilityChanged 事件。 搭配 DeviceWatcher 類別，應用程式可以追蹤及管理所有已連線/中斷連線的 LampArray 裝置，並查看使用者預期應用程式要控制哪些專案。 其中一個範例使用方式是 UI，會呈現每個已連線裝置的圖示、無法使用的圖示呈現灰色，以及使用者可變更前景/背景應用程式喜好設定的動態光源設定頁面連結。
使用者設定
使用者可以透過設定 -> 個人化 -> 動態光源中的動態光源頁面，在個別和全域層級控制及設定其 HID LampArray 裝置。 當至少一台相容裝置連接到 PC 時，此頁面將出現在「設定」中。
連接後，相容裝置將顯示在頁面頂端的裝置卡中，使用者可以在其中更改各個裝置設定。
全域動態照明設定位於裝置卡下方 (對這些設定的變更會影響所有連接的裝置)。
- 在我的裝置上使用動態光源切換可讓使用者開啟或關閉動態光源。 當動態光源關閉時，裝置應該使用其預設的非動態光源行為運作。 動態光源包含一組內建的基本效果。
- 前景中的相容應用程式一律控制光源，可讓使用者開啟或關閉預設的動態光源應用程式行為。 關閉此功能後，即使需要控制的前景應用程式處於活動狀態，背景應用程式也可以控制其關聯裝置。
- 背景光控制項區段可讓使用者排定已自行註冊為環境背景控制器的已安裝應用程式優先順序。 將應用程式拖曳到清單頂端將優先考慮該應用程式，並確保它可以控制清單中其他應用程式的裝置。 環境背景設定與裝置及其連接的連接埠相關聯。 如果將 LampArray 拔下然後插入不同的 (USB) 端口，它將顯示為不同的裝置。
- 亮度滑桿可讓使用者在其裝置上設定 LED 亮度。
- 效果下拉式清單可讓使用者選取其裝置的色彩和效果。
注意
當裝置未選取背景光線控制項時，它會以「自主模式」運作，這表示裝置會還原為預設韌體行為。
封包和應用程式身分識別
環境背景應用程式必須在應用程式清單中聲明「com.microsoft.windows.lighting」AppExtension (有關如何執行此操作的更多詳細資訊，請參閱建立和託管應用程式擴充功能)。 EnvironmentLightingServer 會強制執行這項需求，此需求只會在支援擴充功能的套件身分識別 (已封存應用程式) 程式中接受 AmbientLightingClient 的連線。 為了使使用者能夠為已安裝的應用程式定義策略並在執行階段關聯該策略，此要求是必需的。
環境應用程式需要應用程式標識，以便在執行階段確定使用者偏好。 安裝應用程式之後，如果使用環境 API，系統就必須將應用程式的執行執行個體與使用者的喜好設定相互關聯。 此外，讓應用程式可供設定中的使用者使用，需要安裝後成品，以向系統指出您的應用程式是環境光源 API 的合法使用者。
此身分識別需求可透過 MSIX 封包來達成。
如果您已經使用 MSIX 封裝進行封裝和安裝，則沒有任何進一步的需求。
如果您有未封裝的應用程式，則需要額外的步驟來取得應用程式身分識別。 你可以將安裝移轉到完整的 MSIX，也可以使用 MSIX 的簡化稀疏打包和外部位置功能。 具有外部位置的稀疏打包旨在讓現有應用安裝獲得應用標識的優勢，而無需將設定/安裝完全轉換為 MSIX。 這是設定/安裝中的一個新步驟，它使用工具建立 MSIX 套件來表示您正在安裝的應用程式。
您必須定義描述安裝 AppXManifest.xml 封裝指令清單。 MSIX 套件是使用 MakeAppXPackage 工具建立的。 在安裝期間，您會使用指定已安裝可執行檔案位置的 封裝管理員 API 來安裝 MSIX 套件。 為了方便起見，add-appxpackage PowerShell 指令碼也會封裝此 API 行為。 或者， AddPackageByUriAsync 可以在安裝期間用來安裝 MSIX 套件。
針對未封裝的應用程式安裝，可執行檔也有並存應用程式指令清單需求。
詞彙
以下術語和概念用於描述各種環境照明系統組件。
自發模式
在 HID 規範中定義為一種模式，其中硬體回退到其韌體定義的預設行為。 例如，當作業系統未主動控制裝置或使用者選擇不參與裝置的作業系統時，裝置可能具有預設的預先編程視覺效果。 裝置必須回應 HID 命令以從自主模式返回，以確保與使用者期望的順利互動。
環境應用程式
Windows.Devices.Lights API 取用者，這些取用者也有套件身分識別，並支援必要的應用程式擴充功能。 環境應用程式從 AmbientLightingClient 接收通知。 事件會通知應用程式他們有權存取的裝置。 透過這種方式，應用程式可以顯示列舉已連接照明裝置的 UI，並將目前由於使用者策略設定而無法存取的裝置灰顯。 環境應用程式會利用 Windows.Devices.Lights API，在可用的裝置上驅動效果。
設定小程式
將每個裝置使用者喜好設定儲存在登錄的 HKEY_CURRENT_USER (HKCU) 中。 使用者可以在每個裝置的基礎上定義指定裝置的優先環境應用程式集。 使用者也可以選擇退出動態照明。
應用程式身分識別
應用程式模型概念。 具有應用程式標識的應用程式可以在執行階段被系統識別。
MSIX
一種 Microsoft 部署和打包技術，以前稱為 APPX。
範例
示範如何使用 Windows.Devices.Lights 和 Windows.Devices.Lights.Effects API 來控制周邊裝置的 RGB 光源。
示範如何從桌面螢幕中提取單一代表性的顏色，並使用它來照亮連接的 RGB 裝置上的 LED 燈。