Struct ChartShape 

pub struct ChartShape { /* private fields */ }

高阶图表形状（承载 <p:graphicFrame> + <c:chart r:id="..."/> 引用）。

通过 ChartShape::chart / ChartShape::chart_mut 访问图表数据； 通过 Shape trait 方法（left / top / width / height）调整位置与尺寸。

内部不变量

frame.graphic 始终保持为 Graphic::Chart(_)。本类型所有便捷方法 （chart_type / set_chart_type / data / data_mut / rid / set_rid） 在不变量被破坏时静默忽略或返回 None，绝不 panic—— 这与库整体“零 panic“约定一致（参见 .trae/rules/project_rules.md §5）。

Implementations

impl ChartShape

pub fn new(chart_type: ChartType, data: ChartData) -> Self

构造一个指定类型与数据的图表形状（rid 留空，由 presentation 层填充）。

参数

• chart_type：图表类型（柱/条/线/饼）。
• data：图表数据（类别 + 系列 + 可选标题）。

pub fn from_frame(frame: OxmlFrame) -> Self

从 oxml Frame 构造（通常用于读取已有图表时）。

pub fn chart(&self) -> Option<&OxmlChart>

取内部 oxml Chart 引用。

返回 None 仅在内部不变量被外部错误破坏时（frame.graphic 不是 Chart 变体）。

pub fn chart_mut(&mut self) -> Option<&mut OxmlChart>

取内部 oxml Chart 可变引用。

pub fn chart_type(&self) -> ChartType

图表类型（便捷访问）。

若内部不变量被破坏（frame.graphic 不是 Chart），返回 ChartType::Column 作为兜底。

pub fn set_chart_type(&mut self, chart_type: ChartType)

修改图表类型（保留数据不变）。不变量被破坏时静默忽略。

pub fn data(&self) -> Option<&ChartData>

图表数据引用。

pub fn data_mut(&mut self) -> Option<&mut ChartData>

图表数据可变引用。

pub fn rid(&self) -> &str

当前关联的关系 id（指向 /ppt/charts/chartN.xml）。

新建时为空字符串；由 Presentation::to_opc_package 在写出 chart part 时填充。 不变量被破坏时返回空字符串。

pub fn set_rid(&mut self, rid: impl Into<String>)

设置关系 id（一般由 presentation 层自动调用，用户无需直接设置）。 不变量被破坏时静默忽略。

pub fn set_placeholder(&mut self, ph_idx: u32, ph_type: Option<&str>)

将本图表形状标记为占位符（TODO-007 图表占位符类型化填充）。

写出 XML 时会在 <p:nvGraphicFramePr>/<p:nvPr> 内插入 <p:ph type="chart" idx="..."/>，使 PowerPoint 把该 graphicFrame 识别为图表占位符的填充实例。

参数

• ph_idx：占位符索引（对应 <p:ph idx="..."/>）。
• ph_type：占位符类型字符串（如 "chart" / "obj"），None 时省略 type 属性。

pub fn clear_placeholder(&mut self)

清除占位符标记，使本图表形状变为普通 graphicFrame。

pub fn is_placeholder(&self) -> bool

是否被标记为占位符。

pub fn ph_idx(&self) -> Option<u32>

占位符索引（若已标记）。

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

占位符类型字符串（若已标记）。

pub fn data_labels(&self) -> Option<&DataLabels>

图表级数据标签引用（<c:dLbls>，写在图表元素内、<c:ser> 之前）。

系列级 ChartShape::series_data_labels 会覆盖此处的图表级配置。 返回 None 仅在内部不变量被破坏时（frame.graphic 不是 Chart 变体）。

pub fn set_data_labels(&mut self, labels: Option<DataLabels>)

设置图表级数据标签。

传入 None 清除现有配置。不变量被破坏时静默忽略。

参数

• labels：数据标签配置；None 清除，Some(dl) 写出 <c:dLbls>（若非空）。

pub fn series_data_labels(&self, series_idx: usize) -> Option<&DataLabels>

系列级数据标签引用（按系列索引访问）。

系列级配置会覆盖图表级 ChartShape::data_labels。返回 None 的情况：

• 内部不变量被破坏；
• 索引越界；
• 该系列未设置系列级数据标签（继承图表级）。

pub fn set_series_data_labels( &mut self, series_idx: usize, labels: Option<DataLabels>, )

设置指定系列的数据标签（覆盖图表级配置）。

参数

• series_idx：系列索引（越界时静默忽略）；
• labels：数据标签配置；None 清除该系列的系列级配置（继承图表级）。

pub fn is_series_secondary(&self, series_idx: usize) -> bool

查询指定系列是否绑定到次坐标轴（右侧 Y 轴）。

返回 false 的情况：

• 内部不变量被破坏；
• 索引越界；
• 该系列绑定主轴（secondary_axis=false）。

注意：饼图/散点图/气泡图不支持次坐标轴，写出时该字段被忽略。

pub fn set_series_secondary(&mut self, series_idx: usize, secondary: bool)

设置指定系列是否绑定到次坐标轴（右侧 Y 轴）。

典型场景：主轴显示柱形图，次轴显示折线图（双轴组合图）。

参数

• series_idx：系列索引（越界时静默忽略）；
• secondary：true 绑定次轴，false 绑定主轴。

限制

饼图/散点图/气泡图不支持次坐标轴（OOXML 规范约束）， to_xml 写出时会忽略该字段。

pub fn push_series(&mut self, series: ChartSeries) -> Option<usize>

添加一个新系列到图表数据末尾，返回新系列的索引。

便捷方法：避免外部构造 ChartData 字面量。不变量被破坏时返回 None。

Trait Implementations

impl Clone for ChartShape

fn clone(&self) -> ChartShape

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChartShape

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

Formats the value using the given formatter.

impl Default for ChartShape

fn default() -> ChartShape

Returns the “default value” for a type.

impl Shape for ChartShape

fn rotation(&self) -> f64

图表不支持旋转（OOXML 规范）。调用 Shape::set_rotation 会被忽略。

fn id(&self) -> u32

形状唯一 ID（在所属 slide 内）。

fn set_id(&mut self, id: u32)

设置 ID。

fn name(&self) -> &str

形状名。

fn set_name(&mut self, name: String)

设置形状名。

fn shape_type(&self) -> &'static str

形状类型（如 "text_box" / "picture" / …）。

fn left(&self) -> Emu

左上角 x（EMU）。

fn set_left(&mut self, emu: Emu)

设置左上角 x。

fn top(&self) -> Emu

左上角 y（EMU）。

fn set_top(&mut self, emu: Emu)

设置左上角 y。

fn width(&self) -> Emu

宽（EMU）。

fn set_width(&mut self, emu: Emu)

设置宽。

fn height(&self) -> Emu

高（EMU）。

fn set_height(&mut self, emu: Emu)

设置高。

fn set_rotation(&mut self, _deg: f64)

设置旋转角度。