Crate pptx_rs

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::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::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: 单位、基本类型与颜色。

Structs§

Backdrop: 三维场景背景（<a:backdrop>，OOXML CT_Backdrop，TODO-050）。
Bevel: 棱台（<a:bevelT> / <a:bevelB>，OOXML CT_Bevel）。
BodyProperties: 文本体属性 <a:bodyPr>。
Camera: 相机（<a:camera>，OOXML CT_Camera）。
Cm: 厘米：1 cm = 360000 EMU。
ColorFormat: 颜色高阶视图（pptx.dml.color.ColorFormat）。
EffectList: 效果列表（<a:effectLst>）。
Emu: EMU（English Metric Unit），所有内部几何计算都使用 i64 形式的 EMU。
EmuPoint: 2D 几何点（EMU 整数坐标）。
FillFormat: 填充高阶视图（pptx.dml.fill.FillFormat）。
Font: 字体高阶视图（pptx.text.text.Font）。
GlowEffect: 发光效果（<a:glow>）。
Inches: 英寸：1 inch = 914400 EMU。
Indent: 段落水平缩进 / 悬挂缩进（EMU）。
Inset: 文本框内边距（<a:bodyPr lIns tIns rIns bIns>）。
LightRig: 光照设备（<a:lightRig>，OOXML CT_LightRig）。
Line: 边框（<a:ln>）。
LineFormat: 线框高阶视图（pptx.dml.line.LineFormat）。
Paragraph: 段落中的“结束段落“Run（</a:p> 之前可附带 a:endParaRPr）。
ParagraphFormat: 段落格式高阶视图（pptx.text.text._ParagraphFormat）。
ParagraphProperties: 段落属性 <a:pPr>。
Point3d: 三维点（<a:anchor>，OOXML CT_Point3D）。
Pt: 磅：1 pt = 12700 EMU。
RGBColor: sRGB 颜色（三字节 0-255）。
ReflectionEffect: 反射效果（<a:reflection>）。
Rotation3d: 三维旋转（<a:rot>，OOXML CT_SphereCoords）。
Run: 一个 Run：<a:r> + 文本。
RunProperties: Run 属性 <a:rPr>。
Scene3d: 三维场景（<a:scene3d>，OOXML CT_Scene3D）。
ShadowEffect: 阴影效果（<a:outerShdw> / <a:innerShdw>）。
ShapeProperties: 形状属性 <p:spPr>。
SoftEdgeEffect: 柔化边缘效果（<a:softEdge>）。
Sp3d: 形状 3D 属性（<a:sp3d>，OOXML CT_Shape3D）。
TextBody: 文本体 <p:txBody>。
TextFrame: 文本框高阶视图（pptx.text.textframe.TextFrame）。
Transform: 仿射变换。

Enums§

Alignment: 段落水平对齐方式（algn 属性）。
CameraPreset: 相机预设类型（OOXML ST_PresetCameraType，常用子集）。
Cap: 端帽样式（a:ln cap="..."）。
Color: 一个颜色（a:solidFill 内的颜色）。
ColorRole: 颜色在文档中的角色（仅 hint，不参与序列化）。
Dash: 线型虚实（枚举子集）。
Fill: 填充。
LightRigDirection: 光照方向（OOXML ST_LightRigDirection）。
LightRigType: 光照设备预设类型（OOXML ST_LightRigType，常用子集）。
MaterialPreset: 形状材质预设（OOXML ST_PresetMaterialType，常用子集）。
MsoAnchor: 文本框垂直对齐（MSO_ANCHOR）。
MsoAutoSize: 文本框自动调整策略（MSO_AUTO_SIZE）。
MsoColorType: 颜色类型（MSO_COLOR_TYPE）。
MsoConnectorType: 连接器类型（MSO_CONNECTOR_TYPE）。
MsoFillType: 填充类型（MSO_FILL_TYPE）。
MsoLineDashStyle: 线型虚实（MSO_LINE_DASH_STYLE）。
MsoShapeType: 形状类型（MSO_SHAPE_TYPE）。
MsoThemeColorIndex: 主题色索引（MSO_THEME_COLOR_INDEX）。
PpPlaceholderType: 占位符类型（PP_PLACEHOLDER）。
PresetColor: 预设颜色（prstClr val）。
PresetGeometry: 几何预设形状名（prstGeom prst="..."）。
SchemeColor: 主题色（schemeClr val）。
TextDirection: 段落属性方向（竖排/横排，a:bodyPr vert="..."）。
TextWrapping: 自动换行模式（<a:bodyPr wrap="...">）。
Underline: 文本下划线样式（a:rPr u="..."）。

Traits§

EmuExt: 单位转换 trait，封装“任意类型 → Emu“的语义。

Type Aliases§

PpAlign: 段落水平对齐（PP_ALIGN）——python-pptx 风格别名。

Crate pptx_rs

Crate pptx_rs Copy item path

§项目定位

§顶层模块结构

§三层架构（自下而上）

§最小示例

§单位与坐标系

§错误处理

§公开 API 稳定性

§路线图

§编译期开关说明

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate pptx_rs