跳转至

4. 单元格与取值

本章讲单元格的访问与取值:按坐标或地址定位、写值、整表入口、区域批量操作,以及强类型读取。

Warning

坐标统一 1-based(首行首列为 1,1);A1 地址如 B3 表示第 2 行第 3 列。


4.1 按坐标 / 地址访问单元格

Worksheet.Cell 提供按行列或 A1 地址访问:

参数 类型 说明
row / column int 1-based 行列坐标,如 (1, 1) 即 A1
address string A1 地址,如 "B3"
var ws = Excel.Create().Worksheets["Sheet1"];

var c1 = ws.Cell(1, 1);        // A1
var c2 = ws.Cell("B3");        // B3
Console.WriteLine(c1.IsEmpty);   // True(尚未赋值)

Cell 是引用类型,访问不存在的单元格返回一个 Empty 占位;一旦赋值即落入网格。

输出:

True

4.2 写入值 SetValue

Worksheet.SetValue 越界自动扩展网格;null / DBNull 写空单元格:

参数 类型 说明
row / column int 1-based 坐标,越界自动扩展网格
address string A1 地址
value object? 任意值;null / DBNull 写空单元格
var ws = Excel.Create().Worksheets["Sheet1"];

ws.SetValue(1, 1, "Header");
ws.SetValue("A2", 42);
ws.SetValue("B2", null);       // 清空 B2
Console.WriteLine(ws.Cell("A2").GetString());   // 42

输出:

42

4.3 集合式访问 Cells

Worksheet.Cells 提供整表入口,支持索引器、区域提取、枚举与批量清空:

成员 类型 说明
Cells[int row, int column] Cell 索引器,1-based
Cells[string address] Cell 索引器,A1 地址
Cells.SetValue(...) void 便捷写值
Cells.Range(...) ExcelRange 提取区域
Cells.Clear() void 清空整表值(不删行列)
var ws = Excel.Create().Worksheets["Sheet1"];

ws.Cells[1, 1] = "A1 via cells";      // 索引器(行列)
ws.Cells["B1"] = "B1 via cells";      // 索引器(A1 地址)
ws.Cells.SetValue("C1", 3.14);        // 便捷写值

var range = ws.Cells.Range("A1:D10"); // 提取区域
foreach (var cell in ws.Cells)        // 枚举网格中已有单元格
    Console.WriteLine(cell.GetString());
ws.Cells.Clear();                     // 清空整表值(不删行列)

输出:

A1 via cells
B1 via cells
3.14

4.4 区域操作 ExcelRange

Worksheet.Range 返回连续矩形区域(1-based,含端点),支持批量读写、样式、合并、清空、枚举:

成员 类型 说明
Address string A1 区域地址,如 "A1:D10"
RowCount / ColumnCount int 行数 / 列数
Fill(object? value) void 整区填相同值
Fill(object?[,] data) void 二维数组写入
ToValues() object?[,] 值读回
ToCells() Cell[,] 单元格读回
Style CellStyle? 区域内全部单元格套用样式,见第 6 章
Merge() / Unmerge() void 合并 / 取消合并该区域,见第 7 章
Clear() void 清空区域内值
Cell(rowOffset, colOffset) Cell 区域内相对偏移,0-based
var ws = Excel.Create().Worksheets["Sheet1"];

var r = ws.Range("A1:D10");          // 或 ws.Range(1, 1, 10, 4)
Console.WriteLine(r.Address);        // "A1:D10"
Console.WriteLine($"{r.RowCount} x {r.ColumnCount}");  // 10 x 4

r.Fill("x");                          // 整区填相同值
r.Fill(new object?[,] { { "a", "b" }, { "c", "d" } }); // 二维数组写入
var vals = r.ToValues();              // object?[,] 读回
var cells = r.ToCells();              // Cell[,] 读回
r.Style = new CellStyle { Bold = true };  // 整区统一样式
r.Merge();                            // 合并该区域
r.Unmerge();                          // 取消合并
r.Clear();                            // 清空区域内值

var single = r.Cell(0, 0);            // 区域内相对偏移(0-based)

输出:

A1:D10
10 x 4

4.5 单元格读取方法

Cell 提供强类型与 Try 风格读取:

方法 返回 说明
GetString() string? 文本 / 数字 / 日期 / 布尔按惯例格式化
GetDouble() double 类型不匹配抛 InvalidCastException
GetDateTime() DateTime 日期读取
GetBoolean() bool 布尔读取
GetValue() object? 原始对象,Empty 返回 null
TryGetString / TryGetDouble / TryGetDateTime / TryGetBoolean bool 空单元格返回 false,失败不抛异常
var ws = Excel.Create().Worksheets["Sheet1"];

var cell = ws.Cell("A1");
string? s = cell.GetString();        // 文本 / 数字 / 日期 / 布尔按惯例格式化
double d = cell.GetDouble();         // 类型不匹配抛 InvalidCastException
DateTime dt = cell.GetDateTime();
bool b = cell.GetBoolean();
object? raw = cell.GetValue();       // 原始对象,Empty 返回 null

bool ok = cell.TryGetString(out var s2);   // 空单元格返回 false
bool ok2 = cell.TryGetDouble(out double d2);
bool ok3 = cell.TryGetDateTime(out DateTime dt2);
bool ok4 = cell.TryGetBoolean(out bool b2);

4.6 Value 属性

Cell.Value 与 ExcelRange.Value 是 SetValue / GetValue 的便捷属性写法,与 Excel interop 的习惯一致。读取返回 object?,需要类型安全时仍用 4.5 的 GetString() / GetDouble() 等。

var ws = Excel.Create().Worksheets["Sheet1"];

// 单格:读写标量(Cell / Cells 索引器 / 单格 Range 均可)
ws.Cell("A1").Value = "123";
Console.WriteLine(ws.Cell("A1").Value);        // 123
ws.Cells["B2"].Value = 42;
ws.Cells[3, 3].Value = true;
ws.Range("C1").Value = "经 Range 写";

// 多格 Range:读返回 object?[,](尺寸 = 区域),写标量铺满 / 写二维数组按位填
ws.Range("A10:B11").Value = "x";                          // 4 格全为 x
var grid = (object?[,])ws.Range("A10:B11").Value;         // 读 2D
ws.Range("D1:E2").Value = new object?[,] { { 1, 2 }, { 3, 4 } };

ExcelRange.Value 行为:单格区域(1×1)读写标量;多格区域读返回 object?[,]、写标量等价 Fill、写二维数组等价 Fill(object?[,])。