pptx-rs2 0.5.0

Rust 版本的 PowerPoint .pptx 读写库, 对标 python-pptx
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! 单位、基本类型与颜色。
//!
//! 本模块集中管理 `pptx-rs` 中所有"非 OOXML 强类型但又频繁使用"的小型数据载体。
//! 它是 `crate::lib` 中"高阶 API 层"与"OPC / OOXML 模型层"之间的语义桥梁。
//!
//! # PowerPoint 的几何单位
//!
//! OOXML 中所有几何属性（`<a:off>` / `<a:ext>` / 行高 / 列宽 / 边框 / 缩进）都是
//! **EMU（English Metric Unit）** 整数。换算关系：
//!
//! | 单位      | EMU            | 备注                           |
//! | --------- | -------------- | ------------------------------ |
//! | 1 inch    | 914 400 EMU    | 1 in = 914 400                |
//! | 1 cm      | 360 000 EMU    | 1 cm = 360 000                |
//! | 1 pt      | 12 700 EMU     | 1 pt = 12 700                 |
//! | 1 sp      | 6 350 EMU      | 1 pt = 20 sp（OpenType 子像素）|
//!
//! 库内统一以 `i64` 形式的 EMU 作内部表示，理由：
//!
//! 1. **无浮点漂移**：在缩放 / 旋转 / 多次叠加时仍能保持整型精度。
//! 2. **互操作零成本**：与 python-pptx / Open XML SDK / LibreOffice 完全一致。
//! 3. **可读性**：用户阅读 `Emu(914400)` 与 `Inches(1.0)` 时是等价的。
//!
//! # 类型分层
//!
//! - [`Emu`]：绝对内部单位，整数 NewType。
//! - [`Pt`] / [`Inches`] / [`Cm`]：外部友好单位，浮点 NewType。
//! - [`EmuPoint`]：2D 点（x, y），以 EMU 整数存储，主要给连接器/手绘 freeform 用。
//! - [`EmuExt`]：扩展 trait，统一从 `f64` / `f32` / `i32` / `i64` / `Pt` / `Inches` / `Cm` 转换到 `Emu`。
//! - [`RGBColor`]：sRGB 颜色三字节 0-255，对应 OOXML `<a:srgbClr val="RRGGBB"/>`。
//!
//! # 设计哲学
//!
//! - **不暴露 `f64` 形参**：高阶 API 的"位置 / 大小"参数应接受 NewType 或显式单位
//!   转换。例如 `add_textbox(Inches(1.0), Inches(1.0), Inches(8.0), Inches(1.0))`，
//!   让"单位混用"在编译期就被拒绝。
//! - **浮点语义**：`f64` 在 `EmuExt` 中默认解释为"英寸"——这是最常用的隐含单位；
//!   若需其它语义请显式包装 `Pt(...)` / `Cm(...)`。
//! - **颜色不归此模块管**：主题色（schemeClr）、系统色（sysClr）、preset 颜色
//!   见 [`crate::oxml::color`]。
//!
//! # 与 python-pptx 的对应
//!
//! - `pptx.util.Pt` / `pptx.util.Inches` / `pptx.util.Cm` / `pptx.util.Emu` ←→ 同名 NewType。
//! - `pptx.util.Length` 的 `.x` / `.y` 抽象 → 本库通过 [`EmuPoint`] 暴露。
//! - `pptx.dml.color.RGBColor` ←→ [`RGBColor`]（构造时 `(r, g, b)` 元组也支持）。
//!
//! # 示例
//!
//! ```
//! use pptx_rs::{Emu, Inches, Pt, Cm, EmuExt, RGBColor};
//!
//! // 隐式单位转换
//! let w: Emu = Inches(8.5).emu();
//! assert_eq!(w.value(), (8.5 * 914_400.0) as i64);
//!
//! // 跨单位混算
//! let h = Pt(72.0).emu() + Inches(1.0).emu();
//!
//! // 颜色
//! let red: RGBColor = (255, 0, 0).into();
//! assert_eq!(red, RGBColor::RED);
//! ```
//!
//! # 实现说明
//!
//! 本模块自 v0.5.0 起改为 re-export [`ooxml_core::units`] 的内容。
//! 类型与 API 完全保持不变，仅是把实现下沉到 ooxml-core 公共基座，
//! 便于未来 xlsx-rs / docx-rs 复用同一套单位系统。

pub use ooxml_core::units::{Cm, Emu, EmuExt, EmuPoint, Inches, Pt, RGBColor};

#[cfg(test)]
mod tests {
    use super::*;

    /// 主要单位换算 round-trip 测试。
    #[test]
    fn unit_conversion() {
        assert_eq!(Pt(72.0).emu().value(), 72 * 12_700);
        assert_eq!(Inches(1.0).emu().value(), 914_400);
        assert_eq!(Cm(1.0).emu().value(), 360_000);
        assert!((Emu(914_400).inches() - 1.0).abs() < 1e-9);
        assert!((Emu(12_700).pt() - 1.0).abs() < 1e-9);
    }

    /// RGBColor 基本转换测试。
    #[test]
    fn rgb() {
        let c: RGBColor = (10, 20, 30).into();
        assert_eq!(c, RGBColor(10, 20, 30));
    }
}