框架与适配 · Ionic Framework 源码镜像 · Cordova OpenHarmony 容器
前言
维修台的工单只有两项,设备编号和维修事项。两项都错时,窗口应当告诉维修员要改哪些值,并把键盘送到能立刻改的第一项。连续提交几次以后,焦点还要跟着错误变化。生成预览后再改输入,旧预览也该明确失效。
这个例子把每一步能不能继续输入放到真机上检查。先执行空表单提交,再只填设备编号,最后补齐事项。本文前半保留早期模拟器的定位思路,后半记录用 MateBook 14 本机生成的签名包和同一轮操作。
两枚输入框旁边都有红字,下一次敲键盘究竟写进哪一框?鸿蒙 PC 上这个 Ionic 工单,用一张单子、三次提交回答。每次提交都问一个不同的问题,先看谁接住光标,再看错误是否跟着修好的字段一起消失,最后看预览是不是真用了新值。
第一按:两个都空,焦点给谁

鸿蒙 PC 模拟器全屏,两个字段无效时焦点在设备编号
Ionic 组件对外暴露的是 ion-input 元素,实际光标在它内部的原生输入上。提交时先按字段顺序计算错误列表,然后调用第一处错误的 setFocus()。测试再用 getInputElement() 找到内部输入,核对焦点。这个鸿蒙 PC 示例通过活动元素证明真正聚焦,红框只是帮助读者找到错误。 Ionic ion-input 文档
提交时按字段定义的顺序校验。设备编号和维修事项都空,两个都要给提示,键盘只交给排在前面的设备编号。页面用提示旁的文字告诉人怎么改,脚本再去查 Ionic 内部的真实输入。窗口里的红边能帮助定位,但只有实际输入接到键盘才证明聚焦有效。
错误字符串由字段校验函数返回,页面给对应的提示段落设置文本。aria-describedby 把输入和这条提示关联起来,aria-invalid 反映当前错误状态。setFocus 是 Ionic 给自定义输入提供的接口,而 getInputElement 用于取出内部原生节点作验证。日志判断同时兼容焦点出现在文档和组件影子树中的两种情况。在桌面复测时,若样式表有焦点颜色,但日志仍是 false,先看活动节点,再确认调用时组件已加载。
第二按:只改设备号,另一个输入能接上吗

鸿蒙 PC 模拟器全屏,填好编号后,焦点转到维修事项
不先清空原来的框,直接填 DEV-042。下一次点击生成,设备编号旁的提示消失,内容还在原处,光标转给维修事项。页面每次都按提交时的值算错误集合,所以之前排在第一的字段通过以后,不会拦着用户继续改第二项。允许给正在编辑的输入清掉旧提示,也没必要在每个按键后都挪走光标。把自动聚焦放在提交动作上,使用者可以先完整写完手上的字段。
为什么第一遍日志只剩维修事项与预览结果? 我第一次在结束后才一次性筛日志,没拿到首个无效字段的证据。重新启动空页面,并在每步操作后分别保留日志,才完整看到设备编号、维修事项和预览就绪三条记录。对鸿蒙 PC 的焦点问题,应尽量紧贴操作采集,避免拿最后状态推断前面的焦点。
UGC_IONIC_FIELD invalid=asset focused=true
UGC_IONIC_FIELD invalid=reason focused=true
UGC_IONIC_FIELD preview=ready
第三按:生成以后再改一处,会发生什么

鸿蒙 PC 模拟器全屏,两项通过后显示工单预览
一次提交只移动一次焦点
在 MateBook 14 的 1.0.1 签名版上,先保留两项为空,点击「生成预览」。编号和事项都出现提示,光标落在设备编号。此时没有再点输入框,直接键入 DEV-042。字符进入了编号框,配合 focused=true 这条日志,能确认接过键盘的是组件内部真正可输入的节点。

MateBook 14 真机全屏。空表单显示两处提示,焦点落到设备编号。
再次点击生成按钮。编号格式正确,旁边的红字消失,维修事项仍空着,这次焦点转给维修事项。保持鼠标原处,输入 CHECK,再点击生成,预览显示 DEV-042 · CHECK。

MateBook 14 真机全屏。编号补齐后,第二次提交把焦点交给维修事项。

MateBook 14 真机全屏。两项都有效,生成当前工单。
UGC_IONIC_FIELD invalid=asset focused=true
UGC_IONIC_FIELD invalid=reason focused=true
UGC_IONIC_FIELD preview=ready
窄窗中,两个字段按校验顺序从上到下显示。把已提交的 CHECK 改为 RECHECK,旧预览立即替换成「内容已改动,等待再次检查」。最后再次点击按钮,预览才重新显示该值。这个测试把输入有效和用户已经确认这两件事分开了。

MateBook 14 真机窄窗全屏。修改维修事项之后,旧预览失效。

MateBook 14 真机窄窗全屏。重新提交后,新预览使用 RECHECK。
下方录屏是此前真机的工单操作。本轮同机编译出的应用用这五张全屏图和真机日志记录。

预览区在输入改动时会立即回到等待检查的状态。这个细节对短工单很重要。假如先生成一份,再改设备编号,原来的预览就失去了对应关系。将旧结果清掉后,只有重新走一次校验,读者才会在结果区看到当前两项的组合。复测时也可以在成功后改动任意字段,观察页面回到待检查状态。

鸿蒙 PC 模拟器窄窗全屏,字段改为纵向排列,预览仍在
| 提交时的值 | 页面反应 | 模拟器日志 |
|---|---|---|
| 两项都空 | 标出两个错误,先聚焦设备编号 | invalid=asset focused=true |
| 只有 DEV-042 | 设备编号提示消失,焦点转到维修事项 | invalid=reason focused=true |
| DEV-042 和 CHECK | 生成一条本地预览 | preview=ready |
| 生成后收窄窗口 | 两个字段上下排列,预览继续显示 | 全屏截图中的值一致 |
一个空格能算填写完吗? 两项都先去掉两端空白。设备编号要用 DEV- 加三位数字,维修事项至少三个字符。图里的 CHECK 让第二项通过。改动输入以后旧预览退回待检查,下次生成才读当前的两项。这个结果是工单摘要,提交服务端还要另做业务验证。
我参考 GOV.UK 表单示例,把错误放在对应字段旁边,用能直接照做的文字解释怎么修。这个小表单只有两项,生成预览时会把焦点直接送到第一处错误。布局收窄后,显示顺序和校验顺序保持一致,操作者可以从上往下修。示例验证的是这两处输入的焦点移动,未开启屏幕阅读器验收。 GOV.UK 的字段错误提示示例
<!doctype html>
<html lang="zh-CN" mode="md"><head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>维修工单校验</title>
<link rel="stylesheet" href="./ionic/ionic.bundle.css" />
<link rel="stylesheet" href="./css/field.css" />
<script type="module" src="./ionic/ionic.esm.js"></script><script defer src="./js/field.js"></script>
</head><body><ion-app><ion-content><main>
<header><h1>维修工单</h1><p>检查填写内容后,生成本地工单预览。</p></header>
<form id="ticket" novalidate>
<div class="fields">
<div><ion-input id="asset" label="设备编号" label-placement="stacked" fill="outline" required placeholder="例如 DEV-042"></ion-input><p id="asset-error" class="error"></p></div>
<div><ion-input id="reason" label="维修事项" label-placement="stacked" fill="outline" required placeholder="例如 CHECK"></ion-input><p id="reason-error" class="error"></p></div>
</div>
<button id="submit" type="submit">生成预览</button>
</form>
<section aria-labelledby="preview-label"><h2 id="preview-label">工单预览</h2><p id="summary" role="status">填写两项后即可生成。</p></section>
</main></ion-content></ion-app></body></html>
const form = document.querySelector('#ticket');
const summary = document.querySelector('#summary');
const fields = [
{input: document.querySelector('#asset'), message: '填写 DEV- 加三位数字', valid: value => /^DEV-\d{3}$/.test(value)},
{input: document.querySelector('#reason'), message: '维修事项至少填写三个字符', valid: value => value.length >= 3},
];
function setError(input, message) {
document.querySelector('#' + input.id + '-error').textContent = message;
input.setAttribute('aria-invalid', String(Boolean(message)));
}
for (const {input} of fields) {
input.setAttribute('aria-describedby', input.id + '-error');
input.addEventListener('ionInput', () => {
setError(input, '');
summary.dataset.result = '';
summary.textContent = '内容已改动,等待再次检查。';
});
}
form.addEventListener('submit', async event => {
event.preventDefault();
const values = fields.map(({input}) => String(input.value ?? '').trim());
const invalid = fields.map((field, index) => field.valid(values[index]) ? '' : field.message);
fields.forEach(({input}, index) => setError(input, invalid[index]));
const first = invalid.findIndex(Boolean);
if (first !== -1) {
summary.dataset.result = '';
summary.textContent = '请补齐标记的项目。';
const input = fields[first].input;
await input.setFocus();
const native = await input.getInputElement();
const focused = document.activeElement === native || input.shadowRoot?.activeElement === native;
console.info('UGC_IONIC_FIELD invalid=' + input.id + ' focused=' + focused);
return;
}
summary.dataset.result = 'ok';
summary.textContent = values.join(' · ');
console.info('UGC_IONIC_FIELD preview=ready');
});

模拟器实录,从空表单逐步补齐工单并拖窄窗口
此 GIF 保留此前模拟器的焦点变化。当前真机 1.0.1 的连续提交结果见本轮图和日志。
在鸿蒙电脑把工单页面打进 HAP
用鸿蒙版 DevEco Studio 打开 IonicFieldFocus 项目。entry/src/main/resources/rawfile/www/index.html 放两个字段和预览容器,js/field.js 放校验顺序、错误显示和焦点检查,css/field.css 控制宽窄窗布局。Cordova 宿主加载这套网页资源。将 Ionic 8.8.19 的模块、子模块和 CSS 一起放入 www/ionic。
npm pack --ignore-scripts @ionic/core@8.8.19
tar -xzf ionic-core-8.8.19.tgz package/dist/ionic package/css/ionic.bundle.css package/LICENSE
mkdir -p entry/src/main/resources/rawfile/www/ionic
cp -R package/dist/ionic/. entry/src/main/resources/rawfile/www/ionic/
cp package/css/ionic.bundle.css package/LICENSE entry/src/main/resources/rawfile/www/ionic/
ohpm install --all
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap --no-daemon
本轮在同一台鸿蒙电脑复用已由 npm 获取并解包的 Ionic 8.8.19 前端依赖。在编辑区核对 CSS 引用和 script 地址。旧模板里容易残留别的示例入口,若翻到了别的页面,应按实际启动页和页面标题查打包资源,再改校验代码。
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| 环境 | 型号、系统和工具 | 用途 |
| 本轮真机开发 | HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0、aarch64;鸿蒙版 DevEco Studio 26.0.0.220;Ionic 8.8.19、Cordova 14.0.2,目标与兼容 API 24 | 本机编辑、构建、调试签名安装,核验校验后的焦点和预览状态 |
| 此前模拟器 | MateBook Pro 2in1,软件版本 6.1.0.125(SP12DEVC00E47R1P3),API 24、x86_64 | 验证字段顺序和窄窗提示布局 |

MateBook 14 本机终端,Ionic 工单 HAP 完成组装。
在项目结构的「签名配置」为 com.aasd23.ugcionfield 生成调试签名,等同步后选「此电脑」,运行入口模块。输出先显示签名 HAP 的安装路径,再显示应用启动。在系统应用信息核对 1.0.1 和版本代码 1000001,打开「维修工单」再照上面的顺序试。

MateBook 14 本机 DevEco Studio 工程及签名安装的实际输出。

MateBook 14 真机关于本机全屏,供核对完整系统及 API。
FAQ
看到红色轮廓能证明原生输入控件已经聚焦吗? 轮廓也可能来自组件外层样式。提交后先等待 setFocus(),再用 getInputElement() 找内部输入,并检查文档或 Shadow DOM 的活动元素。验收时不再用鼠标点输入框,直接输入,查看文本实际落在哪一项。
第一次填错就要立即判断完整工单吗? 输入处理只清除正在编辑字段的上一条提示,并让预览回到等待检查。提交时才按字段顺序再检查所有值。这样输入到一半时不会一直抢焦点,也不会展示已经过期的预览。
有 aria-invalid 就可以算辅助技术验收通过吗? 本轮只核对视觉提示、原生输入焦点与键盘文字位置。辅助技术如何朗读错误、读出次序如何,仍应另用目标设备和屏幕阅读器验证。
总结
工单从校验结果里挑第一处错误来聚焦,同时保留其余字段的提示。用户修完上一项再提交,焦点可以自然走到下一项。最后再编辑任一字段,已有预览会失效,直到当前内容重新通过检查。实测对应一份本机签名包的连续动作。