Table、TableRow 和 TableCell¶

featherdoc::Table 用于编辑 Word 表格结构和表格级元数据。 featherdoc::TableRow 用于编辑行元数据和可见单元格文本。 featherdoc::TableCell 用于编辑单元格内容、宽度、合并状态、边框、底色、边距和内部段落。

索引、单位和返回语义¶

表格 API 使用从 0 开始的索引。row_index 表示可见表格行， cell_index 表示该行内的可见单元格，grid_column 表示考虑跨列后的 Word 网格列。宽度、缩进、边距和间距都使用 twips。返回 std::optional<T> 的方法在目标无法解析时返回空值；返回 bool 的方法表示表格 XML 是否成功修改。

常用任务入口¶

常见表格工作流可以从这些入口开始：

创建表格：调用 Document::append_table(...) 或 TemplatePart::append_table(...)。
安全定位单元格：使用 find_row(...)、find_cell(...) 或 find_cell_by_grid_column(...)，并检查返回的 std::optional。
填充矩形数据区域：使用 set_row_texts(...)、set_rows_texts(...) 或 set_cell_block_texts(...)。
固定布局：设置 table_layout_mode::fixed、set_width_twips(...) 和 set_column_width_twips(...)。
设置行和单元格细节：用 TableRow 管重复表头和行高，用 TableCell 管合并、底色、边距、边框和内部段落。

成功/失败语义¶

返回形态	成功含义	失败或无变化含义
`std::optional<TableRow>`	包含已经存在的可见行句柄。	行索引超出当前表格时为空。
`std::optional<TableCell>`	通过可见单元格或网格列解析后，包含单元格句柄。	行、可见单元格或网格列无法解析时为空。
`bool`	`true` 表示请求的单元格、布局或边框修改全部应用。	`false` 表示至少一个目标缺失、参数无效，或没有发生变化。
`TableRow` / `TableCell`	返回句柄指向插入或追加的表格节点。	后续修改应继续使用该返回句柄。
`std::optional<T>` 检查值	包含已有的表格、行或单元格元数据。	空值表示该元数据不存在或无法解析。

短示例¶

auto table = doc.body_template().append_table(2, 2);
table.set_row_texts(0, {"Name", "Status"});
table.set_row_texts(1, {"Ada", "Approved"});

if (auto cell = table.find_cell(1, 1)) {
    cell->set_fill_color("D9EAF7");
}

类型化签名导读¶

签名	参数	返回语义
`std::optional<TableRow> find_row(std::size_t row_index)`	`row_index`：从 0 开始的可见行索引。	目标行不存在时返回空值。
`std::optional<TableCell> find_cell(std::size_t row_index, std::size_t cell_index)`	`row_index`：行索引。`cell_index`：该行内的可见单元格索引。	行或单元格无法解析时返回空值。
`std::optional<TableCell> find_cell_by_grid_column(std::size_t row_index, std::size_t grid_column)`	`row_index`：行索引。`grid_column`：解析后的 Word 网格列。	网格列无法映射到可见单元格时返回空值。
`bool set_cell_text(std::size_t row_index, std::size_t cell_index, const std::string &text)`	`row_index` 和 `cell_index`：可见单元格位置。`text`：替换文本。	目标单元格文本成功替换时返回 `true`。
`bool set_rows_texts(std::size_t start_row_index, const std::vector<std::vector<std::string>> &rows)`	`start_row_index`：首个目标行。`rows`：行/单元格文本矩阵。	所有目标单元格成功更新时返回 `true`。
`bool set_cell_block_texts(std::size_t start_row_index, std::size_t start_cell_index, const std::vector<std::vector<std::string>> &rows)`	`start_row_index` 和 `start_cell_index`：块起点。`rows`：矩形文本矩阵。	目标矩形块成功更新时返回 `true`。
`bool set_column_width_twips(std::size_t column_index, std::uint32_t width_twips)`	`column_index`：从 0 开始的网格列。`width_twips`：列宽，单位 twips。	网格列宽成功更新时返回 `true`。
`bool set_border(table_border_edge edge, border_definition border)`	`edge`：表格边框边。`border`：样式、尺寸、颜色和间距。	边框定义成功写入时返回 `true`。
`bool TableRow::set_texts(const std::vector<std::string> &texts)`	`texts`：当前行可见单元格文本。	所有提供的单元格成功更新时返回 `true`。
`bool TableCell::merge_right(std::size_t additional_cells = 1U)`	`additional_cells`：向右合并的单元格数量。	横向合并元数据成功应用时返回 `true`。
`bool TableCell::merge_down(std::size_t additional_rows = 1U)`	`additional_rows`：向下合并的行数。	纵向合并元数据成功应用时返回 `true`。
`bool TableCell::set_margin_twips(cell_margin_edge edge, std::uint32_t margin_twips)`	`edge`：单元格边距边。`margin_twips`：边距值，单位 twips。	单元格边距成功更新时返回 `true`。

表格结构与查找¶

方法	返回值	用途
`next()`	`Table &`	将表格迭代器推进到下一个表格。
`has_next() const`	`bool`	检查表格迭代器是否还能继续推进。
`rows()`	`TableRow &`	访问当前表格的行迭代器。
`find_row(row_index)`	`std::optional<TableRow>`	按从 0 开始的行索引查找行。
`find_cell(row_index, cell_index)`	`std::optional<TableCell>`	按行索引和可见单元格索引查找单元格。
`find_cell_by_grid_column(row_index, grid_column)`	`std::optional<TableCell>`	按解析后的网格列查找单元格。
`set_cell_text(row_index, cell_index, text)`	`bool`	替换可见单元格文本。
`set_cell_text_by_grid_column(row_index, grid_column, text)`	`bool`	按解析后的网格列替换单元格文本。
`set_row_texts(row_index, texts)`	`bool`	替换某一行的可见单元格文本。
`set_rows_texts(start_row_index, rows)`	`bool`	从指定行开始替换矩形行块。
`set_cell_block_texts(start_row_index, start_cell_index, rows)`	`bool`	从指定行和单元格开始替换矩形单元格块。
`append_row(std::size_t cell_count = 1U)`	`TableRow`	追加一行，并指定单元格数量。

表格布局、样式与边框¶

方法	返回值	用途
`width_twips() const`	`std::optional<std::uint32_t>`	读取表格宽度。
`set_width_twips(width_twips)`	`bool`	设置表格宽度，单位是 twips。
`column_width_twips(column_index) const`	`std::optional<std::uint32_t>`	读取某一网格列宽度。
`set_column_width_twips(column_index, width_twips)`	`bool`	设置某一网格列宽度。
`layout_mode() const`	`std::optional<table_layout_mode>`	读取自动适应或固定布局模式。
`set_layout_mode(table_layout_mode layout_mode)`	`bool`	设置表格布局模式。
`alignment() const`	`std::optional<table_alignment>`	读取表格对齐方式。
`set_alignment(table_alignment alignment)`	`bool`	设置表格对齐方式。
`indent_twips() const`	`std::optional<std::uint32_t>`	读取表格缩进。
`set_indent_twips(indent_twips)`	`bool`	设置表格缩进。
`cell_spacing_twips() const`	`std::optional<std::uint32_t>`	读取单元格间距。
`set_cell_spacing_twips(spacing_twips)`	`bool`	设置单元格间距。
`position() const`	`std::optional<table_position>`	读取浮动表格位置元数据。
`set_position(table_position position)`	`bool`	设置浮动表格位置元数据。
`style_id() const`	`std::optional<std::string>`	读取表格样式 ID。
`set_style_id(style_id)`	`bool`	设置表格样式 ID。
`style_look() const`	`std::optional<table_style_look>`	读取表格样式外观标记。
`set_style_look(table_style_look style_look)`	`bool`	设置表格样式外观标记。
`border(table_border_edge edge) const`	`std::optional<border_inspection_summary>`	读取某个表格边框。
`set_border(table_border_edge edge, border_definition border)`	`bool`	设置某个表格边框。

TableRow¶

方法	返回值	用途
`cells()`	`TableCell &`	访问当前行的单元格迭代器。
`find_cell(cell_index)`	`std::optional<TableCell>`	按可见单元格索引查找单元格。
`find_cell_by_grid_column(grid_column)`	`std::optional<TableCell>`	按解析后的网格列查找单元格。
`height_twips() const`	`std::optional<std::uint32_t>`	读取行高。
`height_rule() const`	`std::optional<row_height_rule>`	读取行高规则。
`set_height_twips(height_twips, row_height_rule)`	`bool`	设置行高和行高规则。
`cant_split() const`	`bool`	检查当前行是否禁止跨页拆分。
`set_cant_split()` / `clear_cant_split()`	`bool`	开启或清除禁止跨页拆分。
`repeats_header() const`	`bool`	检查当前行是否作为重复表头。
`set_repeats_header()` / `clear_repeats_header()`	`bool`	开启或清除重复表头元数据。
`set_texts(texts)`	`bool`	替换当前行的所有可见单元格文本。
`insert_row_before()` / `insert_row_after()`	`TableRow`	在当前行前后插入行。
`append_cell()`	`TableCell`	向当前行追加单元格。

TableCell¶

方法	返回值	用途
`paragraphs()`	`Paragraph &`	访问单元格内部段落。
`get_text() const`	`std::string`	读取单元格扁平化文本。
`set_text(const std::string &text) const`	`bool`	替换单元格文本。
`insert_cell_before()` / `insert_cell_after()`	`TableCell`	在当前单元格前后插入单元格。
`width_twips() const`	`std::optional<std::uint32_t>`	读取单元格宽度。
`set_width_twips(width_twips)`	`bool`	设置单元格宽度，单位是 twips。
`column_span() const`	`std::size_t`	读取横向跨列数量。
`column_index() const`	`std::optional<std::size_t>`	读取解析后的网格列索引。
`merge_right(additional_cells = 1U)`	`bool`	向右合并指定数量的单元格。
`merge_down(additional_rows = 1U)`	`bool`	向下合并指定数量的单元格。
`unmerge_right()` / `unmerge_down()`	`bool`	清除横向或纵向合并状态。
`vertical_merge() const`	`cell_vertical_merge`	读取纵向合并状态。
`row_span() const`	`std::size_t`	读取纵向跨行数量。
`vertical_alignment() const`	`std::optional<cell_vertical_alignment>`	读取单元格垂直对齐方式。
`set_vertical_alignment(alignment)`	`bool`	设置单元格垂直对齐方式。
`text_direction() const`	`std::optional<cell_text_direction>`	读取文字方向。
`set_text_direction(direction)`	`bool`	设置文字方向。
`fill_color() const`	`std::optional<std::string>`	读取单元格底色。
`set_fill_color(fill_color)`	`bool`	设置单元格底色。
`margin_twips(cell_margin_edge edge) const`	`std::optional<std::uint32_t>`	读取某个单元格边距。
`set_margin_twips(edge, margin_twips)`	`bool`	设置某个单元格边距。
`border(cell_border_edge edge) const`	`std::optional<border_inspection_summary>`	读取某个单元格边框。
`set_border(cell_border_edge edge, border_definition border)`	`bool`	设置某个单元格边框。

示例¶

auto table = doc.body_template().append_table(2, 3);
table.set_layout_mode(featherdoc::table_layout_mode::fixed);
table.set_width_twips(9000);
table.set_row_texts(0, {"SKU", "Name", "Quantity"});

auto header = table.find_row(0);
if (header) {
    header->set_repeats_header();
}

auto sku = table.find_cell(0, 0);
if (sku) {
    sku->set_fill_color("D9EAF7");
    sku->set_vertical_alignment(featherdoc::cell_vertical_alignment::center);
}