Flutter 适配 wearable_rotary 鸿蒙穿戴旋转表冠:圆屏长列表单手平滑浏览
📦 Flutter 三方库 wearable_rotary 用于接收手表旋转事件并驱动列表滚动。我在鸿蒙圆屏模拟器上做运动分段浏览示例时,发现上游包缺少鸿蒙实现,于是接入 ArkUI
onDigitalCrown,补齐焦点容器、角度换算和整数幅度解析。
完整代码已开源在 oh-flutter/plugins(packages/wearable_rotary,上游包 wearable_rotary),欢迎提交 Issue 或前往 鸿蒙系统Flutter开源库社区 交流。
前言
我用 Flutter 做了一个圆屏运动分段浏览示例:列表里放入 12 条固定演示数据,转动表冠找条目,点按屏幕做标记。把页面装到 Watch 4 Pro 模拟器后,触屏可以滑动,但直接使用 wearable_rotary 2.0.4 时,模拟器表冠在转,列表却停在原地。
我检查了包的平台注册和日志,发现上游只实现了 Android 与 Tizen,鸿蒙的旋转事件还没有接进来。于是,我补上原生桥接,把接收事件的容器放到 Flutter 页面的父级,并处理通道传来的整数幅度。同一页面随后可以随表冠双向滚动,点按分段做标记后也能继续浏览。这些操作都在模拟器上完成。
图 1 上半部分是同一只模拟器手表操作前后的画面,下半部分画出了表冠事件怎样到达列表。

图1 表冠浏览
一、圆屏长列表单手浏览痛点与社区选型
1.1 在圆屏上浏览并标记分段
页面里有分段名称、示例配速和心率,点击一行可以切换「已标✓」状态。我把数据固定在 Example 中,方便核对滚动方向、当前位置和标记是否保留;它们不是实际训练记录,页面也没有接入运动传感器。Watch 4 Pro 模拟器的圆屏分辨率为 466 × 466 物理像素,像素密度比为 2.0,对应 233 × 233 逻辑像素。
扣除顶部状态和底部偏移提示,初始画面能完整显示三张卡片。想找后面的条目,就得移动列表。我希望用表冠浏览、用触屏选择,让两种操作各做一件事。页面继续使用 Flutter 列表和原来的点击处理,插件负责把表冠输入接进来。
我先在同一页面上试了原版:
- 依赖未改动的 wearable_rotary 2.0.4,启动应用并订阅旋转事件。
- 向下滚动模拟器的虚拟表冠,系统产生输入事件,但 Flutter 列表偏移仍为 0 px。
- 改用触屏拖动,列表能够移动;日志同时记录了旋转事件通道未实现的异常。
触屏拖动正常,说明列表本身能滚动,接下来要查的是表冠输入。上游没有承诺支持 HarmonyOS,所以我把这项工作作为平台扩展。减少手指遮挡是选择表冠交互的理由,不过真人佩戴时的误触率、手汗和手套操作效果,这个模拟器示例都没有测。
1.2 系统能力、跨端插件与业务职责分层
我先确认系统已经提供什么,再看 Flutter 这一侧缺在哪里。
HarmonyOS 从 API 18 起提供 .onDigitalCrown 和 CrownEvent,应用可以取得时间戳、角速度、相对旋转角度及动作阶段,不必处理表冠传感器的内部细节。
我检查了所用版本的 @ohos/flutter_ohos:FlutterPage 内部有用于渲染的 XComponent 和辅助焦点节点,但没有注册表冠回调,也没有把这些事件转成 Flutter 滚动事件或通道消息。因此,插件要做的是接收原生输入,将它转换成“方向加幅度”的旋转事件,再交给列表控制器。
页面仍负责卡片布局、当前分段高亮和勾选状态。圆屏首尾需要留多少空白、哪些记录应该标记,都由 Example 决定。把这部分留在业务页面里,其他应用才可以复用表冠输入,而不必沿用我的运动分段界面。
1.3 社区仓库核查与基线包选型
我检查了 pub.dev 上的相关包,以及 AtomGit 上 oh-Flutter、CPF-Flutter 两个组织的公开仓库,想先找一个能接着改的实现。

图2 上游包页面
图 2 是 wearable_rotary 2.0.4 的发布页。包由 tizen.org 发布,源码在 flutter-tizen/plugins,采用 BSD-3-Clause 许可。页面的平台标签是 Android,仓库里同时保留了 Android 与 Tizen 的穿戴实现。
发布页提示该包已停止更新。我仍选择它,是因为它已经提供了旋转广播流 rotaryEvents 和 RotaryScrollController,纯 Dart 弧形滚动条组件 rotary_scrollbar 也依赖这套接口。补齐底层平台实现后,使用这些接口的页面就可以继续沿用原来的调用方式。表 1 列出了我检查的范围:
| 检索范围 | 候选包或仓库数量 | 核对版本 | 能力覆盖与缺口结论 |
|---|---|---|---|
| oh-Flutter 组织 | 全量遍历 399 仓 | 公开仓库默认分支 | 仅命中 clipboard_watcher 等 3 个无关仓,无表冠旋转插件 |
| CPF-Flutter 组织 | 全量遍历 394 仓 | 公开仓库默认分支 | 无表冠旋转适配仓;已有 wear_plus 仅覆盖圆方屏形状识别 |
| pub.dev 上游主包 | wearable_rotary | 2.0.4 | 含 rotaryEvents 与 RotaryScrollController,仅支持 Android 与 Tizen |
| pub.dev 关联组件 | rotary_scrollbar | 1.1.0 | 纯 Dart 弧形滚动条组件,底层直接依赖 wearable_rotary 获取事件 |
表1 社区仓核查
我接着看了 wearable_rotary 2.0.4 的源码:原生输入通过名为 flutter.wearable_rotary.channel 的事件通道送到 Dart。现有接口已经能表达方向和幅度,缺的是鸿蒙端的事件来源。于是,我以 2.0.4 为基线新增 ohos 目录和焦点容器,保留公开 Dart API,并沿用 BSD-3-Clause 许可。
二、Watch 4 Pro 实测效果与日志对照
2.1 验证环境与同页面对照方案
我让两个工程使用同一份圆屏页面,便于直接比较表冠操作的结果。对照组 com.example.pgc27base 依赖上游 wearable_rotary 2.0.4,宿主 Index.ets 保留默认的 Column 和 FlutterPage。适配组 com.example.pgc27rotary 换成本地修改的插件,并用 WearableRotaryHost 包住 Flutter 页面。
两组使用表 2 中的工具链和同一个模拟器模板:
| 环境维度 | 实际采用版本与参数 |
|---|---|
| Flutter 框架版本 | 3.41.9+ohos-1.0.2(Dart 3.11.5) |
| 开发工具与鸿蒙 SDK | DevEco Studio 26.0.0;SDK/API 26,最低兼容版本 5.1.0(18) |
| 穿戴模拟器与系统 | 本地 Watch 4 Pro 圆形屏模拟器(466 × 466,像素密度 2.0,HarmonyOS 7.0.0.105) |
| 对照包与适配包 | 原版基线 com.example.pgc27base / 鸿蒙适配版 com.example.pgc27rotary |
表2 实测环境配置
图 3—8 对应第五章公开固定提交中的鸿蒙桥接实现,第 4.5 节的控制器重挂载修正也已一并包含在该提交并完成 Dart 回归测试校验。
2.2 旋转表冠与触屏交互前后实录对比
我先从表盘启动原版对照组(图 3)。应用订阅事件时收到 MissingPluginException,顶部提示变成琥珀色的「表冠未接入 · 仅触屏」。拨动模拟器右上侧的虚拟表冠,旋钮纹理会转,列表偏移却一直是 0 px。改用触屏,在表盘中央向上滑动两次后,第 05 段「缓坡恢复」才进入视野。

图3 适配前仅触屏
换上鸿蒙适配版后,我仍在这个页面操作(图 4):
- 顺时针拨动虚拟表冠 4 步,收到 8 个有效角度事件,每个事件推进 18.0 px,列表到达 144 px 🟢↑,第 04 段高亮。
- 点按第 05 段「缓坡恢复」做标记,再顺时针拨动 3 步。列表继续到达 252 px,第 07 段高亮,标记保留。
- 逆时针回拨 4 步,列表回到 108 px 🔴↓,第 03—05 段重新进入视野,第 05 段仍显示「已标✓」。
表冠可以向两个方向滚动列表,点按卡片也没有中断后续旋转。这里要留意顶部的「表冠就绪」:示例发起订阅后就会显示它,是否真的收到了原生输入,要看脉冲计数和 HiLog。

图4 适配后转表冠
我还保留了两张静态画面,方便看清卡片和状态提示。图 5 是冷启动后的页面,WearableRotaryHost 已获焦,第 01 段「热身慢跑 05’42"」带有高亮描边:

图5 穿戴初始就绪
图 6 是顺时针浏览并点按标记后的状态。顶部显示「顺时针 ↓ · 第 07/12 段」和「脉冲 14 · 幅度 18.0 px」,底部偏移为 252 px,并保留已标条目数。表冠负责移动列表,触屏负责选中需要标记的记录:

图6 表冠滚动高亮
2.3 工程关键配置与跨端 HiLog 证据核验
接入时,我检查了图 7 中的四处配置:
- 在插件 pubspec.yaml 中为 ohos 平台注册
WearableRotaryPlugin。 - 在插件 module.json5 的
deviceTypes中加入 wearable。 - 在应用 build-profile.json5 中把
compatibleSdkVersion设为支持表冠事件的 5.1.0(18)。 - 在宿主 Index.ets 中用
WearableRotaryHost包裹FlutterPage,让表冠回调处于页面的焦点祖先链上。

图7 工程关键配置
页面能动以后,我又对照了两组 HiLog,检查系统事件是否经过插件到达 Dart(图 8):

图8 跨端实测日志
对照组启动时报告通道未实现,拨动表冠却仍有 CrownTransformProcessor 的 Virtual Crown 记录。结合宿主和插件源码,可以判断系统已产生输入,但这条输入还没有连接到 Dart 列表。
适配组能看到完整的一次旋转:起始帧 action=0 的角度为 -3.00 度、角速度为 0.00 度每秒;持续帧 action=1 的角度仍为 -3.00 度,角速度为 -120.50 度每秒;停下后出现 action=2,角度和角速度都回到 0.00。
插件把前两帧换算成顺时针、幅度 18.00 的消息发给 Dart,结束时的零角度帧则被过滤。这样,列表只处理有位移的输入。
点按第 5 段标记后约 1.28 秒,我再次顺时针拨动,日志中仍有派发记录。随后逆时针回拨,+3.00 度被映射为 counterClockwise。这段操作里,点按卡片没有导致表冠事件中断。
三、数字表冠事件链路与插件核心实现
3.1 HarmonyOS 数字表冠 API 与三阶段状态机
我检查了 HarmonyOS SDK(API 18—26)的声明。表冠回调挂在 ArkUI 组件上,接收事件的前提与焦点有关:
- 组件通过
onDigitalCrown(event: Optional<Callback<CrownEvent>>)监听事件。它自己获焦时可以接收;焦点在后代节点时,事件也可以沿祖先链向上冒泡,但中途不能被stopPropagation()拦住。 CrownEvent包含纳秒级单调递增时间戳timestamp、角速度angularVelocity(度每秒)、相对上一帧的角度增量degree(度)和动作阶段action。阶段值为BEGIN = 0、UPDATE = 1、END = 2、UNKNOWN = 3;stopPropagation()用于停止冒泡。
Watch 4 Pro 模拟器上采到的角度、角速度与处理方式见表 3:
| 物理操作与阶段 | 动作枚举值 | 实测角度增量 | 实测角速度范围 | 插件桥接处理策略 |
|---|---|---|---|---|
| 顺时针起转帧 | BEGIN (0) | -3.00° | 0.00 °/s | 映射 clockwise,计算像素幅度并派发 |
| 顺时针持续帧 | UPDATE (1) | -3.00° | -89.03 ~ -147.07 °/s | 映射 clockwise,计算像素幅度并派发 |
| 逆时针持续帧 | UPDATE (1) | +3.00° | +83.69 ~ +128.74 °/s | 映射 counterClockwise,派发正数幅度 |
| 旋转停止收尾帧 | END (2) | 0.00° | 0.00 °/s | 消费事件并拦截丢弃,不向 Dart 发空帧 |
表3 表冠阶段语义
方向映射最容易弄反。在这组输入中,从表盘正面看,向下拨动右侧表冠是顺时针旋转,角度增量为负,例如 -3.00 度。页面内容应向上移动,也就是列表偏移增加。向上回拨时角度为正,例如 +3.00 度,列表偏移应减小。
上游控制器收到 clockwise 就增加偏移,收到 counterClockwise 就减小偏移。我据此把 degree < 0 映射成顺时针,把 degree > 0 映射成逆时针。表冠角度的正负不能直接当作列表偏移的正负使用。
这条调用链的先后关系见图 9:

图9 表冠跨端时序
3.2 为什么必须用焦点父容器包裹 FlutterPage
我检查了上游的 Android 实现。宿主 MainActivity 要重写 onGenericMotionEvent,再把输入转发给插件静态方法;只注册 FlutterPlugin,插件还拿不到旋转事件。鸿蒙端也需要宿主接入,只是这里要处理的是 ArkUI 焦点。
在所用的 HarmonyOS 接口中,UIAbility 没有供这里使用的全局表冠回调,事件沿 ArkUI 焦点树传递。如果在 Index.ets 中放一个与 FlutterPage 平级的透明组件,即使把它设为可获焦,也要先确认焦点是否真的落在它上面。
我看了 FlutterPage.ets:根节点是一个声明了默认焦点的 Stack,内部的 XComponent 可以获焦,但关闭了触摸获焦;另有一个同样可以获焦的空文本节点。页面挂载后,焦点会进入这棵子树。旁边的透明组件不在它的祖先链上,便收不到沿这条路径传递的表冠事件。即使手动把焦点移过去,后续触摸也可能改变焦点归属。
我把监听组件改放到 Flutter 页面的外层。这样,叶子节点没有注册表冠处理器时,事件可以向上传到这个可获焦的父容器,不必靠兄弟节点抢焦点。
插件里的 WearableRotaryHost 用 @BuilderParam 接收 Flutter 页面,并开启 .focusable(true)、.defaultFocus(true) 和 .focusOnTouch(true)。下面是 ohos/src/main/ets/components/plugin/WearableRotaryHost.ets 的完整实现:
import hilog from '@ohos.hilog';
import WearableRotaryPlugin from './WearableRotaryPlugin';
const DOMAIN = 0x0000;
const TAG = 'WearableRotaryOhos';
@Component
export struct WearableRotaryHost {
@Builder
private emptyContent(): void {}
// 承接宿主传入的 FlutterPage 子树,使当前 Stack 成为其焦点祖先节点
@BuilderParam content: () => void = this.emptyContent;
@Prop hostFocusId: string = 'wearable_rotary_focus_host';
build() {
Stack() {
this.content()
}
.id(this.hostFocusId)
.width('100%')
.height('100%')
.focusable(true)
.defaultFocus(true)
.focusOnTouch(true)
.onFocus(() => {
hilog.info(DOMAIN, TAG, 'host focus acquired id=%{public}s', this.hostFocusId);
})
.onBlur(() => {
hilog.info(DOMAIN, TAG, 'host focus blurred id=%{public}s', this.hostFocusId);
})
.onDigitalCrown((event: CrownEvent) => {
WearableRotaryPlugin.onDigitalCrown(event);
})
}
}
3.3 原生插件 WearableRotaryPlugin 与通道生命周期实现
父容器收到事件后,WearableRotaryPlugin.ets 负责把消息送到 Dart。这个类实现了 FlutterPlugin 和 StreamHandler,管理名为 flutter.wearable_rotary.channel 的事件通道。插件入口 ohos/index.ets 同时导出两个对象:默认导出的插件类供自动注册器使用,命名导出的 WearableRotaryHost 供宿主页面使用。
类里的静态字段 activeSink 保存当前输出端,degreeScale 决定每度角度换算成多少逻辑像素,默认值为 6.0,可通过 setDegreeScale 调整。messenger 和 instanceSink 则属于当前引擎实例。
引擎连接时,onAttachedToEngine 注册流处理器。下面摘出事件换算、取消订阅和引擎分离几个完整方法;这些字段和注册入口保留在仓库的完整文件中:
static onDigitalCrown(event: CrownEvent | null | undefined): boolean {
if (!event) {
return false;
}
const rawDegree: number = event.degree;
const rawVelocity: number = event.angularVelocity;
const actionCode: number = event.action;
const timestampNs: number = event.timestamp;
const sink: EventSink | null = WearableRotaryPlugin.activeSink;
hilog.info(
DOMAIN,
TAG,
'crownEvent action=%{public}d degree=%{public}s velocity=%{public}s ts=%{public}s hasSink=%{public}s',
actionCode,
rawDegree.toFixed(2),
rawVelocity.toFixed(2),
String(timestampNs),
sink !== null ? 'true' : 'false'
);
// 旋转收尾帧 CrownAction.END 的 degree 为 0,阻断冒泡并拦截空帧,避免列表空转通知
if (!Number.isFinite(rawDegree) || Math.abs(rawDegree) === 0) {
event.stopPropagation();
return true;
}
if (!sink) {
return false;
}
const direction: string = rawDegree < 0 ? 'clockwise' : 'counterClockwise';
const magnitude: number = Math.abs(rawDegree) * WearableRotaryPlugin.degreeScale;
const payload: Map<string, Object> = new Map<string, Object>();
payload.set('direction', direction);
payload.set('magnitude', magnitude);
sink.success(payload);
event.stopPropagation();
hilog.info(
DOMAIN,
TAG,
'dispatch direction=%{public}s magnitude=%{public}s (degree=%{public}s, scale=%{public}s)',
direction,
magnitude.toFixed(2),
rawDegree.toFixed(2),
WearableRotaryPlugin.degreeScale.toFixed(2)
);
return true;
}
onDetachedFromEngine(_binding: FlutterPluginBinding): void {
// 仅当静态活跃槽位仍指向当前实例时才置空,防止旧引擎销毁误清新建引擎的订阅
if (WearableRotaryPlugin.activeSink === this.instanceSink) {
WearableRotaryPlugin.activeSink = null;
}
this.instanceSink = null;
this.messenger?.setMessageHandler(CHANNEL_NAME, null);
this.channel = null;
this.messenger = null;
}
onListen(_args: Any, events: EventSink): void {
this.instanceSink = events;
WearableRotaryPlugin.activeSink = events;
}
onCancel(_args: Any): void {
if (WearableRotaryPlugin.activeSink === this.instanceSink) {
WearableRotaryPlugin.activeSink = null;
}
this.instanceSink = null;
}
这组 Watch 4 Pro 输入中,单个有效事件的角度绝对值为 3.0 度。若直接把度数当作逻辑像素,一个事件只移动 3 px;乘以默认比例系数 6.0 后,一个事件移动 18 px。这个系数用于调整浏览速度,列表行高仍由页面决定,两者没有自动对齐关系。
3.4 Dart 侧通道解析与整数幅度编解码兼容
Dart 层的公开导出、事件模型、方向枚举和控制器构造参数都沿用原来接口。我调整的是 lib/src/wearable_rotary_base.dart 中的私有解析函数,让整数和小数幅度都能被接收:
RotaryEvent _parseEvent(dynamic event) {
if (event is Map) {
final Object? rawDirection = event['direction'];
final Object? rawMagnitude = event['magnitude'];
// 鸿蒙 StandardMessageCodec 会将无小数的 number 按 INT32 编码,需按 num 接收后转 double
if (rawDirection is! String || rawMagnitude is! num) {
throw PlatformException(
code: 'type_cast',
details: 'Platform plugin returns invalid map fields for rotary event',
);
}
return RotaryEvent(
direction: RotaryDirection.values.byName(rawDirection),
magnitude: rawMagnitude.toDouble(),
);
} else if (event is bool) {
// 保留上游对早期 Tizen 仅上报布尔方向载荷的向后兼容
return event
? const RotaryEvent(direction: RotaryDirection.clockwise)
: const RotaryEvent(direction: RotaryDirection.counterClockwise);
} else {
throw PlatformException(
code: 'type_cast',
details: 'Platform plugin returns invalid type for rotary event',
);
}
}
解析时先检查 num,再调用 toDouble(),替换了原来的 as double。原因在于鸿蒙消息编码器会根据数值选择整数或浮点编码。
四、穿戴跨端接入踩坑与异常边界
适配时遇到的几处问题,我整理在表 4 中。数值解析、通道解绑和异常回调看起来都发生在插件里,实际要检查的代码位置不同。
| 问题现象 | 触发根因定位 | 实际修复方案 |
|---|---|---|
首帧旋转抛 TypeError: int is not a subtype of double | ArkTS 无独立浮点类型,StandardMessageCodec 对整数值按 INT32 编码 | Dart 侧按 num 接收并调用 .toDouble() 统一转换 |
onDetachedFromEngine 传 null 编译报错 | 引擎包的 EventChannel.setStreamHandler 参数未声明可空联合类型 | 持有 BinaryMessenger 引用,调用 setMessageHandler(name, null) 解绑 |
| 调试记录中的浮点日志显示异常 | 尚不足以归因为 HiLog 不支持浮点格式 | 固定保留两位小数,再通过 %{public}s 输出 |
广播流的 onError 捕不到通道未注册异常 | Flutter 将 listen 握手异常交由 FlutterError.reportError 处理 | 诊断页面通过 FlutterError.onError 识别激活期的 MissingPluginException |
表4 踩坑排查对照
4.1 StandardMessageCodec 的 ArkTS 整数分流陷阱
我看了 Android 端的 Kotlin 实现,它用浮点数计算幅度,再交给消息通道,与原来的 Dart 解析写法相符。这里核对的是源码,Android 设备没有重新跑过。
ArkTS 使用 number 表示数值。我接着检查了 @ohos/flutter_ohos 中的 StandardMessageCodec.ets:编码器先用 Number.isInteger(value) 判断数值是不是整数;如果是,而且落在 32 位有符号整数范围内,就写入 INT32 标记。
🐛 模拟器的这组输入刚好走到了这个分支。顺时针事件上报 -3 度,乘以比例 6.0 后,幅度是 18。虽然代码里的系数写作 6.0,Number.isInteger(18) 仍然返回真。消息到达 Dart 后,字典里的幅度就是 int,原来的 as double 会在首帧抛出类型错误。
我改成按 num 接收,再转为 double,并补了整数幅度用例。浮点幅度继续走同一套解析,旧 Tizen 只传布尔方向的分支也保留了下来。
4.2 EventChannel 解绑签名缺失与 HiLog 浮点占位符问题
清理插件时,我还碰到了一个编译问题。在引擎分离回调里调用 channel.setStreamHandler(null),会被严格空检查拦住。
我检查了 @ohos/flutter_ohos 的 EventChannel.ets,方法签名是 setStreamHandler(handler: StreamHandler): void,参数没有声明 | null,函数体里却有判空分支。于是,我在绑定引擎时保存 binding.getBinaryMessenger(),分离时直接调用 this.messenger?.setMessageHandler(CHANNEL_NAME, null) 移除处理器。这样保留了注销操作,也不用通过类型强转绕过编译检查。
调试记录还提到,浮点日志曾出现 }f 和字段错位。我查了华为官方的数字表冠示例,其中直接使用 %{public}f 输出角速度与角度。现有记录不足以确定那次异常的原因,所以“HiLog 不支持浮点占位符”这个判断并不成立。
插件最后采用的写法是:先用 .toFixed(2) 保留两位小数,再通过 %{public}s 打印,方便我逐条对照事件。发给 Dart 的幅度仍是数值,日志格式不会改变滚动计算。如果遇到类似输出异常,需要一起核对格式串、参数类型、运行版本和原始日志。
4.3 EventChannel 握手异常路由机制
⚠️ 对照组明明缺少鸿蒙插件,流的 onError 却没有收到通道未注册异常。我在给页面写「仅触屏」提示时,发现了这两条错误路径的区别。
Flutter SDK 的 EventChannel.receiveBroadcastStream 会在首个订阅者加入时调用原生 listen。这一步如果抛出 MissingPluginException,框架交给 FlutterError.reportError 处理,不会把异常放进返回的事件流。
所以,示例在全局错误处理器里匹配通道名和异常类型,用它切换「仅触屏」提示。其他错误继续交给原处理器,页面销毁时也会恢复原处理器。
通道运行期间收到的原生错误信封,以及 Dart 解析事件时抛出的异常,仍可能进入流的 onError,需要保留这一路处理。检查接入结果时,我会实际转动一次表冠并核对事件,而不只看订阅调用有没有报错。
4.4 模拟器虚拟表冠触发机制与 UiTest 能力边界
录制对照画面时,我需要让模拟器产生表冠事件。
HarmonyOS SDK 的 UiTest 有 Driver.crownRotate,但这个 Watch 4 Pro 镜像调用后返回 801,表示能力不支持。我实际使用的是模拟器前台窗口的鼠标滚轮:系统日志把来源记为 Virtual Crown,接着就能看到起始、持续和结束回调。
这些记录说明该镜像的系统事件能够传到 Flutter。物理表冠的触感、采样频率和佩戴体验,需要在实物设备上另行检查。
4.5 列表重新挂载时恢复订阅
复核控制器时,我发现同一个对象第一次挂到列表上可以滚动,移除列表再挂回来,旋转就没反应了。这个逻辑沿用自上游:detach() 取消了订阅,却没有清空保存订阅的字段。再次挂载时,??= 看到字段非空,便跳过了创建监听。
这时继续调整 ArkUI 焦点也无济于事,控制器已经取消了对 Dart 事件流的监听。我在解绑函数里增加了清空字段的操作,让下次挂载能够创建新订阅:
void detach(ScrollPosition position) {
_subscription?.cancel();
// 下次挂载需要新订阅,已取消的对象不能再次使用。
_subscription = null;
super.detach(position);
}
我用同一个控制器连续挂载三次,每次发出幅度为 30 的旋转事件,检查列表偏移是否增加;移除列表后再发事件,检查是否访问了已解绑的位置。修复前,第二次挂载时列表不动;清空订阅后,三次都通过了。这个用例检查的是 Dart 生命周期,不包含原生弹窗焦点或多引擎路由。
五、结论与可直接复用的建议
5.1 这次适配解决了什么
对这个圆屏页面来说,接入后最直接的变化是可以转表冠浏览,点按标记后也能继续转动。页面仍使用原来的 Dart 接口。插件增加的鸿蒙实现负责接收焦点链上的表冠事件、换算方向和幅度,并过滤零角度帧;Dart 解析函数则补上整数幅度的处理。社区仓库主页见 oh-flutter/plugins(包位于 packages/wearable_rotary 目录)。

图10 社区适配仓库
5.2 在自己的项目中使用
💡 社区仓库的 ohos/plugins 分支合入并发版前,可以在应用的 pubspec.yaml 中通过子目录参数引用公开适配分支 abaoge/plugins(feat/ohos_wearable_rotary_2.0.4)对应的固定提交,其中包含表冠焦点桥接、整数幅度解析、第 4.5 节的控制器重挂载订阅恢复与开源合规说明;合入后即可将 url 和 ref 切换为社区仓库的 ohos/plugins 分支(保留 path: packages/wearable_rotary)。上游同版本号的发布包没有这部分实现。
dependencies:
wearable_rotary:
git:
url: https://atomgit.com/abaoge/plugins.git
ref: c4c4e9f2b12f83bb96604a607821d4043ee99a1a
path: packages/wearable_rotary
宿主接入分三步:
- 打开 ohos/build-profile.json5,确认
compatibleSdkVersion不低于"5.1.0(18)"。 - 在 ohos/entry/src/main/module.json5 的
deviceTypes中加入"wearable"。 - 在 ohos/entry/src/main/ets/pages/Index.ets 中导入
WearableRotaryHost,用它包裹FlutterPage,写法如下。
首次引入这个原生组件后,需要完整重新构建应用,热重载不足以完成原生接入。
import common from '@ohos.app.ability.common';
import { FlutterPage } from '@ohos/flutter_ohos';
import { WearableRotaryHost } from 'wearable_rotary';
let storage = LocalStorage.getShared();
const EVENT_BACK_PRESS = 'EVENT_BACK_PRESS';
@Entry(storage)
@Component
struct Index {
private context = getContext(this) as common.UIAbilityContext;
@LocalStorageLink('viewId') viewId: string = "";
build() {
Column() {
WearableRotaryHost() {
FlutterPage({ viewId: this.viewId })
}
}
.width('100%')
.height('100%')
}
onBackPress(): boolean {
this.context.eventHub.emit(EVENT_BACK_PRESS);
return true;
}
}
业务页面导入 package:wearable_rotary/wearable_rotary.dart,再把 RotaryScrollController 交给 ListView.builder。如果还想显示旋转方向,可以同时订阅事件流。下面几个方法放在页面的 State 中,成员包括 _scrollController、可空订阅 _sub 和方向 _dir;订阅和控制器都随页面销毁而释放。
void initState() {
super.initState();
_scrollController = RotaryScrollController(maxIncrement: 48.0);
_sub = rotaryEvents.listen((RotaryEvent event) {
if (!mounted) return;
setState(() => _dir = event.direction);
});
}
void dispose() {
_sub?.cancel();
_scrollController.dispose();
super.dispose();
}
Widget _buildWatchList(List<String> items) {
return ListView.builder(
controller: _scrollController,
itemExtent: 44.0,
// 圆形表盘底部弦长收窄,预留充足底部内边距把末位卡片托举到表盘中央
padding: const EdgeInsets.fromLTRB(24.0, 12.0, 24.0, 84.0),
itemCount: items.length,
itemBuilder: (context, index) => Align(
alignment: Alignment.centerLeft,
child: Text(items[index]),
),
);
}
5.3 使用时保留这几个判断
- 调整浏览速度时,先区分角度比例和单次增量上限。原生比例决定每度对应多少逻辑像素,
maxIncrement限制一个事件最多移动多少。默认比例 6.0 下,3 度对应 18 px,两个事件合计 36 px,并不等于示例的 44 px 行高。控制器用jumpTo()更新位置,没有插值动画或整行吸附。行高、步长和底部留白要各自调整。 - 这份实现按单引擎、单个活动列表使用。原生只保存一个当前输出端,后来的引擎订阅会替换前一个;Dart 广播流也不会替业务判断哪个页面正在显示。多个列表同时监听时,要由业务管理活动页面。我没有测试原生弹窗移出焦点子树后的恢复,使用这类弹窗时需要检查关闭后的焦点位置。
- 运行结果来自 Watch 4 Pro 模拟器的 HarmonyOS 7.0.0.105 / API 26。Android 和 Tizen 的源码保留了下来,但没有做对应设备的运行回归。插件也没有加入物理手表的马达刻度震感;需要震动反馈时,可按业务需求另接
@ohos.vibrator。
中文适配说明整理了接口支持范围与宿主接入条件;完整 Example保留了这套圆屏布局和标记交互,构建与运行说明记录了工具链与对照构建步骤。接到自己的页面时,可以只复用插件和列表控制器。
小结
表冠接通以后,这个圆屏页面能按预想的方式浏览和标记条目了。我在排查中把“列表不动”拆开检查:系统有没有产生事件,宿主能不能收到,控制器是否还在监听。焦点和订阅出了问题,画面看起来一样,改动的位置却完全不同。以后再遇到这类输入问题,我会先顺着事件查到列表,再决定改哪一层。
参考资料
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)