Rust文本布局库harfbuzz-traits使用指南

harfbuzz-traits是一个为HarfBuzz提供Rust原生接口的库，它简化了Unicode文本处理功能在Rust中的使用。

主要功能

• 提供Rust原生接口访问HarfBuzz功能
• 简化Unicode文本处理
• 支持高级文本布局功能
• 与Rust生态系统无缝集成

安装

在Cargo.toml中添加依赖：

[dependencies]
harfbuzz-traits = "0.1"

基本使用方法

1. 创建HarfBuzz字体和缓冲区

use harfbuzz_traits::{Font, Buffer, UnicodeBuffer};

// 创建字体
let font = Font::new_from_file("path/to/font.ttf").expect("Failed to load font");

// 创建文本缓冲区
let mut buffer = Buffer::new();
buffer.add_str("Hello, 世界!"); // 支持Unicode文本

2. 文本整形

use harfbuzz_traits::{Direction, Script, Language};

// 设置文本属性
buffer.set_direction(Direction::LTR); // 从左到右文本
buffer.set_script(Script::Latin);    // 拉丁字母
buffer.set_language(Language::from_string("en").unwrap());

// 执行整形
let output = font.shape(&buffer);

3. 处理整形结果

for glyph_info in output.glyph_infos() {
    println!(
        "Glyph ID: {}, Cluster: {}, Position: {:?}",
        glyph_info.codepoint,
        glyph_info.cluster,
        output.glyph_positions()[glyph_info.index]
    );
}

高级功能示例

自定义字体功能

// 启用字体特性
let mut features = vec![
    Feature::new(b"kern", 1, 0..u32::MAX), // 启用字距调整
    Feature::new(b"liga", 1, 0..u32::MAX), // 启用连字
];

let output = font.shape_with_features(&buffer, &features);

可变字体支持

// 设置字体变体坐标
let variations = vec![
    Variation::new(b"wght", 700.0), // 设置字重为700
    Variation::new(b"wdth", 100.0), // 设置宽度为100
];

let output = font.shape_with_variations(&buffer, &variations);

实际应用示例

计算文本宽度

fn calculate_text_width(font: &Font, text: &str) -> f64 {
    let mut buffer = Buffer::new();
    buffer.add_str(text);
    buffer.set_direction(Direction::LTR);
    
    let output = font.shape(&buffer);
    
    output.glyph_positions()
        .iter()
        .map(|pos| pos.x_advance as f64)
        .sum::<f64>()
        / 64.0 // 转换为点单位
}

let width = calculate_text_width(&font, "Hello, Rust!");
println!("Text width: {} points", width);

完整示例Demo

下面是一个完整的示例，展示如何使用harfbuzz-traits进行文本布局：

use harfbuzz_traits::{Font, Buffer, Direction, Script, Language, Feature};

fn main() {
    // 1. 加载字体文件
    let font = Font::new_from_file("NotoSans-Regular.ttf")
        .expect("Failed to load font file");
    
    // 2. 准备文本内容
    let text = "Hello, 世界! HarfBuzz with Rust";
    
    // 3. 创建文本缓冲区
    let mut buffer = Buffer::new();
    buffer.add_str(text);
    
    // 4. 设置文本属性
    buffer.set_direction(Direction::LTR);
    buffer.set_script(Script::Latin);
    buffer.set_language(Language::from_string("en").unwrap());
    
    // 5. 启用字体特性
    let features = vec![
        Feature::new(b"kern", 1, 0..u32::MAX), // 字距调整
        Feature::new(b"liga", 1, 0..u32::MAX), // 连字
    ];
    
    // 6. 执行文本整形
    let output = font.shape_with_features(&buffer, &features);
    
    // 7. 处理并打印结果
    println!("Text: {}", text);
    println!("Glyph count: {}", output.glyph_infos().len());
    
    for (i, glyph_info) in output.glyph_infos().iter().enumerate() {
        let pos = output.glyph_positions()[i];
        println!(
            "Glyph {}: ID={}, Cluster={}, Position=({}, {}), Advance=({}, {})",
            i,
            glyph_info.codepoint,
            glyph_info.cluster,
            pos.x_offset,
            pos.y_offset,
            pos.x_advance,
            pos.y_advance
        );
    }
    
    // 8. 计算文本总宽度
    let total_width: f64 = output.glyph_positions()
        .iter()
        .map(|pos| pos.x_advance as f64)
        .sum::<f64>() / 64.0;
    
    println!("Total text width: {:.2} points", total_width);
}

注意事项

1. 确保正确设置文本方向、脚本和语言以获得准确结果
2. 处理复杂脚本(如阿拉伯语、印度语系)时需要额外配置
3. 性能关键应用应考虑重用Buffer对象

harfbuzz-traits为Rust开发者提供了强大的文本布局能力，特别适合需要精确文本渲染的应用程序，如文本编辑器、排版工具和UI框架。