@capacitor/motion

本项目基于 @capacitor/[email protected] 开发。

简介

Motion API 提供了追踪加速度计和设备方向（指南针方位等）的能力。本插件是 capacitor 生态系统中的核心插件，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境中使用，本文档仅说明在 OpenHarmony 系统中的使用情况。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/motion

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/motion

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/motion",
  "classpath": "Motion"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 capacitor 模块，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

add_subdirectory(Motion)

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive" // 放在这个中间
  // ...
  Motion
  // ...
  "-Wl,--no-whole-archive"
);

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并复制到对应的目录：

将源码中 src/main/cpp/Motion 目录下的 Motion.h、Motion.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/Motion 目录下。

将源码中 src/main/ets/components/Motion 目录下的 Motion.ets 文件引入到 capacitor 模块中 src/main/ets/components/Motion 目录下。

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入拷贝的 ets 文件路径：

"buildOption": {
  // ...
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/Motion/Motion.ets"
        // ...
      ]
    }
  }
}

卸载

# 卸载 motion 插件
hionic plugin remove @capacitor/motion

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony 需要申请传感器权限，在主工程的 module.json5 的 requestPermissions 添加 ohos.permission.ACCELEROMETER 和 ohos.permission.GYROSCOPE 权限，示例如下：

{
  "name": "ohos.permission.ACCELEROMETER"
},
{
  "name": "ohos.permission.GYROSCOPE"
}

更多权限说明参考：申请应用权限。

使用示例

基础示例：监听加速度计数据

import { Motion } from '@capacitor/motion';

await Motion.addListener('accel', (event) => {
  // 构建详细的消息，包含所有相关属性
  let message = `[实时数据] `;
  // 添加加速度数据（不包括重力）
  message += `加速度: x=${event.acceleration.x.toFixed(3)}, y=${event.acceleration.y.toFixed(3)}, z=${event.acceleration.z.toFixed(3)} | `;
  // 添加重力加速度数据
  message += `重力加速度: x=${event.accelerationIncludingGravity.x.toFixed(3)}, y=${event.accelerationIncludingGravity.y.toFixed(3)}, z=${event.accelerationIncludingGravity.z.toFixed(3)} | `;
  // 添加旋转速率数据
  message += `旋转速率: alpha=${event.rotationRate.alpha?.toFixed(3) || 0}, beta=${event.rotationRate.beta?.toFixed(3) || 0}, gamma=${event.rotationRate.gamma?.toFixed(3) || 0}`;
  console.log(message);
});

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ------------------------------------------------------------ | ------------------------- | ------------------------------------ | | addListener(eventName: 'accel', listenerFunc: AccelListener | Promise<PluginListenerHandle> | 添加一个监听器以获取加速度计数据 | | addListener(eventName: 'orientation', listenerFunc: OrientationListener | Promise<PluginListenerHandle> | 添加监听器以监听设备方向（指南针航向等） | | removeAllListeners() | Promise | 移除所有绑定到该插件的监听器。 |

数据结构

PluginListenerHandle

| 属性名 | 类型 | | ----------- | --------------------- | | remove | () => Promise<void> |

AccelListenerEvent

| 属性名 | 类型 | 描述 | | ------------------------------- | -------------- | ------------------------------------------------------------------ | | acceleration | Acceleration | 物体在三轴 X、Y 和 Z 上的加速度。加速度以 m/s² 表示。 | | accelerationIncludingGravity | Acceleration | 物体在三轴 X、Y 和 Z 上的加速度（包含重力影响）。加速度以 m/s² 表示。 | | rotationRate | RotationRate | 设备在三轴 α、β 和 γ 上的方向变化速率。旋转速率以每秒度数表示。 | | interval | number | 从设备获取数据的时间间隔（以毫秒为单位）。 |

Acceleration

| 属性名 | 类型 | 描述 | | --------- | --------- | ---------------- | | x | number | X 轴上的加速度。 | | y | number | Y 轴上的加速度。 | | z | number | Z 轴上的加速度。 |

RotationRate

| 属性名 | 类型 | 描述 | | --------- | --------- | --------------------------------- | | alpha | number | 绕 Z 轴旋转的量，单位是每秒度数。 | | beta | number | 绕 X 轴旋转的量，单位是每秒度数。 | | gamma | number | 绕 Y 轴旋转的量，单位是每秒度数。 |

类型

AccelListener

(event: AccelListenerEvent): void

OrientationListener

(event: RotationRate): void

OrientationListenerEvent

RotationRate

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- Motion   # 插件核心 C++ 实现
|                             |---- Motion.h
|                             |---- Motion.cpp
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- Motion   # 插件核心 ArkTS 实现
|                                   |---- Motion.ets
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。