HarmonyOS 6 按段读取包内数据:河湾第一次失败,游标该停在哪
配套工程源码、测试材料与运行说明
前言 河岸观测簿第一次读上游成功,第二次在打开河湾数据之前触发一次演示故障。按重试,出现的是河湾,下一次才是下游。我想验证的不是按钮能不能再点,而是失败以后游标留在哪一段。下面这张记录同时数成功交付、按钮尝试和进入资源读取。三列里只有该变化的列变化,才有证据说清落在了哪个分支。
先记住河湾没读到的那一行
| 复测检查点 | 已读段 | 尝试 | 进入资源读取 |
| 刚打开 | 0 | 0 | 0 |
| 上游成功 | 1 | 1 | 1 |
| 河湾首次失败 | 1 | 2 | 1 |
| 重试河湾 | 2 | 3 | 2 |
| 下游成功 | 3 | 4 | 3 |

第二步能看出等待是否挡住了重复点击。脚本在同一位置连续点两下读下一段,再等一段时间核对状态,最后「尝试」只增加了一次,资源函数没有被叫。原因不是界面表面上一定禁用:按钮本身还有可用条件,方法内部才用 waiting 把正在处理的一轮保护起来。进入方法之前和之后分别看,就知道失败是有一轮确实尝试过、另外一次未排队。当这个结果出现「这一段没有读到」时,页面已经保留上游,不应该冒出两个河湾项或跳到下游。
运行的是 MateBook Pro API 24 模拟器,系统 6.1.0.125(SP12DEVC00E47R1P3)。这个失败由代码安排在第二段真正读磁盘资源之前,所以尝试变成二,资源读取还没增加。若把第二段改成一份打不开的文件,进入读取时会记一次而仍交付失败,结果当然不是这张表。三个数分开记录,就是为了查失败发生在入口、I/O 还是最后状态提交。
给每一段一份可独立读取的数据
为了能在没有服务器的情况下复跑,我把三段各存成一个 JSON,放进应用的 rawfile。每份两条站点观测,构建时都在包里。起始页只显示工具和状态,没有先解析三份内容。点下一段时根据 cursor 选文件。这个做法测试的是读取与解析时机,不会减少安装包本来带的资源。如果真实项目想省网络和安装体积,素材该怎么交付需要另做选择。
from pathlib import Path
import json
raw=Path(__file__).resolve().parent/'project/entry/src/main/resources/rawfile'
raw.mkdir(parents=True,exist_ok=True)
data={
'upper.json': [('01','白石湾','12.6','水面平稳'),('02','旧渡口','12.9','背风岸')],
'bend.json': [('03','青苔桥','13.2','浅滩入弯'),('04','竹汀','13.4','阴面回流')],
'lower.json': [('05','芦洲','14.1','水面渐宽'),('06','潮界','14.4','接近河口')],
}
for name, rows in data.items():
values=[dict(id=i,point=p,water=w,note=n) for i,p,w,n in rows]
(raw/name).write_text(json.dumps(values,ensure_ascii=False,indent=2)+'\n',encoding='utf8')
把上方脚本存为 make_readings.py,按原样放在 project 目录旁,运行 python make_readings.py。它会写出 project/entry/src/main/resources/rawfile/upper.json、bend.json、lower.json。路径依赖脚本自身位置。如果你将代码拷进一个不叫 project 的空白工程,要改脚本中的输出路径。打包前用 PAGES 对一遍名字,特别是 bend.json。这样遇到河湾失败时,已经知道正式资源在包里,首次故障来自程序插入的反例。
追三张运行画面时,可以用站名检查到底交付了哪页。上游有白石湾和旧渡口,重试后的河湾应出现青苔桥、竹汀,最后才有芦洲和潮界。采样表的 1、2、3 检查进度,这组不同名字帮读者识别上一段是否被重复追加。将材料换成自己的数据,也留两个肉眼能辨认的字段,当游标错了可以直接从截图看出。
资源列表在这篇由程序设置,读文件并未接受用户外部传来的路径。文件名的选择与页号同行。把观测簿接到真实数据后,如果页由服务端解出,应保留接口中给的页键,避免把最终显示用的水位名称当作磁盘路径。资源读取接口与解析接口也可以分别记录一次耗时:有时慢的是解码大量文本,磁盘只用了一小段时间。对本例而言主要想让失败重放,所以不从 650 毫秒夹具估出真实的读取开销。
游标只能在数据交付时前进
private async nextPage(): Promise<void> {
if (this.waiting || this.cursor >= PAGES.length) return;
const page = this.cursor;
const token = ++this.nonce;
this.waiting = true;
this.problem = false;
this.attempts++;
try {
// 人为留出等待窗口,让重入和失败分支可复现。
await new Promise<void>((resolve: () => void) => { setTimeout(() => resolve(), 650); });
if (token !== this.nonce) return;
if (page === 1 && this.failOnce) {
this.failOnce = false;
throw new Error('模拟暂时读不到第二段');
}
const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
this.loads++;
const bytes = await context.resourceManager.getRawFileContent(PAGES[page]);
代码先把 this.cursor 复制到本次 page,资源名就固定在这一轮。异步等待之间即使另一处重置了 cursor,本轮也不会把新游标误当旧任务的目标。轮次数字主要保护写回而不是取消已经分派的设备调用,你仍然可能在系统日志看到一次旧读取结束。对这个本地样本,避免迟到回写比打开一大套取消 API 直接;若换成网络请求,可能还要在退出时发起真正的取消以节省资源。可以分别断言不会再读取和不会改当前画面,这两个结果不必总是一致。
进入 nextPage 先挡住正在等待或已经到末尾的请求,再保存这一轮使用的页号和 nonce。界面切到等待,尝试数加一。为了方便重放,代码让处理先等 650 毫秒。等待后若 token 已失效直接返回;若这是第一回河湾则故意报错。这个窗口是测试夹具,移入产品前应改成实际 I/O 等待,不要拿这段固定等候做真实加载性能的比较。
const bytes = await context.resourceManager.getRawFileContent(PAGES[page]);
if (token !== this.nonce) return;
const text = util.TextDecoder.create('utf-8').decodeToString(bytes, { stream: false });
const pageRows = JSON.parse(text) as Reading[];
if (!Array.isArray(pageRows) || pageRows.length === 0) throw new Error('无有效观测数据');
this.readings = [...this.readings, ...pageRows];
this.cursor = page + 1;
从资源管理器收字节之后再比一次 token,才解码并解析。样例只接受非空数组,最后才追加到 readings,把 cursor 移到 page 加一。如果把游标提前加一,重试会进到下游,之前的观测丢了一段。如果只在读之前比较轮次,旧任务跨过 await 后仍有写回机会。用户返回起点时,rewind 先让旧 token 作废,再清页面及计数,并恢复演示的一次性失败标记。离开组件也让旧任务失效。
cursor 记的是已经交付的河段数,readings 才保存观测行。每段两条,所以成功时 1 / 3 对应两条记录,最终 3 / 3 是六条。若按钮显示三段已经读完,列表却只出现五条,应查 JSON 的条目以及追加结果,不能只把页号改成正确的值就算修好了。

返回起点以后,谁能结束等待
finally 也检查 token,只有归属当前轮才能把 waiting 改回 false。设想旧河湾读取尚未完成,用户按返回起点,然后开始上游的新读取。旧任务如果来得快,先执行没有保护的 finally,就会解开新任务的锁。此时再点一次,即使新请求还没结束,入口也可能接到第二个。可以用相同延迟或可控替身模拟这个先后,把当前游标、按钮的等待标记和最后内容分别记录。若应用还支持换筛选条件,也应让当前任务和筛选身份一起有效。
顺手区分一下等待锁和故障提示。开始本轮时清掉旧 problem,是为了让读者知道已经重试,而不是仍显示上一次失败。如果这次失败才再展示它。旧任务的 catch 也要看 token,否则退回上游并读取成功以后,旧河湾的失败提示可能最后才冒出来。测试可以把失败模拟器设成慢返回,重进后看新页是否还会被旧错误打断。故障提示、已读列表和下一页按钮三处就都覆盖了。

动态列表常在等新页时还要保留旧段。比如河湾错误后已读仍是 1,用户可以继续查看上游两条数据。若进入等待前先清空 readings,用户看到的会像整个观测簿被破坏,而不是只缺了下一页。当前写法只在最后 append,错误时只改变 problem。上线接服务时宜同时记录错误属于哪一个查询键,避免重试按钮把旧筛选下的提示放到当前列表。能查数据和能交付数据是两个不同阶段,前者增加发生次数,后者才移动游标。
从本地三段迁到服务端游标
文首项目在 rawfile 带了上游、河湾和下游三个 JSON。用 API 24 运行 entry,连续点下一段,状态应当先进上游,然后保留上游并提示河湾失败。点重试后通过 resourceManager.getRawFileContent 读取河湾,解码和解析通过以后再递增下次读取位置。第三段读完按「回到起点」,确认总段数、读取次数和故障注入一起复位。对接服务端时可保留同样的提交原则,把索引的位置换成响应提供的游标。
import { common } from '@kit.AbilityKit';
import { util } from '@kit.ArkTS';
interface Reading {
id: string;
point: string;
water: string;
note: string;
}
const PAGES: string[] = ['upper.json', 'bend.json', 'lower.json'];
@Entry
@Component
struct Index {
@State readings: Reading[] = [];
@State cursor: number = 0;
@State loads: number = 0;
@State attempts: number = 0;
@State waiting: boolean = false;
@State problem: boolean = false;
private nonce: number = 0;
private failOnce: boolean = true;
aboutToDisappear(): void {
this.nonce++;
}
private rewind(): void {
this.nonce++;
this.readings = [];
this.cursor = 0;
this.loads = 0;
this.attempts = 0;
this.problem = false;
this.waiting = false;
this.failOnce = true;
}
private async nextPage(): Promise<void> {
if (this.waiting || this.cursor >= PAGES.length) return;
const page = this.cursor;
const token = ++this.nonce;
this.waiting = true;
this.problem = false;
this.attempts++;
try {
// 人为留出等待窗口,让重入和失败分支可复现。
await new Promise<void>((resolve: () => void) => { setTimeout(() => resolve(), 650); });
if (token !== this.nonce) return;
if (page === 1 && this.failOnce) {
this.failOnce = false;
throw new Error('模拟暂时读不到第二段');
}
const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
this.loads++;
const bytes = await context.resourceManager.getRawFileContent(PAGES[page]);
if (token !== this.nonce) return;
const text = util.TextDecoder.create('utf-8').decodeToString(bytes, { stream: false });
const pageRows = JSON.parse(text) as Reading[];
if (!Array.isArray(pageRows) || pageRows.length === 0) throw new Error('无有效观测数据');
this.readings = [...this.readings, ...pageRows];
this.cursor = page + 1;
} catch (_) {
if (token === this.nonce) this.problem = true;
} finally {
if (token === this.nonce) this.waiting = false;
}
}
build() {
Column({ space: 17 }) {
Row() {
Column({ space: 6 }) {
Text('河岸观测簿').fontSize(44).fontWeight(FontWeight.Bold).fontColor('#E7F8FC')
Text('从上游到下游 · 分段读取').fontSize(17).fontColor('#BFE5EC')
}.alignItems(HorizontalAlign.Start).layoutWeight(1)
Column() {
Text(this.cursor + ' / 3').id('river-cursor').fontSize(36).fontWeight(FontWeight.Bold).fontColor('#F8DE9C')
Text('已读河段').fontSize(15).fontColor('#BFE5EC')
}.alignItems(HorizontalAlign.End)
}.width('100%').padding(24).backgroundColor('#10465E').borderRadius(12)
List({ space: 0 }) {
if (this.readings.length === 0) {
ListItem() {
Text('观测簿还没有打开。先读第一段。').fontSize(19).fontColor('#335567')
.padding(22).width('100%').height(66)
}
}
ForEach(this.readings, (reading: Reading) => {
ListItem() {
Row({ space: 16 }) {
Text(reading.id).width(42).fontSize(15).fontColor('#156C7A').fontWeight(FontWeight.Bold)
Column({ space: 3 }) {
Text(reading.point).fontSize(20).fontWeight(FontWeight.Medium).fontColor('#163949')
Text(reading.note).fontSize(14).fontColor('#476674')
}.alignItems(HorizontalAlign.Start).layoutWeight(1)
Text(reading.water + ' °C').fontSize(23).fontColor('#194C62')
}.width('100%').height(58).padding({ left: 18, right: 18 })
.border({ width: { bottom: 1 }, color: '#BCD8DA' })
}.id('river-' + reading.id)
}, (reading: Reading): string => reading.id)
}.width('100%').height(354).backgroundColor('#F3FAF9').borderRadius(10).clip(true)
Row({ space: 10 }) {
Button(this.problem ? '重试这一段' : (this.waiting ? '正在读取' : '读取下一段'))
.id('river-next').enabled(this.cursor < PAGES.length).onClick(() => { this.nextPage(); })
.backgroundColor('#10465E').fontColor('#FFFFFF')
Button('回到起点').id('river-reset').onClick(() => this.rewind())
.backgroundColor('#CFE9E9').fontColor('#16485A')
Blank()
Text('尝试 ' + this.attempts + ' 次 · 资源读取 ' + this.loads + ' 次')
.id('river-reads').fontSize(15).fontColor('#295361')
}.width('100%')
Text(this.problem ? '这一段没有读到,已显示的记录不变。' :
(this.cursor === PAGES.length ? '已到下游末段' : '继续读取时才打开下一个数据文件'))
.id('river-status').fontSize(15).fontColor(this.problem ? '#9A332C' : '#295361').width('100%')
}.width('100%').height('100%').padding({ left: '7%', right: '7%', top: 21, bottom: 20 })
.backgroundColor('#E0F0EF').align(Alignment.Top)
}
}
完整程序放在 entry/src/main/ets/pages/Index.ets,保留默认 Stage 路由。安装后看右上角「0 / 3」,尝试和读取都为零。成功读取上游以后在河湾按两下,保留失败时上游仍存在的画面。下一次只按一次,等状态离开等待再确认 2 / 3,最后下游显示「已到下游末段」,下一段不可用。每一次都等状态变化后再截,不能只凭一张最终的 3 / 3 推断重试做对了什么。若点「回到起点」测试新的一轮,除了文本清零,还要看河湾的模拟故障是否重新生效。源码中的 rewind 会把 failOnce 设回 true,这样下次仍能复现第一次失败。
这份计数也适合给团队做排查练习。将第二段文件改成错误 JSON,重试应该仍找原段,但资源读取次数会与人为失败不同。若资源已经读取、解析也成功,反而列表不增,可以暂留一条记录说明所读条目数和本轮 token,查看是否被重置保护挡掉。这样分层查问题,不需要在每次点击时输出整份观测原文。正文复测数来自原样例,替换材料后读到的结果应另记为负例。
如果服务返回分页重叠,按稳定站点 ID 决定覆盖、去重还是保留两条独立观测。两轮数据观测点相同但时间不同,ID 可以包括稳定版本或时间键,不能只按名称去重。末尾页也可能返回空数组表示结束。当前本地样本以已知 PAGES 数量为边界,服务器的空页语义要由接口约定,不要把这个例子里「空数组当异常」直接套过去。
缓存策略可以沿同一思路继续。退回上一步时愿意复用已经读过的河湾,就应该留下当时那一版的观测,同时使新的异步返回认得当前筛选。返回起点如果就是要清空,可以像此处一样让旧轮次失效。如果预计同一会话不断读新段,还要限制驻留的旧段,例如仅保留附近页和已经收藏的观测。缓存多久是另一个选择,和每次只读取下一页可以分别测试。只盯着读取次数,会看不出长会话是不是一路把所有记录留在了内存里。
错误样本至少可以留下三组。入口还没读取就失败,次数会形成这篇的分布;读取后才发现 JSON 无效,资源读数应多一次;下一页已经读完又切换筛选,旧内容不能追加。最后恢复正常供给再读一遍,看看重试既恢复数据,又没有吞掉一次点击。三组请求若用同一轮记录比对,记得同时留下任务编号。
FAQ|预先读上游,结果还算懒加载吗? 首屏如果需要一段,首次只准备那一段也能减少前置工作。这篇刻意等用户按键,便于看到零次读取与后续结果。真实项目应把打开后一屏的等待、滑到加载边界的反馈和实际 I/O 数分开记录。放在首屏以前做的工作,最多只是挪了时机,要看用户是不是更舒服。
FAQ|两条样本很小,为什么还有加载队列? 两条方便肉眼核对有没有缺失,不是线上建议页长。线上页长取决于行渲染成本、请求开销和用户滑动速度。先拿真实数据复跑,确认首次可用不慢,继续滑动没有长时间空白,页面退出后也能按需求释放不用的段落。
生产测试可以再加一条末页以后的输入。即使有快捷键或辅助入口绕过灰掉的按钮,nextPage 仍应检查 cursor 没有超出 PAGES。这个保护与是否处于等待是两个条件,录图时末段出现后应逐一确认。
总结 河湾第一次没到手,下一轮仍然从河湾开始。把成功路线的更新集中在一个地方,再让旧轮次连收尾也不能改新页面。这样的失败比只看最后三段都显示,更能检验按需读取是否正确。
更多推荐
所有评论(0)