前言

快递互动卡片用到了陀螺仪。小白如果只写页面代码，不配权限，很容易遇到“代码看起来没问题，但传感器就是没数据”的情况。

这篇专门讲权限怎么配、配在哪里、为什么要这么配。

效果图

快递卡片的亮点是传感器驱动的互动反馈。效果能动起来之前，权限和传感器链路必须先配对。

先看项目文件

权限在：

entry/src/main/module.json5

快递 LiveForm 页面在：

entry/src/main/ets/livecardability/pages/DeliveryLiveCard.ets

传感器封装在：

entry/src/main/ets/utils/GyroscopeUtil.ets

module.json5 里的权限声明

项目里有：

{
  "name": "ohos.permission.GYROSCOPE",
  "reason": "$string:gyroscope_permission_reason",
  "usedScene": {
    "abilities": [
      "DeliveryLiveCardAbility"
    ],
    "when": "always"
  }
}

逐个看。

name 是权限名：

"ohos.permission.GYROSCOPE"

这表示使用陀螺仪。

reason 是权限说明：

"$string:gyroscope_permission_reason"

它对应字符串资源，告诉用户为什么需要这个权限。

usedScene.abilities 写的是：

"DeliveryLiveCardAbility"

表示这个权限主要给快递 LiveForm Ability 使用。

为什么不是写 EntryAbility

谁使用权限，就尽量绑定谁。

快递传感器逻辑在 DeliveryLiveCard 里跑，而这个页面由 DeliveryLiveCardAbility 加载，所以权限绑定 DeliveryLiveCardAbility 更清楚。

如果你全都挂到主 EntryAbility，短期也许能跑，但项目可读性会变差。别人看配置时不知道到底哪个功能用了陀螺仪。

reason 字符串要补

reason 指向字符串资源，比如：

{
  "name": "gyroscope_permission_reason",
  "value": "用于快递互动卡片感知设备倾斜方向"
}

这类文案要写得具体，不要写“用于功能使用”这种废话。

用户看到权限弹窗时，应该知道为什么要开。

DeliveryLiveCard 为什么需要它

DeliveryLiveCard.ets 里订阅陀螺仪：

subscribeGyroscope() {
  GyroscopeUtil.subscribe((data: GyroscopeData) => {
    this.gyroTranslateX = Math.max(-this.maxGyroValue, Math.min(this.maxGyroValue, data.y));
    this.gyroTranslateY = Math.max(-this.maxGyroValue, Math.min(this.maxGyroValue, data.x));
    this.gyroTranslateZ = Math.max(-this.maxGyroValue, Math.min(this.maxGyroValue, data.z));
    this.gyroMethod();
  });
}

没有权限或传感器不可用时，这段回调就可能没有数据。

metadata 也要注意

form_config.json 里的快递卡片还有：

"metadata": [
  {
    "name": "isSupportShake",
    "value": "true"
  }
]

这表示快递卡片支持摇动类交互。

权限是系统能力声明，metadata 是卡片能力描述。两个不是一回事。

小白新增传感器卡片怎么做

如果你新增一个“摇一摇抽奖卡片”，大概需要：

1. 在 module.json5 加对应权限。
2. usedScene.abilities 写你的 LiveForm Ability。
3. 在字符串资源里补权限原因。
4. 在 form_config.json 里给卡片加必要 metadata。
5. 页面里订阅传感器，并在销毁时取消订阅。

排查清单

传感器没反应时，按这个顺序查：

1. module.json5 是否声明 ohos.permission.GYROSCOPE。
2. usedScene.abilities 是否写对 LiveForm Ability 名称。
3. 权限原因字符串是否存在。
4. 真机是否支持对应传感器。
5. GyroscopeUtil.subscribe() 是否执行。
6. LiveForm 关闭时是否调用 unsubscribe()。

写在最后

快递卡片的陀螺仪权限不是可有可无。传感器类互动卡片，第一步就是把权限和使用场景配清楚。

小白记住：先配权限，再写传感器动画。