@sketchjs/yoga-layout

基于 yoga-layout 编译的 WebAssembly 版本，专为 Sketch.js 框架优化，支持在浏览器和 Node.js 环境中使用 Flexbox 布局引擎。 header: 123276157121f8d87d1245f94cf5f87edeeb18b6

🎯 适用场景

• 需要在浏览器中使用 Yoga Layout
• 需要在 Node.js 中进行布局计算

✨ 特性

• 🚀 高性能: 使用 WebAssembly 编译的 Yoga 布局引擎
• 📱 跨平台: 支持浏览器和 Node.js 环境
• 🔧 TypeScript: 完整的 TypeScript 类型定义
• 📐 Flexbox: 完整的 Flexbox 布局算法实现
• 🎯 轻量级: 优化的二进制文件大小

📦 安装

npm

npm install @sketchjs/yoga-layout

pnpm

pnpm add @sketchjs/yoga-layout

yarn

yarn add @sketchjs/yoga-layout

🚀 快速开始

在浏览器中使用

import { loadYoga } from '@sketchjs/yoga-layout';

// 加载 Yoga 布局引擎
const Yoga = await loadYoga();

// 创建根节点
const root = Yoga.Node.create();
root.setWidth(500);
root.setHeight(300);
root.setJustifyContent(Yoga.JUSTIFY_CENTER);

// 创建子节点
const child = Yoga.Node.create();
child.setWidth(100);
child.setHeight(100);

// 添加子节点
root.insertChild(child, 0);

// 计算布局
root.calculateLayout(500, 300, Yoga.DIRECTION_LTR);

// 获取布局结果
console.log('Child layout:', {
  left: child.getComputedLeft(),
  top: child.getComputedTop(),
  width: child.getComputedWidth(),
  height: child.getComputedHeight()
});

在 Node.js 中使用

const { loadYoga } = require('@sketchjs/yoga-layout');

async function calculateLayout() {
  const Yoga = await loadYoga();
  
  const root = Yoga.Node.create();
  root.setWidth(400);
  root.setHeight(400);
  root.setFlexDirection(Yoga.FLEX_DIRECTION_ROW);
  
  const child1 = Yoga.Node.create();
  child1.setWidth(100);
  child1.setHeight(100);
  
  const child2 = Yoga.Node.create();
  child2.setWidth(100);
  child2.setHeight(100);
  
  root.insertChild(child1, 0);
  root.insertChild(child2, 1);
  
  root.calculateLayout(400, 400, Yoga.DIRECTION_LTR);
  
  console.log('Layout calculated successfully');
}

calculateLayout();

📖 API 参考

主要函数

loadYoga(): Promise<Yoga>

加载 Yoga 布局引擎，返回 Yoga 实例。

loadYogaNoWasm(): Yoga

加载不使用 WebAssembly 的 Yoga 版本（如果可用）。

核心类

Yoga.Node

布局节点类，用于创建和管理布局节点。

主要方法：

• create(): Node - 创建新节点
• setWidth(width: number): void - 设置宽度
• setHeight(height: number): void - 设置高度
• setFlexDirection(direction: number): void - 设置 Flex 方向
• insertChild(child: Node, index: number): void - 插入子节点
• calculateLayout(width: number, height: number, direction: number): void - 计算布局

枚举值

布局相关的枚举值可通过 Yoga 对象访问：

• FLEX_DIRECTION_ROW / FLEX_DIRECTION_COLUMN
• JUSTIFY_CENTER / JUSTIFY_FLEX_START / JUSTIFY_FLEX_END
• ALIGN_CENTER / ALIGN_FLEX_START / ALIGN_FLEX_END
• DIRECTION_LTR / DIRECTION_RTL

完整的枚举定义请参考 src/generated/YGEnums.d.ts。

🛠️ 编译说明

前提条件

• Emscripten SDK 已安装并配置
• CMake 3.13 或更高版本
• Node.js 开发环境

编译流程

1. 准备 yoga-layout 源码

   git clone https://github.com/facebook/yoga.git
   cd yoga

2. 复制编译配置

   cp packages/sketch-yoga-layout/CMakeLists.txt javascript/CMakeLists.txt

3. 执行编译

   cd javascript
   npm run build

4. 更新二进制文件

   cp binaries/* ../packages/sketch-yoga-layout/binaries/

编译选项

编译配置支持以下优化选项：

• LTO (Link Time Optimization): 启用链接时优化
• 异常处理: 禁用 C++ 异常以减小体积
• RTTI: 禁用运行时类型信息
• 调试信息: 生产环境禁用调试符号
• 内存管理: 使用 emmalloc 内存分配器

🗂️ 文件结构

sketch-yoga-layout/
├── binaries/           # 编译后的二进制文件
│   ├── yoga-base64.cjs    # CommonJS 版本
│   ├── yoga-base64.mjs    # ES Module 版本
│   ├── yoga-wasm-base64.cjs
│   └── yoga-wasm-base64.mjs
├── src/                # 源代码
│   ├── generated/      # 自动生成的枚举定义
│   ├── index.js        # 主入口文件
│   └── *.d.ts         # TypeScript 类型定义
├── CMakeLists.txt      # 编译配置文件
└── package.json        # 包配置

⚡ 性能优化

• 单文件打包: 使用 SINGLE_FILE=1 将 WASM 内联到 JavaScript 中
• 内存优化: 启用 ALLOW_MEMORY_GROWTH=1 支持动态内存增长
• 体积优化: 使用 -Os 优化级别和 LTO 减小文件体积
• 安全优化: 禁用动态代码执行 (DYNAMIC_EXECUTION=0)

🌐 浏览器兼容性

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

需要支持 WebAssembly 的现代浏览器。

⚠️ 注意事项

• 浏览器环境推荐使用 loadYoga() 异步加载
• 若不使用 WASM，可尝试 loadYogaNoWasm() 作为降级方案

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关链接

• Sketch.js 主项目
• Yoga Layout 官方文档