chore: 初始化uniapp前端项目基础框架

新增项目配置、静态资源、工具类、状态管理、API接口、组件库集成等全套基础代码，完成项目初始化搭建
2026-09-23 21:18:09 +00:00 · 2026-08-02 03:49:27 +08:00
parent 7f8320d3ed
commit 3c9b77f994
278 changed files with 55387 additions and 2 deletions
@@ -0,0 +1,441 @@
+---
+title: 全局反馈组件
+iframe: true
+iframeFormatter: subPages/feedback/index
+---
+
+# 全局反馈组件
+
+本项目基于 Pinia 和 Wot UI 封装了三类可全局调用的反馈能力：GlobalLoading、GlobalToast、GlobalDialog。它们适合在网络请求中间件、路由导航守卫以及其他不方便直接依赖页面内 hook 实例的场景中使用。
+
+:::tip 提示
+Wot UI 原生提供了 useToast、useDialog 等函数式能力，但调用侧通常仍要依赖对应组件实例。这里的全局反馈组件通过 Pinia 保存状态，并在组件内部监听状态后再调用 wd-toast 或 wd-dialog，因此可以把触发逻辑放到更靠近业务流程的位置，例如请求拦截器和路由守卫。
+:::
+
+## 使用前提
+
+使用这套全局反馈封装前，需要保证页面树中已经挂载以下组件实例：
+
+- GlobalLoading
+- GlobalToast
+- GlobalDialog
+
+本项目通过组件自动导入支持直接使用这些组件；业务侧只需要调用对应的 composable：
+
+```vue
+<template>
+  <GlobalLoading />
+  <GlobalToast />
+  <GlobalDialog />
+  <slot />
+</template>
+```
+
+三个组件都会记录触发时所在页面路径，并且仅在相同页面内展示，避免切页后在错误页面继续显示旧反馈。
+
+## 全局加载
+
+### 概述
+
+GlobalLoading 基于 Wot UI 的 wd-toast 封装，适合配合 axios、alova 等请求流程显示全局加载状态。
+
+### 组件特性
+
+- 基于 wd-toast 实现
+- 默认不自动关闭
+- 默认显示遮罩，防止重复操作
+- 自动记录当前页面路径，只在触发页面展示
+
+### 使用
+
+```ts
+import { useGlobalLoading } from '@/composables/useGlobalLoading'
+
+const loading = useGlobalLoading()
+```
+
+### API
+
+#### loading(option)
+
+显示加载状态。
+
+```ts
+loading.loading('加载中...')
+
+loading.loading({
+  msg: '数据加载中',
+  cover: true,
+})
+```
+
+默认会合并以下配置：
+
+- iconName: loading
+- duration: 0
+- cover: true
+- position: middle
+- show: true
+
+#### close()
+
+关闭加载状态。
+
+```ts
+loading.close()
+```
+
+### 参数说明
+
+#### ToastOptions
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| msg | string | - | 加载文案 |
+| iconName | string | loading | 图标名称 |
+| duration | number | 0 | 持续时间，0 表示不自动关闭 |
+| cover | boolean | true | 是否显示遮罩 |
+| position | string | middle | 显示位置：top \| middle \| bottom |
+| show | boolean | true | 是否显示，内部状态字段 |
+
+#### 参数形式
+
+支持两种调用方式：
+
+1. 字符串：作为 msg 使用
+2. 对象：传入完整 ToastOptions
+
+### 示例
+
+```ts
+const { loading, close } = useGlobalLoading()
+
+async function fetchData() {
+  try {
+    loading('正在加载数据...')
+    await api.getData()
+  }
+  finally {
+    close()
+  }
+}
+```
+
+## 全局提示
+
+### 概述
+
+GlobalToast 基于 Wot UI 的 wd-toast 封装，提供统一的全局轻提示能力。
+
+### 组件特性
+
+- 基于 wd-toast 实现
+- 支持 success、error、info、warning 四种快捷调用
+- 支持自定义位置、时长、图标和遮罩
+- 自动记录当前页面路径，只在触发页面展示
+
+### 使用
+
+```ts
+import { useGlobalToast } from '@/composables/useGlobalToast'
+
+const toast = useGlobalToast()
+```
+
+### API
+
+#### show(option)
+
+显示普通提示。
+
+```ts
+toast.show('这是一条提示信息')
+
+toast.show({
+  msg: '自定义提示',
+  duration: 3000,
+  position: 'top',
+})
+```
+
+默认配置：
+
+- duration: 2000
+- show: false
+- 调用时自动补齐 show: true
+- 未传 position 时默认使用 middle
+
+#### success(option)
+
+成功提示，默认附带 success 图标，duration 为 1500。
+
+```ts
+toast.success('操作成功')
+```
+
+#### error(option)
+
+错误提示，默认附带 error 图标，direction 为 vertical。
+
+```ts
+toast.error('操作失败')
+```
+
+#### info(option)
+
+信息提示，默认附带 info 图标。
+
+```ts
+toast.info('这是一条信息')
+```
+
+#### warning(option)
+
+警告提示，默认附带 warning 图标。
+
+```ts
+toast.warning('警告信息')
+```
+
+#### close()
+
+手动关闭当前提示。
+
+```ts
+toast.close()
+```
+
+### 参数说明
+
+#### ToastOptions
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| msg | string | - | 提示内容 |
+| duration | number | 2000 | 持续时间，0表示不自动关闭 |
+| position | string | middle | 显示位置：top \| middle \| bottom |
+| iconName | string | - | 图标名称 |
+| direction | string | - | 布局方向：horizontal \| vertical |
+| cover | boolean | false | 是否显示遮罩 |
+| show | boolean | true | 是否显示，内部状态字段 |
+
+#### 参数形式
+
+所有方法都支持两种调用方式：
+
+1. 字符串：作为 msg 使用
+2. 对象：传入完整 ToastOptions
+
+## 全局弹窗
+
+### 概述
+
+GlobalDialog 基于 Wot UI 的 wd-dialog 封装，用于统一处理提醒、确认和输入等交互流程。
+
+### 组件特性
+
+- 基于 wd-dialog 实现
+- 支持 alert、confirm、prompt 三种模式
+- 支持 success、fail 回调
+- 自动记录当前页面路径，只在触发页面展示
+- 内部统一设置取消按钮和确认按钮为非圆角
+
+### 使用
+
+```ts
+import { useGlobalDialog } from '@/composables/useGlobalDialog'
+
+const dialog = useGlobalDialog()
+```
+
+### API
+
+#### show(option)
+
+显示通用弹窗。
+
+```ts
+dialog.show({
+  title: '提示',
+  msg: '这是一条消息',
+  success: (res) => console.log('成功', res),
+  fail: (res) => console.log('失败', res),
+})
+
+dialog.show('简单提示')
+```
+
+注意：当参数为字符串时，实际会作为 title 使用。
+
+#### alert(option)
+
+显示提醒弹窗，只显示确认按钮。
+
+```ts
+dialog.alert('操作完成')
+
+dialog.alert({
+  title: '提醒',
+  msg: '请注意查看结果',
+})
+```
+
+#### confirm(option)
+
+显示确认弹窗，自动开启取消按钮。
+
+```ts
+dialog.confirm('确定要删除吗？')
+
+dialog.confirm({
+  title: '确认删除',
+  msg: '删除后不可恢复，确定要删除吗？',
+  success: (res) => {
+    if (res.action === 'confirm') {
+      console.log('用户确认删除')
+    }
+  },
+  fail: (res) => {
+    console.log('用户取消删除')
+  },
+})
+```
+
+#### prompt(option)
+
+显示输入弹窗，自动开启取消按钮。
+
+```ts
+dialog.prompt('请输入您的姓名')
+
+dialog.prompt({
+  title: '输入信息',
+  msg: '请输入新的名称',
+  inputValue: '默认值',
+  inputPlaceholder: '请输入内容',
+  success: (res) => {
+    if (res.action === 'confirm') {
+      console.log('用户输入:', res.value)
+    }
+  },
+})
+```
+
+#### close()
+
+手动关闭弹窗。
+
+```ts
+dialog.close()
+```
+
+### 参数说明
+
+#### GlobalDialogOptions
+
+GlobalDialogOptions 基于 Wot UI 的 DialogOptions 扩展，并额外支持 success、fail 回调。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | string | - | 弹窗标题 |
+| msg | string | - | 弹窗内容 |
+| type | string | - | 弹窗类型：alert \| confirm \| prompt |
+| showCancelButton | boolean | 自动设置 | alert 为 false，confirm 和 prompt 为 true |
+| inputValue | string | - | prompt 模式下的输入框默认值 |
+| inputPlaceholder | string | - | prompt 模式下的输入框占位文案 |
+| success | Function | - | 点击确认后的回调 |
+| fail | Function | - | 取消或关闭后的回调 |
+| confirmButtonText | string | 取决于 wd-dialog 默认值 | 确认按钮文本 |
+| cancelButtonText | string | 取决于 wd-dialog 默认值 | 取消按钮文本 |
+
+#### DialogResult
+
+回调参数会透传 wd-dialog 的结果对象，常用字段如下：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| action | string | 用户操作：confirm \| cancel |
+| value | string | 输入框的值，仅 prompt 模式可用 |
+
+#### 参数形式
+
+所有方法都支持两种调用方式：
+
+1. 字符串：作为 title 使用
+2. 对象：传入完整 GlobalDialogOptions
+
+### 示例
+
+```ts
+const { confirm, alert, prompt } = useGlobalDialog()
+const { success, warning } = useGlobalToast()
+
+alert({
+  title: '重要提醒',
+  msg: '这是一个重要提醒',
+})
+
+confirm({
+  title: '确认操作',
+  msg: '确定继续吗？',
+  success: (res) => {
+    if (res.action === 'confirm') {
+      success('继续执行')
+    }
+  },
+})
+
+prompt({
+  title: '输入信息',
+  msg: '请输入您的姓名',
+  success: (res) => {
+    if (res.action === 'confirm' && String(res.value || '').trim()) {
+      success(`您好，${res.value}`)
+    }
+    else {
+      warning('输入不能为空')
+    }
+  },
+})
+```
+
+## 典型场景
+
+### 请求中间件中显示全局加载
+
+```ts
+const globalLoading = useGlobalLoading()
+
+globalLoading.loading('请求中...')
+
+try {
+  await request()
+}
+finally {
+  globalLoading.close()
+}
+```
+
+### 路由守卫中显示确认弹窗
+
+```ts
+const { confirm } = useGlobalDialog()
+
+confirm({
+  title: '离开当前页面',
+  msg: '表单尚未保存，确定离开吗？',
+  success: (res) => {
+    if (res.action === 'confirm') {
+      // 继续跳转
+    }
+  },
+})
+```
+
+## 注意事项
+
+1. GlobalLoading 和 GlobalToast 底层都调用 wd-toast，但使用了不同 selector，不会互相覆盖。
+2. GlobalDialog 使用 wd-dialog，内容字段应使用 msg，而不是 message。
+3. 三个 composable 都会记录 currentPage，仅在触发时所在页面展示反馈。
+4. 使用 duration: 0 的提示或加载时，需要手动调用 close()。
+5. 支付宝小程序场景下组件内部做了兼容处理，业务侧无需额外处理。