工作表级别

Sheet 类代表一个工作表。

属性	类型	说明
`name`	`string`	工作表名称
`hidden`	`boolean`	是否隐藏
`merges`	`RangeNum[]`	合并单元格区域列表
`defaultColWidth`	`number`	默认列宽（像素）
`defaultRowHeight`	`number`	默认行高（像素）
`showGridLines`	`boolean`	是否显示网格线
`showRowColHeaders`	`boolean`	是否显示行列标题
`activeCell`	`CellNum`	当前活动单元格
`activeAreas`	`RangeNum[]`	当前选中区域
`rows`	`Row[]`	所有行
`cols`	`Col[]`	所有列
`rowCount`	`number`	行数（只读）
`colCount`	`number`	列数（只读）
`xSplit`	`number`	冻结列数
`ySplit`	`number`	冻结行数
`drawings`	`Drawing[]`	图形对象列表（图表、图片等）

getRow(r: number): Row

获取指定行对象。

const row = sheet.getRow(0); // 获取第一行

getCol(c: number): Col

获取指定列对象。

const col = sheet.getCol(0); // 获取第一列（A列）

getCell(r: number, c: number): Cell

获取指定单元格。

const cell = sheet.getCell(0, 0); // 获取 A1 单元格

getCellByStr(cellStr: string): Cell

通过字符串引用获取单元格。

const cell = sheet.getCellByStr("A1");

rangeStrToNum(rangeStr: string): RangeNum

将字符串范围转换为数字范围对象。

const rangeNum = sheet.rangeStrToNum("A1:C3");
// 返回: {s:{r:0,c:0}, e:{r:2,c:2}}

eachArea(rangeRef: RangeRef, callback: (r, c, index) => void, reverse?: boolean): void

遍历指定区域的每个单元格。

// 正向遍历
sheet.eachArea("A1:C3", (r, c, index) => {
  const cell = sheet.getCell(r, c);
  console.log(cell.showVal);
});

// 反向遍历（用于删除操作，避免索引混乱）
sheet.eachArea("A:A", (r, c) => {
  if (sheet.getCell(r, c).showVal === "") {
    sheet.delRows(r, 1);
  }
}, true);

showAllHidRows(): void

显示所有隐藏的行。

sheet.showAllHidRows();

showAllHidCols(): void

显示所有隐藏的列。

sheet.showAllHidCols();

addRows(startR: number, num: number): void

在指定位置插入行。

sheet.addRows(5, 3); // 在第 5 行位置插入 3 行

注意：多个同时调用时，应反向遍历以避免索引混乱。

addCols(startC: number, num: number): void

在指定位置插入列。

sheet.addCols(2, 2); // 在第 2 列位置插入 2 列

delRows(startR: number, num: number): void

删除指定行。

sheet.delRows(5, 3); // 删除从第 5 行开始的 3 行

delCols(startC: number, num: number): void

删除指定列。

sheet.delCols(2, 2); // 删除从第 2 列开始的 2 列

mergeCells(rangeRef: RangeRef): void

合并指定区域的单元格。

sheet.mergeCells("A1:C3");
// 或
sheet.mergeCells({s:{r:0,c:0}, e:{r:2,c:2}});

unMergeCells(cellRef: CellRef): void

取消合并（传入区域内任意单元格引用）。

sheet.unMergeCells("A1"); // 取消包含 A1 的合并区域

rangeSort(sortItems: SortItem[], range?: RangeRef): void

对指定区域进行排序。

SortItem 接口：

interface SortItem {
  type: "column" | "row" | "custom";
  order?: "asc" | "desc" | "value"; // type="custom" 时省略
  index: string; // 列/行标签，行从 1 开始，列从 A 开始
  sortData?: any[]; // order="value" 时使用，基于此数据排序
  cb?: (rowsArray: Cell[][], sortIndex: number) => Cell[][]; // type="custom" 时使用
}

示例：按自定义顺序排序

const sheet = SN.activeSheet;
// 除标题外，按 C 列字母顺序排序：A V U T
sheet.rangeSort(
  [{
    type: 'column',
    order: 'value',
    index: 'C',
    sortData: ["A", "V", "U", "T"]
  }],
  {s:{c:0,r:1}, e:{c:sheet.colCount, r:sheet.rowCount}}
);

insertTable(data: (ICellConfig | string | number)[][], startCell: CellRef, globalConfig?: object): RangeNum

在指定位置插入表格数据。

ICellConfig 接口：

interface ICellConfig {
  v?: string;       // 单元格值
  w?: number;       // 列宽（像素），仅在首行设置
  h?: number;       // 行高（像素），仅在首列设置
  b?: boolean;      // 是否粗体
  s?: number;       // 字体大小
  fg?: string;      // 背景色
  a?: 'l' | 'r' | 'c'; // 对齐方式（left/right/center）
  c?: string;       // 文本颜色
  mr?: number;      // 向右合并单元格数（不包括自身）
  mb?: number;      // 向下合并单元格数（不包括自身）
}

globalConfig 参数：

a: 对齐方式
border: 是否显示边框
w: 默认列宽
h: 默认行高
fg: 背景色
c: 文本颜色

示例：生成会议记录模板

const t = [
  [
    { v: "Meeting Minutes", s: 16, mr: 3, fg: "#eee", h: 45, b: true },
    { w: 160 }, "", { w: 160 }
  ],
  ["Time", "", "Location", ""],
  ["Host", "", "Recorder", ""],
  ["Expected", "", "Present", ""],
  ["Absent Members", { mr: 2 }, "", ""],
  ["Topic", { mr: 2 }, "", ""],
  [{ v: "Content", h: 280 }, { mr: 2 }, "", ""],
  [{ v: "Remarks", h: 80 }, { mr: 2 }, "", ""]
]; // 必须是矩形矩阵

SN.activeSheet.insertTable(t, "A1", {
  border: true,
  a: "c",
  h: 35,
  w: 140
});

注意：

对于合并单元格（mr/mb），需要添加相同数量的空字符串占位符，保持二维数组的矩形结构。
例如：{ mr: 2 }, "", ""

addDrawing(config: object): Drawing

添加图形对象（图表、图片等）。

示例：添加图表

SN.activeSheet.addDrawing({
  type: 'chart',
  startCell: 'B2',
  option: {
    title: { text: '销售趋势图' },
    legend: {
      data: ['销量'] // 或使用引用: `${sheet.name}!B3`
    },
    xAxis: {
      type: 'category',
      data: ['一月', '二月', '三月'] // 或引用: `${sheet.name}!C2:E2`
    },
    yAxis: { type: 'value' },
    series: [
      {
        name: '销量',
        type: 'line',
        data: [820, 932, 901] // 或引用: `${sheet.name}!C3:E3`
      }
    ]
  }
});

getDrawingsByCell(cellRef: CellRef): Drawing[]

获取指定单元格位置的所有图形对象。

const drawings = sheet.getDrawingsByCell("B2");

removeDrawing(id: string): void

删除指定 ID 的图形对象。

sheet.removeDrawing("drawing-id");