ArkTS + HarmonyOS 声律实验(第 6 讲):自定义课程持久化与节拍训练收官【共创稿事节】

把一份节拍器示例做成可以长期使用的练习工具,最后需要解决的往往不是“怎么让声音再响一次”,而是“明天还能不能以同样的设置练一遍”。上一轮练习里,用户已经完成三段课程:72 BPM 两小节、96 BPM 三小节、120 BPM 两小节。课程时间线固定为 26 个计划拍位,强拍 7 次;事件账本记录的只是应用的调度结果,并不是麦克风录音测出的听觉准确率。现在用户想把中间一段改成 104 BPM,把热身改成 3/4,关闭应用再回来仍保留设置。若把表单输入直接塞给旧调度器,非法值、半编辑状态和运行中的数组变化会同时出现。
“声律实验”第六篇要完成工程收尾:用户能调整有限的课程段落,提交时进行完整校验,持久化成功后才替换活动课程;真正开始播放时固定一次快照,并继续使用第四篇的 buildTimeline()、第二篇的单计时链与 runId、第三篇的 BeatSoundBank,第五篇的 BeatEvent 账本依然只按计划拍位记账。本篇不引入新的音频合成引擎,也不把 UI 定时器描述成专业实时音频设备。工程的重点是配置生命周期和播放生命周期相互隔离,而不在图表上叠更多波形。
一、为什么编辑中课程不能直接驱动播放
假设当前正在第二段的第一个小节,用户把这一段速度从 96 改成 120。若调度器每次回调都读“正在编辑的数组”,同一段前半部分可能按旧速度排队,后半部分又按新速度计算。旧的 startedAt 没有改变,未来目标时刻却被重新生成,导致重复拍位或突然跳过。更糟的是输入框短暂出现 0、空字符串、2.5 这样的中间值;它们对表单编辑合法,却不能直接成为音乐课程参数。正确的结构应分成三份:草稿可以不完整,已保存课程必须合法,正在播放的课程快照在本次练习中保持不变。
这里沿用原有 PracticeStage 的 title、bpm、meter、bars 四个字段,不改变强弱拍规则。目标界面提供“慢速热身 72 BPM / 4拍 / 2小节”“稳定练习 104 BPM / 4拍 / 3小节”“提速收尾 120 BPM / 3拍 / 2小节”。这样的课程总计仍有 26 拍、7 次强拍,因为更改速度只会改变时间点,不会改变拍位数量。用户在编辑时可以看见目标总拍数;按“保存课程”才生效,按“放弃更改”则恢复上次保存的配置。开始运行后编辑入口暂时禁用,防止未被说明的热更新语义。

产品定义还需要回答最大规模的问题。若允许用户创建上百段,每段设置 64 个小节,buildTimeline 会生成大量 PracticeMark,一次全部展开增加内存和遍历压力。本文面向轻量日常练习,限制最多 8 段、每段最多 16 小节,速度 40~240 BPM,拍号只支持 3/4 与 4/4。这些都是应用自己的边界,不是系统对音乐格式的法定限制。扩展复杂拍号与大型课程时,应重新评估数据结构和节拍组织方式。
二、把“可保存”定义成一套纯函数契约
PracticePlan.ets 已提供 PracticeStage 与 buildTimeline();新增 CourseDraft.ets 负责校验和复制,不要把规则写在 TextInput 的每次 onChange 回调里。编辑字段最终转换成数字之前必须检查整数、范围以及空白标题。校验通过时再预计算一次目标拍位;若计算结果异常,提交立即失败,绝不进入存储。
// entry/src/main/ets/common/practice/CourseDraft.ets
import { PracticeStage, PracticeMark, buildTimeline } from './PracticePlan';
export interface SavedCourse {
schema: number;
title: string;
stages: PracticeStage[];
}
export function copyCourse(source: SavedCourse): SavedCourse {
return {
schema: source.schema, title: source.title,
stages: source.stages.map((s: PracticeStage): PracticeStage => ({
title: s.title, bpm: s.bpm, meter: s.meter, bars: s.bars
}))
};
}
export function validateCourse(course: SavedCourse): number {
if (!course || course.schema !== 1 ||
typeof course.title !== 'string' || !course.title.trim() ||
course.title.length > 32 || !Array.isArray(course.stages) ||
course.stages.length < 1 || course.stages.length > 8) {
throw new Error('课程标题或段落数量不合法');
}
for (const s of course.stages) {
if (!s || typeof s.title !== 'string' || !s.title.trim() ||
s.title.length > 20 || !Number.isSafeInteger(s.bpm) ||
s.bpm < 40 || s.bpm > 240 ||
(s.meter !== 3 && s.meter !== 4) ||
!Number.isSafeInteger(s.bars) || s.bars < 1 || s.bars > 16) {
throw new Error('段落配置有误');
}
}
const marks: PracticeMark[] = buildTimeline(course.stages);
return marks.length;
}
这段代码不能省掉 copyCourse()。如果草稿和已保存配置引用同一个 stages 数组,用户点“放弃更改”只能把输入框文字改回去,却可能已经通过对象引用把已保存课程内容改掉。提交后复制一次用于活动状态,播放开始时再复制一次给运行会话。对于大量对象,深拷贝的成本需要衡量;但每份最多八段的练习配置,用显式字段复制可以减少对序列化副作用的依赖。
校验返回的是计划拍数,便于用户在确认前理解课程规模。例如三段分别有 2×4、3×4、2×3 个拍位,合计 26;三个段落各有 2、3、2 个小节,总计 7 个强拍。只有输入合法时才显示计算结果。假如用户删除所有段落,表单提示“至少保留一个段落”;若把 BPM 改成 0,应该指出“速度需在 40 到 240 之间”,而不是发出一个听不到声音的计时任务。这样不仅方便用户,也为后续自动化单元测试准备了稳定函数边界。
例如页面初次进入时,可以用一份清晰的默认值初始化活动课程,避免各处复制一组互相不一致的数字。它仍然由早前 PracticeStage 模型构成,速度变化只影响各个 atMs,不会凭空增加一个拍位。
export const DEFAULT_COURSE: SavedCourse = {
schema: 1,
title: '三段节拍课程',
stages: [
{ title: '慢速热身', bpm: 72, meter: 4, bars: 2 },
{ title: '稳定练习', bpm: 104, meter: 4, bars: 3 },
{ title: '提速收尾', bpm: 120, meter: 3, bars: 2 }
]
};
三、Preferences 只保存配置,不接管实时节拍
轻量课程适合使用应用私有 Preferences 保存 JSON 文本,沿用前面章节已经解释过的 getPreferencesSync()、getSync()、put() 和 flush()。但这份配置与第五篇 BeatEvent 账本属于两种数据:课程是未来的计划,账本是一次运行的事件;不能把运行中每拍的事件都塞进 course_config_v1 再反复刷新。本文只保存一个已确认课程,便于控制存储规模与迁移边界。
// entry/src/main/ets/common/practice/CourseStore.ets
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
import { SavedCourse, copyCourse, validateCourse } from './CourseDraft';
export class CourseStore {
private prefs: preferences.Preferences;
private readonly key: string = 'course_config_v1';
constructor(context: common.UIAbilityContext) {
this.prefs = preferences.getPreferencesSync(context,
{ name: 'pulsecraft_prefs' });
}
read(fallback: SavedCourse): SavedCourse {
const raw: string = this.prefs.getSync(this.key, '') as string;
if (!raw) { return copyCourse(fallback); }
const parsed: SavedCourse = JSON.parse(raw) as SavedCourse;
validateCourse(parsed);
return copyCourse(parsed);
}
async save(source: SavedCourse): Promise<void> {
validateCourse(source);
const json: string = JSON.stringify(copyCourse(source));
await this.prefs.put(this.key, json);
await this.prefs.flush();
}
}
注意读取错误时没有“自动删除重置”。如果旧 JSON 被损坏,静默改写成默认课程,会使用户以为自己长期调试的练习方案消失。读取应在页面上报告错误并冻结覆盖保存,待用户选择明确的恢复策略。再强调一次,put 的返回不能代替 flush 的完成;只有后者成功后,页面才能提示“课程已保存”。若应用未来保存多份课程,Preferences 的单键覆盖就不适合管理历史版本,应设计数据库主键和迁移方案。
界面调用应守住一个事务顺序:先 validateCourse(draft),然后 await store.save(draft),成功后才把 activeCourse 设为副本,再更新状态提示。失败时 draft 保留,activeCourse 原封不动。如果快速连点保存按钮,使用 saving 状态挡住并发写入。关闭页面时还要区分“已经保存的配置”和“尚未保存的编辑草稿”;默认丢弃未提交修改可以保持语义简单,但应在导航离开时提示,而不是悄悄让草稿看似永久存在。
// entry/src/main/ets/pages/Index.ets(沿用上一版播放器成员)
@State private saving: boolean = false;
@State private configHint: string = '编辑后保存即可生效';
@State private activeCourse: SavedCourse = copyCourse(DEFAULT_COURSE);
@State private draftCourse: SavedCourse = copyCourse(DEFAULT_COURSE);
private courseStore: CourseStore | null = null;
private async saveDraft(): Promise<void> {
if (this.running || this.saving || this.courseStore === null) { return; }
this.saving = true;
try {
const candidate: SavedCourse = copyCourse(this.draftCourse);
const planned: number = validateCourse(candidate);
await this.courseStore.save(candidate);
this.activeCourse = copyCourse(candidate);
this.configHint = `已保存,共 ${planned} 拍`;
} catch (_) {
this.configHint = '课程未保存,请核对输入或重试';
} finally { this.saving = false; }
}
private startSavedCourse(): void {
if (this.running || this.saving) { return; }
const session: SavedCourse = copyCourse(this.activeCourse);
this.marks = buildTimeline(session.stages);
this.beatEvents = [];
this.cursor = 0;
this.startedAt = Date.now();
this.runId++;
this.running = true;
this.queueNext(this.runId);
}
这里直接调用第四篇的 queueNext(),没有复制一份 setInterval。播放器里停止按钮仍须调用旧方法:先设置 running = false,然后 runId++,清除本次 timerId;页面生命周期销毁时也执行相同取消规则。后台时 UI 定时器会被冻结,恢复后必须由旧的迟到拍位策略跳过历史位置,不能为了“补齐进度”播放一串密集短音。第五篇的账本按本次会话清空后重新记录,报表就不会把上一轮练习的事件算进新课程。
四、把音频异常和配置异常分开验证
这一版的回归不能只看“保存按钮变绿”。第一组测试修改第二段 BPM 为 104 并保存,重新进入页面,预期第二段显示 104,而热身和收尾维持原值。第二组在编辑中把第二段 BPM 清空,点击保存,必须保持 activeCourse 原值且不能启动播放;恢复合法数值后再提交,才允许开始。第三组在播放中尝试更改课程,编辑入口应禁用或保持为下次练习的独立草稿,当前 marks 和已开始的时间线必须不变。
第四组专门验证音频资源不可用:如果 BeatSoundBank 的强拍短音尚未完成加载,当前拍位应根据第五篇的账本规则记为 muted 或相应失败状态,而不是把声音问题误诊为 Preferences 写入失败。SoundPool 可用来播放低时延短音,但官方说明它不支持后台播放,也不能仅凭 play() 的 Promise 推断声音到达耳朵的时间。因此本例只报告调度事件与播放请求,不给出没有设备测量依据的“节奏精度百分比”。

最后执行极端参数验证:9 段、0 小节、241 BPM、非 3/4 或 4/4 的拍号、空标题、损坏 JSON、存储 flush() 抛错。每一类都应停在相应的边界,不生成非法时间线,不清除用户已保存的课程,也不默默显示“保存成功”。测试记录可包括课程段落、计算的拍位总数、保存结果、播放中是否禁止编辑和报表事件分类;没有真实设备数据时不应填写想象中的 FPS、抖动毫秒数或音频时延。
从第一篇的速度与拍号控件,到第二篇的单计时链、第三篇的短音池、第四篇的时间线、第五篇的事件账本、第六篇的可恢复课程配置,PulseCraft 最终得到一条清晰的责任链:配置负责定义计划,校验负责拒绝非法输入,调度负责推进索引,短音池负责请求播放,账本负责说明发生了什么。它仍是一款前台音乐练习示例,而非后台播放器或专业音频时钟;后续若要求采样级同步,应转向具备明确实时保障和可测量硬件输出的音频方案,不能在 UI 定时器上堆更多 setTimeout。
参考华为开发者官方 Preferences 接口、Timer 接口 与 SoundPool 接口。实际 DevEco Studio 工程须按安装的 SDK 调整资源加载细节、异常返回类型与设备适配方式。真正完成收官的标准,是下一次打开应用仍能明确地读到合法课程,并且无论用户怎样暂停、编辑或重启,配置不被旧回调和旧草稿悄悄改写。
更多推荐

所有评论(0)