自定义节拍课程与持久化的技术封面

把一份节拍器示例做成可以长期使用的练习工具,最后需要解决的往往不是“怎么让声音再响一次”,而是“明天还能不能以同样的设置练一遍”。上一轮练习里,用户已经完成三段课程: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 次强拍,因为更改速度只会改变时间点,不会改变拍位数量。用户在编辑时可以看见目标总拍数;按“保存课程”才生效,按“放弃更改”则恢复上次保存的配置。开始运行后编辑入口暂时禁用,防止未被说明的热更新语义。

PulseCraft 自定义练习页面的 9:16 竖屏效果

产品定义还需要回答最大规模的问题。若允许用户创建上百段,每段设置 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 调整资源加载细节、异常返回类型与设备适配方式。真正完成收官的标准,是下一次打开应用仍能明确地读到合法课程,并且无论用户怎样暂停、编辑或重启,配置不被旧回调和旧草稿悄悄改写。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐