@king-design/intact 3.5.2 → 3.6.0

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 | 自定义底部内容 |

package/components/tour/index.spec.ts

@@ -0,0 +1,259 @@
+import { Component } from 'intact';
+import BasicDemo from '~/components/tour/demos/basic';
+import DeclarativeDemo from '~/components/tour/demos/declarative';
+import ClosableDemo from '~/components/tour/demos/closable';
+import CustomTextDemo from '~/components/tour/demos/customText';
+import BeforeChangeDemo from '~/components/tour/demos/beforeChange';
+import EventsDemo from '~/components/tour/demos/events';
+import MaskClosableDemo from '~/components/tour/demos/maskClosable';
+import NotargetDemo from '~/components/tour/demos/notarget';
+import { mount, unmount, dispatchEvent, getElement, wait } from '../../test/utils';
+import { Tour, TourStep } from './';
+
+describe('Tour', () => {
+    afterEach(() => {unmount()});
+
+    it('should show and hide tour correctly', async () => {
+        const [instance, element] = mount(BasicDemo);
+        
+        let tourContent = getElement('.k-tour-step');
+        expect(tourContent).to.be.undefined;
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('启动引导')) as HTMLElement;
+        startBtn.click();
+        await wait();
+        
+        tourContent = getElement('.k-tour-step');
+        expect(tourContent).to.exist;
+        
+        expect(tourContent!.querySelector('.k-tour-step-title')!.textContent).to.eql('第一步');
+        
+        const indicator = tourContent!.querySelector('.k-tour-step-indicator');
+        expect(indicator!.textContent!.trim()).to.eql('1 / 2');
+        
+        const nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+        
+        const updatedContent = getElement('.k-tour-step');
+        expect(updatedContent!.querySelector('.k-tour-step-title')!.textContent).to.eql('第二步');
+        
+        const doneBtn = updatedContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        doneBtn.click();
+        await wait();
+        
+        expect(getElement('.k-tour-step')).to.be.undefined;
+    });
+
+    it('should work with declarative TourStep components', async () => {
+        const [instance, element] = mount(DeclarativeDemo);
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('启动引导')) as HTMLElement;
+        startBtn.click();
+        await wait(50);
+        
+        const tourContent = getElement('.k-tour-step');
+        expect(tourContent).to.exist;
+        
+        expect(tourContent!.querySelector('.k-tour-step-title')!.textContent).to.eql('第一步');
+        expect(tourContent!.querySelector('.k-tour-step-body')!.textContent).to.include('子组件方式的第一步');
+
+        const nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait(50);
+        
+        const updatedContent = getElement('.k-tour-step');
+        expect(updatedContent!.querySelector('.k-tour-step-title')!.textContent).to.eql('第二步');
+        expect(updatedContent!.querySelector('.k-tour-step-body')!.textContent).to.include('子组件方式的第二步');
+    });
+
+    it('should handle closable property correctly', async () => {
+        const [instance, element] = mount(ClosableDemo);
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('启动引导')) as HTMLElement;
+        startBtn.click();
+        await wait(50);
+        
+        (instance as any).set('closable', true);
+        await wait(50);
+        const tourContent = getElement('.k-tour-step');
+        expect(tourContent).to.exist;
+        
+        const closeIcon = tourContent!.querySelector('.k-tour-step-close');
+        expect(closeIcon).to.be.null;
+    });
+
+    it('should handle beforeChange correctly', async () => {
+        const [instance, element] = mount(BeforeChangeDemo);
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('启动引导')) as HTMLElement;
+        startBtn.click();
+        await wait();
+        
+        expect((instance as any).get('currentStep')).to.eql(0);
+        
+        let tourContent = getElement('.k-tour-step');
+        let nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+        
+        expect((instance as any).get('currentStep')).to.eql(1);
+        
+        tourContent = getElement('.k-tour-step');
+        nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+        
+        expect((instance as any).get('currentStep')).to.eql(2);
+
+        tourContent = getElement('.k-tour-step');
+        nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+
+        const input = element.querySelector('.step3-input .k-input-inner') as HTMLInputElement;
+        input.value = 'next';
+        dispatchEvent(input, 'input');
+        await wait();
+        
+        tourContent = getElement('.k-tour-step');
+        nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+        console.log('currentStep', (instance as any).get('currentStep'));
+        expect((instance as any).get('currentStep')).to.eql(3);
+    });
+
+    it('should trigger events correctly', async () => {
+        const [instance, element] = mount(EventsDemo);
+        
+        const prevSpy = sinon.spy(instance, 'handlePrev');
+        const nextSpy = sinon.spy(instance, 'handleNext');
+        const finishSpy = sinon.spy(instance, 'handleFinish');
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('开始引导')) as HTMLElement;
+        startBtn.click();
+        await wait();
+        
+        const tourContent = getElement('.k-tour-step');
+        const nextBtn = tourContent!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        nextBtn.click();
+        await wait();
+        
+        expect(nextSpy.callCount).to.eql(1);
+        
+        const prevBtn = getElement('.k-tour-step')!.querySelector('.k-tour-step-buttons .k-btn:not(.k-primary)') as HTMLElement;
+        prevBtn.click();
+        await wait();
+        
+        expect(prevSpy.callCount).to.eql(1);
+        
+        nextBtn.click();
+        await wait();
+        nextBtn.click();
+        await wait();
+        const doneBtn = getElement('.k-tour-step')!.querySelector('.k-tour-step-buttons .k-primary') as HTMLElement;
+        doneBtn.click();
+        await wait();
+        
+        console.log('finishSpy.callCount', finishSpy.callCount);
+        expect(finishSpy.callCount).to.eql(0);
+    });
+
+    it('should handle maskClosable correctly', async () => {
+        const [instance, element] = mount(MaskClosableDemo);
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('启动引导')) as HTMLElement;
+        startBtn.click();
+        await wait(50);
+        
+        const highlight = getElement('.k-tour-target-highlight');
+        expect(highlight).to.exist;
+        
+        dispatchEvent(document, 'click');
+        await wait(50);
+        
+        expect(getElement('.k-tour-step')).to.be.undefined;
+        
+        startBtn.click();
+        await wait(50);
+        (instance as any).set('maskClosable', false);
+        await wait(50);
+        
+        dispatchEvent(document, 'click');
+        await wait(50);
+        
+        expect(getElement('.k-tour-step')).to.exist;
+    });
+
+    it('should handle custom text correctly', async () => {
+        const [instance, element] = mount(CustomTextDemo);
+        
+        const buttons = element.querySelectorAll('.k-btn');
+        const startBtn = Array.from(buttons).find(btn => btn.textContent?.includes('开始自定义按钮引导')) as HTMLElement;
+        startBtn.click();
+        await wait(50);
+        
+        expect(element.innerHTML).to.matchSnapshot();
+    });
+
+    it('should handle target correctly', async () => {
+        const [instance, element] = mount(NotargetDemo);
+        
+        const btn = element.querySelector('.k-btn') as HTMLElement;
+        btn.click();
+        await wait(50);
+        
+        expect(element.innerHTML).to.matchSnapshot();
+    });
+
+    // it('should handle theme correctly', async () => {
+    //     interface DemoProps {
+    //         theme: string;
+    //         tourData: any[];
+    //     }
+        
+    //     class Demo extends Component<DemoProps> {
+    //         static template = `
+    //             const { Tour } = this;
+    //             <div>
+    //                 <Tour
+    //                     data={this.get('tourData')}
+    //                     visible={true}
+    //                     theme={this.get('theme')}
+    //                 />
+    //             </div>
+    //         `;
+    //         Tour = Tour;
+            
+    //         static defaults() {
+    //             return {
+    //                 theme: 'dark',
+    //                 tourData: [
+    //                     {
+    //                         target: 'body',
+    //                         title: '主题测试',
+    //                         content: '测试深色主题'
+    //                     }
+    //                 ]
+    //             } as DemoProps;
+    //         }
+    //     }
+
+    //     const [instance, element] = mount(Demo);
+    //     await wait(50);
+        
+    //     expect(element.innerHTML).to.matchSnapshot();
+        
+    //     instance.set('theme', 'light');
+    //     await wait(50);
+        
+    //     expect(element.innerHTML).to.matchSnapshot();
+    // });
+});

package/components/tour/index.ts

@@ -0,0 +1,2 @@
+export * from './tour';
+export * from './step';

package/components/tour/step.ts

@@ -0,0 +1,55 @@
+import {Component, TypeDefs, VNode, Children} from 'intact';
+import template from './step.vdt';
+import { useConfigContext } from '../config';
+import type {Events} from '../types';
+
+export interface TourStepProps {
+    title?: string | VNode;
+    content?: Children;
+    target?: string | HTMLElement;
+    position?: string | any;
+    nextText?: string;
+    prevText?: string;
+}
+
+export interface TourStepEvents { }
+
+export interface TourStepBlocks {
+    header: null;
+    content: null;
+    footer: null;
+}
+
+const typeDefs: Required<TypeDefs<TourStepProps>> = {
+    title: [String, VNode],
+    content: [String, VNode, Array],
+    target: [String, Object],
+    position: [String, Object],
+    nextText: String,
+    prevText: String,
+};
+
+const defaults = (): Partial<TourStepProps> => ({
+    position: 'bottom',
+    nextText: '下一步',
+    prevText: '上一步',
+});
+
+export class TourStep extends Component<TourStepProps, TourStepEvents, TourStepBlocks> {
+    static template = template;
+    static typeDefs = typeDefs;
+    static defaults = defaults;
+
+    private config = useConfigContext();
+
+    getTarget(): HTMLElement | null {
+        const target = this.get('target');
+        if (!target) return null;
+        
+        if (typeof target === 'string') {
+            return document.querySelector(target);
+        }
+    
+        return target as HTMLElement;
+    }
+}

package/components/tour/step.vdt

@@ -0,0 +1,75 @@
+import {Button} from '../button';
+import {Icon} from '../icon';
+import {makeStyles} from './styles';
+import {TourContext} from './tour';
+import {getRestProps} from '../utils';
+
+const {
+    title,
+    content,
+    className,
+    children,
+    nextText,
+    prevText
+} = this.get();
+
+const { k } = this.config;
+
+const classNameObj = {
+    [`${k}-tour-step`]: true,
+    [className]: className,
+};
+
+<TourContext.Consumer>
+    {({value, total, doneText, onPrev, onNext, onFinish, closable}) => {
+        const isFirst = value === 0;
+        const isLast = value === total - 1;
+        const showHeader = !!title;
+        const displayIndex = value + 1;
+
+        return (
+            <div class={classNameObj} {...getRestProps(this)}>
+                {/* 头部区域 */}
+                <div class={`${k}-tour-step-header`} v-if={!!title || $blocks.header}>
+                    <div class={`${k}-tour-step-title`}>
+                        <b:header>{title}</b:header>
+                    </div>
+                    <div v-if={!closable} class={`${k}-tour-step-close`} ev-click={onFinish}>
+                        <Icon class={`${k}-icon-close`} />
+                    </div>
+                </div>
+                
+                {/* 内容区域 */}
+                <div class={`${k}-tour-step-body`}>
+                    { children || content}
+                </div>
+                
+                {/* 底部区域 */}
+                <div class={`${k}-tour-step-footer`}>
+                    <b:footer>
+                        <div class={`${k}-tour-step-indicator`}>
+                            {displayIndex} / {total}
+                        </div>
+                        <div class={`${k}-tour-step-buttons`}>
+                            <Button
+                                v-if={!isFirst}
+                                size="small"
+                                type="secondary"
+                                ev-click={onPrev}
+                            >
+                                {prevText}
+                            </Button>
+                            <Button
+                                size="small"
+                                type="primary"
+                                ev-click={isLast ? onFinish : onNext}
+                            >
+                                {isLast ? doneText : nextText}
+                            </Button>
+                        </div>
+                    </b:footer>
+                </div>
+            </div>
+        );
+    }}
+</TourContext.Consumer>