# dotNet.ReoGrid 扩展库 - 分组与大纲

通过分组行或列添加大纲
-----------------------------------------------------------------------------

![29 (1)](../images/29-1.png)

添加行或列的大纲分组：

```aardio
// 从第3行开始分组5行（注意：aardio中行号从0开始）
sheet1.AddOutline(ReoGrid.RowOrColumn.Row, 3, 5);  

// 从第5列开始分组2列
sheet1.AddOutline(ReoGrid.RowOrColumn.Column, 5, 2);   
```

注意：`AddOutline` 方法可能会抛出以下异常：

*   **OutlineIntersectedException** - 当要添加的大纲与已有大纲存在交叉区域时
*   **OutlineAlreadyDefinedException** - 当要添加的大纲与已有大纲完全重复时
*   **OutlineTooMuchException** - 当大纲层级超过最大限制10层时
*   **OutlineOutOfRangeException** - 当指定位置超出工作表有效范围时（注：由于大纲需要显示展开/折叠按钮，工作表的最后一行和最后一列不能被分组）

折叠与展开大纲
-------------------------------------------------------------

`AddOutline` 方法会返回大纲对象实例，该对象有两个控制方法：

```aardio
// 添加行大纲并获取实例
var outline = sheet1.AddOutline(ReoGrid.RowOrColumn.Row, 3, 5);
outline.Collapse();    // 折叠
outline.Expand();      // 展开
```

或者直接调用控件的 `CollapseOutline` 和 `ExpandOutline` 方法，通过位置参数指定要操作的大纲：

```aardio
// 直接通过位置参数控制大纲
sheet1.CollapseOutline(ReoGrid.RowOrColumn.Row, 3, 5);
sheet1.ExpandOutline(ReoGrid.RowOrColumn.Row, 3, 5);
```

注意：当指定位置找不到对应大纲时，上述方法会抛出 `OutlineNotFoundException` 异常（本例中必须从第3行开始且行数为5）。

通过取消分组移除大纲
-----------------------------------------------------------------------------------------------

使用 `RemoveOutline` 方法移除指定大纲：

```aardio
// 移除从第3行开始的行分组（5行）
sheet1.RemoveOutline(ReoGrid.RowOrColumn.Row, 3, 5);  
```

注意：当指定位置找不到对应大纲时，`RemoveOutline` 会抛出 `OutlineNotFoundException` 异常。

另可使用 `ClearOutlines` 方法清除工作表中所有指定类型的大纲：

```aardio
// 清除所有行分组大纲
sheet1.ClearOutlines(ReoGrid.RowOrColumn.Row);  
```

自动折叠与展开
-----------------------------------------------------------

当大纲的结束行被隐藏或行高设为0时，大纲会自动折叠；当被分组的行变为可见或行高恢复时，大纲会自动展开。此行为不可禁用，但会触发大纲的折叠/展开事件。

![大纲](../images/1141.png)

调整行高后：

![大纲自动隐藏](../images/1151.png)

自动移除
---------------------------

当大纲关联的所有行或列被删除时，该大纲会自动移除。此行为不可禁用，但会触发 `OutlineRemoved` 事件。

大纲事件
-------------------------------------

当大纲被添加或移除时，会触发以下两个工作表事件：

```aardio
// 添加大纲事件
sheet1.OutlineAdded = function(sender, e){
    winform.msgbox("大纲已添加，范围：" + e.Outline.Start + " 到 " + e.Outline.End);
}

// 移除大纲事件
sheet1.OutlineRemoved = function(sender, e){
    winform.msgbox("大纲已移除，范围：" + e.Outline.Start + " 到 " + e.Outline.End);
}
```

由于删除行会自动移除关联的大纲，此时也会触发 `OutlineRemoved` 事件：

```aardio
// 删除行会触发关联大纲的移除事件
sheet1.DeleteRows(4, 5);  
```

执行上述代码后，会显示消息：
`大纲已移除，范围：5 到 3`

大纲实例和工作表实例都提供了处理折叠/展开操作的事件：

```aardio
// 添加列分组大纲
var outline = sheet1.AddOutline(ReoGrid.RowOrColumn.Column, 1, 3);

// 大纲实例事件
outline.BeforeCollapse = function(sender, e){
    winform.msgbox("即将折叠");
}
outline.BeforeExpand = function(sender, e){
    winform.msgbox("即将展开");
}
outline.AfterCollapse = function(sender, e){
    winform.msgbox("已折叠");
}
outline.AfterExpand = function(sender, e){
    winform.msgbox("已展开");
}

// 工作表实例事件
sheet1.BeforeOutlineCollapse = function(sender, e){
    winform.msgbox("工作表 - 即将折叠");
}
sheet1.AfterOutlineCollapse = function(sender, e){
    winform.msgbox("工作表 - 已折叠");
}
sheet1.BeforeOutlineExpand = function(sender, e){
    winform.msgbox("工作表 - 即将展开");
}
sheet1.AfterOutlineExpand = function(sender, e){
    winform.msgbox("工作表 - 已展开");
}
```

与其他 ReoGrid的"Before"事件类似，可以通过设置 `IsCancelled` 属性为 true 来取消操作：

```aardio
// 通过设置 IsCancelled 取消折叠/展开操作
sheet1.BeforeOutlineCollapse = function(sender, e){
    e.IsCancelled = true;
}
```

更多事件请参考[事件文档](../event/events.html)。

隐藏大纲界面面板
-------------------------------------------------------------

可以隐藏大纲的用户界面，防止最终用户操作大纲。此时仍可通过编程方式控制大纲的折叠/展开：

```aardio
// 禁用行列大纲的界面显示
sheet1.SetSettings(ReoGrid.WorksheetSettings.View_AllowShowOutlines, false);

// 添加大纲1并折叠
var outline1 = sheet1.AddOutline(ReoGrid.RowOrColumn.Row, 1, 3);
outline1.Collapse();

// 添加大纲2并折叠
var outline2 = sheet1.AddOutline(ReoGrid.RowOrColumn.Row, 5, 2);
outline2.Collapse();
```

![自定义表头](../images/1131.png)

如需重新显示大纲界面，将设置改为true即可：

```aardio
// 启用大纲界面显示
sheet1.SetSettings(ReoGrid.WorksheetSettings.View_AllowShowOutlines, true);
```