PureLayout

纯 JavaScript/TypeScript CSS 布局计算引擎
不依赖浏览器 DOM，可在任意 JS 环境中运行

---

这是什么

PureLayout 把浏览器的 CSS Block + Inline + Flexbox + Grid 布局能力从浏览器中拆出来，变成一个独立的 TypeScript 库。类比 Pretext 把文本测量从 DOM 中拆出来的思路。

你可以在 SSR、Web Worker、Canvas、PDF 生成、服务端渲染、高保真 PPT/H5 等任何有 JS 运行时的环境中精确计算 CSS 布局。

Pretext（文本测量） + PureLayout（布局计算） = 完整的无浏览器渲染管线

核心特性

• 零运行时依赖 — 纯 TypeScript 实现，不依赖任何浏览器 API
• Grid 布局 — 轨道尺寸计算（px/fr/%）、repeat()、自动放置、显式定位
• Flexbox 布局 — 完整 Flex Formatting Context，支持 grow/shrink/wrap/对齐
• Block 布局 — BFC、normal flow、margin collapse、clearance
• Inline 布局 — line box 构建、文本排列、软换行
• CSS 级联 — 完整的样式级联、继承、UA 默认值
• 盒模型 — margin/padding/border/box-sizing 完整支持
• 多环境运行 — Node.js / Browser / Worker 通用
• 高保真度 — 100% 通过差分测试，与浏览器像素级对齐

安装

npm install purelayout

快速开始

import { layout, px, FallbackMeasurer } from 'purelayout';

// 1. 定义 Grid 布局树
const tree = {
  tagName: 'div',
  style: { 
    display: 'grid', 
    gridTemplateColumns: '100px 1fr', 
    gap: px(20) 
  },
  children: [
    { tagName: 'div', style: { height: px(50) }, children: ['Sidebar'] },
    { tagName: 'div', style: { height: px(50) }, children: ['Content'] },
  ],
};

// 2. 执行布局计算
const result = layout(tree, {
  containerWidth: 800,
  textMeasurer: new FallbackMeasurer(),
});

// 3. 读取布局结果
console.log(result.root.children[1].contentRect);
// { x: 120, y: 0, width: 680, height: 50 }

支持的 CSS 属性

盒模型

属性	支持的值
display	block, inline, inline-block, flex, grid, none
box-sizing	content-box, border-box
width / height	px, %, em, rem, auto
gap / row-gap / column-gap	px, em, rem, normal

Grid (新)

属性	支持的值
grid-template-columns	px, %, fr, repeat(), auto
grid-template-rows	px, %, auto
grid-column / grid-row	shorthand (e.g., 1 / 3)
grid-column-start/end	<integer>, auto
grid-row-start/end	<integer>, auto

Flexbox

属性	支持的值
flex-direction	row, row-reverse, column, column-reverse
flex-wrap	nowrap, wrap, wrap-reverse
justify-content	flex-start, flex-end, center, space-between, space-around, space-evenly
flex-grow / flex-shrink / flex-basis	完整支持

定位

属性	支持的值
position	static, absolute, relative, fixed
top / right / bottom / left	px, %, em, rem, auto

演示

运行 npm run demo 查看所有演示效果。

1:1 高保真还原挑战 (v0.3.1 亮点)

展示如何将复杂的 CSS 布局（包含绝对定位、多级嵌套、自定义边框）完美还原。

H5 预览 (1:1 还原)	PPT 导出结果 (高保真)

运行 node demos/demo-challenges-fidelity.mjs 亲自体验。

数据可视化

展示仪表盘网格、统计卡片、图表容器等（由 Grid + Flex 驱动）。

布局算法

100% 浏览器保真度

通过 Playwright 采集浏览器真实渲染数据作为 Ground Truth，与 PureLayout 输出逐像素对比。

分类	Fixtures	通过	保真度
Block 布局	11	11	100%
Inline 布局	7	7	100%
Box Model	5	5	100%
Flex 布局	25	25	100%
Grid 布局	4	4	100%
定位 (New)	2	2	100%
合计	54	54	100%

路线图

Phase 4 — 定位与浮动 (进行中)

• position: absolute / relative / fixed
• top / right / bottom / left 偏移计算
• float / clear
• z-index
• Table 布局

高级功能

• 差分测试框架 + 保真度监控
• Pretext 适配器 (精确文本测量集成)
• PPT 导出适配器 (支持图像 & 高保真排版)
• @purelayout/pdf — PDF 渲染适配器
• @purelayout/canvas — Canvas 渲染适配器
• parseStyleNode(html) — HTML 字符串快速解析

许可证

MIT License