Lib.rs

› Rendering | Algorithms
#flexbox #yoga

taitank-rs

A cross-platform Flexbox layout engine in Rust

Owned by MeloAlright.

3 releases

0.1.2 Dec 7, 2025
0.1.1 Nov 30, 2025
0.1.0 Nov 16, 2025

#3 in Rendering

MIT license

150KB
3K SLoC

Taitank Rust

License Rust CI Documentation Crates.io

Taitank Rust 是 Taitank 的 Rust 实现版本，一个跨平台的轻量级 Flexbox 布局引擎。

✨ 特性

  • ✅ 完整的 Flexbox 支持 - 支持所有 Flexbox 布局属性，与 C++ 版本功能完全一致
  • ✅ 高性能 - 优化的布局算法，支持布局缓存，性能与 C++ 版本相当
  • ✅ 内存安全 - Rust 的所有权系统确保内存安全，无需手动管理内存
  • ✅ 类型安全 - 强类型系统减少运行时错误，编译时捕获问题
  • ✅ API 兼容 - 与 C++ 版本 API 兼容，易于迁移
  • ✅ 测试覆盖 - 完整的单元测试覆盖（30+ 测试文件，280+ 测试用例）
  • ✅ 多平台支持 - 支持 macOS、Linux、Windows、Android、iOS
  • ✅ WebAssembly - 完整的 WASM 绑定，可在浏览器和 Node.js 中使用
  • ✅ C FFI - 提供 C 兼容接口，可从任何支持 C 的语言调用
  • ✅ 详细文档 - 完整的 API 文档和使用示例

🚀 快速开始

安装

在 Cargo.toml 中添加依赖：

[dependencies]
taitank-rs = "0.1.2"

或者从 Git 仓库使用：

[dependencies]
taitank-rs = { git = "https://github.com/rustq/taitank-rs.git" }

基本使用

use taitank::*;

// 创建根节点
let root = node_create();
set_width(&root, 500.0);
set_height(&root, 300.0);
set_flex_direction(&root, FlexDirection::Row);
set_padding(&root, CSSDirection::All, 20.0);

// 创建子节点
let child1 = node_create();
set_width(&child1, 100.0);
set_height(&child1, 100.0);
set_margin(&child1, CSSDirection::Right, 10.0);
insert_child(&root, child1.clone(), 0);

// 创建使用 flex 的子节点
let child2 = node_create();
set_flex(&child2, 1.0); // flex: 1 自动填充剩余空间
set_height(&child2, 100.0);
insert_child(&root, child2.clone(), 0);

// 执行布局计算
do_layout(&root, VALUE_UNDEFINED, VALUE_UNDEFINED, TaitankDirection::Ltr, None);

// 获取布局结果
println!("Root: {}x{}", get_width(&root), get_height(&root));
println!("Child1: {}x{} at ({}, {})", 
         get_width(&child1), get_height(&child1),
         get_left(&child1), get_top(&child1));
println!("Child2: {}x{} at ({}, {})", 
         get_width(&child2), get_height(&child2),
         get_left(&child2), get_top(&child2));

📚 示例

项目包含多个示例，展示不同的使用场景：

# 运行基本示例
cargo run --example basic

# 运行复杂布局示例
cargo run --example complex

# 运行绝对定位示例
cargo run --example absolute_position

查看 examples/ 目录获取更多示例代码。

🧪 测试

运行所有测试：

cargo test

运行特定测试：

cargo test align_self_test

运行测试并显示输出：

cargo test -- --nocapture

📊 性能测试

使用 Criterion 进行性能基准测试：

cargo bench --bench benchmark

基准测试包括：

  • Stack with flex - 堆叠 flex 布局 (~4.05 µs)
  • Align stretch in undefined axis - 未定义轴拉伸对齐 (~4.04 µs)
  • Nested flex - 嵌套 flex 布局 (~60.5 µs)
  • Huge nested layout - 大型嵌套布局 (~3.41 ms)
  • Huge nested layout (no style) - 无样式大型嵌套布局 (~8.06 ms)

性能报告会生成在 target/criterion/ 目录下，包含详细的性能分析。

📖 API 文档

生成并查看 API 文档：

cargo doc --open

在线文档：https://docs.rs/taitank-rs

🌐 平台支持

Rust 库

直接作为 Rust 库使用，支持以下平台：

  • ✅ macOS (x86_64, arm64)
  • ✅ Linux (x86_64, arm64)
  • ✅ Windows (x86_64, MSVC/GNU)
  • ✅ Android (arm64-v8a, armeabi-v7a, x86, x86_64)
  • ✅ iOS (arm64, x86_64 simulator)

📁 项目结构

taitank-rust/
├── src/                    # 源代码
│   ├── api.rs              # 公共 API
│   ├── node.rs             # 节点核心实现
│   ├── style.rs            # 样式管理
│   ├── flex.rs             # Flexbox 类型和枚举
│   ├── flexline.rs         # FlexLine 实现
│   ├── cache.rs            # 布局缓存
│   ├── config.rs           # 配置管理
│   ├── util.rs             # 工具函数
│   └── lib.rs              # 库入口
├── tests/                  # 单元测试（30+ 测试文件）
├── examples/               # 示例代码
│   ├── basic.rs            # 基本使用示例
│   ├── complex.rs          # 复杂布局示例
│   └── absolute_position.rs # 绝对定位示例
├── benches/                # 性能基准测试
│   └── benchmark.rs        # Criterion 基准测试
├── .cargo/                 # Cargo 配置
│   └── config.toml         # 交叉编译配置
├── .github/                # GitHub 配置
│   └── workflows/          # CI/CD 工作流
├── build.sh                # 构建脚本
├── Cargo.toml              # 项目配置
├── README.md               # 本文件
├── PLATFORMS.md            # 平台构建指南
└── INTEGRATION.md          # 集成指南

🎯 支持的布局属性

尺寸

  • set_width() / get_width() - 宽度
  • set_height() / get_height() - 高度
  • set_min_width() / set_min_height() - 最小尺寸
  • set_max_width() / set_max_height() - 最大尺寸

Flex 属性

  • set_flex() - flex 简写
  • set_flex_grow() - flex-grow
  • set_flex_shrink() - flex-shrink
  • set_flex_basis() - flex-basis
  • set_flex_direction() - flex-direction
  • set_flex_wrap() - flex-wrap

对齐

  • set_justify_content() - justify-content
  • set_align_items() - align-items
  • set_align_content() - align-content
  • set_align_self() - align-self

间距

  • set_margin() / get_margin() - 外边距
  • set_padding() / get_padding() - 内边距
  • set_border() / get_border() - 边框
  • set_margin_auto() - 自动边距

定位

  • set_position_type() - position (relative/absolute)
  • set_position() - 位置设置

其他

  • set_display() - display (flex/none)
  • set_overflow() - overflow
  • set_direction() - 布局方向 (LTR/RTL)
  • set_node_type() - 节点类型 (Default/Text)

调试

  • print_node() - 打印节点树结构
  • reset() - 重置节点状态
  • mark_dirty() / is_dirty() - 脏标记管理

🔄 与 C++ 版本的差异

优势

  • 内存安全: Rust 的所有权系统确保内存安全，无需手动释放内存
  • 类型安全: 更强的类型检查，减少运行时错误
  • 并发安全: Rust 的并发模型确保线程安全
  • 零成本抽象: Rust 的零成本抽象保证性能

API 差异

  • 命名风格: 遵循 Rust 命名约定（snake_case）
  • 内存管理: 使用 Rc<RefCell<>> 进行引用计数，自动管理内存
  • 错误处理: 使用 Rust 的 Result 类型进行错误处理
  • 可选参数: 使用 Option<T> 替代 C++ 的可选参数

兼容性

  • ✅ 所有 C++ API 功能均已实现
  • ✅ 布局算法与 C++ 版本完全一致
  • ✅ 所有测试用例均通过
  • ✅ 性能与 C++ 版本相当

📝 贡献

欢迎贡献代码！请确保：

  1. 代码格式: 运行 cargo fmt 确保代码格式正确
  2. 代码检查: 运行 cargo clippy 确保没有警告
  3. 测试通过: 运行 cargo test 确保所有测试通过
  4. 文档更新: 更新相关文档和注释
  5. 提交信息: 使用清晰的提交信息

开发流程

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

代码规范

  • 遵循 Rust 官方代码风格
  • 使用有意义的变量和函数名
  • 添加必要的文档注释
  • 编写单元测试

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

  • Taitank C++ - 原始 C++ 实现
  • Yoga - Flexbox 布局算法的参考实现

🔗 相关链接

📊 项目状态

  • ✅ 核心功能完成
  • ✅ 所有测试通过
  • ✅ API 文档完整
  • ✅ 示例代码完善
  • ✅ 性能基准测试
  • ✅ WASM 绑定
  • ✅ C FFI 接口
  • ✅ 多平台支持

🗺️ 路线图

  • 添加更多示例
  • 性能优化
  • 扩展文档
  • 社区反馈和改进

License

MIT

No runtime deps