跳到主要内容

长篇文档显示测试

本文是一篇专门用于界面测试的长文档，不代表真实产品规范。它覆盖多级标题、长段落、列表、表格、代码块、引用、告警框和页内目录，便于检查桌面端与移动端的阅读体验。

测试建议

请分别在亮色与深色模式下查看，并将窗口宽度调整为 320px、768px、996px 和 1200px，重点观察顶部栏、左侧导航、右侧目录、正文宽度与代码块横向滚动。

1. 测试目标​

长篇技术文档通常同时包含说明文字、操作步骤、配置示例与故障排查。页面需要在内容密度较高时仍保持清晰的层级，让读者能够快速定位当前章节，并在连续滚动后理解自己所处的位置。

本页主要验证以下内容：

  • 顶部固定导航在长距离滚动时是否稳定；
  • 左侧文档导航能否正确高亮当前页面；
  • 右侧页内目录能否跟随当前标题；
  • 多级标题之间的字号、间距与锚点是否合理；
  • 长代码、宽表格和连续英文是否产生异常页面溢出；
  • 深色模式下正文、边框和代码高亮是否具有足够对比度；
  • 移动端折叠菜单是否遮挡正文或导致页面跳动。

1.1 阅读节奏​

理想的正文宽度应避免每行过长。中文正文通常以每行约 30 至 45 个汉字较为舒适；如果正文区域过宽，视线从行尾回到下一行开头时容易失去位置。如果区域过窄，则会产生大量换行，影响代码、表格和列表的阅读。

1.2 滚动稳定性​

滚动页面时不应出现以下现象：

  1. 顶部栏高度反复变化；
  2. 页面左右轻微抖动；
  3. 目录高亮导致布局位移；
  4. 图片或代码块加载后正文突然跳跃；
  5. 横向滚动条使页面右侧出现空白。

2. 示例场景​

假设 XiaoLight 设备需要经过注册、联网、配置、验证和上线五个阶段。每个阶段都可能包含不同角色参与的操作，因此文档必须同时说明前置条件、执行步骤、预期结果与失败后的恢复方式。

2.1 前置条件​

开始前请确认：

  • 已获得设备管理权限；
  • 开发机已安装 Node.js 20 或更高版本；
  • 网络能够访问所需服务；
  • 已准备测试环境，不会影响生产数据；
  • 已记录当前配置，以便出现问题时回滚。
测试环境

本文中的命令与地址仅用于展示排版。请勿将示例令牌、域名或设备编号用于真实环境。

2.2 基础流程​

2.2.1 初始化​

初始化阶段负责生成本地配置并检查运行环境。下面的示例代码用于验证多行代码块、注释和长命令的显示效果：

pnpm install
pnpm check:brand
pnpm lint
pnpm typecheck
pnpm build

执行完成后，应看到所有命令以状态码 0 退出。若安装依赖时出现网络错误，应先确认代理和软件源配置，而不是反复删除锁文件。

2.2.2 写入配置​

{
  "deviceId": "demo-device-001",
  "environment": "staging",
  "features": {
    "telemetry": true,
    "automaticUpdates": false,
    "diagnostics": true
  },
  "endpoints": {
    "api": "https://api.example.invalid/v1",
    "telemetry": "https://telemetry.example.invalid/collect"
  }
}

JSON 代码块应保留缩进，并在窄屏下独立横向滚动，而不是撑宽整个页面。

2.2.3 验证结果​

验证可以按以下顺序进行：

  1. 检查配置文件是否生成；
  2. 检查关键字段是否存在；
  3. 启动本地服务；
  4. 发送一次健康检查请求；
  5. 查看日志中是否包含错误；
  6. 关闭服务并确认资源已释放。

2.3 状态对照表​

状态含义建议操作是否阻塞上线
pending等待执行检查任务队列是
running正在执行等待并观察日志是
passed验证通过继续下一阶段否
warning存在非阻塞问题记录风险并评估否
failed验证失败停止流程并排查是

表格在桌面端应完整显示；在移动端如果宽度不足，应在表格区域内部滚动，不能让整个页面产生横向滚动条。

3. 配置说明​

3.1 环境变量​

环境变量适合保存部署环境之间不同、但不应直接写入代码仓库的值。变量名称应清晰表达作用，并为可选值提供安全默认值。

APP_ENV=staging
LOG_LEVEL=info
FEATURE_TELEMETRY=true
REQUEST_TIMEOUT_MS=10000
敏感信息

真实密钥、访问令牌和密码不得写入文档示例或提交到 Git。示例中应使用明显无效的占位值。

3.2 配置优先级​

当同一配置存在多个来源时，建议使用以下优先级：

  1. 命令行参数；
  2. 环境变量；
  3. 本地配置文件；
  4. 程序默认值。

这种顺序便于部署系统在不改动文件的情况下覆盖配置，同时允许开发环境保留方便使用的默认值。

3.3 长文本测试​

下面是一段较长的连续说明，用于观察正文行宽和换行效果。系统在处理设备状态时，应将采集、传输、存储和展示视为相互独立但可以追踪的阶段。采集阶段负责保证原始数据具有时间戳和来源标识；传输阶段需要处理网络抖动、超时与重试；存储阶段需要明确保留期限与清理策略；展示阶段则应区分最新状态、历史趋势和异常事件。任何阶段失败时，都应保留足够的上下文用于诊断，同时避免日志中包含敏感信息。

第二段用于确认段落之间的垂直间距。良好的技术文档不应依赖大量空行制造层级，而应通过标题、列表、引用和告警框表达结构。读者在快速浏览时通常先关注标题和关键词，再决定是否阅读完整段落，因此每个章节开头应尽快说明结论与适用范围。

4. 操作步骤​

4.1 创建任务​

任务创建请求示例：

type DeploymentTask = {
  id: string;
  environment: "staging" | "production";
  status: "pending" | "running" | "passed" | "failed";
};

export function canDeploy(task: DeploymentTask): boolean {
  return task.environment === "staging" && task.status === "passed";
}

4.2 执行任务​

  • 检查输入参数；
  • 创建任务记录；
  • 上传部署文件；
  • 等待边缘节点确认；
  • 执行上线后健康检查。

任务执行期间应持续记录阶段状态，但不要使用毫秒级高频轮询。对于耗时较长的操作，优先使用事件通知或带退避的轮询策略。

4.3 查看结果​

成功状态只代表当前检查已通过，不代表未来不会出现故障。上线后仍需保留监控、告警和回滚能力。

结果页至少应展示任务编号、开始时间、结束时间、执行环境、最终状态和错误摘要。详细日志可以折叠显示，避免大量文本压过主要结论。

5. 故障排查​

5.1 页面出现横向滚动​

依次检查：

  1. 是否存在未换行的超长字符串；
  2. 代码块是否设置独立的横向滚动；
  3. 表格外层是否允许滚动；
  4. 绝对定位的隐藏测量元素是否仍计入溢出区域；
  5. 图片是否设置了最大宽度；
  6. 固定宽度组件是否超过视口。

5.2 主题切换后颜色异常​

确认根元素同时具有正确的主题标记，并检查组件是否使用语义变量，而不是写死某个灰色色阶。切换主题时，背景、正文、边框、卡片和代码块应同时更新。

5.3 目录没有高亮​

目录高亮依赖标题层级与滚动位置。标题不应跳级，例如从二级标题直接跳到四级标题；同一页面也应避免大量重复标题，否则自动生成的锚点不易理解。

5.4 页面加载后跳动​

可能原因包括：

  • 字体加载前后尺寸不同；
  • 图片未声明尺寸；
  • 客户端初始状态与服务端输出不同；
  • 导航项在 hydration 后重新计算宽度；
  • 异步内容插入到当前视口上方。

解决时应优先消除布局不确定性，而不是简单隐藏页面溢出。

6. 可访问性检查​

6.1 键盘操作​

仅使用键盘完成以下操作：

  1. 从地址栏进入页面；
  2. 聚焦顶部导航链接；
  3. 打开与关闭折叠菜单；
  4. 切换明暗主题；
  5. 访问左侧导航中的其他文档；
  6. 返回当前长文档。

焦点样式必须清晰可见，且不能只通过颜色变化表达状态。

6.2 屏幕阅读器​

页面应只有一个主要的一级标题。导航、正文、页内目录和页脚应具有明确的语义区域。装饰性图标应标记为隐藏，交互按钮则需要可理解的名称。

6.3 对比度​

正文、次级文字、链接和边框应在亮色与深色背景下保持可辨识。浅灰文字不应用于关键操作或长段正文。

7. 性能观察​

长文档本身通常不会造成明显性能问题，但语法高亮、图片、交互式示例和大量目录节点可能增加脚本执行与布局计算。

建议观察：

  • 首次内容绘制时间；
  • 页面滚动是否保持流畅；
  • 切换主题时是否出现明显卡顿；
  • 页面目录是否频繁触发布局；
  • 搜索索引是否包含当前文档；
  • 构建产物是否出现异常增长。

7.1 避免不必要的脚本​

纯文本、列表、表格和代码示例应优先使用 Markdown 与原生 HTML。只有确实需要交互时才引入 React 组件，以减少客户端 hydration 工作。

7.2 图片策略​

本测试页没有插入真实图片。如果后续需要测试图片，应同时覆盖横图、竖图、小图和超宽图，并明确宽高，检查加载前后的布局稳定性。

8. 最终检查清单​

  • 顶部栏在滚动时保持稳定；
  • 左侧导航正确显示本文；
  • 右侧目录正确高亮章节；
  • 亮色与深色模式均可阅读；
  • 代码块只在自身区域横向滚动；
  • 表格不会撑宽整个页面；
  • 320px 宽度下没有页面级横向滚动；
  • 标题锚点可以复制并跳转；
  • 页面底部的上一篇/下一篇链接正确；
  • 搜索能够找到“长篇文档显示测试”。

9. 总结​

长篇文档的核心不是堆积内容，而是在大量信息中保持稳定、清晰和可导航。本测试页提供了一组常见内容形态，可用于持续检查主题升级、样式调整和响应式改动是否引入回归。

完成测试后可以保留本文作为视觉回归样例，也可以在正式内容完善后将其移除。