# tour (w-tour)

- **Import**: `WTour` from `win-design-next`
- **Tag**: `<w-tour>`
- **说明**: Tour 漫游式引导
- **分类**: data-display
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/tour.md`

## API

## Tour API

### Tour Attributes

| 属性名                    | 说明                                                             | 类型                                                                                                                                                                        | 默认值                         |
| ------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| show-arrow                | 是否显示箭头                                                     | `boolean`                                                                                                                                                                   | true                           |
| placement                 | 引导卡片相对于目标元素的位置                                     | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `bottom`                       |
| content-style             | c 为 content 自定义样式                                          | `CSSProperties`                                                                                                                                                             | —                              |
| mask                      | 是否启用遮罩，通过自定义属性改变遮罩样式以及填充的颜色           | `boolean` \| ^[Object]`{ style?: CSSProperties; color?: string; }`                                                                                                          | `true`                         |
| type                      | 类型，影响底色与文字颜色                                         | `default` \| `primary`                                                                                                                                                      | `default`                      |
| model-value / v-model     | 打开引导                                                         | `boolean`                                                                                                                                                                   | —                              |
| current / v-model:current | 当前值                                                           | `number`                                                                                                                                                                    | —                              |
| scroll-into-view-options  | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数 | `boolean` \| `ScrollIntoViewOptions`                                                                                                                                        | ^[Object]`{ block: 'center' }` |
| z-index                   | Tour 层级                                                        | `number`                                                                                                                                                                    | `2001`                         |
| show-close                | 是否显示关闭按钮                                                 | `boolean`                                                                                                                                                                   | `true`                         |
| close-icon                | 自定义关闭图标，默认 Close                                       | `string` \| `Component`                                                                                                                                                     | —                              |
| close-on-press-escape     | 是否可以通过按下 ESC 关闭引导                                    | `boolean`                                                                                                                                                                   | `true`                         |
| target-area-clickable     | 启用蒙层时，target 元素区域是否可以点击。                        | `boolean`                                                                                                                                                                   | `true`                         |

### Tour slots

| 插槽名     | 说明                                            |
| ---------- | ----------------------------------------------- |
| default    | tourStep 组件列表                               |
| indicators | 自定义指示器, scope 参数是 `{ current, total }` |

### Tour events

| 事件名 | 说明                           | 类型                                   |
| ------ | ------------------------------ | -------------------------------------- |
| close  | callback function on shutdown  | ^[Function]`(current: number) => void` |
| finish | callback function on finished  | ^[Function]`() => void`                |
| change | callback when the step changes | ^[Function]`(current: number) => void` |

### TourStep Attributes

| 属性名                   | 说明                                                                                                               | 类型                                                                                                                                                                        | 默认值    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| target                   | 获取引导卡片指向的元素， 为空时居中于屏幕。 自以来支持字符串和函数类型。 字符串类型是文档.querySelector 的选择器。 | `HTMLElement` \| `string` \| ^[Function]`() => HTMLElement`                                                                                                                 | —         |
| show-arrow               | 是否显示箭头                                                                                                       | `boolean`                                                                                                                                                                   | `true`    |
| title                    | title                                                                                                              | `string`                                                                                                                                                                    | —         |
| description              | description                                                                                                        | `string`                                                                                                                                                                    | —         |
| placement                | 引导卡片相对于目标元素的位置                                                                                       | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `bottom`  |
| content-style            | 为 content 自定义样式                                                                                              | `CSSProperties`                                                                                                                                                             | —         |
| mask                     | 是否启用蒙层，也可传入配置改变蒙层样式和填充色                                                                     | `boolean` \| ^[Object]`{ style?: CSSProperties; color?: string; }`                                                                                                          | `true`    |
| type                     | 类型，影响底色与文字颜色                                                                                           | `default` \| `primary`                                                                                                                                                      | `default` |
| next-button-props        | “下一步”按钮的属性                                                                                                 | ^[Object]`{ children: VueNode \| string; onClick: Function }`                                                                                                               | —         |
| prev-button-props        | “上一步”按钮的属性                                                                                                 | ^[Object]`{ children: VueNode \| string; onClick: Function }`                                                                                                               | —         |
| scroll-into-view-options | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数，默认跟随 Tour 的                                 | `boolean` \| `ScrollIntoViewOptions`                                                                                                                                        | —         |
| show-close               | 是否显示关闭按钮                                                                                                   | `boolean`                                                                                                                                                                   | `true`    |
| close-icon               | 自定义关闭图标，默认 Close                                                                                         | `string` \| `Component`                                                                                                                                                     | —         |

### TourStep slots

| 插槽名  | 说明        |
| ------- | ----------- |
| default | description |
| header  | header      |

### TourStep events

| 事件名 | 说明                          | 参数                    |
| ------ | ----------------------------- | ----------------------- |
| close  | callback function on shutdown | ^[Function]`() => void` |
