Flutter 三方库「flutter_displaymode」的鸿蒙化适配指南
开发工具： 华为云码道
本文配套仓库（预定地址）： oh-flutter/flutter_displaymode
flutter_displaymode 将显示参数查询与首选刷新率请求封装为 Flutter 接口，应用可以读取当前模式、选择期望刷新率并恢复系统自动调度。本文以 flutter_displaymode 0.7.0 为例，介绍源码准备、OHOS 工程配置、ArkTS 实现和 example 真机运行。
插件注册 Android 和 OHOS；保留其他平台目录不代表这些平台已有可用的原生注册实现。配套仓库地址统一规划为 oh-flutter/flutter_displaymode；尚未创建或同步时，先使用本地源码。本文代码参考本地提交 192250f2a0ab00ed584510a31430772e05c22c83；该提交需同步到配套仓库后才能通过远端获取。
截图标注：操作步骤与截图命令真机运行图（从左到右）：显示模式列表／请求最高刷新率／恢复自动模式。采集于 2026-09-09，设备 ALN-AL00 / HUAWEI Mate 60 Pro，系统 OpenHarmony 6.1.1.120（API 24）；使用本地当前源码构建的签名 Release HAP。
Automatic 已选中时，ACTIVE 仍可显示 120 Hz；请求设置不等于系统必然切换到某一物理刷新率。
执行目录：本文 Markdown 所在目录。先用 hdc list targets 获取设备 ID，将下列 <device-id> 替换为实际值。截图使用仓库完整 Demo；snapshot_display 在本机要求 .jpeg 后缀，图片保持原始真机画面。
mkdir -p blog-assets/flutter_displaymode
显示模式列表： 启动 Demo，在 Modes 查看当前候选列表与 ACTIVE 标记。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-modes.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-modes.jpeg ./blog-assets/flutter_displaymode/modes.jpeg
请求最高刷新率： 点击 Highest Hz，等待列表更新，保留首选单选标记和 ACTIVE 标记。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-highest-hz.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-highest-hz.jpeg ./blog-assets/flutter_displaymode/highest-hz.jpeg
恢复自动模式： 点击 Automatic 左侧的单选按钮，确认其被选中后截图；文本区域不一定响应点击。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-automatic.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-automatic.jpeg ./blog-assets/flutter_displaymode/automatic.jpeg
一、插件简介与适配目标
显示模式包含分辨率与刷新率。OHOS 实现通过默认显示屏读取当前尺寸和刷新率，并根据 supportedRefreshRates 构造可选模式；通过 DisplaySync 请求期望帧率范围。
例如，滚动界面可以请求较高刷新率，节能场景可以请求较低刷新率，在功能结束后恢复自动模式。业务仍需查询当前活动模式，而不是把请求值当作硬件实际状态。
所有公开操作通过 MethodChannel 异步返回，没有给 Dart 提供连续模式事件流。原生内部的 frame 回调用于维持 DisplaySync 请求，不是 Flutter 渲染帧率统计。
二、环境准备
环境搭建参考社区文档：Flutter OH 开发环境搭建，完成 Flutter OH SDK 安装、环境变量和 DevEco Studio 配置。
完成后，在宿主机终端执行以下命令，确认当前选中的是支持 OHOS 的 Flutter 工具链，并能发现目标设备：
flutter --version
flutter doctor -v
hdc list targets
本文使用的工具链和复现时补全的 SDK 配置如下：
| 项目 | 版本或配置 | 用途 |
|---|---|---|
| Flutter OHOS SDK | 3.44.9+ohos-0.0.1-canary1 | Flutter 编译与 OHOS 平台工具链 |
| Flutter 分支 | oh-3.44.9-dev | CPF-Flutter 对应开发分支 |
| Dart SDK | 3.12.2 | Dart 语言与包管理环境 |
| HarmonyOS 开发套件 | 7.0.0（API 26） | 开发套件版本及对应的 API 级别 |
compileSdkVersion | 26.0.0（本文补全） | 编译时使用的 SDK API |
targetSdkVersion | 26.0.0（本文补全） | 应用面向的行为版本 |
compatibleSdkVersion | 5.1.0(18) | 当前工程声明的最低兼容版本 |
| 插件版本 | 0.7.0 | pubspec.yaml 中的包版本 |
| 原生语言 | ArkTS | HarmonyOS 插件实现 |
| 插件产物 | HAR | 被应用 entry 模块依赖 |
2.1 开发套件版本与工程中的 SDK 版本配置
7.0.0（API 26） 和 26.0.0 涉及 HarmonyOS 开发套件版本（API 版本）及其底座 OpenHarmony 的版本号体系。在本文工程中，相关版本的含义与配置方式如下：
7.0.0（API 26）表示 HarmonyOS 开发套件版本为7.0.0，对应 API 26。26.0.0是本文 HarmonyOS 应用工程中compileSdkVersion和targetSdkVersion的属性值。5.1.0(18)是本文工程中compatibleSdkVersion的属性值，声明最低兼容 API 18。
本地示例未显式填写 compileSdkVersion、targetSdkVersion。下面为沿用 API 26 工具链时需合并的 product 片段，补全值不代表原文件已包含这些字段：
{
"name": "default",
"compatibleSdkVersion": "5.1.0(18)",
"compileSdkVersion": "26.0.0",
"targetSdkVersion": "26.0.0",
"runtimeOS": "HarmonyOS"
}
这组配置使用 API 26 SDK 编译，并以 API 26 为目标版本，最低兼容 API 18。DisplaySync 提交的是期望帧率范围，最终显示刷新率受系统调度影响，不强制切换物理分辨率。模式 ID 根据当前刷新率列表生成，不应跨会话或显示环境变化持久化。
三、从源码仓库开始准备适配工程
3.1 将上游源码同步到 AtomGit
适配已有第三方插件时，先从 Pub 包信息或项目 README 确认上游地址、包名、版本和许可证。同步仓库时保留源码、许可证和提交历史，方便后续跟踪上游更新。
在 AtomGit 网页的新建仓库流程中，找到从已有仓库导入的入口，填写上游 Git 地址，选择自己有写权限的组织或个人空间，设置目标仓库名称后执行导入。完成后检查目标分支、pubspec.yaml、LICENSE 和提交历史是否完整，并记录适配起点的提交号。如果上游本身托管在 AtomGit，也可以通过 Fork 获得自己的工作仓库。
上游源码为 https://github.com/ajinasokan/flutter_displaymode，本文基于 0.7.0。配套仓库预定为 flutter_displaymode。仓库创建并同步适配代码后，再执行下面的拉取命令；尚未同步时使用本地副本。需要提交修改时，使用自己有写权限的仓库或 Fork。
3.2 将代码拉取到宿主机
在安装了 Flutter OH 和 DevEco Studio 的开发电脑上打开终端，进入准备存放项目的目录，执行：
git clone https://atomgit.com/oh-flutter/flutter_displaymode.git
cd flutter_displaymode
pwd
ls
git remote -v
git status --short --branch
git rev-parse HEAD
git clone 会创建 flutter_displaymode/ 目录；cd 后的位置就是下文所说的插件仓库根目录，这里应能看到 pubspec.yaml、lib/ 和 example/。Git 仓库名和 Dart 包名均为 flutter_displaymode。
需要使用与本文相同的代码版本时，先确认配套仓库已经包含下列本地参考提交，再在没有未提交修改的仓库中执行：
git switch --detach 192250f2a0ab00ed584510a31430772e05c22c83
适配其他插件时，使用该插件对应版本的 tag 或 commit 作为分支起点。
图 1：在宿主机终端输入 AtomGit 仓库拉取命令。
3.3 在仓库根目录创建适配分支
接着在 flutter_displaymode/ 根目录创建分支。分支名统一使用 feat/ohos_库名称_版本号，库名称取 pubspec.yaml 的 name，版本号取此次适配的基线版本。本例为：
git switch -c feat/ohos_flutter_displaymode_0.7.0
git branch --show-current
如果该分支已存在，使用 git switch feat/ohos_flutter_displaymode_0.7.0 切换即可。
图 2：在 flutter_displaymode 仓库根目录输入适配分支创建命令。
3.4 自动补全 OHOS 适配结构
分支创建后，仍在同一个插件根目录执行结构补全。以下命令适用于尚无 ohos/ 目录的既有 Flutter 平台插件：
flutter create --template=plugin --platforms=ohos --project-name flutter_displaymode .
git status --short
git diff -- pubspec.yaml lib example
--template=plugin指定插件模板。--platforms=ohos指定需要补全的平台。--project-name flutter_displaymode使用 Dart 包名，避免当前目录重命名后生成错误的包名。- 最后的
.表示在当前插件目录补全工程，不是另建一层flutter_displaymode/。
该命令生成 OHOS 平台脚手架，业务逻辑需要在 ArkTS 中实现。生成后通过 diff 检查 pubspec.yaml、lib/ 和 example/ 的变化，保留已有 API、其他平台注册项及依赖配置。不同 Flutter OH 版本生成的模板可能略有差异。
如果生成后 example/ohos/ 仍不存在，进入已有示例应用补全平台：
cd example
flutter create --platforms=ohos .
cd ..
本地适配工作区已经包含 ohos/ 和 example/ohos/，直接运行示例时可以跳过结构补全。新建插件则使用 flutter create --org com.nutpi --template=plugin --platforms=ohos flutter_displaymode；已有插件使用上面的 . 在当前目录补全。
图 3：在插件根目录输入 OHOS 结构补全命令。
3.5 适配后的项目目录
适配后的关键目录如下：
flutter_displaymode/
├── lib/
│ ├── flutter_displaymode.dart
│ └── src/
│ ├── flutter_display_mode.dart
│ └── model/
│ └── display_mode.dart
├── ohos/
│ ├── src/
│ │ └── main/
│ │ ├── ets/
│ │ │ └── components/
│ │ │ └── plugin/
│ │ │ └── DisplayModePlugin.ets
│ │ └── module.json5
│ ├── index.ets
│ └── oh-package.json5
├── example/
│ ├── lib/
│ │ └── main.dart
│ └── ohos/
│ ├── entry/
│ │ └── src/
│ │ └── main/
│ │ └── module.json5
│ └── build-profile.json5
├── pubspec.yaml
├── README.OpenHarmony_CN.md
├── README.OpenHarmony.md
├── CHANGELOG.OpenHarmony.md
└── test/
项目根目录如下，其中包含 ohos/、example/ 及实际保留的说明文件；交付文档清单见第六节：
图 4：适配后的 flutter_displaymode 项目根目录。
| 文件 | 主要职责 |
|---|---|
lib/flutter_displaymode.dart | 提供业务公开 API |
lib/src/flutter_display_mode.dart | 实现平台协议或数据模型 |
lib/src/model/display_mode.dart | 实现平台协议或数据模型 |
ohos/src/main/ets/components/plugin/DisplayModePlugin.ets | 注册通道并实现 OHOS 原生能力 |
ohos/src/main/module.json5 | 声明 HAR 模块和权限 |
example/lib/main.dart | 演示接口调用与结果显示 |
四、Dart 接口与通道分析
OHOS 实现需要遵循 Dart 层已有的方法、参数和回调约定。先阅读 lib/flutter_displaymode.dart、lib/src/flutter_display_mode.dart、lib/src/model/display_mode.dart，再在 ohos/src/main/ets/components/plugin/DisplayModePlugin.ets 中实现对应的原生调用。适配其他已有平台的插件时，也应保留其公开接口和其他平台实现。
本例的对应关系如下：
| Dart 入口或模型 | 通道协议 | OHOS 实现 | 应保持的行为 |
|---|---|---|---|
supported | getSupportedModes | supportedRefreshRates + 当前值 | Dart 插入 DisplayMode.auto |
active / preferred | getActiveMode / getPreferredMode | 真实显示值 / 本会话首选值 | 两者可以不同 |
setPreferredMode(mode) | setPreferredMode，mode.id | DisplaySync 帧率请求 | 0 撤销请求 |
setHighRefreshRate() / setLowRefreshRate() | Dart 选择后调用 setPreferredMode | 当前分辨率内选最高或最低 | 不是自动持续跟踪模式 |
原生端需要保持方法名、参数键和返回类型一致，不能只保留方法名称而改变业务语义。
4.1 跨端架构与调用时序
Flutter 侧通过 MethodChannel('flutter_display_mode') 调用 OHOS 实现。本插件使用一次性的异步调用，不提供持续事件流。
4.1.1 一次完整读取显示模式的时序
4.2 显示模型：lib/src/model/display_mode.dart
class DisplayMode {
const DisplayMode({
required this.id,
required this.width,
required this.height,
required this.refreshRate,
});
factory DisplayMode.fromJson(Map<String, dynamic> json) {
return DisplayMode(
id: json['id'] as int,
width: json['width'] as int,
height: json['height'] as int,
// OpenHarmony reports integral refresh rates as integers over the
// standard method codec, while Android reports a floating-point value.
refreshRate: (json['refreshRate'] as num).toDouble(),
);
}
final int id;
final int width;
final int height;
final double refreshRate;
static const DisplayMode auto = DisplayMode(
id: 0,
width: 0,
height: 0,
refreshRate: 0,
);
String toString() {
return '#$id ${width}x$height @ ${refreshRate.toInt()}Hz';
}
bool operator ==(Object other) =>
identical(this, other) ||
other is DisplayMode &&
runtimeType == other.runtimeType &&
width == other.width &&
height == other.height &&
refreshRate == other.refreshRate;
int get hashCode => width.hashCode ^ height.hashCode ^ refreshRate.hashCode;
}
refreshRate 使用 num.toDouble，兼容 OHOS 整数与其他平台浮点编码。自动模式 id 为 0、尺寸和刷新率均为 0；相等比较不包含 id，不能只凭对象相等推断原生模式编号相同。
4.3 公开 API 与平台接口
FlutterDisplayMode 提供静态属性和方法，supported、active、preferred 分别用于候选列表、当前活动值和首选请求。最高/最低助手在当前分辨率中选择：
static Future<void> setHighRefreshRate() async {
final List<DisplayMode> modes = await supported;
final DisplayMode activeMode = await active;
DisplayMode newMode = activeMode;
for (final DisplayMode mode in modes) {
if (mode.height == newMode.height &&
mode.width == newMode.width &&
mode.refreshRate > newMode.refreshRate) {
newMode = mode;
}
}
await setPreferredMode(newMode);
}
static Future<void> setLowRefreshRate() async {
final List<DisplayMode> modes = await supported;
final DisplayMode activeMode = await active;
DisplayMode newMode = activeMode;
for (final DisplayMode mode in modes) {
if (mode.height == newMode.height &&
mode.width == newMode.width &&
mode.refreshRate < newMode.refreshRate) {
newMode = mode;
}
}
await setPreferredMode(newMode);
}
4.4 Dart 通道协议分析
4.4.1 通道名称必须两端完全一致
const methodChannel = MethodChannel('flutter_display_mode');
通道名称属于跨语言协议。Dart 和 ArkTS 任何一端拼写不一致，都会出现“方法未实现”或“调用找不到插件”等问题。
4.4.2 查询候选与活动模式
static Future<List<DisplayMode>> get supported async {
final List<dynamic> rawModes =
(await _channel.invokeMethod<List<dynamic>>('getSupportedModes'))!;
final List<DisplayMode> modes = rawModes.map((dynamic i) {
final Map<String, dynamic> item =
(i as Map<dynamic, dynamic>).cast<String, dynamic>();
return DisplayMode.fromJson(item);
}).toList();
modes.insert(0, DisplayMode.auto);
return modes;
}
static Future<DisplayMode> get active async {
final Map<dynamic, dynamic> mode =
(await _channel.invokeMethod<Map<dynamic, dynamic>>('getActiveMode'))!;
return DisplayMode.fromJson(mode.cast<String, dynamic>());
}
supported 在原生列表头部插入 DisplayMode.auto，业务不要假定固定长度或固定 60/120Hz。active 应在设置后重新获取，并考虑系统生效时机。
4.4.3 设置首选并恢复自动
static Future<void> setPreferredMode(DisplayMode mode) async {
return await _channel.invokeMethod<void>(
'setPreferredMode',
<String, dynamic>{'mode': mode.id},
);
}
static Future<DisplayMode> get preferred async {
final Map<dynamic, dynamic> mode = (await _channel
.invokeMethod<Map<dynamic, dynamic>>('getPreferredMode'))!;
return DisplayMode.fromJson(mode.cast<String, dynamic>());
}
恢复自动调用 setPreferredMode(DisplayMode.auto)，原生释放 DisplaySync。preferred 返回记录的首选模式，不代表屏幕已切换到该值。
五、补全 OHOS 原生实现与工程配置
5.1 在 DisplayModePlugin.ets 中实现原生能力
业务层沿用已有 API，原生侧在 DisplayModePlugin 中接入 ArkUI display 与 ArkGraphics2D displaySync，通过 Flutter 通道回传结果。
下面列出类中的主要成员和方法，完整文件还包含 getUniqueClassName() 等插件接口；各段均为核心摘录，需要结合完整类使用。
原生插件位于：
ohos/src/main/ets/components/plugin/DisplayModePlugin.ets
5.1.1 引入 Flutter 和 HarmonyOS 能力
import {
FlutterPlugin,
FlutterPluginBinding,
MethodCall,
MethodCallHandler,
MethodChannel,
MethodResult,
} from '@ohos/flutter_ohos';
import { display } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { displaySync } from '@kit.ArkGraphics2D';
FlutterPlugin 负责接入 Flutter Engine 生命周期，MethodChannel 接收 Dart 命令；系统能力由 ArkUI display 与 ArkGraphics2D displaySync 提供。错误和事件处理以对应方法实现为准。
5.1.2 连接 Flutter Engine
private channel: MethodChannel | null = null;
private frameRateRequest: displaySync.DisplaySync | null = null;
private preferredModeId: number = 0;
private readonly frameCallback = (_info: displaySync.IntervalInfo): void => {
};
onAttachedToEngine(binding: FlutterPluginBinding): void {
this.channel = new MethodChannel(binding.getBinaryMessenger(), CHANNEL_NAME);
this.channel.setMethodCallHandler(this);
}
Engine 注册 flutter_display_mode 通道。注意包名是 flutter_displaymode，通道名多一个下划线，必须按源码保持一致。原生 frameCallback 不向 Dart 推送事件。
5.1.3 构造可用显示模式
private getRefreshRates(currentDisplay: display.Display): Array<number> {
const reportedRates = currentDisplay.supportedRefreshRates;
const refreshRates = new Array<number>();
if (reportedRates !== undefined) {
for (const rate of reportedRates) {
if (rate > 0 && refreshRates.indexOf(rate) === -1) {
refreshRates.push(rate);
}
}
}
if (refreshRates.indexOf(currentDisplay.refreshRate) === -1) {
refreshRates.push(currentDisplay.refreshRate);
}
refreshRates.sort((left: number, right: number): number => left - right);
return refreshRates;
}
private getSupportedModes(): Array<DisplayModeData> {
const currentDisplay = display.getDefaultDisplaySync();
const refreshRates = this.getRefreshRates(currentDisplay);
const modes = new Array<DisplayModeData>();
for (let index = 0; index < refreshRates.length; index++) {
modes.push(this.createMode(index + 1, currentDisplay, refreshRates[index]));
}
return modes;
}
private getActiveMode(): DisplayModeData {
const currentDisplay = display.getDefaultDisplaySync();
const refreshRates = this.getRefreshRates(currentDisplay);
let activeModeId = refreshRates.indexOf(currentDisplay.refreshRate) + 1;
if (activeModeId === 0) {
activeModeId = 1;
}
return this.createMode(activeModeId, currentDisplay, currentDisplay.refreshRate);
}
刷新率去重、补入当前值并排序，模式使用同一当前分辨率。系统没有 supportedRefreshRates 时，只能依据当前值构造候选；列表变化后不要复用旧 ID。
5.1.4 请求刷新率与释放请求
private setPreferredMode(modeId: number): void {
if (!Number.isInteger(modeId) || modeId < 0) {
throw new Error(`${ERROR_INVALID_MODE}: mode must be a non-negative integer.`);
}
if (modeId === 0) {
this.releaseFrameRateRequest();
return;
}
const currentDisplay = display.getDefaultDisplaySync();
const refreshRates = this.getRefreshRates(currentDisplay);
const index = modeId - 1;
if (index < 0 || index >= refreshRates.length) {
throw new Error(`${ERROR_INVALID_MODE}: mode ${modeId} is not supported.`);
}
const refreshRate = refreshRates[index];
this.releaseFrameRateRequest();
const request = displaySync.create();
request.setExpectedFrameRateRange({
min: refreshRate,
max: refreshRate,
expected: refreshRate,
});
request.on('frame', this.frameCallback);
request.start();
this.frameRateRequest = request;
this.preferredModeId = modeId;
}
private releaseFrameRateRequest(): void {
if (this.frameRateRequest !== null) {
this.frameRateRequest.stop();
this.frameRateRequest.off('frame', this.frameCallback);
this.frameRateRequest = null;
}
this.preferredModeId = 0;
}
非负整数 modeId=0 表示自动；其他值映射当前刷新率列表。请求设置 min/max/expected 后启动 DisplaySync；重复设置先释放旧请求。这里不提供强制物理模式切换。
5.1.5 处理 MethodChannel 命令
onMethodCall(call: MethodCall, result: MethodResult): void {
try {
switch (call.method) {
case 'getActiveMode':
result.success(this.getActiveMode());
break;
case 'getSupportedModes':
result.success(this.getSupportedModes());
break;
case 'getPreferredMode':
result.success(this.getPreferredMode());
break;
case 'setPreferredMode':
this.setPreferredMode(call.argument('mode') as number);
result.success(null);
break;
default:
result.notImplemented();
}
} catch (error) {
const businessError = error as BusinessError;
result.error(
businessError.code === undefined ? ERROR_DISPLAY : String(businessError.code),
businessError.message ?? `Failed to handle ${call.method}.`,
null,
);
}
}
onMethodCall 捕获原生异常，缺少错误码时返回 DISPLAY_ERROR。非法 modeId 在消息中含 invalidMode，但代码抛的是普通 Error，因此不能把 PlatformException.code 一概写成 invalidMode。未知方法返回 notImplemented。
5.1.6 Engine 解绑时释放资源
onDetachedFromEngine(_binding: FlutterPluginBinding): void {
this.releaseFrameRateRequest();
this.channel?.setMethodCallHandler(null);
this.channel = null;
}
Engine 解绑调用 releaseFrameRateRequest，停止 DisplaySync、解除 frame 回调并将 preferredModeId 归零，再清理方法通道。
5.2 声明插件和宿主权限
查询显示参数和提交当前实现的 DisplaySync 请求不需要新增敏感权限。HAR 与本地 example entry 均未声明 requestPermissions。
5.2.1 插件 HAR 的权限
插件 ohos/src/main/module.json5 的模块配置如下：
{
"module": {
"name": "flutter_displaymode",
"type": "har",
"deviceTypes": [
"default",
"tablet"
]
}
}
5.2.2 应用 entry 的权限
最终安装的是宿主应用。以下片段来自 example/ohos/entry/src/main/module.json5，合并时保留原有 Ability 等配置：
{
"module": {
"requestPermissions": []
}
}
上面用空数组表达无需新增权限，本地 entry 没有 requestPermissions 字段时可保持省略。无需照搬其他插件的运动或位置权限。
5.3 注册并导出插件
pubspec.yaml 通过以下配置声明 OHOS 插件类：
flutter:
plugin:
platforms:
ohos:
pluginClass: DisplayModePlugin
插件的 ohos/index.ets 需要导出实现：
import DisplayModePlugin from './src/main/ets/components/plugin/DisplayModePlugin';
export default DisplayModePlugin;
执行 flutter pub get 和构建后，Flutter 工具会为应用生成插件注册代码。通常不应手工编辑 GeneratedPluginRegistrant.ets，因为下次构建可能覆盖它。
注册异常的排查步骤见第九节 MissingPluginException。
5.4 检查 example 的 OHOS 应用结构
本例的 example/ohos/build-profile.json5 应在 products 中设置版本。下面按第二节补全 compileSdkVersion、targetSdkVersion，请合并到现有工程；其中 signingConfig: "default" 需要与本机配置的签名名称一致，签名材料保留在本地。
{
"app": {
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.1.0(18)",
"runtimeOS": "HarmonyOS",
"compileSdkVersion": "26.0.0",
"targetSdkVersion": "26.0.0"
}
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
}
]
}
配置后，在 DevEco Studio 中执行一次 Sync Project。如果 entry 模块正常识别，Project 视图中会出现 entry，并能打开 entry 模块的签名配置。
六、补全交付文件并提交适配分支
6.1 除代码外还要补全哪些文件
代码适配完成后，还需要整理安装说明、接口文档、版本记录和开源信息。接收仓库有专用模板时，按其格式填写：
| 文件 | 应写清楚的内容 |
|---|---|
README.OpenSource | 上游名称、源码地址、适配版本或提交、版权及许可证信息；按仓库模板列出第三方依赖 |
README.md | 原项目说明、OHOS 支持入口、配套 Demo 和文档链接；保留上游信息 |
README.OpenHarmony_CN.md | 简介、AtomGit 安装方式、版本对应关系、环境约束、权限、接口表、示例、已验证范围和遗留问题 |
README.OpenHarmony.md | 与中文说明对应的英文文档 |
CHANGELOG.OpenHarmony.md | OHOS 新增能力、适配版本、兼容限制与测试范围 |
LICENSE / NOTICE | 保留上游许可证；NOTICE 按许可证和原项目要求保留或补充 |
example/README.md | 依赖方式、运行目录、签名、操作步骤与效果图；覆盖候选模式、active/preferred 区别、最高/最低请求与恢复自动 |
pubspec.yaml、ohos/oh-package.json5 | 核对包名、版本、插件注册、仓库地址、许可证和依赖 |
.gitignore | 忽略构建缓存及本机签名材料，不漏提交必要源码和配置 |
README.OpenSource 记录库本身的来源与版本。本例的包名为 flutter_displaymode，版本为 0.7.0，采用 MIT 许可证；Flutter 和 HarmonyOS SDK 版本写入环境说明。
现有说明文件以目录树为准。README.OpenSource 等缺失交付文件按接收仓库要求补全；安装与反馈链接统一替换为本文预定的 AtomGit 地址，并在仓库创建、适配代码同步后核对。
6.2 提交前检查
提交前先完成第八节的插件、example 和真机测试，再从根目录检查改动：
git branch --show-current
git diff --check
git status --short
git diff --stat
git diff
检查 diff 中的接口、平台注册和依赖变化，移除本机路径及签名信息，并使文档中的版本和分支与提交内容一致。
6.3 提交并推送到 AtomGit
文档和代码整理完成后，在 Git 仓库根目录暂存并提交。以下命令以第 6.1 节文档已经补全为前提，文件名按项目实际情况调整：
git add lib ohos pubspec.yaml example test
git add README.md README.OpenSource README.OpenHarmony_CN.md
git add README.OpenHarmony.md CHANGELOG.OpenHarmony.md
git diff --cached --check
git diff --cached --stat
git diff --cached
git commit -m "feat: add OHOS support for flutter_displaymode 0.7.0"
git remote -v
git branch --show-current
git push -u origin feat/ohos_flutter_displaymode_0.7.0
DevEco 可能向 example/ohos/build-profile.json5 写入本机签名配置，需要在提交前从暂存内容中移除。推送时，origin 应指向自己的 AtomGit 仓库，当前分支为 feat/ohos_flutter_displaymode_0.7.0。
推送后在 AtomGit 发起合并请求，说明上游来源和版本、OHOS 实现范围、依赖及权限、测试环境、操作结果、已知限制，并附 Demo 运行图。目标分支和评审流程以接收仓库要求为准。
七、使用根目录 example 演示接入
插件包自带 example/，可以直接用来调试插件和体验显示模式查询与刷新率请求。
7.1 本地适配时使用路径依赖
当前 example/pubspec.yaml 的依赖是：
dependencies:
flutter:
sdk: flutter
flutter_displaymode:
path: ../
../ 相对于 example/pubspec.yaml 指向插件根目录，修改根目录插件后可直接联调。
7.2 通过 AtomGit 引入插件
业务应用通过 AtomGit 引入时，将 flutter_displaymode 的 path 配置替换为下面的 Git 依赖。仓库同步后，可固定到本文的本地参考提交：
dependencies:
flutter:
sdk: flutter
flutter_displaymode:
git:
url: https://atomgit.com/oh-flutter/flutter_displaymode.git
ref: 192250f2a0ab00ed584510a31430772e05c22c83
使用自己的适配版本时，先推送分支，再将 url 改为对应仓库，ref 改为 feat/ohos_flutter_displaymode_0.7.0。正式发布后可固定到 tag 或 commit。
从插件根目录执行：
cd example
flutter pub get
flutter pub deps
检查 example/pubspec.lock 中 flutter_displaymode 的来源为 git，并核对 url、ref 和 resolved-ref。同时检查没有 dependency_overrides 或 pubspec_overrides.yaml 将其覆盖回本地依赖，确认应用使用的是 Git 依赖。
7.3 调用接口实现显示模式查询与刷新率请求
下面的页面可用于插件包内的 example/lib/main.dart，是便于讲解的最小页面；仓库完整 Demo 的入口和布局可能不同，第八节截图与验收步骤以仓库完整 Demo 为准。
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_displaymode/flutter_displaymode.dart';
void main() {
runApp(const MaterialApp(home: DemoPage()));
}
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
String _status = '尚未操作';
bool _busy = false;
void _show(String value) {
if (mounted) setState(() => _status = value);
}
Future<void> _run(Future<String> Function() action) async {
if (_busy) return;
setState(() => _busy = true);
try {
_show(await action());
} catch (error) {
_show('调用失败：$error');
} finally {
if (mounted) setState(() => _busy = false);
}
}
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('显示模式')),
body: ListView(
padding: const EdgeInsets.all(16),
children: [
Text(_status),
const SizedBox(height: 16),
FilledButton(onPressed: _busy ? null : () => _run(() async {
final modes = await FlutterDisplayMode.supported;
final active = await FlutterDisplayMode.active;
final preferred = await FlutterDisplayMode.preferred;
return '候选：$modes\n当前：$active\n首选：$preferred';
}), child: const Text('查询显示模式')),
FilledButton(onPressed: _busy ? null : () => _run(() async {
await FlutterDisplayMode.setHighRefreshRate();
return '首选：${await FlutterDisplayMode.preferred}，当前：${await FlutterDisplayMode.active}';
}), child: const Text('请求最高刷新率')),
FilledButton(onPressed: _busy ? null : () => _run(() async {
await FlutterDisplayMode.setLowRefreshRate();
return '首选：${await FlutterDisplayMode.preferred}，当前：${await FlutterDisplayMode.active}';
}), child: const Text('请求最低刷新率')),
FilledButton(onPressed: _busy ? null : () => _run(() async {
await FlutterDisplayMode.setPreferredMode(DisplayMode.auto);
return '已撤销首选请求';
}), child: const Text('恢复自动')),
],
),
);
}
}
7.4 页面退出时恢复系统自动模式
异步回调先检查 mounted。页面独占刷新率请求时，可在离开时调用 setPreferredMode(DisplayMode.auto)；最小示例提供显式“恢复自动”按钮。多个页面共享时由应用级服务决定恢复时机，Engine 解绑也会清理原生请求。
八、验证、构建与鸿蒙设备运行效果
8.1 分别验证插件与 example
从插件仓库根目录执行：
flutter pub get
flutter analyze
flutter test
cd example
flutter pub get
flutter analyze
flutter test
现有测试覆盖 supported 自动模式插入、整数刷新率解析、active/preferred 解码、设置参数与最高刷新率选择；example Widget 测试验证列表。mock 返回 120Hz 不代表设备实际运行在 120Hz。Widget 测试应匹配实际保留的 Demo 页面；如果替换成第七节最小页面，也要相应调整原来的 UI 断言。
Dart 测试覆盖接口和页面逻辑，候选模式、active/preferred 区别、最高/最低请求与恢复自动还需要在鸿蒙设备上验证。以上为 Dart 测试复现命令，本次未重新执行这些测试；本次已重新构建、安装并运行签名 Release HAP，具体真机采集范围见 8.5。
8.2 确认设备连接
hdc list targets
flutter devices
设备首次连接电脑时，需要在手机端确认调试授权。列表为空时，检查 USB 连接、调试模式和电脑授权。
8.3 配置签名
真机安装的 HAP 通常需要有效签名。推荐使用 DevEco Studio 为 entry 模块配置自动签名：
- 用 DevEco Studio 打开
example/ohos，不是仓库根目录； - 等待工程 Sync 成功，确认 Project 视图中存在
entry模块； - 打开 File > Project Structure > Signing Configs；
- 为
defaultproduct 选择或生成签名； - 确认设备、应用包名、证书和 Profile 匹配；
- 再回到终端执行 Flutter 构建或运行。
签名材料保存在本机，公开仓库中只保留构建所需的通用配置。
8.4 运行示例
以下命令在 example/ 目录执行，将 <device-id> 替换为设备列表中的实际 ID：
flutter run -d <device-id>
也可以先构建 HAP：
flutter build hap --debug
典型产物位于：
example/ohos/entry/build/default/outputs/default/
目录中通常包含已签名和未签名 HAP。真机安装应选择与当前设备匹配的已签名产物。
本次真机截图使用签名 Release HAP。在插件包的 example/ 目录完成签名配置后执行：
flutter build hap --release
hdc -t <device-id> install -r build/ohos/hap/entry-default-signed.hap
hdc -t <device-id> shell aa start -a EntryAbility -b com.ajinasokan.flutterdisplaymode_example
8.5 在设备上测试显示模式查询与刷新率请求
- 运行完整 Demo，确认 Plugin example app 页面 Modes 列表显示 Automatic 和实际候选模式。
- 点击 Fetch，记录 active 与 preferred，并核对尺寸和刷新率。
- 选择候选模式或点击 Highest Hz，等待后再次 Fetch 比较请求与活动值。
- 点击 Lowest Hz，重复比较，不要求系统必须采用请求值。
- 选择 Automatic，确认首选恢复自动；必要时滑动 Lists 页面触发负载，再查询活动值。
- 重复设置并退出重进，检查请求清理；在不同设备上分别记录候选列表，勿预设一定有 120Hz。
页面初始提示来自 Demo 默认值，调用结果或事件到达后才反映系统状态。上述列表为完整验收步骤，本次实际采集范围如下。
8.6 鸿蒙设备运行效果
OHOS 实现提供显示模式查询与刷新率请求。以下为仓库完整 Demo 的三张真机运行截图，按实际状态记录。
截图标注：操作步骤与截图命令真机运行图（从左到右）：显示模式列表／请求最高刷新率／恢复自动模式。采集于 2026-09-09，设备 ALN-AL00 / HUAWEI Mate 60 Pro，系统 OpenHarmony 6.1.1.120（API 24）；使用本地当前源码构建的签名 Release HAP。
Automatic 已选中时，ACTIVE 仍可显示 120 Hz；请求设置不等于系统必然切换到某一物理刷新率。
执行目录：本文 Markdown 所在目录。先用 hdc list targets 获取设备 ID，将下列 <device-id> 替换为实际值。截图使用仓库完整 Demo；snapshot_display 在本机要求 .jpeg 后缀，图片保持原始真机画面。
mkdir -p blog-assets/flutter_displaymode
显示模式列表： 启动 Demo，在 Modes 查看当前候选列表与 ACTIVE 标记。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-modes.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-modes.jpeg ./blog-assets/flutter_displaymode/modes.jpeg
请求最高刷新率： 点击 Highest Hz，等待列表更新，保留首选单选标记和 ACTIVE 标记。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-highest-hz.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-highest-hz.jpeg ./blog-assets/flutter_displaymode/highest-hz.jpeg
恢复自动模式： 点击 Automatic 左侧的单选按钮，确认其被选中后截图；文本区域不一定响应点击。
hdc -t <device-id> shell snapshot_display -f /data/local/tmp/flutter_displaymode-automatic.jpeg
hdc -t <device-id> file recv /data/local/tmp/flutter_displaymode-automatic.jpeg ./blog-assets/flutter_displaymode/automatic.jpeg
| 模式列表 | 最高刷新率请求 | 恢复自动 |
|---|---|---|
| 实际候选模式 | 请求与活动值 | 恢复系统调度 |
DisplaySync 提交的是期望帧率范围，最终显示刷新率受系统调度影响，不强制切换物理分辨率。模式 ID 根据当前刷新率列表生成，不应跨会话或显示环境变化持久化。
九、FAQ：适配过程与使用问题
9.1 Missing SDK components
典型错误如下：
Missing SDK components. SDK path: ...,
missing components: toolchains,ets,js,native,previewer.
这个错误发生在 Hvigor 同步阶段。通常需要检查构建工具使用的 SDK 路径、组件是否完整，以及 Hvigor 与 SDK 的版本是否匹配。
处理顺序：
- 在 DevEco Studio SDK Manager 中确认 API 26 组件已经下载完整；
- 检查 Flutter 和 DevEco Studio 使用的 SDK 路径是否一致；
- 避免误用
/Applications/DevEco-Studio.app/Contents/sdk之类的不完整目录； - 确认 SDK 根目录下存在
toolchains、ets、js、native、previewer； - 执行
flutter config --ohos-sdk <正确路径>； - 重新执行
flutter doctor -v和 DevEco Studio Sync。
因为 Sync 和 Compile 首先读取 Mac 本地 SDK。手机 API 版本只在部署、安装和运行时参与兼容判断。即使完全不连接手机，本地 SDK 不完整时也会得到相同错误。
当前工程的 compatibleSdkVersion 是 API 18，因此 API 24 在安装版本门槛上是满足的；但功能是否可用还取决于目标系统能力、权限和运行环境，不能仅凭最低版本判断。
9.2 DevEco Studio 中看不到 entry 模块
插件的 ohos/ 目录是 HAR 模块，可安装应用的 entry 模块位于 example/ohos/entry。
请直接使用 DevEco Studio 打开：
flutter_displaymode/example/ohos
如果仍看不到 entry，先解决 SDK Sync 错误，再检查 example/ohos/build-profile.json5 的 modules 是否包含 ./entry。同步失败时，Project Structure 无法正确解析模块，签名界面也可能不显示 entry。
9.3 无法手动签名
签名配置依附于可构建的应用模块和 product。只有 HAR 插件模块、工程 Sync 失败，或者打开了错误目录时，DevEco Studio 都可能无法提供 entry 签名入口。
建议先确认：
- 打开的是
example/ohos； - SDK 组件完整并且 Sync 成功；
entry的模块类型为entry；defaultproduct 和 target 已正确关联；- 当前账号、证书和调试设备状态有效。
9.4 请求 120Hz 成功，active 为什么没变化
DisplaySync 表达期望范围，系统可根据功耗、温度、应用状态选择实际刷新率。再次查询 active 判断结果；它仍不是 Flutter 的实际渲染 FPS，也不会强制切换物理分辨率。
9.5 MissingPluginException
这通常表示 Dart 通道找不到已注册的原生插件。新增原生插件后需要重新构建应用。从仓库根目录执行：
cd example
flutter clean
flutter pub get
flutter run -d <device-id>
如果仍然出现，检查自动生成的插件注册文件中是否包含 DisplayModePlugin，同时核对 pubspec.yaml、ohos/index.ets 和 oh-package.json5。
9.6 反复设置会不会叠加请求
setPreferredMode 在创建新 DisplaySync 前调用 releaseFrameRateRequest，正常路径只保留一个当前请求。业务仍应避免并发竞争，多个页面由统一服务管理首选模式。
9.7 编译成功但安装失败
常见原因包括：
- HAP 未签名或使用了错误的 Profile；
- 设备未加入调试设备列表；
- 包名与签名 Profile 不匹配；
- 安装包的
compatibleSdkVersion高于设备 API； - 手机上已经安装了使用不同证书签名的同包名应用。
根据安装错误码区分签名、版本和包名冲突，再处理对应配置。
9.8 flutter create 不认识 ohos，或包名不合法
先执行 flutter --version，确认使用的是 OHOS 版工具链，环境配置回到第二节的社区链接核对。包名报错时，确认当前目录包含目标插件的 pubspec.yaml，并显式传入 --project-name flutter_displaymode；本例仓库名和 Dart 包名均为 flutter_displaymode。生成后检查 diff，再补充 ArkTS 业务实现。
9.9 AtomGit 依赖提示找不到分支或无权限
先检查 URL 是否指向已同步的目标仓库，再确认 feat/ohos_flutter_displaymode_0.7.0 已推送。仓库未创建、适配分支未推送或提交未同步时，应先完成同步；不能直接使用仅存在本地的提交号。私有仓库还需在本机配置 Git 认证。
9.10 改了本地 ArkTS，Demo 为什么没变化
先检查 example/pubspec.yaml：Git 依赖读取远程提交，不会自动读取本地插件改动。本地联调切回 path: ../；测试远程版本则先提交推送，再更新依赖并核对 pubspec.lock 的 resolved-ref。原生代码变动后停止应用并重新构建运行，不能只做 Dart 热重载。
9.11 保存的模式 ID 失效或列表只剩一个刷新率
ID 由当前支持刷新率排序生成，不能跨会话或显示变化保存。较低 API 未提供 supportedRefreshRates 时，只返回当前刷新率加自动模式。重新查询列表后选择，非法 ID 的错误码通常为 DISPLAY_ERROR、消息含 invalidMode。
相关链接
作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。
更多推荐
0
0- 0
已为社区贡献36条内容
所有评论(0)