@wuipkg/component

面向通用移动端或 H5 的基础 Vue 3 组件封装。通常基于 vant 生态进行轻量级抽象与补齐。

安装

pnpm install @wuipkg/component

API 详细说明与组件使用示例

1. RegionPicker (地区选择器)

基于 van-cascader 的可异步延迟加载逐层省市区数据的地域弹层组件。

Props 属性 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | show | boolean | false | 控制弹出层的显示与隐藏状态。 | | depth | number | 3 | 指定最大支持请求及下钻的层级深度。 | | getProvince | () => Promise<Region[]> | - | 顶层省份拉取加载函数，被触发展示且内容为空时自动执行。 | | getCity | (provinceId: string) => Promise<Region[]> | - | 选中省份节点未见子级时激发的拉取地市回调。 | | getArea | (cityId: string) => Promise<Region[]> | - | 获取区县的回调（仅当 depth > 2 且触发了市级节点时被选用）。 |

Emits 暴露事件 | 事件名称 | 回调参数 | 说明 | | --- | --- | --- | | update:show | (visible: boolean) | 通知外部视图闭合，保持对弹框收展状态的数据进行同步。 | | finish | (selectedOptions: Region[]) | 用户选定深度的树节点后的最终完成回调输出。 |

用法示例：

<template>
  <div class="address-pane" @click="visible = true">
    点击选择地区关联：{{ selectedText }}
  </div>

  <RegionPicker
    v-model:show="visible"
    :depth="2"
    :getProvince="api.getProvinceList"
    :getCity="id => api.getCityList(id)"
    @finish="onFinish"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RegionPicker } from '@wuipkg/component'

const visible = ref(false)
const selectedText = ref('未选择')

// api 模拟调用获取接口格式均为 { id: string, name: string }[] 即可
const api = {
  getProvinceList: async () => [{ id: '11', name: '北京' }],
  getCityList: async (pid) => [{ id: '1101', name: '朝阳区' }]
}

const onFinish = (selectedBranches) => {
  // selectedBranches: 包含了你选中每一层级的完整节点对象集
  selectedText.value = selectedBranches.map(node => node.name).join(' / ')
}
</script>

2. IntroModal (引导介绍弹层)

多见于平台产品进行新人特权引导或富文本安全过滤介绍面板的展示（已捆绑了 dompurify 组件完成防御注入的安全渲染）。

Props & Emits 属性 | 参数属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | show | boolean | false | 弹窗的显隐驱动开关。 | | title | string | - | 弹框顶部的中央主标。 | | content | string | - | 作为主要宣导的主体富文本展示区（支持安全解析及样式的 HTML 源渲染）。 |

用法示例：

<template>
  <button @click="showModal = true">打开平台守则</button>

  <IntroModal
    v-model:show="showModal"
    title="社区新人注意事项"
    content="<strong>规则 1：</strong>不要破坏和谐！<br/><i>享受沟通</i>"
    @close="handleCloseTracking"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { IntroModal } from '@wuipkg/component'

const showModal = ref(false)

const handleCloseTracking = () => {
    // 监听打点
    console.log('用户关闭了规则引导浮层可以去自由活动了。')
}
</script>

3. Draggable (悬浮拖拽与吸附容器)

实现全局悬浮窗或者是基于自定义容器限制范围内的指端响应惯性拖曳功能。

Props 属性 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | defaultLeft / defaultTop | number| 0 | 组件挂载初始定位渲染呈现出来的左置与顶部坐标高度像素。 | | getConinter| () => HTMLElement | () => document.body | 指定该悬浮框能受限制游离拖动的最大父级安全边际DOM对象。 |

用法示例：

<template>
  <Draggable :defaultLeft="20" :defaultTop="80">
    <div class="fixed-bubble">
      客服联系入口 / 或者是其它功能球
    </div>
  </Draggable>
</template>

<script setup lang="ts">
import { Draggable } from '@wuipkg/component'
</script>

<style>
.fixed-bubble {
  width: 50px;
  height: 50px;
  border-radius: 25px;
  background-color: blue;
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
}
</style>

4. SafeArea (安全区占位)

适配移动端机型特性的刘海屏（Top 指状区域）或底部交互手势栏（Bottom 指纹或返回手把区域）自适应隔断及留白的结构防塌陷组件。

Props 属性 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | position | 'bottom' \| 'top' | 'bottom' | 指示填补挤下是占用顶部状态栏还是底侧的安全区 padding 模型空间。 |

用法示例：

<template>
  <div class="mobile-app">
    <!-- 将头部内容从刘海里顶出来 -->
    <SafeArea position="top" />
    <header>我的导航极简栏</header>

    <main class="content-scroll"></main>

    <footer>固定底部悬浮提交按钮</footer>
    <!-- 在底部增加对 HomeIndicator 的挤兑填充以免盖住功能实体按钮 -->
    <SafeArea position="bottom" />
  </div>
</template>

<script setup lang="ts">
import { SafeArea } from '@wuipkg/component'
</script>