HarmonyOS 鸿蒙Next阅读器排版与渲染求助：多方案迭代后仍存的文字裁切、页面空白与分页异常

一、问题摘要（TL;DR）

在 HarmonyOS NEXT（API 12）上使用 Stack + Swiper + 绝对定位 Text 实现阅读器分页排版时，存在以下顽固异常：

1. 顶部固定空白：每页正文上方始终预留一块空白区域，疑似章节标题占位，但后续页不应保留；
2. 左侧固定空白：正文整体向右偏移，左侧出现一列无法消除的空白；
3. 段落间异常空白：正文段与段之间出现大面积留白，且最后一页末尾无法填满；
4. 文字显示不全/硬裁切：正文底部文字被截断，覆盖翻页模式下第一页后内容直接消失，滚动模式下文字超出可视区域被遮住；
5. 分页失效：整章内容全部挤在一页显示，翻页直接跳章而非逐页翻行；
6. 菜单与正文层级错乱：点击屏幕唤出的阅读菜单被正文文字层或TopBar遮挡。

已尝试 Canvas 自绘、WebView、Stack+Text 三种渲染方案，均无法根治。现向社区寻求自适应分页填满的正确实现思路。

二、环境信息

三、问题详细描述

3.1 顶部空白（所有页面）

• 现象：每页正文内容并非从 TopBar（36vp 高）下方紧贴开始，而是再向下偏移一段距离；第1页标题下方、后续页正文顶部均保留固定空白带；
• 期望：第 1 页标题下方直接接正文，后续页正文应从 TopBar 底部零间距开始；
• 实际：所有页面顶部都保留了一个固定高度的空白带，疑似引擎内部硬编码了 paddingTop 或 Swiper/Stack 存在默认间距。

3.2 左侧空白（所有页面）

• 现象：正文第一行相对于屏幕左边缘有明显缩进，且不是首行缩进效果，而是整页所有行都右移；
• 期望：用户设置的 pagePadding 仅作为左右边距，正文应在边距内顶格排列（除首行缩进外）；
• 实际：左侧始终有一列空白，且随字号调大变得更宽。

3.3 段落间空白 & 底部填充不全（所有页面）

• 现象：段落与段落之间出现远超行高的空白；最后一页底部大量留白，文字未填满至 BottomBar（32vp 高）上方；
• 期望：段落间距可控（如 0.05×行高），且每页文字应填满可用内容区域，最后一页底部空白由自然排版决定，不应整页悬空；
• 实际：段落间距过大，且分页算法似乎提前换页，导致每页底部都有未利用空间。

3.4 文字显示不全 / 硬裁切（历史遗留，当前方案仍存在）

• 现象：
  • 覆盖翻页模式：第一页正常显示，翻到第二页后内容直接消失（空白页），再翻页则跳章；
  • 滚动模式：正文内容超出上下 UI 边界，文字被 TopBar/BottomBar 遮挡截断；
  • 行尾裁字：部分页面最后一行文字只显示上半截或完全消失；
• 期望：无论何种翻页方式，文字应完整显示在内容区域内，不被任何 UI 层裁切；分页应精确到行，不能出现半行或整页空白；
• 历史方案表现：
  • Canvas 方案：因缓冲区缩放比问题，文字行距异常，底部文字被硬裁切；
  • WebView 方案：无法精确获取内容高度，分页不可控，同样出现裁切；
  • Stack+Text 方案：虽然避免了 Canvas 缩放问题，但绝对定位的 Text 组件仍出现底部截断和跨页内容丢失。

3.5 分页失效 / 整章挤在一页（历史遗留，当前方案仍存在）

• 现象：整章所有文字堆叠在同一页，页码显示 “1 / 1”；点击翻页直接跳到下一章，而非本章下一页；
• 期望：根据内容区域高度自动计算每页可容纳行数，实现逐页翻行；
• 历史表现：早期 Canvas 方案中，因 pageHeight 计算未扣除 TopBar/BottomBar，导致单页高度被撑满；改为 Stack+Text 后，分页逻辑已独立，但用户调整字号/行距后仍偶现单页堆叠。

3.6 菜单与正文层级错乱（历史遗留）

• 现象：点击屏幕中间唤出阅读菜单（目录/设置/字体），菜单弹窗被正文文字层或 TopBar/BottomBar 遮挡，无法完整显示；
• 期望：菜单层 zIndex 应最高，覆盖在所有文字和 UI 之上；
• 历史修复：曾通过调整 zIndex(999) 和 position 部分修复，但在绝对定位 Text 方案下，Swiper 内部的文字层似乎仍覆盖在菜单之上。

3.7 页面层级异常（历史遗留）

• 现象：视觉上感觉存在两层页面——一个空白层和一个文字层，文字层被缩小，导致四周出现空白边框；
• 推测：可能是 Swiper 的 SwiperItem 或 Stack 内部存在默认 padding/margin，或绝对定位的 Text 坐标原点与容器原点不一致。

四、已尝试方案及结果

方案 1：Canvas 自绘（已废弃）

思路：使用 Canvas + CanvasRenderingContext2D.fillText() 手动绘制文字，通过 measureText 计算断行。
结果：

• Canvas 缓冲区与屏幕像素比不一致，导致行距异常、文字右侧留白；
• 无法使用系统字体回退，中文排版精度差；
• 文字硬裁切：底部文字被 Canvas 边界截断，无法完整显示最后一行；
• 结论：放弃 Canvas 方案。

方案 2：WebView 渲染（已废弃）

思路：将章节内容注入 WebView，通过 CSS column-fill: auto 或 JS 计算分页。
结果：

• WebView 在鸿蒙上无法精确获取内容高度，分页不可控；
• 翻页动画与系统手势冲突；
• 文字硬裁切：WebView 内部滚动区域与外部容器尺寸不匹配，导致底部文字被截断；
• 结论：放弃 WebView 方案。

方案 3：Stack + 绝对定位 Text（当前方案）

思路：

• UI 层：Stack 承载 Swiper，Swiper 内用 ForEach 生成每页；
• 每页是一个 Stack，内部用 ForEach 遍历 LineInfo 数组，通过 Text().position({x, y}) 绝对定位渲染；
• 排版层：TextLayoutEngine 接收纯内容区域尺寸（screenWidth - padding×2 × screenHeight - topBar - bottomBar），内部零 padding，逐行计算坐标。

核心排版算法：

// 内容区域计算（UI 层）
const contentWidth = screenWidth - pagePadding * 2;
const contentHeight = screenHeight - topBarHeight - bottomBarHeight;

// 引擎参数（排版层）
const params: LayoutParams = {
  text: chapter.content,
  title: chapter.title,
  pageWidth: contentWidth,
  pageHeight: contentHeight,
  fontSize: 18,
  lineHeight: 1.8,
  paddingLeft: 0, paddingRight: 0, paddingTop: 0, paddingBottom: 0,
  indentSize: Math.round(fontSize * 2) // 首行缩进 2 字符
};

// 渲染映射（UI 层）
Text(line.text).position({
  x: pagePadding + line.x, // line.x 在引擎内为 0 或 indentSize
  y: topBarHeight + line.y // line.y 在引擎内从 0 开始
})

结果：

• 编译通过，分页正常，章节切换正常；
• 但以下问题依然存在：顶部空白、左侧空白、段落间空白、底部填充不全、文字裁切。

方案 3 的迭代修复记录

五、关键代码（最小复现）

5.1 排版引擎核心（TextLayoutEngine.ets）

export class TextLayoutEngine {
  static layout(params: LayoutParams): PageInfo[] {
    const pages: PageInfo[] = [];
    const lineHeightPx = Math.round(params.fontSize * params.lineHeight);
    const indentSize = params.indentSize ?? Math.round(params.fontSize * 2);
    const paragraphSpacing = Math.round(lineHeightPx * 0.05);

    const paragraphs = TextLayoutEngine.mergeLinesToParagraphs(params.text);
    let currentLines: LineInfo[] = [];
    let usedHeight = 0;
    let isFirstPage = true;

    // 第 1 页标题
    if (params.title.length > 0 && isFirstPage) {
      currentLines.push({
        text: params.title, x: 0, y: 0,
        width: measureWidth(params.title), height: lineHeightPx, isIndent: false
      });
      usedHeight = lineHeightPx;
    }

    for (let pIdx = 0; pIdx < paragraphs.length; pIdx++) {
      let remaining = paragraphs[pIdx];
      let isFirstLine = true;
      while (remaining.length > 0) {
        const maxLineWidth = params.pageWidth - (isFirstLine ? indentSize : 0);
        const breakPoint = TextLayoutEngine.findBreakPoint(remaining, maxLineWidth, params);
        const lineText = remaining.substring(0, breakPoint);
        remaining = remaining.substring(breakPoint).trimStart();

        const lineInfo: LineInfo = {
          text: lineText,
          x: isFirstLine ? indentSize : 0,
          y: usedHeight,
          width: measureWidth(lineText),
          height: lineHeightPx,
          isIndent: isFirstLine
        };

        // 分页判断
        if (usedHeight + lineHeightPx > params.pageHeight) {
          if (currentLines.length > 0) pages.push({ title: params.title, lines: currentLines });
          currentLines = [lineInfo];
          usedHeight = lineHeightPx;
          isFirstPage = false;
        } else {
          currentLines.push(lineInfo);
          usedHeight += lineHeightPx;
        }
        isFirstLine = false;
      }
      if (pIdx < paragraphs.length - 1) usedHeight += paragraphSpacing;
    }
    if (currentLines.length > 0) pages.push({ title: params.title, lines: currentLines });
    return pages;
  }
}

5.2 页面渲染核心（CanvasReaderPage.ets）

// 内容区域 = 屏幕 - TopBar - BottomBar - 用户边距
const contentWidth = this.screenWidth - this.uiSettings.pagePadding * 2;
const contentHeight = this.screenHeight - this.topBarHeight - this.bottomBarHeight;

// Swiper 内绝对定位渲染
ForEach(this.pages, (page, pageIndex) => {
  Stack() {
    ForEach(page.lines, (line, lineIndex) => {
      Text(line.text)
        .fontSize(this.uiSettings.fontSize)
        .lineHeight(this.uiSettings.fontSize * this.uiSettings.lineHeight)
        .maxLines(1)
        .position({
          x: this.uiSettings.pagePadding + line.x,
          y: this.topBarHeight + line.y
        })
    })
  }
})

六、求助方向

1. 顶部空白根因：在引擎内部 paddingTop 已置 0、标题仅占一行高的情况下，为何页面顶部仍出现固定空白？是否 Swiper 或 Stack 内部有默认间距？
2. 左侧空白根因：line.x 在引擎内为 0（非首行）或 indentSize（首行），UI 层再加 pagePadding，为何所有行都整体右移？是否 Text 组件本身有默认内边距？
3. 段落间与底部空白：paragraphSpacing 已设为 0.05×lineHeight，为何仍出现大段留白？分页判断 usedHeight + lineHeightPx > pageHeight 是否过于保守，导致提前换页？
4. 文字硬裁切：绝对定位的 Text 组件在 Swiper 内为何会出现底部截断？是否 Text 的 lineHeight 与实际渲染高度不一致（如包含行间距或字体上行/下行）？
5. 分页堆叠：整章内容挤在一页的根本原因是什么？是 pageHeight 计算错误，还是 Swiper 未正确识别多页？
6. 菜单层级：在 Stack + 绝对定位 Text + Swiper 的组合下，如何确保弹窗菜单始终覆盖在最上层？
7. 自适应排版最佳实践：在 ArkTS 严格模式下，除绝对定位 Text 外，是否有更原生的方式实现纯文本分页填满（如 Text 的 constraintSize + maxLines 动态计算）？

感谢各位大佬指点，如有需要补充代码或日志，随时提供。