Windows Universal Samples 之 PresenceSensor:HumanPresenceSensor API 完整实战指南
Windows Universal Samples 之 PresenceSensor:HumanPresenceSensor API 完整实战指南
本指南以 Samples/PresenceSensor 示例为蓝本,系统讲解 UWP(Universal Windows Platform)中 Windows.Devices.Sensors.HumanPresenceSensor API 的定位、获取、选择与数据读取方法。阅读完本文,你将掌握如何获取默认存在传感器、按检测距离筛选传感器、通过系统选择器与设备监视器(DeviceWatcher)让用户自主选传感器,以及如何通过事件与轮询两种方式读取实时数据,并能在 Windows 11 设备上完成构建与部署。
示例概述与场景矩阵
本示例用于定位存在传感器(Presence Sensor)并从中读取数据,覆盖了 HumanPresenceSensor API 的六个核心使用场景:
| 场景 | 核心 API / 机制 | 说明 |
|---|---|---|
| 获取默认存在传感器 | HumanPresenceSensor.GetDefaultAsync() |
获取系统默认传感器并实时显示数据 |
| 从可用传感器中选择一个 | GetDeviceSelector() + DeviceInformation.FindAllAsync() + FromIdAsync() |
枚举全部传感器,按检测范围等条件挑选 |
| 让用户选择传感器 | DevicePicker |
弹出系统标准选择器对话框 |
| 检测传感器的接入与移除 | DeviceInformation.CreateWatcher() |
实时监控传感器热插拔 |
| 存在传感器数据事件 | ReadingChanged 事件 |
传感器上报新读数时实时刷新 UI |
| 轮询存在传感器读数 | GetCurrentReading() |
按需读取当前读数快照 |
在 SampleConfiguration.cs 中,三个场景被注册为导航条目:Data Events(Scenario1)、Polling(Scenario2)、Choosing(Scenario3),对应功能名称 Presence Sensor。仓库同时提供了 C#(cs)与 C++/WinRT(cppwinrt)两种实现,C++ 版本通过 Project.idl 声明运行时类,界面则统一复用 shared 目录下的 XAML 文件。
场景一:数据事件——监听默认传感器的实时上报
获取默认传感器
点击 "Get default sensor" 按钮后,示例通过 HumanPresenceSensor.GetDefaultAsync() 获取系统默认存在传感器,并将结果绑定到 ReadingChanged 事件上,数据会实时更新显示。核心代码见 Scenario1_DataEvents.xaml.cs:
// Try to get the default presence sensor.
try
{
sensor = await HumanPresenceSensor.GetDefaultAsync();
}
catch (UnauthorizedAccessException)
{
// The user denied this app presence sensor access.
sensor = null;
}
if (sensor != null)
{
VisualStateManager.GoToState(this, "Ready", true);
// Begin listening for data reports.
sensor.ReadingChanged += ReadingChanged;
}
else
{
rootPage.NotifyUser("No presence sensor found", NotifyType.ErrorMessage);
}
值得注意的细节:
- 权限拒绝处理:若用户拒绝了本应用的传感器访问权限,
GetDefaultAsync()会抛出UnauthorizedAccessException,示例捕获后将sensor置为null,避免后续空引用。 - 导航离开时解除订阅:在
OnNavigatedFrom中执行sensor.ReadingChanged -= ReadingChanged并置空引用,防止页面退出后事件继续触发导致泄漏。
事件回调与读数结构
ReadingChanged 回调携带 HumanPresenceSensorReadingChangedEventArgs,其 Reading 属性为 HumanPresenceSensorReading。示例在回调中通过 Dispatcher.RunAsync 回到 UI 线程更新界面(Scenario1_DataEvents.xaml.cs):
async private void ReadingChanged(HumanPresenceSensor sender, HumanPresenceSensorReadingChangedEventArgs e)
{
await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
{
HumanPresenceSensorReading reading = e.Reading;
if (null != reading)
{
if (sensor.IsEngagementSupported)
{
EngagementStateTextBlock.Text = reading.Engagement.ToString();
}
else
{
EngagementStateTextBlock.Text = "Not Supported";
}
if (sensor.IsPresenceSupported)
{
DetectionStateTextBlock.Text = reading.Presence.ToString();
}
else
{
DetectionStateTextBlock.Text = "Not Supported";
}
// Show the detection distance, if available
DetectionDistanceTextBlock.Text = reading.DistanceInMillimeters == null ? "Unavailable" : reading.DistanceInMillimeters.ToString();
TimestampTextBlock.Text = reading.Timestamp.ToString("u");
}
});
}
每次上报的读数包含四类信息,对应界面上的四行显示(见 Scenario1_DataEvents.xaml):
- Engagement State(参与状态):由
reading.Engagement提供,仅在sensor.IsEngagementSupported为真时有效,否则显示 "Not Supported"; - Detection State(存在检测状态):由
reading.Presence提供,仅在sensor.IsPresenceSupported为真时有效; - Distance in mm(检测距离,毫米):
reading.DistanceInMillimeters为可空值,为null时显示 "Unavailable"; - Timestamp(时间戳):
reading.Timestamp以"u"(通用可排序格式)格式化输出。
这种"先查能力位、再读对应字段"的防御式写法,是因为不同硬件所支持的检测能力并不相同,示例为不支持的能力预留了降级显示。UI 侧通过 VisualStateManager 的 Ready 状态,在获取到传感器后将 "Get default sensor" 按钮收起、展开数据面板(见 Scenario1_DataEvents.xaml)。
场景二:轮询——枚举传感器并按检测范围挑选
枚举全部存在传感器
与场景一直接取默认传感器不同,场景二先通过 HumanPresenceSensor.GetDeviceSelector() 获取设备选择器字符串,再用 DeviceInformation.FindAllAsync() 枚举系统全部存在传感器,为"挑选最合适的传感器"提供基础(Scenario2_Polling.xaml.cs):
string selector = HumanPresenceSensor.GetDeviceSelector();
DeviceInformationCollection deviceInfos = await DeviceInformation.FindAllAsync(selector);
foreach (DeviceInformation deviceInfo in deviceInfos)
{
HumanPresenceSensor foundSensor = null;
try
{
foundSensor = await HumanPresenceSensor.FromIdAsync(deviceInfo.Id);
}
catch (UnauthorizedAccessException)
{
// The user denied this app presence sensor access.
foundSensor = null;
}
...
}
按检测距离区间筛选
示例以传感器报告的检测距离范围作为挑选依据,演示了"用数据指导选型"的思路。MinDetectableDistanceInMillimeters 与 MaxDetectableDistanceInMillimeters 分别表示该传感器可检测的最小/最大距离(毫米),示例要求候选传感器覆盖 200mm~1200mm(0.2m~1.2m)的区间:
const uint distanceInMillimetersLValue = 200; // 0.2m
const uint distanceInMillimetersRValue = 1200; // 1.2m
if (foundSensor.MinDetectableDistanceInMillimeters <= distanceInMillimetersLValue &&
foundSensor.MaxDetectableDistanceInMillimeters >= distanceInMillimetersRValue)
{
rootPage.NotifyUser("Found a presence sensor that meets the detection range", NotifyType.StatusMessage);
sensor = foundSensor;
}
else
{
rootPage.NotifyUser("Presence sensor does not meet the detection range, using it anyway", NotifyType.StatusMessage);
sensor = foundSensor; // Your app may decide not to use this sensor and keep looking for another.
}
代码注释明确指出这两个阈值是"TODO: Customize these values to your application's needs"——生产应用应根据自身业务场景(如近场交互、远距离探测)调整该区间。同时注意,部分传感器不报告检测范围(MaxDetectableDistanceInMillimeters 为 null),示例对这种传感器采用"照常使用"策略,而真实应用可能选择继续寻找更合适的设备。
读取单次读数快照
选定传感器后,点击 "Get Data" 按钮即可通过 GetCurrentReading() 同步读取当前读数(Scenario2_Polling.xaml.cs):
HumanPresenceSensorReading reading;
try
{
reading = sensor.GetCurrentReading();
}
catch (UnauthorizedAccessException)
{
reading = null;
}
if (reading != null)
{
// 与场景一相同的字段输出逻辑:Engagement / Presence / DistanceInMillimeters / Timestamp
}
轮询与事件的差异在于:事件模式由硬件主动推送、适合持续监控;轮询模式按需取快照、适合"用户点击才刷新"的交互。示例中 GetCurrentReading() 为同步调用,无需 await。UI 侧 Scenario2_Polling.xaml 在进入 Ready 状态后才启用 "Get Data" 按钮。
场景三:选择——系统选择器与动态监视器
使用 DevicePicker 让用户挑选
点击 "Use picker" 按钮时,示例使用 DevicePicker 弹出系统标准设备选择对话框,用户选定后应用立即读取一次读数(Scenario3_Choosing.xaml.cs):
DevicePicker picker = new DevicePicker();
picker.Appearance.Title = "Select a presence sensor from which to read data";
picker.Filter.SupportedDeviceSelectors.Add(HumanPresenceSensor.GetDeviceSelector());
// Calculate the position of the button next to which we will place the picker.
GeneralTransform transform = ScenarioPickButton.TransformToVisual(null);
Rect rect = transform.TransformBounds(new Rect(0.0, 0.0, ScenarioPickButton.ActualWidth, ScenarioPickButton.ActualHeight));
DeviceInformation deviceInfo = await picker.PickSingleDeviceAsync(rect);
if (deviceInfo != null)
{
await ReadOneReadingFromSensorAsync(deviceInfo);
}
要点:
- 通过
picker.Filter.SupportedDeviceSelectors.Add(HumanPresenceSensor.GetDeviceSelector())限定选择器只显示存在传感器; PickSingleDeviceAsync(rect)以按钮的屏幕坐标为锚点弹出选择器,返回用户选中的DeviceInformation;- 选中后复用统一的
ReadOneReadingFromSensorAsync辅助方法:先FromIdAsync打开传感器,再GetCurrentReading()读取并展示,若打开失败(用户拒绝授权)则提示 "Could not access sensor"。
使用 DeviceWatcher 动态监视传感器插拔
点击 "Start watcher" 按钮时,示例通过 DeviceInformation.CreateWatcher(HumanPresenceSensor.GetDeviceSelector()) 创建设备监视器,实时监听传感器设备的添加、移除、更新与枚举完成四种事件(Scenario3_Choosing.xaml.cs):
watcher = DeviceInformation.CreateWatcher(HumanPresenceSensor.GetDeviceSelector());
watcher.Added += OnHumanPresenceSensorAdded;
watcher.Removed += OnHumanPresenceSensorRemoved;
watcher.Updated += OnHumanPresenceSensorUpdated;
watcher.EnumerationCompleted += OnHumanPresenceSensorEnumerationCompleted;
watcher.Start();
四个事件处理器的职责:
| 事件 | 处理逻辑 |
|---|---|
Added |
将新发现的传感器以 ListBoxItem(内容为设备名、Tag 存放 DeviceInformation)加入列表 Scenario3_Choosing.xaml.cs |
Removed |
按 DeviceInformationUpdate.Id 在列表中找到对应项并移除 Scenario3_Choosing.xaml.cs |
Updated |
调用 itemDeviceInfo.Update(update) 刷新设备信息,并同步更新显示名称 Scenario3_Choosing.xaml.cs |
EnumerationCompleted |
通知用户 "All sensors found. Monitoring for changes...",表示首次枚举完成、进入持续监视阶段 Scenario3_Choosing.xaml.cs |
所有回调都通过 Dispatcher.RunAsync 切回 UI 线程再操作 ListBox,符合 UWP 的线程模型要求。页面离开时在 OnNavigatedFrom 中调用 watcher.Stop() 停止监视(Scenario3_Choosing.xaml.cs)。从列表中选中某传感器并点击 "Poll selected sensor" 按钮,即可读取该传感器的当前读数。界面布局见 Scenario3_Choosing.xaml,设备列表 SensorsList 居中占满一行,读数面板置于底部。
权限声明:humanPresence 设备能力
HumanPresenceSensor 属于受保护的系统设备,应用必须在清单中显式声明对应的设备能力。C# 版本的 Package.appxmanifest 中声明如下:
<Capabilities>
<DeviceCapability Name="humanPresence"/>
</Capabilities>
此外清单的 TargetDeviceFamily 声明了最低目标版本(MinVersion="10.0.22621.1778"),这与 README 中"Windows 11 build 22624 或更高"的系统要求一致——HumanPresenceSensor API 是较新的传感器 API,仅在较新版本的 Windows 11 上可用。若缺少该能力声明,运行时访问传感器会抛出 UnauthorizedAccessException,这正是三个场景的代码中反复捕获该异常的原因。C++/WinRT 版本同样在 cppwinrt 的清单 中声明了该能力。
系统要求与构建运行
系统要求
- Windows 11 build 22624 或更高版本:存在传感器 API 依赖较新的系统版本,旧版本系统上无法正常运行。
构建示例
- 若下载的是示例 ZIP 压缩包,务必解压整个压缩包,而不是只解压包含目标示例的文件夹——示例依赖仓库根目录的
SharedContent目录中的共享代码与资源(README 头部 frontmatter 中的extendedZipContent也指定了SharedContent与LICENSE需要一并解压)。 - 启动 Microsoft Visual Studio,选择 文件 > 打开 > 项目/解决方案。
- 在解压目录中依次进入
Samples子目录 → 本示例子目录 → 首选语言子目录(C++ 或 C#),双击其中的解决方案文件(.sln)。本仓库提供了 PresenceSensor.sln(C#)与 PresenceSensor.sln(C++/WinRT)两个解决方案。 - 按 Ctrl+Shift+B,或选择 生成 > 生成解决方案。
运行示例
后续步骤取决于你是只部署,还是既要部署又要运行:
- 仅部署:选择 生成 > 部署解决方案。
- 部署并运行(调试):按 F5,或选择 调试 > 开始调试。
- 运行(不调试):按 Ctrl+F5,或选择 调试 > 开始执行(不调试)。
运行时请确认设备具备存在传感器硬件(如支持用户存在检测的笔记本/一体机),并在系统弹出权限提示时允许应用访问,否则三个场景均会因 UnauthorizedAccessException 而提示传感器不可用。
相关主题
本示例聚焦"读取"一侧的传感器 API;与之互补的周边主题包括:
- ProximitySensor(接近传感器)示例:Samples/ProximitySensor——同为设备感应类 API,关注近距离探测,可与存在传感器对照学习;
- DeviceEnumerationAndPairing(设备枚举与配对)示例:Samples/DeviceEnumerationAndPairing——展示更多针对设备的操作,如高级枚举、配对与筛选,可用于深化场景三中"选择传感器"部分的实现。
小结
PresenceSensor 示例完整覆盖了 HumanPresenceSensor API 的两条主线:事件驱动(ReadingChanged 实时推送)与按需轮询(GetCurrentReading() 快照读取),并在此基础上演示了三种获取传感器的方式——默认传感器、按能力筛选、用户主动选择(DevicePicker / DeviceWatcher)。从源码可以提炼出四条可复用的工程经验:始终捕获 UnauthorizedAccessException 以优雅处理权限拒绝;读取字段前先检查 IsEngagementSupported / IsPresenceSupported 能力位;处理可空字段(如 DistanceInMillimeters);在页面导航离开时解除事件订阅并停止 DeviceWatcher。配合 humanPresence 设备能力声明与 Windows 11 build 22624+ 的系统前提,即可在真实设备上构建出可靠的存在感知能力。