Expand description
pptx-rs —— Rust 实现的 PowerPoint .pptx 读写库，对标 python-pptx。
§项目定位
pptx-rs 旨在以 Rust 的强类型 + 零 unsafe + 零异步的“现代化“姿态，完整复刻
python-pptx 提供的 PowerPoint 文档读写能力，并在性能与可维护性上做到更优。
当前处于 0.3.0 阶段。
§顶层模块结构
Presentation/Slide/Slides：高阶面向用户 API。shape：形状（AutoShape/Picture/Group/Connector/Table/TextBox）。opc：OPC（Open Packaging Convention）容器层 —— zip、Part、关系。oxml：OOXML 模型层 —— PresentationML / DrawingML 的强类型 XML 模型。units/RGBColor：EMU / Pt / Inches / 颜色。crypto：.pptx 文件加密（ECMA-376 Agile Encryption：AES-256-CBC + SHA-512）。ppt97：.ppt 97-2003 二进制格式支持（水印注入 + RC4 CryptoAPI 加密）。Error/Result：错误与 Result 别名。
§三层架构（自下而上）
高阶 API 层 Presentation / Slide / Shapes
↑ 借用
OOXML 模型层 oxml/{sp, pic, slide, master, layout, ...}
↑ 序列化
OPC 容器层 opc/{Part, Relationships, ContentTypes}
↑ 读写
zip crate下层绝不依赖上层。详见 架构总览 与 pptx-rs-architecture SKILL。
§最小示例
use pptx_rs::Presentation;
let mut prs = Presentation::new().unwrap();
let counter = prs.id_counter();
let slide = prs.slides_mut().add_slide(counter).unwrap();
let mut tb = slide.shapes_mut().add_textbox(
pptx_rs::Inches(1.0), pptx_rs::Inches(1.0),
pptx_rs::Inches(8.0), pptx_rs::Inches(1.0),
).unwrap();
tb.set_text("hello");
prs.save("hello.pptx").unwrap();§单位与坐标系
全部几何计算均以 EMU（English Metric Unit，i64）为内部单位，理由：
- OOXML 中所有几何属性（
off/ext/ 行高 / 列宽 / 边框）都是整数 EMU； - 整数运算保证无浮点精度漂移；
- 与其他 Office 工具（python-pptx / Open XML SDK）互操作零成本。
外部 API 通过 Inches / Pt / Cm 三种 NewType 包装 + units::EmuExt 扩展 trait
提供便捷转换；类型系统会阻止“英寸和磅混用“的潜在 bug。
§错误处理
库内禁止 panic! / unwrap()。所有公开 API 返回 Result<T>，错误统一归入
enum Error 的 11 个变体（Io / Zip / Xml / Opc / Oxml / NotFound /
IndexOutOfRange / NotImplemented / Encryption / Ppt97 / Other）。错误消息遵循小写 + 句末无标点。
§公开 API 稳定性
0.3.x 期间：
pub方法签名（方法名 / 参数 / 返回类型）—— 不承诺稳定，允许小调整；pub字段 —— 不承诺稳定，调整走CHANGELOG标注internal；- 破坏性变更 —— 需先
#[deprecated(note = "...")]一段时间。
详见 更新日志 与 project_rules.md。
§路线图
详见 README.md 的“路线图“段、 更新日志 与 pptx-rs-overview SKILL。
§编译期开关说明
forbid(unsafe_code)：库内绝对禁止unsafe块（与项目规则 §5 一致）。deny(rust_2018_idioms)：禁止 2015 风格的 idiom（#[macro_use]、路径写法等）。warn(missing_debug_implementations)：所有pub类型应实现Debug（如未实现会警告）。
Re-exports§
pub use crate::error::Error;pub use crate::error::Result;pub use crate::units::Cm;pub use crate::units::Emu;pub use crate::units::EmuExt;pub use crate::units::EmuPoint;pub use crate::units::Inches;pub use crate::units::Pt;pub use crate::units::RGBColor;pub use crate::oxml::simpletypes::Alignment;pub use crate::oxml::simpletypes::Cap;pub use crate::oxml::simpletypes::MsoAnchor;pub use crate::oxml::simpletypes::MsoAutoSize;pub use crate::oxml::simpletypes::MsoColorType;pub use crate::oxml::simpletypes::MsoConnectorType;pub use crate::oxml::simpletypes::MsoFillType;pub use crate::oxml::simpletypes::MsoLineDashStyle;pub use crate::oxml::simpletypes::MsoShapeType;pub use crate::oxml::simpletypes::MsoThemeColorIndex;pub use crate::oxml::simpletypes::PpAlign;pub use crate::oxml::simpletypes::PpPlaceholderType;pub use crate::oxml::simpletypes::PresetGeometry;pub use crate::oxml::simpletypes::TextDirection;pub use crate::oxml::simpletypes::TextWrapping;pub use crate::oxml::simpletypes::Underline;pub use crate::oxml::color::Color;pub use crate::oxml::color::ColorFormat;pub use crate::oxml::color::ColorRole;pub use crate::oxml::color::PresetColor;pub use crate::oxml::color::SchemeColor;pub use crate::oxml::sppr::Dash;pub use crate::oxml::sppr::EffectList;pub use crate::oxml::sppr::Fill;pub use crate::oxml::sppr::FillFormat;pub use crate::oxml::sppr::GlowEffect;pub use crate::oxml::sppr::Line;pub use crate::oxml::sppr::LineFormat;pub use crate::oxml::sppr::ReflectionEffect;pub use crate::oxml::sppr::ShadowEffect;pub use crate::oxml::sppr::ShapeProperties;pub use crate::oxml::sppr::SoftEdgeEffect;pub use crate::oxml::sppr::Transform;pub use crate::oxml::txbody::BodyProperties;pub use crate::oxml::txbody::Font;pub use crate::oxml::txbody::Indent;pub use crate::oxml::txbody::Inset;pub use crate::oxml::txbody::Paragraph;pub use crate::oxml::txbody::ParagraphFormat;pub use crate::oxml::txbody::ParagraphProperties;pub use crate::oxml::txbody::Run;pub use crate::oxml::txbody::RunProperties;pub use crate::oxml::txbody::TextBody;pub use crate::oxml::txbody::TextFrame;pub use crate::oxml::shape::ExtensionEntry;pub use crate::oxml::shape::ExtensionList;pub use crate::oxml::shape::ShapeLocks;pub use crate::oxml::shape::ShapeStyle;pub use crate::oxml::shape::StyleRef;pub use crate::oxml::shape::LockType;pub use crate::oxml::sppr::Backdrop;pub use crate::oxml::sppr::Bevel;pub use crate::oxml::sppr::Camera;pub use crate::oxml::sppr::CameraPreset;pub use crate::oxml::sppr::LightRig;pub use crate::oxml::sppr::LightRigDirection;pub use crate::oxml::sppr::LightRigType;pub use crate::oxml::sppr::MaterialPreset;pub use crate::oxml::sppr::Point3d;pub use crate::oxml::sppr::Rotation3d;pub use crate::oxml::sppr::Scene3d;pub use crate::oxml::sppr::Sp3d;pub use crate::oxml::chart::Chart;pub use crate::oxml::chart::ChartCategory;pub use crate::oxml::chart::ChartData;pub use crate::oxml::chart::ChartSeries;pub use crate::oxml::chart::ChartType;pub use crate::oxml::section::Section;pub use crate::oxml::section::SectionList;pub use crate::oxml::ole::OleObject;pub use crate::oxml::ole::OLE_GRAPHIC_DATA_URI;pub use crate::oxml::shape::MediaKind;pub use crate::presentation::AudioEntry;pub use crate::presentation::DiagramEntry;pub use crate::presentation::VideoEntry;pub use crate::oxml::shape::SmartArtRef;pub use crate::shape::smartartshape::SmartArtShape;pub use crate::oxml::diagram::ColorsDef;pub use crate::oxml::diagram::DataModel;pub use crate::oxml::diagram::DataModelConnection;pub use crate::oxml::diagram::DataModelPoint;pub use crate::oxml::diagram::LayoutCategory;pub use crate::oxml::diagram::LayoutDef;pub use crate::oxml::diagram::QuickStyleDef;pub use crate::oxml::diagram::StyleLabel;pub use crate::crypto::ModifyProtection;pub use crate::presentation::Presentation;pub use crate::presentation::CoreProperties;pub use crate::presentation::CustomProperties;pub use crate::presentation::CustomPropertyValue;pub use crate::slide::Shapes;pub use crate::slide::ShapesMut;pub use crate::slide::Slide;pub use crate::slide::SlideBackground;pub use crate::slide::SlideId;pub use crate::slide::SlideRef;pub use crate::slide::Slides;pub use crate::slide_layouts::Placeholder;pub use crate::slide_layouts::SlideLayout;pub use crate::slide_layouts::SlideLayoutRef;pub use crate::slide_layouts::SlideLayouts;pub use crate::slide_masters::SlideMaster;pub use crate::slide_masters::SlideMasterRef;pub use crate::slide_masters::SlideMasters;pub use crate::notes_masters::NotesMasterRef;pub use crate::notes_masters::NotesMasters;pub use crate::oxml::notesmaster::NotesMaster;pub use crate::oxml::comments::Comment;pub use crate::oxml::comments::CommentAuthor;pub use crate::oxml::comments::CommentAuthorList;pub use crate::oxml::comments::CommentList;pub use crate::oxml::slide::MorphOption;pub use crate::oxml::slide::SplitOrientation;pub use crate::oxml::slide::Transition;pub use crate::oxml::slide::TransitionDirection;pub use crate::oxml::slide::TransitionSpeed;pub use crate::oxml::slide::TransitionType;
Modules§
- crypto
- 加密与保护模块：修改密码保护 + ECMA-376 Agile Encryption。
- error
- 错误类型与
Result别名。 - notes_
masters - 备注母版（Notes Master）—— 高阶 API（TODO-045）。
- opc
- OPC（Open Packaging Convention）容器层。
- oxml
- OOXML XML 模型层。
- ppt97
- PowerPoint 97-2003 二进制格式（
.ppt）支持模块。 - presentation
- 演示文稿（Presentation）—— 顶层 API
- shape
- 高阶形状：AutoShape / Picture / Group / Connector / Table / TextBox / Freeform。
- slide
- 单张幻灯片（Slide）—— 高阶 API
- slide_
layouts - 幻灯片版式（Slide Layout）—— 高阶 API
- slide_
masters - 幻灯片母版（Slide Master）—— 高阶 API
- units
- 单位、基本类型与颜色。