# Tabledef API 参考

## 概述

Tabledef API 提供管理 Excel 表格(也称为列表对象)的函数，包括表格属性、列管理、汇总行和样式选项。

## 表格属性

const char *td_name(TabledefHandle td)

  获取表格名称。

  参数:

    - td -- 表格句柄。

  返回:

    表格名称

void td_range(TabledefHandle td, int *beginRow, int *beginCol, int *endRow, int *endCol)

  获取表格范围坐标。

  参数:

    - td -- 表格句柄。

    - beginRow -- 存储起始行索引的指针。

    - beginCol -- 存储起始列索引的指针。

    - endRow -- 存储终止行索引的指针。

    - endCol -- 存储终止列索引的指针。

const char *td_display_name(TabledefHandle td)

  获取表格显示名称。

  参数:

    - td -- 表格句柄。

  返回:

    表格显示名称。

void td_set_display_name(TabledefHandle td, const char *name)

  设置表格显示名称。

  参数:

    - td -- 表格句柄。

    - name -- 新的显示名称。

const char *td_comment(TabledefHandle td)

  获取表格注释。

  参数:

    - td -- 表格句柄。

  返回:

    表格注释。

void td_set_comment(TabledefHandle td, const char *comment)

  设置表格注释。

  参数:

    - td -- 表格句柄。

    - comment -- 表格注释。

## 列管理

const char *td_col_name(TabledefHandle td, int idx)

  按索引获取列名。

  参数:

    - td -- 表格句柄。

    - idx -- 列索引。

  返回:

    列名。

int td_set_col_name(TabledefHandle td, int idx, const char *name)

  设置列名。

  参数:

    - td -- 表格句柄。

    - idx -- 列索引。

    - name -- 新列名。

  返回:

    成功返回 1，失败返回 0。

int td_insert_col(TabledefHandle td, int idx, const char *colName)

  向表格插入新列。

  参数:

    - td -- 表格句柄。

    - idx -- 插入列的位置。

    - colName -- 新列的名称。

  返回:

    成功返回 1，失败返回 0。

void td_delete_col_by_index(TabledefHandle td, int idx)

  按索引删除列。

  参数:

    - td -- 表格句柄。

    - idx -- 要删除的列索引。

void td_delete_col(TabledefHandle td, const char *colName)

  按名称删除列。

  参数:

    - td -- 表格句柄。

    - colName -- 要删除的列名。

## 汇总行设置

void td_set_totals_row_label(TabledefHandle td, const char *label)

  设置汇总行标签。

  参数:

    - td -- 表格句柄。

    - label -- 汇总行标签。

void td_set_display_total(TabledefHandle td, int show)

  设置是否显示汇总行。

  参数:

    - td -- 表格句柄。

    - show -- 1 显示汇总行，0 隐藏。

int td_totals_row_func(TabledefHandle td, int column_idx)

  获取列的汇总行函数。

  参数:

    - td -- 表格句柄。

    - column_idx -- 列索引。

  返回:

    汇总函数类型(参见 `TotalsFuncEnum`)。

void td_set_totals_row_func(TabledefHandle td, int colIndex, int func)

  设置列的汇总行函数。

  参数:

    - td -- 表格句柄。

    - colIndex -- 列索引。

    - func -- 汇总函数类型(参见 `TotalsFuncEnum`)。

## 表格样式

const char *td_style_name(TabledefHandle td)

  获取表格样式名称。

  参数:

    - td -- 表格句柄。

  返回:

    表格样式名称。

  - 内置表格样式

void td_set_style_name(TabledefHandle td, const char *style_name)

  按名称设置表格样式。

  参数:

    - td -- 表格句柄。

    - style_name -- 表格样式名称。

void td_set_preset_style(TabledefHandle td, int id)

  设置表格预设样式。

  参数:

    - td -- 表格句柄。

    - id -- 预设样式 ID。

int td_row_strips(TabledefHandle td)

  检查是否启用行条纹（交替行颜色）。

  参数:

    - td -- 表格句柄。

  返回:

    启用行条纹返回 1，否则返回 0。

void td_set_row_strips(TabledefHandle td, int strips)

  设置行条纹(交替行颜色)。

  参数:

    - td -- 表格句柄。

    - strips -- 1 启用行条纹，0 禁用。

## 枚举类型

相关枚举类型的定义请参考 枚举类型，特别是 TotalsFuncEnum。

## 使用说明

- 表格提供结构化数据管理，具有内置的筛选、排序和格式化功能

- 汇总行函数可以执行自动计算，如求和、平均值、计数等

- 表格样式控制视觉外观，包括颜色、边框和条纹

- 列操作自动调整表格范围并保持数据完整性

## 与工作表的集成

表格通常通过工作表函数创建和访问:

    // Add table to worksheet
    TabledefHandle table = ws_add_tabledef(worksheet, "SalesData", 1, 1, 10, 5);

    // Configure table properties
    td_set_display_name(table, "Monthly Sales");
    td_set_display_total(table, 1);

    // Set total functions for specific columns
    td_set_totals_row_func(table, 3, TOTALS_FUNC_SUM);  // Sum for column 3 (sales amount)
    td_set_totals_row_func(table, 4, TOTALS_FUNC_AVERAGE);  // Average for column 4 (units sold)

Styled using the Piccolo Theme