@king-design/intact 3.5.2 → 3.6.0-beta.0

package/components/tour/demos/custom.md

@@ -0,0 +1,98 @@
+---
+title: 自定义内容
+order: 2
+---
+
+通过使用`TourStep`组件的block，可以自定义引导步骤的内容。
+
+```vdt
+import {Tour, TourStep, Button, Icon} from 'kpc';
+
+<div>
+    <div class="example-container">
+        <Button id="btn5">示例元素</Button>
+    </div>
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        ev-finish={this.close}
+    >
+        <TourStep
+            target="#btn5"
+            position="bottom"
+        >
+            <b:header>
+                <div style="display: flex; align-items: center">
+                    <Icon class="ion-android-star" style="margin-right: 5px; color: #f0ad4e" />
+                    <span class="custom-title">自定义标题</span>
+                    <span style="margin-left: 8px; color: #999; font-size: 12px">带图标和样式</span>
+                </div>
+            </b:header>
+            <div class="custom-content">
+                <p>这是一个自定义的复杂内容，可以包含图片、链接等任何元素。</p>
+                <a href="javascript:;" style="color: #2d8cf0">了解更多</a>
+            </div>
+            <b:footer>
+                <div class="step-indicator">{this.get('currentStep') + 1} / 1</div>
+                <div class="custom-footer">
+                    <Button size="small" type="danger" style="margin-right: 8px;" ev-click={this.close}>跳过</Button>
+                    <Button size="small" type="primary" ev-click={this.close}>我知道了</Button>
+                </div>
+            </b:footer>
+        </TourStep>
+    </Tour>
+    <div style="margin-top: 20px;">
+        <Button ev-click={this.settour}>
+            启动自定义引导
+        </Button>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,
+        };
+    }
+
+    @bind
+    settour() {
+        this.set({
+            showTour: true,
+            currentStep: 0
+        });
+    }
+
+    @bind
+    close() {
+        this.set({
+            showTour: false
+        });
+    }
+}
+```
+
+```styl
+.custom-title
+    font-weight bold
+    color #2d8cf0
+
+.custom-content
+    text-align center
+    padding 8px 0
+    
+.custom-footer
+    display flex
+    justify-content space-between
+    align-items center
+    width 100%
+    .k-btn
+        margin-right 8px
+
+``` 

package/components/tour/demos/customText.md

@@ -0,0 +1,94 @@
+---
+title: 自定义按钮文本
+order: 3
+---
+
+每个步骤可以单独设置按钮文本，实现更灵活的用户体验。
+
+```vdt
+import {Tour, Button} from 'kpc';
+
+<div>
+    <div class="example-container">
+        <Button id="welcome-btn">欢迎页面</Button>
+        <Button id="feature-btn" style="margin-left: 20px;">功能介绍</Button>
+        <Button id="finish-btn" style="margin-left: 20px;">完成设置</Button>
+    </div>
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        data={this.get('tourData')} 
+        doneText="完成"
+        ev-finish={this.close}
+    />
+    <div style="margin-top: 20px;">
+        <Button type="primary" ev-click={this.startTour}>
+            开始自定义按钮引导
+        </Button>
+        <span style="margin-left: 10px;">
+            当前步骤: {this.get('currentStep') >= 0 ? this.get('currentStep') + 1 : '未启动'}
+        </span>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,
+            tourData: [
+                {
+                    target: '#welcome-btn',
+                    title: '欢迎使用！',
+                    content: '欢迎来到我们的应用，让我们开始引导之旅吧！',
+                    position: 'bottom',
+                    nextText: '开始探索',
+                },
+                {
+                    target: '#feature-btn',
+                    title: '功能介绍',
+                    content: '这里是主要功能区域，您可以在这里进行各种操作。',
+                    position: 'bottom',
+                    nextText: '前进',
+                    prevText: '回到开始',
+                },
+                {
+                    target: '#finish-btn',
+                    title: '设置完成',
+                    content: '恭喜！您已经完成了所有设置，现在可以开始使用了。',
+                    position: 'top',
+                    prevText: '返回上一步',
+                }
+            ]
+        };
+    }
+
+    @bind
+    startTour() {
+        this.set({
+            showTour: true,
+            currentStep: 0
+        });
+    }
+
+    @bind
+    close() {
+        this.set({
+            showTour: false
+        });
+    }
+}
+```
+
+```styl
+.example-container
+    padding: 20px
+    border: 1px dashed #ddd
+    border-radius: 4px
+    margin-bottom: 20px
+``` 

package/components/tour/demos/declarative.md

@@ -0,0 +1,72 @@
+---
+title: 声明式用法
+order: 1
+---
+
+使用`TourStep`子组件可以声明式地定义引导步骤，更加灵活。
+
+```vdt
+import {Tour, TourStep, Button} from 'kpc';
+
+<div>
+    <div class="example-container">
+        <Button id="btn3">示例元素1</Button>
+        <Button id="btn4" style="margin-left: 20px;">示例元素2</Button>
+    </div>
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        ev-finish={this.close}
+    >
+        <TourStep
+            target="#btn3"
+            title="第一步"
+            content="这是使用子组件方式的第一步说明"
+            position="left"
+        />
+        <TourStep
+            target="#btn4"
+            title="第二步"
+            position="top"
+        >这是使用子组件方式的第二步说明</TourStep>
+    </Tour>
+    <div style="margin-top: 20px;">
+        <Button ev-click={this.settour}>
+            启动引导
+        </Button>
+        <span style="margin-left: 10px;">
+            当前步骤: {this.get('currentStep') >= 0 ? this.get('currentStep') + 1 : '未启动'}
+        </span>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,  // 默认不显示
+        };
+    }
+
+    @bind
+    settour() {
+        // 重置步骤并显示Tour
+        this.set({
+            showTour: true,
+            currentStep: 0
+        });
+    }
+
+    @bind
+    close() {
+        this.set({
+            showTour: false
+        });
+    }
+}
+``` 

package/components/tour/demos/events.md

@@ -0,0 +1,101 @@
+---
+title: 事件处理
+order: 5
+---
+
+```vdt
+import {Tour, Button, Message} from 'kpc';
+
+<div>
+    <div class="example-container">
+        <Button id="event-btn1">第一步</Button>
+        <Button id="event-btn2" style="margin-left: 20px;">第二步</Button>
+        <Button id="event-btn3" style="margin-left: 20px;">第三步</Button>
+    </div>
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        data={this.get('tourData')} 
+        ev-prev={this.handlePrev}
+        ev-next={this.handleNext}
+        ev-finish={this.handleFinish}
+    />
+    <div style="margin-top: 20px;">
+        <Button ev-click={this.startTour}>
+            开始引导
+        </Button>
+        <span style="margin-left: 10px;">
+            当前步骤: {this.get('currentStep') >= 0 ? this.get('currentStep') + 1 : '未启动'}
+        </span>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+import {Message} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,
+            tourData: [
+                {
+                    target: '#event-btn1',
+                    title: '第一步',
+                    content: '点击"下一步"按钮，将触发next事件',
+                },
+                {
+                    target: '#event-btn2',
+                    title: '第二步',
+                    content: '点击"上一步"按钮，将触发prev事件',
+                },
+                {
+                    target: '#event-btn3',
+                    title: '第三步',
+                    content: '点击"完成"按钮或关闭图标，将触发finish事件',
+                }
+            ]
+        };
+    }
+
+    @bind
+    startTour() {
+        this.set({
+            showTour: true,
+            currentStep: 0,
+        });
+    }
+
+    @bind
+    handlePrev(index: number) {
+        Message.success(`上一步事件触发: 当前步骤 ${index + 1}`);
+    }
+
+    @bind
+    handleNext(index: number) {
+        Message.success(`下一步事件触发: 当前步骤 ${index + 1}`);
+    }
+
+    @bind
+    handleFinish() {
+        Message.success('引导结束事件触发');
+        this.set({
+            showTour: false
+        });
+    }
+
+}
+```
+
+```styl
+.event-log
+    margin-top 5px
+    padding 10px
+    border 1px solid #eee
+    border-radius 4px
+    max-height 150px
+    overflow-y auto
+``` 

package/components/tour/demos/maskClosable.md

@@ -0,0 +1,76 @@
+---
+title: 遮罩层交互
+order: 5
+---
+
+```vdt
+import {Tour, Button, Switch} from 'kpc';
+
+<div>
+    <div class="example-container">
+        <Button id="maskDemo1">目标元素1</Button>
+        <Button id="maskDemo2" style="margin-left: 20px;">目标元素2</Button>
+    </div>
+    
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        data={this.get('tourData')} 
+        maskClosable={this.get('maskClosable')}
+        ev-finish={this.finishTour}
+    />
+    <div style="margin-top: 20px;">
+        <div style="margin-bottom: 10px;">
+            <Switch v-model="maskClosable" />
+            <span style="margin-left: 10px;">点击遮罩关闭引导: {this.get('maskClosable') ? '启用' : '禁用'}</span>
+        </div>
+        <Button ev-click={this.startTour}>
+            启动引导
+        </Button>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,
+            maskClosable: true,
+            tourData: [
+                {
+                    target: '#maskDemo1',
+                    title: '遮罩层交互',
+                    content: '当maskClosable为true时，点击遮罩层可关闭引导',
+                    position: 'bottom'
+                },
+                {
+                    target: '#maskDemo2',
+                    title: '禁用遮罩层关闭',
+                    content: '当maskClosable为false时，点击遮罩层无反应，必须使用按钮进行操作',
+                    position: 'right'
+                }
+            ]
+        };
+    }
+
+    @bind
+    startTour() {
+        this.set({
+            showTour: true,
+            currentStep: 0
+        });
+    }
+
+    @bind
+    finishTour() {
+        this.set({
+            showTour: false
+        });
+    }
+}
+``` 

package/components/tour/demos/notarget.md

@@ -0,0 +1,59 @@
+---
+title: 无目标元素
+order: 3
+---
+
+当没有指定目标元素或目标元素不存在时，Tour会居中显示。
+
+```vdt
+import {Tour, TourStep, Button} from 'kpc';
+
+<div>
+    <Tour
+        v-model="currentStep"
+        visible={this.get('showTour')}
+        ev-finish={this.close}
+    >
+        <TourStep title="无目标元素-第一步">
+            <span>当没有指定target属性或者目标元素不存在时，Tour会居中显示在屏幕中央。</span>
+        </TourStep>
+        <TourStep title="无目标元素-第二步">
+            <span>当没有指定target属性或者目标元素不存在时，所有步骤都会居中显示在屏幕中央。</span>
+        </TourStep>
+    </Tour>
+    <div style="margin-top: 20px;">
+        <Button ev-click={this.settour}>
+            启动无目标引导
+        </Button>
+    </div>
+</div>
+```
+
+```ts
+import {bind} from 'kpc';
+
+export default class extends Component {
+    static template = template;
+    static defaults() {
+        return {
+            currentStep: 0,
+            showTour: false,
+        };
+    }
+
+    @bind
+    settour() {
+        this.set({
+            showTour: true,
+            currentStep: 0
+        });
+    }
+
+    @bind
+    close() {
+        this.set({
+            showTour: false
+        });
+    }
+}
+``` 

package/components/tour/index.md

@@ -0,0 +1,48 @@
+---
+title: 引导式导航
+category: 组件
+order: 99
+sidebar: doc
+---
+
+# 属性
+
+## Tour
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | 当前显示的步骤索引，从0开始，可通过`v-model`双向绑定 | `number` | `0` |
+| visible | 是否展示引导组件 | `boolean` | `true` |
+| data | 步骤数据数组，用于数据驱动方式 | `TourStepData[]` | `undefined` |
+| beforeChange | 步骤切换前的回调函数，返回false可阻止切换 | `(current: number) => boolean \| Promise<boolean>` | `undefined` |
+| maskClosable | 点击遮罩层是否可关闭 | `boolean` | `false` |
+| closable | 是否展示关闭图标 | `boolean` | `true` |
+| doneText | 完成按钮文本 | `string` | `"完成"` |
+
+## TourStep
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| target | 目标元素，可以是CSS选择器或DOM元素 | `string \| HTMLElement` | `undefined` |
+| title | 步骤标题 | `string \| VNode` | `undefined` |
+| content | 步骤内容 | `string \| VNode` | `undefined` |
+| nextText | 下一步按钮文本 | `string` | `"下一步"` |
+| prevText | 上一步按钮文本 | `string` | `"上一步"` |
+| position | 弹出位置，可选值：`top`、`right`、`bottom`、`left` | `string` | `"bottom"` |
+
+# 事件
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| prev | 点击上一步按钮时触发 | `(index: number)` |
+| next | 点击下一步按钮时触发 | `(index: number)` |
+| finish | 引导完成时触发 | - |
+
+# 扩展点
+
+## TourStep
+
+| 名称 | 说明 |
+| --- | --- |
+| title | 自定义标题内容 |
+| footer | 自定义底部内容 |