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 series_format(&self, series_idx: usize) -> Option<&SeriesFormat>

查询指定系列的样式（<c:spPr>）。

返回 None 的情况：

• 内部不变量被破坏（frame.graphic 不是 Chart 变体）；
• 索引越界；
• 该系列未设置样式（PowerPoint 自动分配主题色）。

pub fn set_series_format( &mut self, series_idx: usize, format: Option<SeriesFormat>, )

设置指定系列的样式（颜色/填充/边框）。

参数

• series_idx：系列索引（越界时静默忽略）；
• format：系列样式；None 清除该系列的样式（PowerPoint 自动分配主题色）。

示例

use pptx_rs::oxml::chart::{ChartData, ChartSeries, ChartType, SeriesFormat};
use pptx_rs::oxml::color::Color;
use pptx_rs::units::RGBColor;
use pptx_rs::{Presentation, Inches};

let mut prs = Presentation::new().expect("Presentation::new failed");
let counter = prs.id_counter();
let slide = prs.slides_mut().add_slide(counter).expect("add_slide failed");
let data = ChartData {
    series: vec![ChartSeries::new("S1", vec![1.0, 2.0])],
    ..Default::default()
};
let mut chart = slide.shapes_mut()
    .add_chart(ChartType::Column, data, Inches(1.0), Inches(1.0), Inches(8.0), Inches(4.0))
    .expect("add_chart failed");
// 设置第 0 个系列为红色
chart.set_series_format(0, Some(SeriesFormat::solid_fill(Color::RGB(RGBColor(0xFF, 0x00, 0x00)))));

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 secondary_chart_type(&self) -> Option<ChartType>

查询次图表类型（组合图模式，模块 D）。

返回 None 的情况：

• 内部不变量被破坏；
• 未设置次图表类型（非组合图模式）。

设置次图表类型后，secondary_axis=true 的系列会写入第二个图表元素 （如 c:lineChart），与主图表元素共用类别轴但绑定次 valAx。

pub fn set_secondary_chart_type(&mut self, chart_type: Option<ChartType>)

设置次图表类型，启用组合图模式（模块 D）。

典型场景：主轴柱形图 + 次轴折线图（双轴组合图）。 设置后，to_xml 会把 secondary_axis=true 的系列写入第二个图表元素。

参数

• chart_type：次图表类型；None 清除组合图模式（所有系列写入主图表元素）。

示例

use pptx_rs::oxml::chart::{ChartData, ChartSeries, ChartType};
use pptx_rs::{Presentation, Inches};

let mut prs = Presentation::new().expect("Presentation::new failed");
let counter = prs.id_counter();
let slide = prs.slides_mut().add_slide(counter).expect("add_slide failed");
let mut s1 = ChartSeries::new("Bar", vec![10.0, 20.0]);
let mut s2 = ChartSeries::new("Line", vec![5.0, 8.0]);
s2.secondary_axis = true;  // 折线系列绑定次轴
let data = ChartData {
    series: vec![s1, s2],
    ..Default::default()
};
let mut chart = slide.shapes_mut()
    .add_chart(ChartType::Column, data, Inches(1.0), Inches(1.0), Inches(8.0), Inches(4.0))
    .expect("add_chart failed");
// 启用组合图模式：次轴折线图
chart.set_secondary_chart_type(Some(ChartType::Line));

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)

设置旋转角度。