Struct Slide 

pub struct Slide { /* private fields */ }

幻灯片的高阶包装。直接拥有 oxml OxmlSld。

该类型既“包装“oxml 模型，又把 id 计数器共享给 Presentation， 是“高阶 API ↔ OOXML 模型“之间的唯一桥梁。

Implementations

impl Slide

pub fn to_xml(&self) -> String

把当前 slide 序列化为 XML 字符串。

用途

• 调试：直接 println!("{}", slide.to_xml())；
• 测试 fixture：与已知 snapshot 对比；
• 自定义输出管道：把 XML 与 zip 步骤解耦。

pub fn shapes(&self) -> Shapes<'_>

不可变形状集合视图。

pub fn shapes_mut(&mut self) -> ShapesMut<'_>

可变形状集合视图。

pub fn internal_id(&self) -> u32

内部 ID（在所属 Presentation 内的 sldIdLst 序号，与 shape id 独立）。

pub fn layout_rid(&self) -> String

取 layout 关系 id（指向 ppt/slideLayouts/slideLayoutN.xml）。

pub fn set_layout_rid(&mut self, rid: String)

设置 layout 关系 id。

pub fn layout_partname(&self) -> Option<&str>

取 slide layout 的 OPC part 路径（/ppt/slideLayouts/slideLayoutN.xml）。

返回 None 表示未捕获（新建场景）；写路径兜底为 ../slideLayouts/slideLayout1.xml。

pub fn name(&self) -> &str

取 slide 名（对应 p:sld/p:cSld/@name，空字符串表示未命名）。

对标 python-pptx Slide.name。

pub fn set_name(&mut self, name: Option<&str>)

设置 slide 名。None 或空字符串等价于“移除名字“。

pub fn notes_text(&self) -> Option<String>

备注文本（speaker notes）拼成单字符串。

返回 None 表示当前 slide 没有任何 <p:notes> 部分。 多段落以 \n 拼接，与 python-pptx 行为一致。

pub fn has_notes_slide(&self) -> bool

是否存在 notes slide。

对标 python-pptx Slide.has_notes_slide。 与 Self::notes_text 不同：后者读取 notes 内容，前者只判断“是否创建了 notes 容器“——一旦写过 notes，本值即持续为 true，直至显式 set_notes_text(None)。

pub fn follow_master_background(&self) -> bool

是否继承 master 背景。

对标 python-pptx Slide.follow_master_background。

实现语义

• inner.background 为 None：未设置独立背景，渲染时回退到 master → 返回 true；
• inner.background 为 Some(SlideBackground::Reference { idx=1001, scheme_color="bg1" })： 显式引用 master 背景 → 返回 true；
• inner.background 为 Some(SlideBackground::Property(_))：已设置独立背景 → 返回 false；
• 其它 Reference（非 bg1/1001）：视为“引用主题背景样式“，仍算继承 → 返回 true。

pub fn set_follow_master_background(&mut self, v: bool)

设置“是否继承 master 背景“。

• v = true：清空独立背景（inner.background = None），渲染时回退到 master；
• v = false：若当前已是独立背景则保留；否则写入一个“占位“的纯白背景， 后续可通过 Self::set_background_solid 修改颜色。

对标 python-pptx Slide.follow_master_background = True/False。

pub fn set_background_solid(&mut self, color: Color)

设置纯色背景（写出 <p:bg><p:bgPr><a:solidFill>...</a:solidFill></p:bgPr></p:bg>）。

对标 python-pptx slide.background.fill.solid(); slide.background.fill.fore_color.rgb = ...。

参数

• color：填充颜色（Color::RGB / Color::Scheme / Color::Preset）； Color::None 等价于 Self::clear_background。

示例

s.set_background_solid(Color::RGB(RGBColor::RED));

pub fn clear_background(&mut self)

清空独立背景（回退到继承 master 背景）。

等价于 set_follow_master_background(true)。

pub fn extract_text(&self) -> String

提取 slide 中所有文本内容（纯文本，不含格式）。

对标 pypdf PageObject.extract_text() / python-pptx Shape.text_frame.text。 遍历 slide 上所有形状的文本体，把每个 Run 的 text 拼接成单字符串， 段落间以 \n 分隔，形状间以 \n\n 分隔。

与 pypdf 的差异

• pypdf 的 extract_text() 按 PDF 内容流顺序提取，可能乱序；
• 本方法按 slide XML 中的形状声明顺序提取，与 PowerPoint 中阅读顺序一致。

pub fn clone_slide(&self) -> Slide

深拷贝当前 slide（分配新 id / rid / partname 由 Slides 在插入时处理）。

对标 pypdf PdfWriter.clone_page_from_reader。 返回的 Slide 与原 slide 完全独立——修改克隆体不影响原件。

pub fn set_title_text(&mut self, text: &str) -> bool

设置标题占位符的文本（TODO-007）。

对标 python-pptx slide.shapes.title.text = "..."。

查找策略与 Shapes::title 一致：优先 ph_type == "title" / "ctrTitle"， 其次 ph_idx == 0。找到后替换其文本体为单段落单 Run。

返回

• true：找到标题占位符并已设置；
• false：未找到标题占位符。

pub fn title_text(&self) -> Option<String>

取标题占位符的文本（TODO-007）。

对标 python-pptx slide.shapes.title.text。 未找到标题占位符时返回 None。

pub fn append_body_paragraph(&mut self, text: &str) -> bool

向正文占位符追加一个段落（TODO-007）。

对标 python-pptx slide.placeholders[1].text_frame.add_paragraph()。

查找策略：优先 ph_type == "body"，其次 ph_idx == 1。 找到后在文本体末尾追加一个新段落（单 Run，文本为 text）。

返回

• true：找到正文占位符并已追加；
• false：未找到正文占位符。

pub fn set_body_text(&mut self, text: &str) -> bool

设置正文占位符的文本（替换全部段落，TODO-007）。

对标 python-pptx slide.placeholders[1].text_frame.text = "..."。

返回

• true：找到正文占位符并已设置；
• false：未找到正文占位符。

pub fn body_text(&self) -> Option<String>

取正文占位符的文本（TODO-007）。

对标 python-pptx slide.placeholders[1].text_frame.text。 未找到正文占位符时返回 None。

pub fn set_footer_text(&mut self, text: &str) -> bool

设置页脚占位符的文本（TODO-007 剩余小项）。

对标 python-pptx slide.placeholders[footer_idx].text_frame.text = "..."。

查找策略：仅按 ph_type == "ftr" 匹配（不按 ph_idx 回退，因为页脚 占位符的 idx 在不同版式中取值不一）。找到后替换其文本体为单段落单 Run。

返回

• true：找到页脚占位符并已设置；
• false：未找到页脚占位符（页脚占位符需由版式/母版提供）。

pub fn footer_text(&self) -> Option<String>

取页脚占位符的文本（TODO-007 剩余小项）。

未找到页脚占位符时返回 None。

pub fn set_date_text(&mut self, text: &str) -> bool

设置日期占位符的文本（TODO-007 剩余小项）。

对标 python-pptx slide.placeholders[dt_idx].text_frame.text = "..."。

查找策略：仅按 ph_type == "dt" 匹配。找到后替换其文本体。

注意

PowerPoint 默认会让日期占位符显示“自动更新日期“；一旦显式设置文本， 会覆盖自动日期。如需恢复自动日期，请重新从版式继承占位符。

返回

• true：找到日期占位符并已设置；
• false：未找到日期占位符。

pub fn date_text(&self) -> Option<String>

取日期占位符的文本（TODO-007 剩余小项）。

未找到日期占位符时返回 None。

pub fn set_slide_number_text(&mut self, text: &str) -> bool

设置幻灯片编号占位符的文本（TODO-007 剩余小项）。

对标 python-pptx slide.placeholders[sldNum_idx].text_frame.text = "..."。

查找策略：仅按 ph_type == "sldNum" 匹配。找到后替换其文本体。

注意

与日期占位符类似，PowerPoint 默认会自动渲染当前页码；显式设置文本 会覆盖自动页码。

返回

• true：找到编号占位符并已设置；
• false：未找到编号占位符。

pub fn slide_number_text(&self) -> Option<String>

取幻灯片编号占位符的文本（TODO-007 剩余小项）。

未找到编号占位符时返回 None。

pub fn background(&self) -> SlideBackground<'_>

取得 slide 背景的高阶视图（只读）。

对标 python-pptx Slide.background。

实现说明

返回的 SlideBackground 句柄仅提供读取能力（如 fill_type()）。 若需修改背景，请使用以下方法：

• Self::set_background_solid：设置纯色背景；
• Self::clear_background：清空独立背景；
• Self::set_follow_master_background：切换继承/独立。

pub fn transition(&self) -> Option<&Transition>

读取幻灯片过渡（<p:transition>）。

对标 python-pptx slide.transition（python-pptx 实际只暴露底层元素，本 API 返回结构体）。

返回 Some(&Transition) 表示该幻灯片已设置过渡；None 表示未设置（遵循 PowerPoint 默认行为）。

示例

if let Some(t) = s.transition() {
    println!("speed = {:?}", t.speed);
}

pub fn set_transition(&mut self, transition: Transition)

设置幻灯片过渡（<p:transition>）。

对标 python-pptx 中通过 slide.element.transition 操作过渡的方式，本 API 接收结构体直接覆盖。

若传入 TransitionType::None，等价于 Self::clear_transition。

参数

• transition：过渡配置（速度/换片方式/类型）

示例

let t = Transition {
    speed: TransitionSpeed::Slow,
    advance_click: true,
    advance_after_ms: Some(5000),
    transition_type: TransitionType::Fade { thru_blk: false },
};
s.set_transition(t);

pub fn clear_transition(&mut self)

清除幻灯片过渡（等价于删除 <p:transition> 元素）。

清除后该幻灯片将使用 PowerPoint 默认的“无过渡“行为。

pub fn notes(&self) -> Option<&TextBody>

备注文本体（TextBody）的可选引用。

对标 python-pptx slide.notes_slide.notes_text_frame。 当未设置备注时返回 None。

pub fn notes_mut(&mut self) -> Option<&mut TextBody>

备注文本体（TextBody）的可变引用。

pub fn set_notes(&mut self, tb: Option<TextBody>)

直接覆盖备注文本体。None 表示删除备注。

pub fn notes_rid(&self) -> Option<&str>

备注 part 的关系 id（rIdNotesN），由 Presentation::save 在打包时注入。

pub fn set_notes_text(&mut self, text: Option<&str>)

设置备注文本（整体替换）。

若 text 为 None，则删除 notes；否则按 \n 切分为多段。 备注的持久化由 crate::presentation::Presentation::save 在打包阶段 写入 /ppt/notesSlides/notesSlideN.xml；本方法仅设置内存模型。

pub fn comments(&self) -> Option<&CommentList>

返回该 slide 的评论列表（不可变）。

None 表示该 slide 没有评论 part。

pub fn comments_mut(&mut self) -> Option<&mut CommentList>

返回该 slide 的评论列表（可变）。

pub fn set_comments(&mut self, lst: Option<CommentList>)

直接覆盖评论列表。None 表示删除评论。

pub fn add_comment<X: EmuExt, Y: EmuExt>( &mut self, author_id: u32, pos_x: X, pos_y: Y, text: impl Into<String>, ) -> u32

添加一条评论。

这是便捷 API：自动维护评论索引（idx 在该 slide 内递增）， 并确保 comments 字段为 Some。

参数

• author_id：作者 ID（需在 Presentation.comment_authors 中存在）；
• pos_x / pos_y：评论锚点坐标（EMU）；
• text：评论正文。

返回值

新评论在该 slide 中的 idx。

示例

use pptx_rs::Presentation;
use pptx_rs::Inches;

let mut p = Presentation::new().unwrap();
let counter = p.id_counter();
// 先注册作者，拿到 author_id（必须在借用 slides_mut 之前完成）
let author_id = p.comment_authors_mut().get_or_insert_id("张三", "ZS");
let slide = p.slides_mut().add_slide(counter).unwrap();
let idx = slide.add_comment(author_id, Inches(1.0), Inches(1.0), "评论内容");

pub fn clear_comments(&mut self)

清除该 slide 的所有评论。

Trait Implementations

impl Clone for Slide

fn clone(&self) -> Slide

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Slide

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.