pptx_rs/
lib.rs

1//! pptx-rs —— Rust 实现的 PowerPoint `.pptx` 读写库，对标 [python-pptx](https://github.com/scanny/python-pptx)。
2//!
3//! # 项目定位
4//!
5//! `pptx-rs` 旨在以 Rust 的强类型 + 零 unsafe + 零异步的"现代化"姿态，完整复刻
6//! `python-pptx` 提供的 PowerPoint 文档读写能力，并在性能与可维护性上做到更优。
7//! 当前处于 **0.3.0** 阶段。
8//!
9//! # 顶层模块结构
10//!
11//! - [`Presentation`] / [`Slide`] / [`Slides`]：高阶面向用户 API。
12//! - [`shape`]：形状（`AutoShape` / `Picture` / `Group` / `Connector` / `Table` / `TextBox`）。
13//! - [`opc`]：OPC（Open Packaging Convention）容器层 —— zip、Part、关系。
14//! - [`oxml`]：OOXML 模型层 —— PresentationML / DrawingML 的强类型 XML 模型。
15//! - [`units`] / [`RGBColor`]：EMU / Pt / Inches / 颜色。
16//! - [`crypto`]：.pptx 文件加密（ECMA-376 Agile Encryption：AES-256-CBC + SHA-512）。
17//! - [`ppt97`]：.ppt 97-2003 二进制格式支持（水印注入 + RC4 CryptoAPI 加密）。
18//! - [`Error`] / [`Result`]：错误与 Result 别名。
19//!
20//! # 三层架构（自下而上）
21//!
22//! ```text
23//!   高阶 API 层    Presentation / Slide / Shapes
24//!        ↑ 借用
25//!   OOXML 模型层   oxml/{sp, pic, slide, master, layout, ...}
26//!        ↑ 序列化
27//!   OPC 容器层    opc/{Part, Relationships, ContentTypes}
28//!        ↑ 读写
29//!   zip crate
30//! ```
31//!
32//! 下层绝不依赖上层。详见
33//! [架构总览](https://github.com/WenTao-Love/pptx-rs/blob/main/docs/ARCHITECTURE.md) 与
34//! [pptx-rs-architecture SKILL](https://github.com/WenTao-Love/pptx-rs/blob/main/.trae/skills/pptx-rs-architecture/SKILL.md)。
35//!
36//! # 最小示例
37//!
38//! ```no_run
39//! use pptx_rs::Presentation;
40//!
41//! let mut prs = Presentation::new().unwrap();
42//! let counter = prs.id_counter();
43//! let slide = prs.slides_mut().add_slide(counter).unwrap();
44//! let mut tb = slide.shapes_mut().add_textbox(
45//!     pptx_rs::Inches(1.0), pptx_rs::Inches(1.0),
46//!     pptx_rs::Inches(8.0), pptx_rs::Inches(1.0),
47//! ).unwrap();
48//! tb.set_text("hello");
49//! prs.save("hello.pptx").unwrap();
50//! ```
51//!
52//! # 单位与坐标系
53//!
54//! 全部几何计算均以 **EMU**（English Metric Unit，`i64`）为内部单位，理由：
55//!
56//! - OOXML 中所有几何属性（`off` / `ext` / 行高 / 列宽 / 边框）都是整数 EMU；
57//! - 整数运算保证**无浮点精度漂移**；
58//! - 与其他 Office 工具（python-pptx / Open XML SDK）互操作零成本。
59//!
60//! 外部 API 通过 [`Inches`] / [`Pt`] / [`Cm`] 三种 NewType 包装 + [`units::EmuExt`] 扩展 trait
61//! 提供便捷转换；类型系统会阻止"英寸和磅混用"的潜在 bug。
62//!
63//! # 错误处理
64//!
65//! 库内**禁止** `panic!` / `unwrap()`。所有公开 API 返回 [`Result<T>`]，错误统一归入
66//! [`enum Error`](Error) 的 11 个变体（`Io` / `Zip` / `Xml` / `Opc` / `Oxml` / `NotFound` /
67//! `IndexOutOfRange` / `NotImplemented` / `Encryption` / `Ppt97` / `Other`）。错误消息遵循**小写 + 句末无标点**。
68//!
69//! # 公开 API 稳定性
70//!
71//! `0.3.x` 期间：
72//!
73//! - `pub` 方法签名（方法名 / 参数 / 返回类型）—— **不承诺稳定**，允许小调整；
74//! - `pub` 字段 —— **不承诺稳定**，调整走 `CHANGELOG` 标注 `internal`；
75//! - 破坏性变更 —— 需先 `#[deprecated(note = "...")]` 一段时间。
76//!
77//! 详见 [更新日志](https://github.com/WenTao-Love/pptx-rs/blob/main/docs/CHANGELOG.md) 与
78//! [project_rules.md](https://github.com/WenTao-Love/pptx-rs/blob/main/.trae/rules/project_rules.md)。
79//!
80//! # 路线图
81//!
82//! 详见 [README.md 的"路线图"段](https://github.com/WenTao-Love/pptx-rs#路线图)、
83//! [更新日志](https://github.com/WenTao-Love/pptx-rs/blob/main/docs/CHANGELOG.md) 与
84//! [pptx-rs-overview SKILL](https://github.com/WenTao-Love/pptx-rs/blob/main/.trae/skills/pptx-rs-overview/SKILL.md)。
85//!
86//! # 编译期开关说明
87//!
88//! - `forbid(unsafe_code)`：库内**绝对禁止** `unsafe` 块（与项目规则 §5 一致）。
89//! - `deny(rust_2018_idioms)`：禁止 2015 风格的 idiom（`#[macro_use]`、路径写法等）。
90//! - `warn(missing_debug_implementations)`：所有 `pub` 类型应实现 `Debug`（如未实现会警告）。
91
92#![forbid(unsafe_code)]
93#![deny(rust_2018_idioms)]
94#![warn(missing_debug_implementations)]
95
96/// 库统一的 `Result` 类型别名。所有公共 API（除特别声明）均返回该类型。
97///
98/// # 示例
99///
100/// ```no_run
101/// use pptx_rs::Result;
102///
103/// fn read_something() -> Result<String> { Ok(String::new()) }
104/// ```
105pub use crate::error::{Error, Result};
106
107// 重新导出常用单位类型，保持与 python-pptx 的 `from pptx import Pt, Inches` 风格相近。
108pub use crate::units::{Cm, Emu, EmuExt, EmuPoint, Inches, Pt, RGBColor};
109
110// 重新导出常用枚举（OOXML simple types），对标 `pptx.enum.*`。
111// 这些枚举在 oxml 与 shape 两侧都被用到，提到 crate 根以减少路径深度。
112pub use crate::oxml::simpletypes::{
113    Alignment, Cap, MsoAnchor, MsoAutoSize, MsoColorType, MsoConnectorType, MsoFillType,
114    MsoLineDashStyle, MsoShapeType, MsoThemeColorIndex, PpAlign, PpPlaceholderType, PresetGeometry,
115    TextDirection, TextWrapping, Underline,
116};
117
118// 重新导出颜色、变换、填充、边框等"最常用基础类型"。
119pub use crate::oxml::color::{Color, ColorFormat, ColorRole, PresetColor, SchemeColor};
120pub use crate::oxml::sppr::{
121    Dash, EffectList, Fill, FillFormat, GlowEffect, Line, LineFormat, ReflectionEffect,
122    ShadowEffect, ShapeProperties, SoftEdgeEffect, Transform,
123};
124// 重新导出文本体相关：TextFrame / Paragraph / Run / Font / ParagraphFormat。
125pub use crate::oxml::txbody::{
126    BodyProperties, Font, Indent, Inset, Paragraph, ParagraphFormat, ParagraphProperties, Run,
127    RunProperties, TextBody, TextFrame,
128};
129// 重新导出主题样式 + 扩展列表（p:style / p:extLst）。
130pub use crate::oxml::shape::{ExtensionEntry, ExtensionList, ShapeLocks, ShapeStyle, StyleRef};
131// 形状锁定类型枚举（TODO-027 高阶 API）。
132pub use crate::oxml::shape::LockType;
133// 三维效果相关类型（TODO-050 scene3d / sp3d / backdrop）。
134pub use crate::oxml::sppr::{
135    Backdrop, Bevel, Camera, CameraPreset, LightRig, LightRigDirection, LightRigType,
136    MaterialPreset, Point3d, Rotation3d, Scene3d, Sp3d,
137};
138// 图表相关类型（TODO-004 基础图表支持）。
139pub use crate::oxml::chart::{Chart, ChartCategory, ChartData, ChartSeries, ChartType};
140// 章节分组相关类型（TODO-039 Section 分组）。
141pub use crate::oxml::section::{Section, SectionList};
142// OLE 对象相关类型（TODO-043 OLE 嵌入）。
143pub use crate::oxml::ole::{OleObject, OLE_GRAPHIC_DATA_URI};
144// 音视频媒体相关类型（TODO-033 音视频嵌入）。
145pub use crate::oxml::shape::MediaKind;
146pub use crate::presentation::{AudioEntry, DiagramEntry, VideoEntry};
147// SmartArt 最小保留类型（TODO-037 SmartArt 识别 + round-trip）。
148pub use crate::oxml::shape::SmartArtRef;
149// SmartArt 高阶句柄（TODO-037 创建 API）。
150pub use crate::shape::smartartshape::SmartArtShape;
151// SmartArt 结构化解析类型（TODO-037 SmartArt 数据模型）。
152pub use crate::oxml::diagram::{
153    ColorsDef, DataModel, DataModelConnection, DataModelPoint, LayoutCategory, LayoutDef,
154    QuickStyleDef, StyleLabel,
155};
156
157// 高阶顶层 API 重新导出。
158pub use crate::crypto::ModifyProtection;
159pub use crate::presentation::Presentation;
160pub use crate::presentation::{CoreProperties, CustomProperties, CustomPropertyValue};
161pub use crate::slide::{Shapes, ShapesMut, Slide, SlideBackground, SlideId, SlideRef, Slides};
162pub use crate::slide_layouts::{Placeholder, SlideLayout, SlideLayoutRef, SlideLayouts};
163pub use crate::slide_masters::{SlideMaster, SlideMasterRef, SlideMasters};
164// 备注母版相关类型（TODO-045 NotesMaster 访问）。
165pub use crate::notes_masters::{NotesMasterRef, NotesMasters};
166pub use crate::oxml::notesmaster::NotesMaster;
167// 评论相关类型（TODO-036）。
168pub use crate::oxml::comments::{Comment, CommentAuthor, CommentAuthorList, CommentList};
169// 幻灯片过渡相关类型（TODO-020 高阶 API）。
170pub use crate::oxml::slide::{
171    MorphOption, SplitOrientation, Transition, TransitionDirection, TransitionSpeed, TransitionType,
172};
173
174// 按模块组织源代码。模块顺序遵循"底层→高层"：
175// error → units → opc → oxml → crypto → ppt97 → 顶层。
176// ppt97（.ppt 97-2003 二进制格式支持）独立于 .pptx 主线，作为可选模块放在 crypto 之后。
177pub mod crypto;
178pub mod error;
179pub mod notes_masters;
180pub mod opc;
181pub mod oxml;
182pub mod ppt97;
183pub mod presentation;
184pub mod shape;
185pub mod slide;
186pub mod slide_layouts;
187pub mod slide_masters;
188pub mod units;
pptx_rs/lib.rs

pptx_rs/
lib.rs
