更新记录

1.0.0（2026-06-07） 下载此版本

初次提交

平台兼容性

uni-app x(4.61)

其他

laoqianjunzi-sensor

laoqianjunzi-sensor 是一个面向 uni-app x 的标准 UTS 传感器插件，使用统一 API 管理四端传感器监听、页面亮度、接近态和音频路由能力。

适用范围

• app-android
• app-harmony
• app-ios
• web

插件目标

• 统一封装多种传感器监听入口，避免页面分别处理不同平台 API。
• 在插件内提供独立演示页，便于直接验证运行行为。
• 仅保留 Android、iOS、鸿蒙三端均支持的能力，确保跨平台行为一致。
• 使用传感器键名（如 accelerometer）作为标识，不再使用数字编号。

目录结构

laoqianjunzi-sensor
├─package.json
├─pages/
│ └─index.uvue
├─pages_init.json
└─utssdk/
  ├─index.uts
  ├─interface.uts
  ├─common.uts
  ├─unierror.uts
  ├─app-android/
  ├─app-harmony/
  ├─app-ios/
  └─web/

能力列表

1. 传感器监听

• 统一方法：startSensorWatch、stopSensorWatch、setSensorPacketListener
• 统一清单：getSensorCatalog
• 统一回调结构：SensorPacket

支持的传感器如下：

2. 系统能力

• 页面亮度：setScreenLightness、getScreenLightness
• 音频路由：setSpeakerphoneEnabled
• 接近态：setProximitySensingEnabled、getProximitySensingEnabled、getProximityDetected
• 运行权限：requestRuntimeAccess

平台说明

说明：

• 传感器是否可用由设备硬件、系统权限、浏览器实现共同决定。
• Web 端存在较大浏览器差异，getSensorCatalog() 返回的是当前运行环境探测到的能力结果。
• 部分 Web 浏览器会把运动或方向访问放到用户手势触发的权限流程中，建议先调用 requestRuntimeAccess()。

快速开始

1. 导入插件

import {
  getSensorCatalog,
  setSensorPacketListener,
  startSensorWatch,
  stopSensorWatch
} from '@/uni_modules/laoqianjunzi-sensor'

2. 查看能力清单

const catalog = getSensorCatalog()
console.log(catalog)

3. 监听传感器

setSensorPacketListener((packet) => {
  console.log(packet)
})

const result = startSensorWatch({
  sensorType: 'accelerometer',
  readingInterval: 200
})

console.log(result)

4. 停止监听

stopSensorWatch('accelerometer')

主要类型

SensorCatalogItem

type SensorCatalogItem = {
  sensorType: string
  label: string
}

SensorCapability

type SensorCapability = {
  sensorType: string
  label: string
  isSupported: boolean
}

SensorPacket

type SensorPacket = {
  phase: 'reading' | 'accuracy' | 'error'
  sensorType: string
  label: string
  snapshot: SensorSnapshot | null
  errorCode: number
  errorMessage: string
}

RuntimeAccessResult

type RuntimeAccessResult = {
  granted: boolean
  permissions: Array<string>
  grantResults: Array<number>
  code: number
  message: string
}

演示页

插件内置演示页：

• 路径：/uni_modules/laoqianjunzi-sensor/pages/index

演示页包含以下内容：

• 传感器清单与可用性状态
• 监听开始 / 停止
• 页面亮度快速切换
• 扬声器、接近监听开关
• 权限申请入口
• 最新回调数据与日志输出

权限与配置

Android

已在 utssdk/app-android/AndroidManifest.xml 中声明：

• android.permission.ACTIVITY_RECOGNITION
• android.permission.BODY_SENSORS
• android.permission.MODIFY_AUDIO_SETTINGS
• android.permission.WRITE_SETTINGS

iOS

已在 utssdk/app-ios/info.plist 中补充：

• NSMotionUsageDescription

Harmony

• 若业务需要请求特定传感器权限，请在宿主工程侧根据实际上架要求补充对应权限配置。

使用建议

• 页面离开前调用 stopSensorWatch 并清空 setSensorPacketListener(null)。
• 如果需要持续展示多种数据，建议每次只开启必要传感器，避免长期并发采样。
• 对 Web 端请优先在目标浏览器真机验证，不建议把桌面浏览器结果视为原生端能力基准。

错误码

注意事项

• sensorType 参数使用字符串键名（如 'accelerometer'），不再使用数字编号。
• readingInterval 单位为毫秒，建议从 100 到 500 之间按需取值。
• 亮度控制默认作用于当前页面或当前窗口，不建议在无用户感知的情况下频繁切换。
• 本插件仅保留 Android、iOS、鸿蒙三端均支持的能力，确保跨平台行为一致。