更新记录

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

• 初次提交

平台兼容性

uni-app(5.0)

uni-app x(5.0)

laoqianjunzi-step

laoqianjunzi-step 是一个基于 uni_modules + utssdk 规范实现的标准 UTS API 插件，用于在 uni-app x 项目中提供步态能力检测、实时步数监听、区间累计查询，以及 Web 联调模拟能力。

插件当前以 app-android、app-harmony、app-ios、web 四端为主要支持目标，同时保留了 mp-weixin 的平台汇总步数载荷读取能力，便于在同一套业务接口下完成多端接入。

功能概览

• 检测当前设备或运行环境是否具备步态能力。
• 监听当前会话内的实时步数变化。
• 按时间区间查询累计步数。
• Web 端提供稳定的模拟步数流，方便联调和演示。
• 微信小程序可获取微信运动加密载荷，交由服务端解密后再完成区间统计。

插件结构

uni_modules/laoqianjunzi-step
├─package.json
├─readme.md
├─changelog.md
├─pages_init.json
├─pages/
│ └─index.uvue
└─utssdk/
  ├─interface.uts
  ├─unierror.uts
  ├─index.uts
  ├─app-android/
  │ ├─config.json
  │ └─index.uts
  ├─app-ios/
  │ ├─config.json
  │ └─index.uts
  ├─app-harmony/
  │ ├─config.json
  │ └─index.uts
  ├─web/
  │ └─index.uts
  └─mp-weixin/
    └─index.js

说明：

• utssdk/interface.uts 统一定义插件对外暴露的类型和 API。
• utssdk/unierror.uts 统一定义错误码和错误对象。
• utssdk/index.uts 为跨平台入口，按平台导出具体实现。
• pages/index.uvue 为插件自带演示页。
• pages_init.json 用于把演示页按 uni_modules 标准方式注册到宿主项目页面路由。

适用平台

安装与使用

将插件放入项目的 uni_modules 目录后，始终从插件根目录导入：

import {
  probeStepTracking,
  probeSummaryStepSupport,
  watchLiveStride,
  haltLiveStride,
  requestSummaryStepPayload,
  readStrideRange,
  type LiveStepOptions,
  type StepPulse,
  type StepRangeOptions,
  type StepSummaryOptions,
  type StepSummaryPacket,
  type StepSummaryEntry,
  type StepPluginFailure
} from '@/uni_modules/laoqianjunzi-step'

注意：

• 仅支持从 @/uni_modules/laoqianjunzi-step 导入。
• 不要直接导入 utssdk 内部的 index.uts、interface.uts 或平台子目录文件。

页面注册

插件自带演示页：uni_modules/laoqianjunzi-step/pages/index

推荐做法：

• 使用插件根目录下的 pages_init.json，由 HBuilderX 在导入插件时自动合并页面路由。
• 如果当前工程已经直接包含该插件源码，也可以手动在宿主项目的 pages.json 中注册页面。

示例：

{
  "pages": [
    {
      "path": "uni_modules/laoqianjunzi-step/pages/index",
      "style": {
        "navigationBarTitleText": "步态演示"
      }
    }
  ]
}

权限与平台配置

插件已在各平台的 config.json 中写入必要配置，但使用前仍建议确认宿主项目的运行环境与权限表现符合预期。

Android

• 最低版本：Android 5.0（SDK 21）
• 插件声明权限：android.permission.ACTIVITY_RECOGNITION
• 运行时会在 Android 10+ 申请运动识别权限
• 使用真实原生能力时，建议在自定义基座或正式打包环境验证

iOS

• 最低版本：iOS 12
• 依赖框架：CoreMotion.framework
• 隐私说明：NSMotionUsageDescription

HarmonyOS Next

• 权限：ohos.permission.ACTIVITY_MOTION

Web

• 无需额外权限
• 用于联调、演示和接口验证，不读取真实步态传感器

API 总览

插件对外暴露以下 API：

• probeStepTracking()
• probeSummaryStepSupport()
• watchLiveStride(options)
• haltLiveStride()
• requestSummaryStepPayload(options)
• readStrideRange(options)

类型定义

StepPulse

type StepPulse = {
  count : number,
  timestamp : number
}

• count：本次返回的累计步数
• timestamp：当前回调触发时的毫秒时间戳

StepPluginFailure

type StepPluginFailure = {
  errSubject : string,
  errCode : 9211001 | 9211002 | 9211003 | 9211004 | 9211005 | 9211006,
  errMsg : string,
  detail : string
}

• errSubject：错误主题，固定为插件标识
• errCode：业务错误码
• errMsg：错误简述
• detail：平台侧补充说明

LiveStepOptions

type LiveStepOptions = {
  success ?: (res : StepPulse) => void,
  fail ?: (res : StepPluginFailure) => void,
  complete ?: (res : any) => void
}

StepSummaryEntry

type StepSummaryEntry = {
  timestamp : number,
  step : number
}

StepSummaryPacket

type StepSummaryPacket = {
  provider : 'mp-weixin',
  code : string,
  encryptedData : string,
  iv : string,
  cloudID : string | null,
  requestedAt : number
}

StepSummaryOptions

type StepSummaryOptions = {
  success ?: (res : StepSummaryPacket) => void,
  fail ?: (res : StepPluginFailure) => void,
  complete ?: (res : any) => void
}

StepRangeOptions

type StepRangeOptions = {
  from : number,
  to : number,
  summaryEntries ?: StepSummaryEntry[],
  success ?: (res : StepPulse) => void,
  fail ?: (res : StepPluginFailure) => void,
  complete ?: (res : any) => void
}

API 详细说明

probeStepTracking()

检查当前平台是否具备步态能力。

const supported = probeStepTracking()

返回值：boolean

平台行为：

• Android：检查系统步态传感器是否存在
• HarmonyOS：检查计步传感器是否可订阅
• iOS：检查 CMPedometer 是否可用
• Web：检查定时器与本地缓存是否可用于模拟
• 微信小程序：返回 false

probeSummaryStepSupport()

检查当前平台是否支持平台侧汇总步数读取。

const summarySupported = probeSummaryStepSupport()

返回值：boolean

平台行为：

• 微信小程序：返回微信运动能力是否可用
• 其他平台：返回 false

watchLiveStride(options)

开始监听实时步数。

watchLiveStride({
  success: (res : StepPulse) => {
    console.log('当前步数', res.count)
  },
  fail: (err : StepPluginFailure) => {
    console.error(err.errCode, err.errMsg, err.detail)
  }
})

行为说明：

• Android / HarmonyOS / iOS：返回当前监听会话内的累计步数
• Web：返回模拟步数流中的累计步数
• 同一时间仅保留一个有效监听会话，新会话会覆盖旧会话
• 监听开始后，业务层应在页面销毁或离开时主动调用 haltLiveStride() 释放资源

haltLiveStride()

停止当前监听会话。

haltLiveStride()

适用场景：

• 页面离开时清理监听
• 业务显式停止计步
• 重建监听前主动释放旧会话

requestSummaryStepPayload(options)

在微信小程序中读取微信运动加密载荷。

requestSummaryStepPayload({
  success: (packet : StepSummaryPacket) => {
    console.log(packet.code)
  }
})

返回说明：

• 插件不会直接返回明文步数
• code、encryptedData、iv 需要发送到服务端解密
• 若开通云开发，可能额外返回 cloudID

平台限制：

• 仅 mp-weixin 支持
• Android / HarmonyOS / iOS / Web 调用会返回不支持错误

readStrideRange(options)

查询指定时间区间内的累计步数。

const now = Date.now()
const todayStart = new Date(new Date().getFullYear(), new Date().getMonth(), new Date().getDate()).getTime()

readStrideRange({
  from: todayStart,
  to: now,
  success: (res : StepPulse) => {
    console.log('今日累计步数', res.count)
  },
  fail: (err : StepPluginFailure) => {
    console.error(err.errMsg)
  }
})

参数说明：

• from：开始时间，毫秒时间戳
• to：结束时间，毫秒时间戳
• summaryEntries：仅在微信小程序场景下使用，传入服务端解密后的步数列表

平台行为：

• Android：优先使用事件明细精确统计，必要时回退到按日快照
• HarmonyOS：优先使用事件明细精确统计，必要时回退到按日快照
• iOS：直接调用系统 CMPedometer 区间查询
• Web：读取模拟监听阶段生成的本地缓存
• 微信小程序：依赖 summaryEntries 完成本地区间汇总

使用示例

1. 检测支持并开始监听

import {
  probeStepTracking,
  watchLiveStride,
  haltLiveStride,
  type StepPulse,
  type StepPluginFailure
} from '@/uni_modules/laoqianjunzi-step'

if (probeStepTracking()) {
  watchLiveStride({
    success: (res : StepPulse) => {
      console.log('实时步数', res.count)
    },
    fail: (err : StepPluginFailure) => {
      console.error('监听失败', err.errMsg)
    }
  })
}

// 页面销毁时
haltLiveStride()

2. 查询今日步数

import { readStrideRange, type StepPulse } from '@/uni_modules/laoqianjunzi-step'

const now = Date.now()
const date = new Date(now)
const start = new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()

readStrideRange({
  from: start,
  to: now,
  success: (res : StepPulse) => {
    console.log('今日步数', res.count)
  }
})

3. 查询最近 7 天步数

import { readStrideRange } from '@/uni_modules/laoqianjunzi-step'

const now = Date.now()
const today = new Date(now)
const todayStart = new Date(today.getFullYear(), today.getMonth(), today.getDate()).getTime()
const weekStart = todayStart - 6 * 86400000

readStrideRange({
  from: weekStart,
  to: now,
  success: (res) => {
    console.log('近 7 天步数', res.count)
  }
})

4. 微信小程序汇总步数流程

import {
  requestSummaryStepPayload,
  readStrideRange,
  type StepSummaryPacket,
  type StepSummaryEntry
} from '@/uni_modules/laoqianjunzi-step'

requestSummaryStepPayload({
  success: (packet : StepSummaryPacket) => {
    // 将 packet.code、packet.encryptedData、packet.iv 发送到服务端
    // 服务端解密后返回 stepInfoList，再映射为 StepSummaryEntry[]
    const summaryEntries : StepSummaryEntry[] = []

    readStrideRange({
      from: Date.now() - 7 * 86400000,
      to: Date.now(),
      summaryEntries: summaryEntries,
      success: (res) => {
        console.log(res.count)
      }
    })
  }
})

错误码

四端行为差异说明

app-android

• 依赖系统步态传感器
• 实时监听数据会同步写入本地缓存
• 区间查询更适合查询插件运行期间产生过缓存的数据

app-harmony

• 依赖 @ohos.sensor
• 成功启动监听后立即进入监听态
• 区间查询依赖本地缓存数据

app-ios

• 依赖 CMPedometer
• 实时监听与历史查询都由系统能力直接提供
• 无需像 Android / HarmonyOS 一样依赖本地缓存做主路径统计

web

• 不读取真实硬件传感器
• 适合业务联调、页面演示、接口打通和回归测试
• 区间查询依赖模拟监听时生成的本地缓存

演示页说明

插件自带演示页位于：uni_modules/laoqianjunzi-step/pages/index

演示页覆盖以下能力：

• 设备支持检测
• 实时监听与停止监听
• 今日步数查询
• 最近 7 天步数查询
• 错误信息展示
• 微信小程序汇总载荷获取

如果你需要验证插件的完整交互流程，建议直接运行该页面。

使用建议

• 在页面 onUnmounted 或离开页面时调用 haltLiveStride()。
• 区间查询使用毫秒时间戳，避免混入秒级时间戳。
• Web 端仅用于联调，不应视为真实计步结果。
• 微信小程序场景中，requestSummaryStepPayload() 与服务端解密流程应配套使用。

说明

本插件所有步数数据均在本地传感器、系统运动能力或业务侧传入的数据范围内处理，不会主动向远端服务发送任何运动数据。