Pretext 布局

概述

使用 Pretext 在浏览器环境中测量多行文本，避免在性能热点路径中重复产生 DOM 重排开销。当文本宽度频繁变化且需要基于缓存测量结果获得稳定的高度或逐行几何信息时，推荐使用。

工作流程

1. 确认运行时环境。

- 将 Pretext 视为以浏览器优先设计。

- 如果任务是纯 Node 或 CLI 环境，且不支持 OffscreenCanvas 和 document，则不应承诺直接运行时支持。

1. 根据任务匹配 API。

- 需要测量高度和行数时，使用 prepare() 加上 layout()。

- 需要自定义渲染时，使用 prepareWithSegments() 加上 layoutWithLines()、walkLineRanges() 或 layoutNextLine()。

1. 保持布局输入与实际样式同步。

- 从目标元素或设计令牌源读取 font 和 line-height。

- 使用网络字体时，需等待 document.fonts.ready 后再信任测量结果。

1. 积极缓存。

- 每个 (text, font, whiteSpace, locale) 输入只需准备一次。

- 在宽度变化时复用已准备的句柄。

1. 当准确性至关重要时，与真实 UI 进行验证。

- 对若干代表性字符串对比 Pretext 测量结果与实际 DOM 高度。

- 若功能依赖多语言、表情符号或窄宽度场景，应包含这些情况。

决策指南

• 当用户需要块级高度、缩放性能、虚拟化、滚动锚定或渲染前预测量文本时，选择 prepare() 加 layout()。
• 当需要自定义行绘制、Canvas 文本、SVG 文本、自动包裹宽度探测或可变行宽时，选择 prepareWithSegments() 加丰富的行级 API。
• 若任务依赖 Pretext 不打算完全覆盖的 CSS 行为，则应选择普通 DOM 测量。

核心规则

• 除非目标环境确实提供兼容的 canvas 上下文，否则不要声称支持服务器端。
• 保持 font 和 lineHeight 与真实 UI 一致；测量误差通常源于输入不匹配，而非布局调用本身。
• 在 macOS 上对精度敏感的流程中避免使用 system-ui；建议使用命名字体。
• 将 prepare() 视为开销较大的步骤，layout() 视为性能热点路径。
• 处理类似 textarea 的内容时，显式传入 { whiteSpace: 'pre-wrap' }。

实现检查清单

• 明确文本来源、目标宽度来源、字体来源和行高来源。
• 判断功能是否仅需高度，还是也需要逐行数据。
• 缓存已准备的句柄，避免每次调整大小都调用 prepare()。
• 添加一个小的验证路径，对代表性样本对比 Pretext 输出与实时 DOM 结果。
• 在集成点附近文档化任何不支持的 CSS 或运行时假设。

脚本

• 如需一个最小化的浏览器启动模板，可运行 scripts/scaffold_browser_demo.py --out <dir>，该脚本会将 @chenglou/pretext 正确接入。
• 将生成的模板作为临时起点；生成后根据项目实际情况调整 font、line-height、white-space 模式和 UI 标记。

参考资料

• 阅读 references/browser-integration.md 了解常见的浏览器集成模式和可复用的测量循环。
• 选择简单 API 与丰富 API 之间时，阅读 references/usage-patterns.md。
• 在回答关于准确性、字体、white-space、表情符号、双向文本行为或非浏览器运行时的问题前，阅读 references/caveats.md。
• 阅读 references/project-examples.md 获取可移植的集成模式，适用于任意基于浏览器的应用或 AI CLI 工作空间。