Taitank Rust

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 文档
• 原始项目

📊 项目状态

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

🗺️ 路线图

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

License

MIT