动态照明
本主题介绍 Windows 应用如何为实施开放式人机接口设备 (HID)照明标准的多个不同连入设备提供动态照明效果。 尤其是适用于带一个或多个灯具（灯、LED、灯泡等）的设备的 LampArray 规范。
重要的 API
概述
借助 Windows 中的动态照明支持，应用开发人员和最终用户能够在多个外围设备及其他连入设备中控制和同步照明效果。
支持的应用类型和平台
- Win10 版本 1809（2018 年 10 月）及更高版本。
- 适用于前台 UWP 和 Win32 应用。
- Windows 11 版本 23466（预览）及更高版本。
- 适用于前台和后台（环境）UWP 和 Win32 应用。
- Xbox GDK 2023 年 3 月更新 1 及更高版本。
- 请参阅游戏开发工具包 (GDK) 中的照明 API。
支持的设备和设备类型
- 键盘或辅助键盘
- 鼠标
- 游戏控制器（游戏手柄、飞行杆、方向盘等）。
- 外围设备（一般设备，如扬声器、鼠标垫、麦克风、网络摄像头等）。
- 场景（房间/舞台/区域设备，如灯泡、聚光灯、闪光灯、广告牌、相机闪光灯等）。
- 通知（用户注意设备，如警报器、语音助手等）。
- 机箱（内部电脑组件，如 RAM、主板、风扇等）。
- 可穿戴设备（耳机、手表、健身追踪器、鞋子等配件）。
- 家具（如椅子、桌子、书架等）。
- 艺术类（如油画或雕塑）。
- 头戴设备（专为头部设计的配件，如耳机或麦克风）。
当 Windows 应用程序处于前台（从 Windows 10 开始）和处于后台（也称为环境照明，从 Windows 11 开始）中时，应用程序可以控制 HID LampArray 设备。
用户可以通过“设置”->“个性化”->“动态照明”屏幕自定义其 LampArray 设备体验（包括前台和后台），由此可以同步来自不同制造商的设备、控制所选设备和不同相关功能的亮度和效果，以及环境后台应用的设备访问优先级。 通过这些功能，你的应用能够娱乐用户、提高用户的工作效率、增强用户的 Windows 体验的可访问性，并跨一组与动态照明兼容的设备提供丝滑的连贯体验。
设备优先级
Windows 根据应用状态确定动态照明的优先级。 默认情况下，将始终为前台应用分配 LampArray 设备的控制权，除非用户在“设置”中另行指定。 如果有两个或更多环境后台应用尝试控制某个 LampArray 设备，系统会将控制权分配给在“设置”中具有优先级的应用。
后台（环境）照明
Windows.Devices.Lights 中的“环境”API 使后台应用程序能够在用户与前台中不相关的应用程序（例如驱动同步照明效果的音乐应用）交互时控制 LampArray 设备。
应用可以接收 LampArray.AvailabilityChanged 事件，具体取决于用户设置。 如果与 DeviceWatcher 类结合使用，应用可以跟踪和管理所有已连接/断开连接的 LampArray 设备，并查看用户希望应用控制哪些设备。 一个使用例子是为每个连入的设备呈现图标的 UI，不可用的设备会灰显，链接到动态照明设置页面后，用户可以在其中更改前台/后台应用首选项。
用户设置
用户可以通过“设置”-“个性化>”->“动态照明”中的“动态照明”页，在个人和全局级别控制和配置其 HID LampArray 设备。 当至少有一个兼容设备连接到电脑时，“设置”中将显示此页面。
兼容设备连接后会显示在页面顶部的设备卡中，用户可在其中更改各个设备设置。
全局动态照明设置位于设备卡下方（更改这些设置会影响所有连接的设备）。
- 通过“在我的设备上使用动态照明”切换开关，用户可以打开或关闭动态照明。 当动态照明关闭时，设备应会按其默认的非动态照明方式运行。 动态照明包括内置的一组基本效果。
- 通过“前台的兼容应用始终可控制照明”，用户可打开或关闭默认的动态照明应用行为。 如果此功能关闭，后台应用就可以控制其关联的设备，即使想要控制的前台应用处于活动状态也不会有影响。
- 通过“后台光控制”部分，用户可以让注册为环境后台控制器的已安装应用具有优先权。 将应用拖到列表顶部可使其具有优先权，并确保它对设备的控制权高于列表中其他应用。 环境后台设置与设备及其连接的端口绑定。 如果拔下 LampArray 再将其插入另一个 (USB) 端口，它会显示为另一个设备。
- 通过“亮度”滑块，用户可在其设备上设置 LED 亮度。
- 通过“效果”下拉列表，用户可为其设备选择颜色和效果。
注意
如果未为某个设备选择“后台灯控制”，该设备会以“自治模式”运行，这意味着设备会恢复其默认固件行为。
打包和应用标识
环境后台应用程序必须在应用程序清单中声明“com.microsoft.windows.lighting”AppExtension（有关如何执行此操作的详细信息，请参阅创建并托管应用程序扩展）。 这一要求由 AmbientLightingServer 强制执行，它只接受具有包标识（打包应用）且支持扩展的进程中来自 AmbientLighting 客户端的连接。 若要使用户能够定义策略用于已安装的应用，然后在运行时关联该策略，就需要满足此要求。
环境应用程序需要应用标识，以便可以在运行时确定用户首选项。 当安装应用程序后，如果它使用环境 API，则系统需要将正在运行的应用实例与用户的首选项相关联。 此外，如果要在设置中让应用对用户可用，需要一个安装后项目，用于向系统指示应用是环境照明 API 的合法使用者。
此标识要求是通过 MSIX 打包实现的。
如果已在使用 MSIX 打包功能打包和安装，就没有进一步的要求了。
如果有未打包的应用，则还需要执行其他步骤来获取应用程序标识。 可以将安装迁移到完整的 MSIX，也可以使用简化的 MSIX 功能：稀疏打包和外部位置。 使用外部位置进行稀疏打包旨在让现有应用安装获得应用标识的优势，而无需将设置/安装完全转换为 MSIX。 这是设置/安装中的一个新步骤，它使用工具创建 MSIX 包来表示要安装的应用。
必须定义用于描述安装的 AppXManifest.xml 打包清单。 MSIX 包使用 MakeAppXPackage 工具创建。 在安装时，使用包管理器 API 安装 MSIX 包，该 API 指定已安装的可执行文件的位置。 为便于操作，add-appxpackage PowerShell 脚本 还会包装此 API 行为。 也可以在安装时使用 AddPackageByUriAsync 来安装 MSIX 包。
对于未打包的应用安装，可执行文件还有并行应用程序清单要求。
有关打包和未打包应用的更深的入说明，请参阅部署概述。
术语表
以下术语和概念用于描述各种环境照明系统组件。
“自治”模式
在 HID 规范中定义为一种模式，其中硬件会回退到其固件定义的默认行为。 例如，当 OS 未主动控制设备或用户选择退出设备操作系统参与时，设备可能会呈现预编程的默认视觉效果。 设备必须响应 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 灯。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈