Windows Universal Samples 之 PresenceSensor:HumanPresenceSensor API 完整实战指南

原创2026-09-24 21:20:581,925 阅读
文章标签:示例工程

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 依赖较新的系统版本,旧版本系统上无法正常运行。

构建示例

  1. 若下载的是示例 ZIP 压缩包,务必解压整个压缩包,而不是只解压包含目标示例的文件夹——示例依赖仓库根目录的 SharedContent 目录中的共享代码与资源(README 头部 frontmatter 中的 extendedZipContent 也指定了 SharedContent 与 LICENSE 需要一并解压)。
  2. 启动 Microsoft Visual Studio,选择 文件 > 打开 > 项目/解决方案。
  3. 在解压目录中依次进入 Samples 子目录 → 本示例子目录 → 首选语言子目录(C++ 或 C#),双击其中的解决方案文件(.sln)。本仓库提供了 PresenceSensor.sln(C#)与 PresenceSensor.sln(C++/WinRT)两个解决方案。
  4. 按 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+ 的系统前提,即可在真实设备上构建出可靠的存在感知能力。

登录后查看全文
Windows-universal-samples