@yeez-tech/controllable-delivery-guide

可控交付数据使用指引（Vue 3）。支持弹窗模式与页面嵌入模式；宿主决定挂载位置与触发方式。

安装

npm install @yeez-tech/controllable-delivery-guide

弹窗模式（默认）

宿主自行提供按钮，通过 v-model:visible 控制显隐：

<template>
  <button @click="visible = true">打开指引</button>

  <ControllableDeliveryGuide
    v-model:visible="visible"
    mode="modal"
    :learn-more-url="docUrl"
    @close="onClose"
  />
</template>

<script setup>
import { ref } from 'vue'
import { ControllableDeliveryGuide } from '@yeez-tech/controllable-delivery-guide'
import '@yeez-tech/controllable-delivery-guide/style.css'

const visible = ref(false)
const docUrl = ref('') // 可控交付介绍文档链接，后续补充

function onClose() {}
</script>

也可通过实例方法：guideRef.value?.open() / close()。

页面嵌入模式

用于替换宿主页内指定区域（如「购买成功」）。无遮罩、宽度跟随父容器：

<template>
  <!-- 宿主选定的容器，例如购买成功内容区 -->
  <div class="purchase-success-slot">
    <ControllableDeliveryGuide
      mode="page"
      :learn-more-url="docUrl"
      @learn-more="onLearnMore"
    />
  </div>
</template>

页面模式下默认不显示右上角关闭按钮；如需显示可传 :closable="true"，并监听 @close 由宿主卸载/切换区块。

「了解更多」在页面模式下会打开链接并触发 @learn-more，不会自动卸载组件（由宿主决定后续 UI）。

Props

| 属性 | 类型 | 默认 | 说明 | |------|------|------|------| | mode | 'modal' \| 'page' | 'modal' | 弹窗 / 页面嵌入 | | visible | boolean | false | 弹窗模式显隐（v-model:visible） | | learnMoreUrl | string | '' | 「了解更多」文档链接 | | closable | boolean | false | 页面模式下是否显示关闭按钮 | | onClose | () => void | — | 关闭回调（亦可通过 @close） | | onLearnMore | () => void | — | 「了解更多」额外回调 |

交互

• 了解更多：新标签页打开 learnMoreUrl（若有）；弹窗模式同时关闭弹窗
• 下一步（步骤 1–4）：进入下一步
• 再看一遍（步骤 5）：回到步骤 1，不关闭
• 右上角 X（弹窗，或页面模式且 closable）：关闭 / 通知宿主

目录结构

controllable-delivery-guide/
├── src/
│   ├── lib/             # 核心组件（build:lib 入口）
│   ├── types/
│   ├── styles/
│   └── demo/            # 本地调试页（不进 npm）
│       ├── index.html
│       └── purchase-success.html
├── dist/                # npm 库产物（build:lib）
├── dist-demo/           # Demo 产物（build / build:demo）
└── typings/

本地开发

cd controllable-delivery-guide
npm install
npm run dev          # 启动 demo（端口 5177）

• 首页：弹窗模式调试 -「打开页面模式」→ /purchase-success.html：模拟购买成功页内嵌

构建：

npm run build:lib    # 打包核心库 → dist/（发布用）
npm run build:demo   # 打包 demo → dist-demo/（仅调试）