# Tour 漫游式引导

`Tour` 用于分步骤引导用户认识界面功能。每一步由回调决定要高亮的控件或矩形区域；可选的 Popover 回调用来定制说明气泡。

在 aardio 中，`Tour` 的 owner 需要 WinForms `Form`，推荐创建嵌入的 `AntdUI.BaseForm`。被引导目标也应是 WinForms/AntdUI 控件，普通 aardio 控件不能直接作为 `result.Set(control)` 的参数。

## 最小步骤示例

```aardio
import win.ui;
import dotNet.AntdUI;

var winform = win.form(text="AntdUI Tour";right=640;bottom=380)
winform.add(
customBase={cls="custom";left=0;top=0;right=640;bottom=380;z=1};
host1={cls="custom";left=40;top=40;right=180;bottom=76;z=2};
host2={cls="custom";left=40;top=100;right=260;bottom=136;z=3};
btnStart={cls="button";text="开始引导";left=40;top=170;right=160;bottom=206;z=4}
)

var baseForm = AntdUI.BaseForm(winform.customBase);
var btn1 = AntdUI.Button(winform.host1);
btn1.Text = "第一步目标";
var input = AntdUI.Input(winform.host2);
input.PlaceholderText = "第二步目标";

winform.btnStart.oncommand = function(){
    var cfg = AntdUI.Tour.Config(baseForm,function(result){
        select(result.Index) {
            case 0 {
                result.Set(btn1);
            }
            case 1 {
                result.Set(input);
            }
            else {
                result.Close();
            }
        }
    });
    cfg.SetScale(1.08).SetMaskClosable(true).SetClickNext(true);
    AntdUI.Tour.open(cfg);
}

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

## Tour.Config

常用构造：

```aardio
var cfg = AntdUI.Tour.Config(baseForm,function(result){
    // result.Index 为当前步骤序号，从 0 开始
});
```

带气泡回调：

```aardio
var cfg = AntdUI.Tour.Config(baseForm,
    function(result){
        if(result.Index == 0) result.Set(btn1);
        else result.Close();
    },
    function(popover){
        // 可在这里根据 popover.Index 定制说明气泡
        return true;
    }
);
```

常用属性：

| 属性 | 说明 |
| --- | --- |
| `Form` | 所属 WinForms 窗口，aardio 中推荐 `AntdUI.BaseForm` |
| `Scale` | 高亮区域缩放比例 |
| `MaskClosable` | 点击遮罩是否关闭 |
| `ClickNext` | 点击是否自动下一步 |
| `StepCall` | 步骤回调，参数为 `Tour.Result` |
| `PopoverCall` | 气泡回调，参数为 `Tour.Popover` |

常用链式方法：`SetScale`、`SetMaskClosable`、`SetClickNext`、`SetCall`、`SetStepCall`。

## Tour.Result

步骤回调收到 `result` 对象：

```aardio
var stepCall = function(result){
    if(result.Index == 0){
        result.Set(btn1); // 高亮控件
    }
    elseif(result.Index == 1){
        result.Set(System.Drawing.Rectangle(100,100,200,80)); // 高亮区域
    }
    else {
        result.Close(); // 结束引导
    }
}
```

常用成员：

- `Index`：当前步骤序号，0 基索引。
- `Set(control)`：高亮 WinForms/AntdUI 控件。
- `Set(rectangle)`：高亮指定矩形区域。
- `Close()`：结束引导。

## Tour.Popover

气泡回调收到 `popover` 对象，常用属性：`Form`、`Tour`、`Index`、`Rect`。

如果只需要默认气泡，可省略 Popover 回调；如果要自定义说明内容，可在回调中按 `popover.Index` 创建或更新内容。

## TourForm

`AntdUI.Tour.open(cfg)` 返回 `TourForm`，可调用：

- `Previous()`：上一步。
- `Next()`：下一步。
- `Close()`：关闭。
- `LoadData()`：重新加载步骤数据。

## 常见坑

- `Tour` 的窗口参数是 WinForms `Form`，普通 aardio `win.form` 不等价。
- `result.Set(control)` 的 control 也必须是 WinForms/AntdUI 控件。
- 步骤序号从 0 开始，最后一步应调用 `result.Close()`。
- 复杂气泡内容可结合 `Popover` 或 WinForms 控件，但要注意生命周期。