HarmonyOS鸿蒙Next中Reader Kit深度使用反馈：TXT页码计算、字体切换、文本选择、程序化翻页等6项API改进建议

HarmonyOS鸿蒙Next中Reader Kit深度使用反馈：TXT页码计算、字体切换、文本选择、程序化翻页等6项API改进建议 尊敬的华为 Reader Kit 团队及各位开发者：

我是 HarmonyOS NEXT 生态应用开发者，基于 Reader Kit（@kit.ReaderKit）构建了一款本地电子书阅读器。在深度集成过程中，Reader Kit 的 EPUB 解析和排版能力为我们节省了大量开发成本，感谢团队提供这一重要的系统能力。

目前我们已完成了书架管理、目录解析、主题切换、书签笔记、自动阅读等完整功能链路的开发。但在深度定制过程中，遇到了 6 项与 API 边界和 TXT 格式支持相关的问题。这些问题并非基础使用疑问，而是我们在尝试实现"精细化阅读体验"时触到的 API 能力边界，且目前应用层 workaround 均未能完全生效。

现将问题汇总反馈，希望能为 Reader Kit 后续迭代提供参考，也期待社区共同探讨解决方案。

一、环境信息

• HarmonyOS 版本：HarmonyOS NEXT 5.0.5 Release 及以上
• DevEco Studio：6.1.0 Release
• SDK 版本：HarmonyOS 6.1.0 Release SDK (API 17)
• Reader Kit：随 DevEco Studio 6.1.0 集成的系统版本
• 测试设备：华为手机（直板机）
• 测试书籍格式：TXT、EPUB

二、问题清单（按影响优先级排序）

🔴 问题 1：TXT 文件页码/进度计算异常，章节总页数固定返回 14

现象：

• 阅读 TXT 文件时，无论文件大小（测试过 500KB ~ 5MB），pageShow 回调返回的章节总页数始终为 14。
• 翻到第 15 页后，页码显示变为 “15/14”，越界显示。
• 全书进度百分比因此混乱。

当前代码逻辑：

我们在 pageShow 回调中通过 JSON.stringify 提取 chapterTotalPage / totalPage / pageCount / totalPages / pageTotal / totalPageNum 等字段，但 TXT 场景下这些字段始终为 14 或 0。

已尝试的 workaround：

• 应用层自行按 fileSize / 300 估算总页数，并强制修正 chapterTotalPageCount = max(estimated, currentOffset + 1)。
• 效果：⚠️ 部分兜底。可避免 “15/14” 的越界显示，但估算值与 ReaderKit 实际排版页数无法对齐，页码仍不准确。

期望：

• TXT 场景下，ReaderKit 能按实际排版结果返回准确的章节页数或全书页数。
• 或提供 API 让开发者获取当前章节的实际字符/字节偏移量，以便应用层自行计算准确进度。

🔴 问题 2：切换字体后正文不刷新，且阅读位置丢失

现象：

1. 通过 setPageConfig() 修改 fontName 和 fontPath 后，正文字体无任何变化。
2. 必须调用 startPlay() 才能触发重新排版，但调用后页面跳回当前章节第一页，丢失阅读位置。

当前代码逻辑：

• 配置对象：

  let setting: readerCore.ReaderSetting = {
    fontName: 'Source Han Serif SC Medium',
    fontPath: 'fonts/思源宋体-中等.otf',
    fontSize: 18,
    // ... 其他字段
  };
  readerController.setPageConfig(setting);
  readerController.startPlay(currentIndex, domPos);
  

• domPos 来源于 pageShow 回调中通过 JSON.stringify 提取的隐藏字段，格式未公开。

已尝试的 workaround：

1. 在 pageShow 中缓存 domPos，切换字体时传入 startPlay。
2. 若 domPos 为空，回退到 bookParserHandler.getDomPosByCatalogHref(catalogItem.href)。
3. resourceRequest 回调中同时匹配 fontName、fontPath、rawFile 和纯文件名，确保字体文件被加载。
4. 效果：❌ 未生效。切换字体后正文仍无变化，且位置丢失。

核心疑问：

1. fontName 应传字体族名还是文件名？fontPath 应传相对路径还是绝对路径？
2. setPageConfig() 是否有配套的重排/刷新方法，而非必须走 startPlay？
3. startPlay(index, domPos) 的 domPos 正确格式是什么？（href / xpath / 内部标识？）

期望：

• 切换字体后，ReaderKit 能原地重排并保持阅读位置，或提供明确的"保持位置重排"API。

🔴 问题 3：长按正文无法触发文本选择（选字、复制、笔记）

现象：

• 在 ReadPageComponent 上长按正文，无任何反应。
• 无法获取系统级文本选择手柄（蓝色拖柄）和原生菜单（复制/全选）。
• 应用层无法获取当前页文字内容，自定义笔记功能难以实现。

当前代码逻辑：

• 已尝试 ReadPageComponent 外层添加 bindSelectionMenu，但不确定 ReaderKit 是否支持。
• 尝试通过 readerController.getCurrentPageText() 获取文本，但返回空或整页文本，无法精确到选中段落。
• 未找到 getTextOffsetAtPoint(x, y) 或类似的位置映射 API。

已尝试的 workaround：

• 自定义 TextSelectionOverlay 浮层，但没有触发机制（不知道长按事件从哪里获取）。
• 效果：❌ 未生效。长按无任何反应，无法获取选中文字。

核心疑问：

1. ReadPageComponent 是否内置支持长按选字？需要额外配置吗？
2. ReaderKit 是否提供 DOM/文本位置映射 API，以便应用层实现自定义选字？
3. getCurrentPageText() 的正确使用方式是什么？

期望：

• 支持系统级或 ReaderKit 原生的文字选择手柄与菜单回调。
• 或提供 API 获取触摸点对应的文本偏移量，让应用层实现自定义选字。

🟡 问题 4：程序化翻页 API 未明确暴露，自动阅读无法翻页

现象：

• 实现"自动阅读"功能时，遮罩进度走满 100% 后，需要代码触发翻页，但未找到明确的 nextPage() / prevPage() 公开 API。
• 目前只能通过反射式调用尝试多个可能的方法名，全部失败。

当前代码逻辑：

let ctrl = readerController as any;
let apis = ['nextPage', 'flipForward', 'forward', 'goNextPage', 'pageForward'];
for (let name of apis) {
  if (typeof ctrl[name] === 'function') {
    ctrl[name](); // 尝试调用
    break;
  }
}

• 效果：❌ 未生效。所有反射调用均无法触发翻页，自动阅读卡在遮罩满格后重新开始。

期望：

• 明确暴露 nextPage() / prevPage() 或 flipForward() / flipBackward() 等稳定的程序化翻页 API。

🟡 问题 5：自动阅读手势体系未生效

现象：

• 自动阅读开启后，尝试通过 GestureGroup 实现：
  • 单击 → 弹出菜单（不退出自动阅读）
  • 双击 → 暂停/恢复自动阅读
  • 侧滑 → 暂停并提示"再次侧滑退出"
• 但上述手势均未正确响应，自动阅读时点击屏幕直接退出或无任何反应。

当前代码逻辑：

• 在自动阅读遮罩层上叠加 GestureGroup(GestureMode.Exclusive, TapGesture({count: 2}), TapGesture({count: 1}), PanGesture(...))。
• 效果：❌ 未生效。手势事件似乎被 ReaderKit 底层消费或未被正确拦截。

期望：

• 明确 ReadPageComponent 或上层覆盖层的事件消费规则。
• 或提供自动阅读相关的官方手势/控制 API。

🟡 问题 6：目录弹窗（CatalogDialog）与底部菜单（BottomMenu）层级冲突

现象：

• 点击 BottomMenu 的"目录"按钮后，CatalogDialog 从底部滑出，但高度占满全屏，覆盖了 BottomMenu。
• 期望目录面板为半屏高度，且 BottomMenu 保持在底部可见。

当前布局：

• BottomMenu 使用 position({ y: '100%' }).markAnchor({ y: '100%' }) 固定在底部，zIndex(100)。
• CatalogDialog 同样使用底部定位，但 zIndex(300)，导致覆盖。

已尝试的 workaround：

• 调整 offset({ y: -240 }) 试图只露出部分内容。
• 效果：⚠️ 部分生效。视觉上目录上滑，但外层 Stack 仍占全屏，BottomMenu 被遮挡。

期望：

• 提供官方建议的"半屏弹窗 + 底部菜单共存"布局方案。
• 或 CatalogDialog 本身支持高度限制，不与底部菜单冲突。

🟢 问题 7：翻页模式切换 UI 已自行实现（非阻塞）

现象：

• SettingsPanel 中"翻页模式"按钮只显示 4 个汉字，用户无法直观知道当前是"仿真"还是"滑动"。

已自行实现：

• 主按钮显示 翻页模式:滑动，点击后上方浮现 仿真 按钮，点击切换。
• 效果：✅ 已生效。属于应用层 UI 优化，非 ReaderKit 缺陷。

三、问题汇总表

四、期望的改进方向

再次感谢 Reader Kit 团队提供如此重要的系统能力。以上问题均来自真实开发场景，且应用层 workaround 目前无法完全解决，希望能为组件后续迭代提供参考。期待官方回复，也欢迎社区开发者共同探讨。

祝好！