🔍
🎯 官网演示

单元格级别

Cell 类代表单个单元格，提供完整的数据、样式、验证等功能。

属性 类型 说明
editVal string 编辑值或公式（可读写）
calcVal any 计算值（只读）
showVal string 显示值（只读）
type string 单元格类型（只读）：string/number/date/time/dateTime/boolean/error
isFormula boolean 是否为公式（只读）
isMerged boolean 是否为合并单元格
master CellNum | null 如果是合并单元格，指向主单元格

属性 类型 说明
font object 字体样式
alignment object 对齐方式
border object 边框样式
fill object 填充样式
numFmt string 数字格式

属性 类型 说明
hyperlink object 超链接配置
dataValidation object 数据验证规则
validData boolean 数据验证结果（只读）

字体样式配置对象。

{
  name?: string;        // 字体名称，如 'Arial', '微软雅黑'
  size?: number;        // 字体大小，默认 11
  bold?: boolean;       // 是否粗体
  italic?: boolean;     // 是否斜体
  underline?: string;   // 下划线：'single' | 'double' | 'none'
  strike?: boolean;     // 是否删除线
  color?: string;       // 字体颜色，格式：'#RRGGBB'
  vertAlign?: string;   // 上下标：'superscript' | 'subscript'
  outline?: boolean;    // 是否轮廓（Mac专用）
  charset?: number;     // 字符集
}

示例：

const cell = sheet.getCell(0, 0);

// 基础字体设置
cell.font = {
  name: '微软雅黑',
  size: 14,
  bold: true
};

// 带颜色和下划线
cell.font = {
  size: 12,
  color: '#FF0000',
  underline: 'single'
};

// 删除线
cell.font = { strike: true };

对齐方式配置对象。

{
  horizontal?: string;  // 水平对齐：'left' | 'center' | 'right' | 'fill' | 'justify' | 'distributed'
  vertical?: string;    // 垂直对齐：'top' | 'middle' | 'bottom' | 'justify' | 'distributed'
  wrapText?: boolean;   // 是否自动换行
  indent?: number;      // 缩进级别（仅 horizontal='left'/'right' 时有效）
}

示例：

// 水平居中，垂直居中
cell.alignment = {
  horizontal: 'center',
  vertical: 'middle'
};

// 自动换行
cell.alignment = { wrapText: true };

// 左对齐并缩进2级
cell.alignment = {
  horizontal: 'left',
  indent: 2
};

// 两端对齐
cell.alignment = {
  horizontal: 'justify',
  vertical: 'top'
};

边框样式配置对象，可单独设置四个方向的边框。

{
  top?: {
    style: string;    // 边框样式
    color?: string;   // 边框颜色，格式：'#RRGGBB'，默认 '#000000'
  };
  right?: { style: string; color?: string; };
  bottom?: { style: string; color?: string; };
  left?: { style: string; color?: string; };
  diagonal?: { style: string; color?: string; };
}

边框样式 (style)：

  • thin - 细线（最常用）
  • medium - 中等
  • thick - 粗线
  • dotted - 点线
  • dashed - 虚线
  • double - 双线
  • hair - 极细线
  • dashDot - 点划线
  • dashDotDot - 双点划线
  • mediumDashed - 中等虚线
  • mediumDashDot - 中等点划线
  • mediumDashDotDot - 中等双点划线
  • slantDashDot - 斜点划线

示例：

// 设置所有边框
cell.border = {
  top: { style: 'thin' },
  right: { style: 'thin' },
  bottom: { style: 'thin' },
  left: { style: 'thin' }
};

// 设置单边框
cell.border = {
  bottom: { style: 'medium', color: '#FF0000' }
};

// 添加对角线
cell.border = {
  diagonal: { style: 'thin', color: '#0000FF' }
};

// 清空边框
cell.border = {};

填充样式配置对象，支持纯色填充和渐变填充。

{
  type: 'pattern';       // 填充类型
  pattern: string;       // 图案类型
  fgColor?: string;      // 前景色，格式：'#RRGGBB'
  bgColor?: string;      // 背景色，格式：'#RRGGBB'
}

图案类型 (pattern)：

  • solid - 纯色（最常用）
  • darkGray - 深灰
  • mediumGray - 中灰
  • lightGray - 浅灰
  • gray125 - 12.5% 灰
  • gray0625 - 6.25% 灰
  • darkHorizontal - 深色横线
  • darkVertical - 深色竖线
  • darkDown - 深色斜线（左上到右下）
  • darkUp - 深色斜线（左下到右上）
  • darkGrid - 深色网格
  • darkTrellis - 深色斜网格
  • lightHorizontal - 浅色横线
  • lightVertical - 浅色竖线
  • lightDown - 浅色斜线（左上到右下）
  • lightUp - 浅色斜线（左下到右上）
  • lightGrid - 浅色网格
  • lightTrellis - 浅色斜网格

{
  type: 'gradient';        // 填充类型
  gradientType?: string;   // 渐变类型：'linear' | 'path'
  degree?: number;         // 线性渐变角度（0-360）
  left?: number;           // 左侧偏移（0-1）
  right?: number;          // 右侧偏移（0-1）
  top?: number;            // 顶部偏移（0-1）
  bottom?: number;         // 底部偏移（0-1）
  stops: Array<{           // 渐变色停止点
    position: number;      // 位置（0-1）
    color: string;         // 颜色，格式：'#RRGGBB'
  }>;
}

示例：

// 纯色背景（最常用）
cell.fill = {
  type: 'pattern',
  pattern: 'solid',
  fgColor: '#FFFF00'
};

// 图案填充
cell.fill = {
  type: 'pattern',
  pattern: 'lightGrid',
  fgColor: '#FF0000',
  bgColor: '#FFFFFF'
};

// 线性渐变（从红到蓝）
cell.fill = {
  type: 'gradient',
  gradientType: 'linear',
  degree: 90,
  stops: [
    { position: 0, color: '#FF0000' },
    { position: 1, color: '#0000FF' }
  ]
};

// 路径渐变
cell.fill = {
  type: 'gradient',
  gradientType: 'path',
  left: 0.5,
  right: 0.5,
  top: 0.5,
  bottom: 0.5,
  stops: [
    { position: 0, color: '#FFFFFF' },
    { position: 1, color: '#000000' }
  ]
};

// 清空填充
cell.fill = {};

数字格式字符串，用于控制数值、日期、时间的显示格式。

格式字符串 说明 示例
0 整数 1234
0.00 保留2位小数 1234.50
#,##0 千分位分隔符 1,234
#,##0.00 千分位+2位小数 1,234.50
0% 百分比 50%
0.00% 百分比+2位小数 50.25%
0.00E+00 科学计数法 1.23E+03
# ?/? 分数 1 1/4
¥#,##0.00 货币格式 ¥1,234.50
yyyy/m/d 日期（年/月/日） 2024/1/15
m/d/yyyy 日期（月/日/年） 1/15/2024
yyyy-mm-dd 日期（年-月-日） 2024-01-15
h:mm 时间（时:分） 14:30
h:mm:ss 时间（时:分:秒） 14:30:25
yyyy/m/d h:mm:ss 日期时间 2024/1/15 14:30:25
[Red]0.00 负数显示红色 -12.34
0.00;[Red]-0.00 正数黑色，负数红色 12.34 或 -12.34

数字部分：

  • 0 - 占位符，不足补0
  • # - 占位符，不足不显示
  • , - 千分位分隔符
  • . - 小数点
  • % - 百分比
  • ? - 空格占位（用于对齐）

日期部分：

  • yyyy - 四位年份（2024）
  • yy - 两位年份（24）
  • m - 月份（1-12）
  • mm - 月份补0（01-12）
  • mmm - 月份简写（Jan-Dec）
  • mmmm - 月份全称（January-December）
  • d - 日期（1-31）
  • dd - 日期补0（01-31）
  • ddd - 星期简写（Sun-Sat）
  • dddd - 星期全称（Sunday-Saturday）

时间部分：

  • h - 小时（0-23）
  • hh - 小时补0（00-23）
  • m - 分钟（0-59）
  • mm - 分钟补0（00-59）
  • s - 秒（0-59）
  • ss - 秒补0（00-59）
  • AM/PM - 12小时制

示例：

const cell = sheet.getCell(0, 0);

// 数字格式
cell.editVal = 1234.5;
cell.numFmt = '#,##0.00';  // 显示：1,234.50

// 百分比
cell.editVal = 0.258;
cell.numFmt = '0.00%';     // 显示：25.80%

// 货币
cell.editVal = 1234.5;
cell.numFmt = '¥#,##0.00'; // 显示：¥1,234.50

// 日期
cell.editVal = '2024/1/15';
cell.numFmt = 'yyyy-mm-dd'; // 显示：2024-01-15

// 时间
cell.editVal = '14:30:25';
cell.numFmt = 'h:mm:ss';    // 显示：14:30:25

// 自定义格式（正数、负数、零、文本）
cell.numFmt = '0.00;[Red]-0.00;"零";@';

// 清除格式（恢复常规）
cell.numFmt = null;

超链接配置对象。

{
  target?: string;    // 外部链接 URL（如 'https://example.com'）
  location?: string;  // 内部链接位置（如 'Sheet2!A1'）
  tooltip?: string;   // 鼠标悬停提示文本
}

示例：

// 外部链接
cell.editVal = '访问官网';
cell.hyperlink = {
  target: 'https://www.sheetnext.com',
  tooltip: '点击访问 SheetNext 官网'
};

// 内部链接（跳转到其他工作表）
cell.editVal = '查看数据';
cell.hyperlink = {
  location: 'Sheet2!A1',
  tooltip: '跳转到 Sheet2 的 A1 单元格'
};

// 移除超链接
cell.hyperlink = {};

数据验证规则配置对象，用于限制单元格可输入的内容。

{
  type: string;              // 验证类型：'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom'
  operator?: string;         // 操作符：'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual'
  allowBlank?: boolean;      // 是否允许空白，默认 false
  formula1: any;             // 公式1（type='list' 时为数组）
  formula2?: any;            // 公式2（范围验证时使用）
  showInputMessage?: boolean; // 是否显示输入提示，默认 true
  promptTitle?: string;      // 输入提示标题
  prompt?: string;           // 输入提示内容
  showErrorMessage?: boolean; // 是否显示错误提示，默认 true
  errorTitle?: string;       // 错误提示标题
  error?: string;            // 错误提示内容
  errorStyle?: string;       // 错误样式：'stop' | 'warning' | 'information'
  showDropDown?: boolean;    // 是否显示下拉框（type='list' 时），默认 true
}

示例：

// 下拉列表
cell.dataValidation = {
  type: 'list',
  formula1: ['优秀', '良好', '及格', '不及格'],
  showDropDown: true,
  promptTitle: '请选择',
  prompt: '请从列表中选择一个等级'
};

// 整数范围（1-100）
cell.dataValidation = {
  type: 'whole',
  operator: 'between',
  formula1: 1,
  formula2: 100,
  errorTitle: '输入错误',
  error: '请输入 1 到 100 之间的整数'
};

// 小数验证（大于0）
cell.dataValidation = {
  type: 'decimal',
  operator: 'greaterThan',
  formula1: 0,
  errorTitle: '输入错误',
  error: '请输入大于 0 的数字'
};

// 日期范围
cell.dataValidation = {
  type: 'date',
  operator: 'between',
  formula1: '2024/1/1',
  formula2: '2024/12/31',
  errorTitle: '日期错误',
  error: '请输入 2024 年的日期'
};

// 时间验证
cell.dataValidation = {
  type: 'time',
  operator: 'between',
  formula1: '9:00:00',
  formula2: '18:00:00',
  errorTitle: '时间错误',
  error: '请输入工作时间（9:00-18:00）'
};

// 文本长度限制
cell.dataValidation = {
  type: 'textLength',
  operator: 'lessThanOrEqual',
  formula1: 20,
  errorTitle: '文本过长',
  error: '最多输入 20 个字符'
};

// 移除验证
cell.dataValidation = {};