# dotNet.ReoGrid 扩展库 - 入门指南

参考链接： 🅰 [aardio 文档 - .NET 调用指南](https://www.aardio.com/zh-cn/docs/library-guide/std/dotNet/_.html) 📄 [ReoGrid 文档增强检索](https://www.aardio.com/zh-cn/docs/library-guide/ext/dotNet/ReoGrid/search/)

> [本文档](https://www.aardio.com/zh-cn/docs/library-guide/ext/dotNet/ReoGrid/) 适用 aardio `v40.21` 以上版本，dotNet.ReoGrid 扩展库 `v2.9` 以上版本。  

## ReoGrid 介绍

- 开源免费  
<a href="https://github.com/unvell/ReoGrid" target="_blank">ReoGrid</a> 是一个高效、强大、免费、开源的电子表格组件，支持数据格式设置、冻结窗格、大纲视图、公式计算、图表制作、脚本执行等功能。它兼容 Excel 的 `*.xlsx` 文件格式。

- 不需要安装 Excel  
ReoGrid 不需要安装 Excel 就能在主流桌面系统上稳定运行，仅需要系统自带的 NET  .NET 4.7.2（ Win10 1809 就已经自带，这基本是目前主流 .NET 程序的最低要求，即使更老的操作系统也都已普及安装了 ）。

- 生成体积较小的独立 EXE  
使用 aardio 调用这类 .NET 组件可以生成独立 EXE 文件，不需要携带任何外部 DLL 程序集。

## 在 aardio 中使用 dotNet.ReoGrid 扩展库

### 1. 安装扩阿展库

- 在 aardio 中打开 `工具 » 扩展库` 搜索并勾选 `dotNet.ReoGrid` 扩展库，  
- 点击 `安装 / 更新` 按钮。

> ✅ 在 aardio 中直接运行包含  `import dotNet.ReoGrid` 语句的代码也会自动安装扩展库。

### 2. 导入 ReoGrid 名字空间

`import dotNet.ReoGrid`  语句会导入 `dotNet.ReoGrid` 以及 `ReoGrid` 名字空间， `ReoGrid` 与 `dotNet.ReoGrid` 都指向 .NET 里的 `unvell.ReoGrid` 名字空间，在代码中应当使用更简洁的 `ReoGrid` 名字空间。

dotNet.ReoGrid 也会导入 `ReoScript` 名字空间，用于支持 ReoGrid 脚本相关的功能。

要特别注意 aardio 的 `import` 语句与  C# 的 `using` 语句存在区别：

- aardio 的 `import` 只会引入名字空间，但并不会污染现有名字空间。
- 而 C# 的 using 语句则会将引入名字空间的成员放到当前作用域，从而可以缩短访问名称，但也会使来源混淆不清并带来名字污染问题，导致同名冲突。

aardio 中访问 .NET 对象要写完整名字空间，示例：

```aardio
//引入名字空间
import dotNet.ReoGrid; 
 
//创建 Actcion
var action = ReoGrid.Actions.SetRowsHeightAction(1,1,100);
```

aardio 不能像 C# 那样用 SetRowsHeightAction 代替 ReoGrid.Actions.SetRowsHeightAction ， 必须指定完整的名字空间。

但是在 aardio 里名字空间或者类都可以通过赋值语句指定更短的名称，例如：

```aardio
//用局部变量指向类
var SetRowsHeightAction = ReoGrid.Actions.SetRowsHeightAction;

//直接使用类创建对象
var action = SetRowsHeightAction(1,1,100);
```

> 注意在 aardio 中构造类的实例不需要使用 new 关键字。


# ReoGrid 快速入门示例

🅰 示例：

```aardio
import win.ui;
/*DSG{{*/
var winform = win.form(text="ReoGrid 入门")
/*}}*/

//导入扩展库
import dotNet.ReoGrid; 

/*
在界面线程中创建并显示控件参数 @1 必须指定宿主窗口（或者 custom 控件）。
在工作线程中只能创建不需要显示的 ReoGridControl 控件（不必指定参数）。
*/
var grid = ReoGrid.ReoGridControl(winform);

//获取当前工作表
var sheet1 = grid.CurrentWorksheet;

//存取行列值
sheet1[0, 0] = time.now(); 

// 设置单元格数据
sheet1["A1"] = " 欢迎使用 ReoGrid"; // A1 格式下标
sheet1[1, 0] = 123.45;  //数值下标，0 为起始索引，表示 B2 单元格
sheet1.Cells["A1"].Data = "测试"; //也可以通过 Cells 集合获取单元格对象，然后通过 Data 字段赋值

//构造表示单元格位置的 CellPosition
var pos = ReoGrid.CellPosition("A10")
sheet1[pos] = "我是 A10"; //也可以这样写

// 设置区域数据，直接显示 aardio 字符串数组（一次性设置一个数组比循环设置数据快很多）
sheet1["B2:D4"] = [
    ["产品", "单价", "数量"],
    ["苹果", 5.8, 10],
    ["香蕉", 3.5, 20]
];

//调用函数设置列数据，参数（行索引、列索引，数据），注意 .NET 起始下标为 0
sheet1.SetCellData(5, 2, "hello world");

winform.show();
win.loopMessage();
```

本文档中所有示例代码都基于上面的程序，并使用相同的变量命名：

- `winform` 表示 win.form 窗体对象
- `grid` 表示 ReoGrid.ReoGridControl 表格控件对象。
- `sheet1` 表示 `grid.CurrentWorksheet`

创建表格时 `var grid = ReoGrid.ReoGridControl(winform)` 这里的 `winform` 参数也可以更换为其他控件窗口。如果我们只希望在窗体的一部分区域显示表格，就可以先在窗口上放一个 static 或 custom 控件，然后以该控件窗口作作为 ReoGrid.ReoGridControl 的构造参数创建表格实例。

## ReoGrid 组件概述

![215](./images/215.png)

常用对象：
* [工作簿(Workbook)](./workbook.html)
* [工作表(Worksheet)](./sheet1.html)
* [单元格(Cell)](./cell.html)
* [行标题和列标题](./worksheet/row-and-column.html)
* [区域(Range)](./worksheet/range.html)
* [样式(Style)](./cell/style.html)

常用事件：
* [事件列表](./event/events.html)

## 工作簿与工作表

ReoGrid 控件本身也是一个工作簿，一个控件(工作簿)可以包含多个工作表。

![161](./images/161.png)

调用控件(工作簿)API：

```aardio
// 获取表格控件实例
var grid = ReoGrid.ReoGridControl(winform);
// 调用控件方法
grid.method();
```

调用工作表 API ：

```aardio
// 获取当前活动工作表
var sheet1 = grid.CurrentWorksheet;
// 调用工作表方法
sheet1.method();
```

## 访问工作表（ worksheet ）

工作表提供了许多方法来管理单元格数据、样式、边框、轮廓、区域和公式计算等。以下示例演示如何通过调用工作表API来设置单元格数据。

使用工作表索引属性设置单元格数据：

```aardio
// 获取当前活动工作表实例
var sheet1 = grid.CurrentWorksheet;
// 设置单元格数据
sheet1["A1"] = "hello world";  // 使用A1表示法
sheet1[2, 1] = 10;  // 使用行列索引(从0开始)
```

或者调用`SetCellData`方法：

```aardio
// 设置指定位置的单元格数据
sheet1.SetCellData(2, 1, "hello world");  // aardio中直接传行列索引，不需要 ReoGrid.CellPosition 对象
```

了解更多关于工作表的内容。

## 通过执行操作访问

操作 (actions) 是 ReoGrid 核心提供的撤销框架，许多操作可以通过执行操作来完成。通过操作完成的操作可以通过调用控件的Undo方法撤销。使用操作执行操作的步骤：

### 1. 获取 Action：

所有 Actvion 都在 ReoGrid.Actions 名字空间下。

```aardio
var SetRowsHeightAction = ReoGrid.Actions.SetRowsHeightAction;
```

### 2. 调用表格控件的 `DoAction` 方法：

创建 Action 并调用 `grid.DoAction` 执行操作：

```aardio

// 创建 Action，不需要使用 new 关键字
var setRowsHeight = SetRowsHeightAction(1,1,100);

// 执行 Actvion
grid.DoAction(grid.CurrentWorksheet,setRowsHeight );
```

撤销或重做操作：

```aardio
// 撤销操作
grid.Undo();

// 重做操作
grid.Redo();
```

重复执行最后一个操作，应用到另一个区域：

```aardio
// 重复最后操作到新区域
grid.RepeatLastAction( ReoGrid.RangePosition(2, 3, 5, 5) );
```

注意 aardio 里要写为 `ReoGrid.RangePosition(2, 3, 5, 5) ` 而不是 C# 那样写为 `new RangePosition(2, 3, 5, 5) `，aardio 里不要省略名字空间前缀并且需要移除多余的 new 关键字。

用户应用程序可以扩展脚本函数和对象以提供自定义脚本功能，详见[自定义函数](./formula/custom-function.html)。

## aardio 使用说明

1. aardio 的数组索引是自 1 开始, 访问 .NET 对象时如果使用 `netObject[1]` 这样的单值索引的下标 aardio 会自动将索引减 1 ，但如果使用其他方式传索引时不会减 1。例如 ReoGrid 访问单元格需要指定多项索引，则行列索引从 0 开始，例如在 aardio 中同样要用 `sheet1[0, 0]` 访问第一个单元格。
2. 可以直接使用 A1 表示法或行列索引访问单元格，例如 `sheet1.Cells["A1"].Data = "测试"`。
3. 导入 dotNet.ReoGrid 以后会自动导入 ReoGrid 名字空间，其他由同一个程序集加载的 ReoGrid 下面的其他子名字空间不需要再导入，aardio 会自动处理。但访问名字空间内的对象要写全称，例如 `ReoGrid.RangePosition(2, 3, 5, 5) ` , 而不是  `RangePosition(2, 3, 5, 5) `，除非先将 ReoGrid.RangePosition 赋值到名称更短的变量。
4. 可以直接调用 ReoGrid 的属性与方法，无需额外设置。