feat(comp:tour): supports targetDisabled (#1869)

packages/components/tour/demo/TargetDisabled.md

@@ -0,0 +1,14 @@
+---
+order: 0
+title:
+  zh: 禁用目标区域
+  en: Target disabled
+---
+
+## zh
+
+通过 `targetDisabled` 或者 `step.targetDisabled` 禁用目标区域
+
+## en
+
+Disable target operation via ``targetDisabled` or `step.targetDisabled`.

packages/components/tour/demo/TargetDisabled.vue

@@ -0,0 +1,59 @@
+<template>
+  <div>
+    <IxButton @click="beginTour">Begin</IxButton>
+    <IxDivider />
+    <IxSpace>
+      <div ref="firstBtnRef">
+        <IxButton>Step1</IxButton>
+      </div>
+      <div ref="secondBtnRef">
+        <IxButton>Step2</IxButton>
+      </div>
+      <div ref="thirdBtnRef">
+        <IxButton>Step3</IxButton>
+      </div>
+    </IxSpace>
+  </div>
+  <IxTour v-model:visible="tourVisible" :steps="steps" :onClose="onClose" :onFinish="onFinish" targetDisabled></IxTour>
+</template>
+
+<script setup lang="ts">
+import type { TourStep } from '@idux/components/tour'
+
+import { ref } from 'vue'
+
+const tourVisible = ref(false)
+
+const beginTour = () => (tourVisible.value = true)
+
+const firstBtnRef = ref<HTMLElement>()
+const secondBtnRef = ref<HTMLElement>()
+const thirdBtnRef = ref<HTMLElement>()
+
+const steps: TourStep[] = [
+  {
+    title: 'Step1',
+    description: 'this is description...',
+    target: () => firstBtnRef.value,
+  },
+  {
+    title: 'Step2',
+    description: 'this is description...',
+    target: () => secondBtnRef.value,
+  },
+  {
+    title: 'Step3',
+    description: 'this is description...',
+    target: () => thirdBtnRef.value,
+  },
+]
+
+const onClose = () => {
+  console.log('onClose')
+}
+const onFinish = () => {
+  console.log('onFinish')
+}
+</script>
+
+<style scoped lang="less"></style>

packages/components/tour/docs/Api.zh.md

@@ -17,34 +17,43 @@
 | `showArrow` | 浮层是否显示箭头 | `boolean` | `true` | ✅ | - |
 | `steps` | 步骤配置 | `TourStep[]` | - | - | - |
 | `scrollIntoViewOptions` | `scrollIntoView` 参数 | `boolean \| ScrollIntoViewOptions` | `true` | ✅ | - |
+| `targetDisabled` | 是否禁用目标区域 | `boolean` | `false` | - | - |
 | `zIndex` | 浮层和遮罩的zIndex | `number` | - | - | - |
 | `onChange` | `activeIndex`值变化的回调函数 | `(current: number, pre: number) => void` | - | - | - |
 | `onClose` | 关闭的回调函数 | `() => void` | - | - | - |
 | `onFinish` | 结束的回调函数 | `() => void` | - | - | - |
 
 ```ts
 interface TourMaskOptions {
-  color?: string
-  class?: string
+  color?: string // 遮罩颜色
+  class?: string // 遮罩自定义class
+  outlineColor?: string // 目标区域外轮廓
+}
+
+interface TargetGap {
+  offset?: number // 目标高亮的区域距离实际节点的间距
+  radius?: number // 目标高亮区域的边框圆角
+  outline?: number // 目标高亮区域的外轮廓
 }
 
 type TargetGetter = () => HTMLElement | null | Promise<HTMLElement | null>
 
 interface TourStep {
-  title: string
-  description?: string
-  gap?: number | TargetGap
-  mask?: boolean | TourMaskOptions
-  target?: MaybeElement | null | string | TargetGetter
-  placement?: PopperPlacement
-  showArrow?: boolean
-  nextButton?: ButtonProps | boolean
-  nextButtonText?: string
-  prevButton?: ButtonProps | boolean
-  prevButtonText?: string
-  scrollIntoViewOptions?: boolean | ScrollIntoViewOptions
-  beforeEnter?: () => void | Promise<void>
-  afterLeave?: () => void | Promise<void>
+  title: string // 标题
+  description?: string // 描述
+  gap?: number | TargetGap // 目标高亮区域配置
+  mask?: boolean | TourMaskOptions // 遮罩配置
+  target?: MaybeElement | null | string | TargetGetter // 目标节点获取
+  targetDisabled?: boolean // 是否禁用目标操作
+  placement?: PopperPlacement // 浮层位置
+  showArrow?: boolean // 是否展示箭头
+  nextButton?: ButtonProps | boolean // 下一步的按钮配置
+  nextButtonText?: string // 下一步按钮文字
+  prevButton?: ButtonProps | boolean // 上一步的按钮配置
+  prevButtonText?: string // 上一步按钮文字
+  scrollIntoViewOptions?: boolean | ScrollIntoViewOptions // 滚动到可视区域
+  beforeEnter?: () => void | Promise<void> // 进入之前执行
+  afterLeave?: () => void | Promise<void> // 结束之后执行，步骤跳转之前会等待执行结果
 }
 ```
 

packages/components/tour/src/Mask.tsx

@@ -23,6 +23,7 @@ export default defineComponent({
       maskClass,
       maskStyle,
       maskOutlineStyle,
+      activeStep,
     } = inject(tourToken)!
 
     const classes = computed(() => {
@@ -35,6 +36,7 @@ export default defineComponent({
         hashId.value,
         maskClass.value,
         animatable ? `${prefixCls}-animatable` : undefined,
+        activeStep.value?.targetDisabled ? `${prefixCls}-target-disabled` : undefined,
       ])
     })
 

packages/components/tour/src/composables/useActiveStep.ts

@@ -83,6 +83,7 @@ export function useActiveStep(
       ...step,
       index,
       target,
+      targetDisabled: step.targetDisabled ?? props.targetDisabled,
       gap: mergedGap,
       mask: step.mask ?? props.mask,
       placement: step.placement ?? props.placement,

packages/components/tour/src/types.ts

@@ -49,6 +49,7 @@ export interface TourStep {
   gap?: number | TargetGap
   mask?: boolean | TourMaskOptions
   target?: MaybeElement | null | string | TargetGetter
+  targetDisabled?: boolean
   placement?: PopperPlacement
   showArrow?: boolean
   nextButton?: ButtonProps | boolean
@@ -119,6 +120,10 @@ export const tourProps = {
   scrollIntoViewOptions: {
     type: [Boolean, Object] as PropType<boolean | ScrollIntoViewOptions>,
   },
+  targetDisabled: {
+    type: Boolean,
+    default: false,
+  },
   zIndex: Number,
 
   // events

packages/components/tour/style/index.less

@@ -13,7 +13,10 @@
     clip-rule: evenodd;
     stroke-linejoin: round;
     stroke-miterlimit: 2;
-    pointer-events: none;
+
+    &:not(&-target-disabled) {
+      pointer-events: none;
+    }
 
     & &-target {
       pointer-events: auto;