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 占位;一旦赋值即落入网格。
输出:
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
输出:
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(); // 清空整表值(不删行列)
输出:
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)
输出:
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?[,])。