工具型应用增加阅读内容时,真正难的不是多放几段文字,而是避免新功能反过来污染主流程。文章目录如果可被页面随意修改,返回阅读页时顺序就可能变化;语音引擎如果在离页后继续初始化,用户已经回到转盘页却突然听到朗读;自动播放计时任务如果没有取消,快速返回也可能在后台触发;收藏若直接把整篇文章复制进 Preferences,正文更新后又会出现两份内容来源。

本文基于“转盘决定吧”1.0.9 的真实源码,沿 ReadingLibrary.ets、Reading.ets、ReadingVoiceService.ets 与首页路由入口还原阅读小站。当前工程已经实现四篇静态文章、手机与宽屏布局、字号调整、中文音色候选、最长 220 个代码单元的文本切段、逐段朗读以及离页停止。需要特别说明:源码中尚没有收藏字段、收藏按钮或收藏持久化服务;本文会把这一事实明确标出,再给出只保存稳定文章 ID 的扩展边界,不会把建议写成现有功能。

阅读与朗读能力隔离封面

文章围绕五个问题展开:

  1. 静态文章目录怎样保持单一来源,不被页面原地改写。
  2. 阅读页怎样用独立路由和局部状态接入,而不依赖转盘结果与历史服务。
  3. 中文长文怎样切成可连续提交给 Core Speech Kit 的片段。
  4. 语音引擎创建、回调推进、停止与离页之间怎样建立会话边界。
  5. 收藏尚未实现时,怎样按文章 ID 增加能力而不复制正文。

可核验环境:工程现存的 report-202606131742406040.json 记录了 SDK 6.0.2.130(API 22)、Hvigor 6.22.3、Node.js 25.9.0,以及当次 release assembleApp 成功。本轮只阅读源码并精修文章,没有重新构建、安装或运行应用,因此不把历史报告当作本轮验证。示例中的类名和状态来自真实工程;带“扩展写法”或“建议实现”的片段只说明下一步设计。

源码事实与建议实现的边界

本文以“阅读小站分段朗读隔离契约”作为唯一核对标记,先把已存在能力与演进建议分开:

分类可由当前源码确认的内容本文不作的推断
当前源码事实ReadingLibrary 内置四篇文章,articles() 返回静态数组,findById() 未命中时回退首篇不据此宣称支持在线目录、搜索、同步或动态更新
当前源码事实Reading 页面具有字号档位、宽窄布局、450 毫秒自动播放、播放忙碌态,离页时调用 stop() 并解绑单一监听器不据此宣称自动播放计时器已取消,或异步引擎初始化已具备会话隔离
当前源码事实ReadingVoiceService 查询中文音色,离线候选优先于在线候选;标题、摘要和正文按 220 个代码单元上限切段,再通过完成回调推进不据此宣称所有设备都具备可用离线音色,也不虚构真机播放结果
建议实现目录快照、可空查找、会话号、请求 ID 核对、计时器清理、可取消订阅、引擎错误后重建、仅保存文章 ID 的收藏服务这些代码用于说明边界,当前项目尚未实现,尤其不能把收藏描述成现有功能
验证边界本轮未执行构建、真机语音、断网、离页竞态或 AppGallery 发布验证不报告未实际发生的构建、运行、兼容性、质量或发布数据

后文使用“当前”时只陈述已读取文件可以证明的行为;出现“应”“可以”“建议”时,均指待实现方案。这样既能讨论生命周期风险,也不会把理想设计写成已经交付的能力。

一、先确认当前阅读功能的真实边界

首页通过独立路由进入阅读页:

router.pushUrl({ url: Routes.READING });

首页还有一个“立即播放”入口,把布尔参数传给同一页面:

router.pushUrl({
  url: Routes.READING,
  params: { autoPlay: true }
});

阅读页只依赖文章目录和语音服务,不写转盘选项,不新增决定历史,也不改变主导航状态。页面自身保存 selectedId、字号档位、播放状态和自动播放标记。这种接入方式的价值在于:阅读是一个完整但独立的功能岛,退出页面以后应当停止持有音频会话。

选择文章到逐段朗读的运行流程

当前能力可以按源码逐项列清楚:

能力当前状态代码位置
四篇内置文章已实现ReadingLibrary.ITEMS
文章选择已实现selectedId 与 ArticleCard
字号增减已实现fontStep
中文语音朗读已实现ReadingVoiceService
路由自动播放已实现autoPlay 参数与 450 毫秒延迟
离页停止已实现aboutToDisappear()
阅读收藏当前未实现无收藏字段、服务或存储键

二、ReadingArticle 是内容契约

文章模型由稳定 ID、标题、摘要、标签、阅读分钟数和正文段落组成:

export class ReadingArticle {
  id: string = '';
  title: string = '';
  summary: string = '';
  tag: string = '';
  minutes: number = 1;
  paragraphs: string[] = [];

  constructor(
    id: string,
    title: string,
    summary: string,
    tag: string,
    minutes: number,
    paragraphs: string[]
  ) {
    this.id = id;
    this.title = title;
    this.summary = summary;
    this.tag = tag;
    this.minutes = minutes;
    this.paragraphs = paragraphs;
  }
}

id 如 gentle-choice、tiny-ritual 不承担展示任务,适合作为列表标识、当前选中项、收藏索引和未来深链参数。标题可能修改,标签可能重新归类,正文也可能更新,但稳定 ID 不应跟随文案变化。

阅读小站不干扰主工具的关键,是让文章目录保持只读,让收藏只依赖稳定文章 ID,并让每次语音会话在切文、离页或新会话开始时显式失效。

三、静态目录适合当前内容规模

ReadingLibrary 内置四篇文章,主题分别是缩小选择问题、给随机结果一点仪式感、朋友局随机玩法和每日轻量重启。每篇文章有摘要、标签、预计分钟数和三段正文,随应用版本一起发布。

private static readonly ITEMS: ReadingArticle[] = [
  new ReadingArticle(
    'gentle-choice',
    '选择困难时,先把问题变小',
    '把大决定拆成今天能试的一小步,转盘的结果就更像提示,而不是压力。',
    '决策方法',
    3,
    [
      '当一个问题让人迟迟不敢开始……',
      '例如“我要不要换一种生活方式”……',
      '如果抽到的结果让你明显抗拒……'
    ]
  )
];

四篇短文、无需搜索、无需在线更新时,ArkTS 静态目录很合适:没有异步加载,不需要额外页面状态,内容与版本天然一致。若以后文章增长到数百篇,再考虑资源 JSON、本地仓库或分页;当前不必为了未来可能性增加复杂数据层。

四、目录接口不应暴露共享可变数组

当前 articles() 直接返回静态数组:

static articles(): ReadingArticle[] {
  return ReadingLibrary.ITEMS;
}

页面目前只读取它,所以运行正常。但调用方如果执行 sort()、splice() 或给 paragraphs 追加内容,就会改写全局目录。重新进入页面后取得的仍是被修改过的引用。

最小改进是返回独立快照:

static articles(): ReadingArticle[] {
  return ReadingLibrary.ITEMS.map((item: ReadingArticle) => {
    return new ReadingArticle(
      item.id,
      item.title,
      item.summary,
      item.tag,
      item.minutes,
      item.paragraphs.slice()
    );
  });
}

外层数组和段落数组都复制,页面可以安全排序或筛选。更严格的做法是把目录声明为 readonly 接口,让业务代码在编译阶段就无法修改。

五、未知文章 ID 不应总是静默回到第一篇

当前查找方法在未命中时返回首篇文章:

static findById(id: string): ReadingArticle {
  const found = ReadingLibrary.ITEMS.find((item: ReadingArticle) => item.id === id);
  if (found !== undefined) {
    return found;
  }
  return ReadingLibrary.ITEMS[0];
}

页面默认 ID 来自同一目录,正常交互不会出错。问题出现在收藏恢复、深链或内容下线:保存的旧 ID 已不存在时,用户会被静默带到第一篇,看不出原文章已经失效。

可以把查找和默认选择分开:

static findById(id: string): ReadingArticle | undefined {
  return ReadingLibrary.ITEMS.find((item: ReadingArticle) => item.id === id);
}

static defaultArticle(): ReadingArticle {
  const first = ReadingLibrary.ITEMS[0];
  if (!first) {
    throw new Error('Reading library is empty.');
  }
  return first;
}

页面首次进入显式使用默认文章,恢复旧 ID 时则能展示“文章已更新或下线”的状态。

六、阅读页只保存短期界面状态

页面状态如下:

@State articles: ReadingArticle[] = ReadingLibrary.articles();
@State selectedId: string = ReadingLibrary.defaultArticleId();
@State fontStep: number = 0;
@State voicePlaying: boolean = false;
@State voiceBusy: boolean = false;
@State voiceStatus: string = '点击播放开始朗读';
@State autoPlayHandled: boolean = false;

文章选择、字号、按钮进行中状态都属于当前页面会话,不需要写入转盘服务或决定历史。只有 currentBreakpoint 通过 @StorageProp 从全局布局状态读取。这样的状态所有权很清楚:主工具无需知道用户正在看哪篇文章,也不应因阅读页的语音回调重新渲染。

如果未来需要记住字号,可以增加单独的阅读设置键;不要把它塞进转盘选项或历史记录结构。

七、宽屏与手机采用不同信息顺序

页面通过断点判断宽屏:

private isWide(): boolean {
  return this.currentBp !== 'sm';
}

lg 使用最大 1120vp、文章列表宽 340vp;md 使用最大 840vp、列表宽 292vp。宽屏中列表和阅读器左右并排,手机中先展示阅读器,再在下方展示文章列表。

if (this.isWide()) {
  Row() {
    Column() { this.ArticleList(); }
      .width(this.listPaneWidth());
    Column() { this.Reader(); }
      .layoutWeight(1)
      .margin({ left: 16 });
  }
} else {
  Scroll() {
    Column() {
      this.Reader();
      Column() { this.ArticleList(); }
        .margin({ top: 14 });
    }
  }
}

这让阅读能力独立于设备形态。需要留意手机端外层页面滚动与阅读器内部正文滚动同时存在,手势体验应在真机上核对,尤其是大字号、长文和横屏小窗口。

阅读页各模块职责结构

八、字号档位有明确上下界

正文基础字号为 16,fontStep 最小 -2、最大 4,因此实际范围是 14 到 20;行高从 23 到 35 同步变化:

private bodyFontSize(): number {
  return 16 + this.fontStep;
}

private bodyLineHeight(): number {
  return 27 + this.fontStep * 2;
}

按钮颜色在边界处变弱,方法本身也再次限制范围。界面反馈和业务守卫同时存在,连续点击不会越界。若字号需要跨会话保存,只持久化档位整数即可,不要保存计算后的字号和行高两份事实。

九、播放按钮用 busy 阻止重复启动

页面的 toggleVoice() 首先判断 voiceBusy:

private async toggleVoice(): Promise<void> {
  if (this.voiceBusy) {
    return;
  }
  this.voiceBusy = true;
  try {
    if (this.voicePlaying) {
      ReadingVoiceService.stop();
    } else {
      await ReadingVoiceService.start(this.selectedArticle());
    }
  } catch (err) {
    this.voicePlaying = false;
    this.voiceStatus = ReadingVoiceService.getStatus();
    promptAction.showToast({ message: this.voiceStatus });
  } finally {
    this.voiceBusy = false;
  }
}

语音引擎首次创建可能需要时间,busy 能阻止用户在等待期间连续发起多个 start()。按钮还通过透明度表达进行中状态。更完整的交互可以让控件真正进入不可用状态,并在状态文案中区分“正在准备”和“正在朗读”。

十、start 先停止旧会话再构建片段

语音服务的启动顺序是:停止现有播放但暂不通知;从文章构建片段;更新为准备状态;确保引擎可用;把索引设为零并提交第一段。

static async start(article: ReadingArticle): Promise<void> {
  ReadingVoiceService.stop(false);
  ReadingVoiceService.segments = ReadingVoiceService.buildSegments(article);
  if (ReadingVoiceService.segments.length === 0) {
    throw new Error('Article content is empty.');
  }

  ReadingVoiceService.status = '正在准备朗读';
  ReadingVoiceService.notifyState();
  await ReadingVoiceService.ensureEngine();

  ReadingVoiceService.currentIndex = 0;
  ReadingVoiceService.speaking = true;
  ReadingVoiceService.status = '正在朗读';
  ReadingVoiceService.notifyState();
  ReadingVoiceService.speakCurrent();
}

旧会话先停止,保证切换文章时不会两篇同时朗读;空文章在创建引擎前失败,避免无意义初始化。

十一、朗读内容包含标题、摘要和全部正文

buildSegments() 的来源顺序很清楚:标题、摘要、正文段落。

private static buildSegments(article: ReadingArticle): string[] {
  const source: string[] = [article.title, article.summary].concat(article.paragraphs);
  const result: string[] = [];
  source.forEach((part: string) => {
    ReadingVoiceService.splitText(part)
      .forEach((segment: string) => result.push(segment));
  });
  return result;
}

阅读顺序由内容结构决定,页面不需要逐段调用语音接口。若未来加入图片说明或作者信息,应先决定它是否属于朗读正文,再修改这一处内容投影,不要在页面点击事件里临时拼字符串。

十二、220 长度切分优先保留中文语义停顿

服务把单段上限设为 220。超过上限时,先在范围内向前寻找最后一个句号;句号位置太靠前则寻找逗号;仍不合适才按上限硬切。

private static splitText(text: string): string[] {
  const clean = text.trim();
  if (clean.length === 0) return [];

  const result: string[] = [];
  let remain = clean;
  while (remain.length > MAX_SEGMENT_LENGTH) {
    let cut = remain.lastIndexOf('。', MAX_SEGMENT_LENGTH);
    if (cut < 60) cut = remain.lastIndexOf(',', MAX_SEGMENT_LENGTH);
    if (cut < 60) {
      cut = MAX_SEGMENT_LENGTH;
    } else {
      cut += 1;
    }
    result.push(remain.substring(0, cut).trim());
    remain = remain.substring(cut).trim();
  }
  if (remain.length > 0) result.push(remain);
  return result;
}

60 的下限避免第一段只留下很短一句。当前文章是中文纯文本,这一策略够用;若内容包含较多 emoji 或扩展字符,普通 length 可能在代理对中间切开,应改为按代码点或更正式的句子边界切分。

十三、音色候选先离线、再在线

源码先查询离线中文音色,再查询在线中文音色,最后补充 person 为 0 到 5 的回退候选,并去掉语言、人物和模式完全相同的重复项。

private static async resolveVoiceCandidates(): Promise<VoiceCandidate[]> {
  const result: VoiceCandidate[] = [];
  await ReadingVoiceService.appendVoicesFromQuery(result, OFFLINE_MODE);
  await ReadingVoiceService.appendVoicesFromQuery(result, ONLINE_MODE);

  FALLBACK_PERSONS.forEach((person: number) => {
    ReadingVoiceService.appendUniqueCandidate(result, {
      language: LANGUAGE_ZH_CN,
      person,
      online: OFFLINE_MODE
    });
    ReadingVoiceService.appendUniqueCandidate(result, {
      language: LANGUAGE_ZH_CN,
      person,
      online: ONLINE_MODE
    });
  });
  return result;
}

模块清单声明了 ohos.permission.INTERNET,与在线候选路径相符。若产品对外明确定位为完全离线,就不能只在文案里写“离线”,而应移除在线候选、核对语音能力在无网时的真实行为,并重新审视网络权限。能力、权限和隐私说明必须一致。

十四、引擎创建按候选逐一回退

ensureEngine() 复用已存在的引擎;首次创建时按候选列表尝试:

for (let i = 0; i < candidates.length; i += 1) {
  const candidate = candidates[i];
  try {
    const engine = await textToSpeech.createEngine({
      language: candidate.language,
      person: candidate.person,
      online: candidate.online
    });
    ReadingVoiceService.engine = engine;
    ReadingVoiceService.currentCandidate = candidate;
    ReadingVoiceService.bindListener(engine);
    return;
  } catch (err) {
    lastError = JSON.stringify(err);
    ReadingVoiceService.shutdownEngine();
  }
}

一个候选失败不会直接终止,服务会清理残留引擎并尝试下一项。全部失败后状态变为“朗读服务不可用,请稍后重试”,页面通过监听器和异常路径得到反馈。

十五、完成回调负责推进下一段

引擎监听器在开始、完成、停止和错误时更新服务状态。完成回调只在响应类型符合预期且仍处于 speaking 时推进:

onComplete: (_requestId: string, response: textToSpeech.CompleteResponse) => {
  if (response.type === 1 && ReadingVoiceService.speaking) {
    ReadingVoiceService.playNext();
  }
}

playNext() 将索引加一;到达末尾时清空片段并通知“朗读完成”,否则调用 speakCurrent() 提交下一段。页面只观察播放布尔值和状态文案,不承担片段编排。

十六、仅靠 speaking 还不足以隔离旧回调

考虑这一时序:文章 A 正在朗读,用户切换到文章 B;服务停止 A 并启动 B;此时 A 的迟到完成回调到达,而全局 speaking 已经因 B 变为 true。旧回调可能错误地让 B 跳过一段。

可以给每次 start() 分配会话号,并把它写入请求 ID:

private static session: number = 0;

static async start(article: ReadingArticle): Promise<void> {
  const session = ReadingVoiceService.session + 1;
  ReadingVoiceService.session = session;
  ReadingVoiceService.stop(false);
  ReadingVoiceService.segments = ReadingVoiceService.buildSegments(article);
  await ReadingVoiceService.ensureEngine();
  if (session !== ReadingVoiceService.session) return;
  ReadingVoiceService.currentIndex = 0;
  ReadingVoiceService.speaking = true;
  ReadingVoiceService.speakCurrent(session);
}

static stop(notify: boolean = true): void {
  ReadingVoiceService.session += 1;
  // 清理播放状态并停止引擎
}

回调解析或映射到对应会话,只允许当前会话推进。文章切换、手动停止和离页都会使旧会话失效。

十七、异步建引擎与离页之间存在竞态

页面离开时确实调用了:

aboutToDisappear(): void {
  ReadingVoiceService.stop();
  ReadingVoiceService.setListener(undefined);
  this.voicePlaying = false;
  this.voiceBusy = false;
  this.voiceStatus = '已停止朗读';
}

但如果 start() 正在等待 ensureEngine(),离页时 speaking 可能仍是 false。stop() 清理状态后,异步创建稍后成功,原来的 start() 继续执行并把 speaking 重新设为 true,此时页面已经消失且监听器已经解绑,朗读却可能开始。

上一节的会话号正好解决这个问题:stop() 递增会话,ensureEngine() 返回后先比较会话号,过期操作直接结束,不再提交第一段。

十八、450 毫秒自动播放计时器也要取消

路由参数为 autoPlay: true 时,页面延迟 450 毫秒调用播放:

setTimeout(() => {
  this.toggleVoice();
}, 450);

这个延迟给页面入场留出时间,但任务编号没有保存。如果用户在 450 毫秒内返回,aboutToDisappear() 先停止服务,随后旧计时任务仍可能调用 toggleVoice()。

可以保存并清理任务:

private autoPlayTimer: number = -1;
private active: boolean = false;

aboutToAppear(): void {
  this.active = true;
  this.autoPlayTimer = setTimeout(() => {
    if (this.active) this.toggleVoice();
  }, 450);
}

aboutToDisappear(): void {
  this.active = false;
  if (this.autoPlayTimer >= 0) clearTimeout(this.autoPlayTimer);
  this.autoPlayTimer = -1;
  ReadingVoiceService.stop();
  ReadingVoiceService.setListener(undefined);
}

页面任务和服务会话双重收口,才能确保离开阅读页后不会突然播音。

十九、监听器最好返回取消函数

当前服务只保存一个静态监听器:

static setListener(listener?: ReadingVoiceStateListener): void {
  ReadingVoiceService.listener = listener;
  ReadingVoiceService.notifyState();
}

单页面使用没有问题,离页时传 undefined 即可。未来若桌面卡片、悬浮控制或其他页面也观察播放状态,后注册者会覆盖前一个监听器。

更容易管理的接口是订阅后返回取消函数,或用监听器集合:

static subscribe(listener: ReadingVoiceStateListener): () => void {
  ReadingVoiceService.listeners.add(listener);
  listener(ReadingVoiceService.speaking, ReadingVoiceService.status);
  return () => ReadingVoiceService.listeners.delete(listener);
}

页面持有自己的取消函数,不需要知道服务中还有哪些消费者。

二十、引擎错误后应允许重新创建

当前 onError 会停止状态、清空片段并提示异常,但保留 engine 引用。下一次 start() 调用 ensureEngine() 时看到引擎存在,会直接复用。如果错误意味着引擎已不可用,用户重试可能再次失败。

可以按错误性质决定是否调用 shutdownEngine()。至少在无法继续朗读的引擎级错误后清理引用,让下一次启动重新解析候选。关闭过程仍要捕获异常,避免清理失败覆盖原始问题。

二十一、收藏当前未实现,扩展时只保存 ID

源码没有收藏状态,这是当前事实。若下一版增加收藏,最小数据结构不是复制 ReadingArticle,而是保存 ID 集合:

const FAVORITE_KEY = 'reading_favorite_ids_v1';

export class ReadingFavoriteService {
  private static ids: string[] = [];

  static isFavorite(articleId: string): boolean {
    return ReadingFavoriteService.ids.includes(articleId);
  }

  static async toggle(articleId: string): Promise<void> {
    const exists = ReadingFavoriteService.ids.includes(articleId);
    ReadingFavoriteService.ids = exists
      ? ReadingFavoriteService.ids.filter((id: string) => id !== articleId)
      : [articleId, ...ReadingFavoriteService.ids];
    await PreferencesStore.putJson<string[]>(FAVORITE_KEY, ReadingFavoriteService.ids);
  }
}

文章正文继续来自 ReadingLibrary,收藏只表达用户与文章 ID 的关系。正文更新后,收藏仍指向最新内容,不会在 Preferences 中留下旧副本。

二十二、收藏装载要清理失效 ID

文章可能在新版本中下线或改 ID。收藏服务装载后应与当前目录求交集:

static normalize(ids: string[]): string[] {
  const validIds = new Set(
    ReadingLibrary.articles().map((article: ReadingArticle) => article.id)
  );
  const unique = new Set<string>();
  ids.forEach((id: string) => {
    if (validIds.has(id)) unique.add(id);
  });
  return Array.from(unique);
}

这样旧 ID 不会让收藏页显示空白条目。若产品希望保留“已下线文章”的历史提示,则应保存单独快照模型,而不是让无效 ID 静默回退到首篇。

二十三、如何确保阅读能力不污染主工具

从工程边界看,可以用一张表约束依赖方向:

模块可以依赖不应依赖
Reading 页面文章目录、收藏边界、语音服务、断点状态转盘结果、骰子状态、历史列表
ReadingLibraryReadingArticle 模型页面组件、语音引擎、Preferences
收藏服务文章 ID、Preferences 封装文章正文副本、语音状态
语音服务Core Speech Kit、文章只读输入路由、转盘服务、页面实例

阅读入口可以出现在首页,但进入以后拥有独立状态;离开以后停止语音并解绑订阅;收藏只保存 ID;引擎错误不会改写主工具数据。这些约束比“把代码放在不同文件”更能保证隔离。

二十四、自动化用例应覆盖切段与会话

切段函数适合做纯逻辑用例:空白文本返回空数组;短文本保留为一段;长文本优先在句号切开;每段去除首尾空白;所有片段拼接后的语义顺序不变。

会话用例则要模拟异步时序:

it('ignores engine result after stop', 0, async () => {
  const startTask = ReadingVoiceService.start(article);
  ReadingVoiceService.stop();
  await startTask;
  expect(ReadingVoiceService.isSpeaking()).assertFalse();
});

还应覆盖:A 文章开始后立刻切到 B,A 的迟到回调不会推进 B;离页前触发自动播放,计时器被取消;音色查询失败后使用回退候选;引擎错误后下一次启动能够重新创建。

二十五、真实页面核验路径

  1. 从首页普通入口进入,默认选中 gentle-choice,不自动播放。
  2. 从“立即播放”入口进入,只自动启动一次,按钮进行中状态不会接受第二次点击。
  3. 依次选择四篇文章,标题、摘要、标签、分钟数和正文对应同一个 ID。
  4. 朗读时切换文章,旧文章立即停止,新文章不会跳过第一段。
  5. 朗读时返回首页,声音停止;等待数秒也不会重新开始。
  6. 自动播放入口进入后立刻返回,450 毫秒计时任务不会在后台启动语音。
  7. 断网时优先使用可用离线中文音色;全部不可用时页面给出明确状态。
  8. 引擎异常后再次点击播放,服务可以重新创建而非反复复用坏实例。
  9. 在手机、平板和 2in1 窗口切换断点,列表与正文都可达。
  10. 把字号调到最小和最大,行高、内滚动和控制栏不重叠。
  11. 收藏扩展完成后,重启应用仍保留有效 ID,正文继续来自静态目录。

二十六、常见问题与排查顺序

现象先看哪里常见原因处理方式
返回首页后突然开始朗读自动播放任务450 毫秒计时器未取消保存任务编号,离页清理
离页后仍在准备并最终播音start() 异步路径引擎创建完成后未核对会话使用会话号使旧启动失效
切文章时跳过第一段完成回调上一会话的迟到回调推进新列表回调绑定请求 ID 与会话号
一次引擎错误后永远无法重试onError保留了不可用引擎引用关闭引擎,下次重新解析候选
文章顺序被其他页面改变articles()返回静态数组共享引用返回深一层的目录快照
无效文章 ID 总显示第一篇findById()未命中时静默回退查找返回可空结果,页面显式处理
无网无法朗读音色候选与设备能力没有可用离线中文音色展示不可用状态,不假装播放
收藏正文与目录版本不一致收藏数据结构把整篇文章复制进存储只保存稳定文章 ID

排查时先确认页面是否仍处于活动状态,再看当前会话号和请求 ID,然后看片段索引与引擎回调,最后核对音色候选。这样能把页面任务、服务状态和设备能力问题分开。

二十七、工程落地清单

  • [ ] 文章使用稳定 ID,标题和标签只负责展示。
  • [ ] ReadingLibrary 返回只读定义或独立快照。
  • [ ] 默认文章选择与未知 ID 处理使用不同接口。
  • [ ] 阅读页只保存选中项、字号和播放等短期状态。
  • [ ] 手机与宽屏布局都保证正文和文章列表可达。
  • [ ] 播放进行中禁止重复启动,状态文案准确。
  • [ ] 标题、摘要与正文按固定顺序进入切段器。
  • [ ] 长文本优先按中文标点切分,每段不超过约定上限。
  • [ ] 音色候选顺序与产品的离线或在线定位一致。
  • [ ] 每次启动都有会话号,旧回调不能推进新文章。
  • [ ] 自动播放计时器在离页时取消。
  • [ ] 离页停止朗读、解绑监听并使异步启动失效。
  • [ ] 引擎级错误后允许关闭并重新创建。
  • [ ] 收藏扩展只保存文章 ID,不复制标题和正文。
  • [ ] 失效收藏 ID 在装载阶段被清理或显式展示。
  • [ ] 阅读服务不依赖转盘结果和决定历史。

总结

“转盘决定吧”的阅读小站已经具备一条完整的静态阅读与语音链路:ReadingLibrary 提供四篇文章,Reading 页面根据断点组织列表和正文,用有限字号档位改善阅读体验,ReadingVoiceService 查询中文音色、把标题摘要正文切成最长 220 的片段,并通过完成回调逐段推进。页面离开时停止服务并解绑监听,体现了独立功能不干扰主工具的基本方向。

继续完善时,最值得优先处理的是生命周期竞态:自动播放计时器要取消,等待引擎创建的旧启动要由会话号拦住,上一文章的迟到回调不能推进新文章。收藏目前尚未出现在源码中,接入时只保存稳定文章 ID,让正文继续由静态目录提供。这样阅读、收藏和朗读各自拥有明确事实来源,也不会把转盘、历史和首页状态卷进语音生命周期。

参考文件

  • entry/src/main/ets/model/Models.ets
  • entry/src/main/ets/service/ReadingLibrary.ets
  • entry/src/main/ets/service/ReadingVoiceService.ets
  • entry/src/main/ets/pages/Reading.ets
  • entry/src/main/ets/views/HomeView.ets
  • entry/src/main/module.json5
Logo

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

更多推荐