# UI Docs 完整文档

> Vue 3 业务组件与 AI 对话项目文档，提供动态表单、数据表格、预计进度条和视觉特效的使用示例与技术实践。

# AI 阅读

> 通过 llms.txt 索引、独立 Markdown 与完整文档，让 AI 助手读取 UI Docs 的组件参数、代码示例和使用限制，并回到原始页面查看预览。

原始页面：[AI 阅读](http://docs.quyongqing.cn/ai.html)

UI Docs 提供纯 Markdown 版本，方便 AI 助手读取组件 API 和示例，也适合下载后在编辑器中查阅。参数表、暴露方法与折叠代码都包含在文档中，交互预览请在原始网页查看。

## 选择阅读入口

-   [文档索引 llms.txt](http://docs.quyongqing.cn/llms.txt)：按组件与项目列出文档和摘要，适合先定位相关内容。
-   [完整文档 llms-full.txt](http://docs.quyongqing.cn/llms-full.txt)：合并本站所有导出的正文，适合需要同时参考多个组件的场景。
-   [下载 QyqForm Markdown](http://docs.quyongqing.cn/components/qyq-form.md)：只读取动态表单的说明、参数和示例。
-   [下载预计进度条 Markdown](http://docs.quyongqing.cn/components/estimated-progress-bar.md)：只读取模拟进度、完成和失败处理的说明。

需要其他组件时，可从索引中选择对应 Markdown。每篇文档都附有原始页面链接，便于检查交互效果和引用来源。

## 在 AI 助手中使用

将所需文档的完整链接粘贴给支持网页读取的 AI 助手，再描述你的业务场景。例如，附上 QyqForm 文档地址后可以这样提问：

> 请根据这篇文档，用 QyqForm 编写一个包含关键词和状态筛选的 Vue 3 示例。说明所需依赖，以及查询、重置时由调用方处理的逻辑。

如果助手无法访问链接，可以把下载后的 Markdown 文件作为上下文提供。优先选取相关组件文档，有跨组件需求时再使用完整文档。

## 使用前核对

-   本仓库提供组件源码接入方式，具体依赖与导入路径见各组件文档。
-   AI 生成的代码仍需结合项目中的组件版本和业务接口进行检查。
-   标注为“模板片段”的示例需要配合实际数据和事件处理，不能直接作为完整页面运行。
-   涉及错误、取消、校验或重置时，参考对应文档的限制说明。

还可以浏览[组件目录](http://docs.quyongqing.cn/components/)和[项目专题](http://docs.quyongqing.cn/projects/)，按场景选择资料。

---

# EstimatedProgressBar 预计进度条

> 无法获取真实进度时，使用 EstimatedProgressBar 为 Vue 3 异步任务展示模拟进度，了解 start、finish、reset 的调用方式与失败、取消处理。

原始页面：[EstimatedProgressBar 预计进度条](http://docs.quyongqing.cn/components/estimated-progress-bar.html)

## 说明

`EstimatedProgressBar` 是用于 Vue 3 异步任务的模拟进度条，适合文件导出、AI 生成、批量同步等无法获取真实完成比例的场景。调用 `start()` 后，进度先快后慢推进到 99%；业务任务成功后调用 `finish()` 补到 100%，失败或取消时调用 `reset()` 清理展示。

## 适用场景与边界

| 任务情况 | 建议处理 |
| --- | --- |
| 接口仅返回最终结果 | 开始任务时调用 `start()`，成功后调用一次 `finish()` |
| 已有上传字节数或后端真实进度 | 使用能够绑定真实百分比的进度组件 |
| 超时、失败或用户取消 | 由调用方处理请求状态，调用 `reset()` 并展示对应提示 |
| 多个任务同时执行 | 为各任务分别维护实例或由业务层汇总状态 |

显示的百分比是等待反馈，不代表服务端完成比例；`durationSeconds` 只控制模拟动画的预计时长，不会设置请求超时，也不会在时间到达后自动完成任务。

## 接入条件

组件只依赖 Vue。将 `src/components/EstimatedProgressBar/index.vue` 放入项目后直接导入即可；示例中的 `@` 指向使用方的 `src`。`text` 是必传文案，默认预计时长为 28 秒，默认完成后保留展示。组件通过 `ref` 提供 `start()`、`finish()`、`reset()`，无需调用方维护显示开关。

## 实时预览

组件内部会先快后慢推进到 99%，适合“真实任务未返回，但页面需要稳定反馈”的场景。

当外部任务完成后，只需要调用一次 `finish()`，组件会自动补到 100%。

## 源码位置

`src/components/EstimatedProgressBar/index.vue`

## 基本参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | `-` | 进度条上方的说明文案，通常用于提示当前任务状态。 |
| `durationSeconds` | `number` | `28` | 模拟进度推进到 99% 的预计时长，单位为秒。 |
| `hideOnComplete` | `boolean` | `false` | 完成后是否自动隐藏进度条。 |

## 暴露方法

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `start()` | `() => void` | `-` | 开始模拟进度，按时长缓动推进到 99%。 |
| `finish()` | `() => Promise<void>` | `-` | 通知组件真实任务已完成，随后平滑补到 100%。 |
| `reset()` | `() => void` | `-` | 停止动画并重置为 0%，同时隐藏进度条。 |

## 事件

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `progress` | `(percent: number) => void` | `-` | 进度变化时触发，适合在父组件里同步当前百分比文本。 |

## 基本使用方法

下面使用延时模拟异步任务，可在接入组件后直接运行。实际使用时把延时替换为业务请求，并确认请求成功后再调用 `finish()`；如果使用 `fetch`，还需要检查响应的 `ok` 或业务状态码。

```vue
<template>
  <div class="task-progress">
    <button type="button" :disabled="loading" @click="handleTask">
      {{ loading ? '处理中…' : '开始任务' }}
    </button>

    <EstimatedProgressBar
      ref="progressBarRef"
      text="正在生成报告，请稍候..."
      :duration-seconds="20"
    />
    <p role="status">{{ taskMessage }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import EstimatedProgressBar from '@/components/EstimatedProgressBar/index.vue'

const progressBarRef = ref<InstanceType<typeof EstimatedProgressBar> | null>(null)
const loading = ref(false)
const taskMessage = ref('')

async function handleTask() {
  if (loading.value || !progressBarRef.value) return

  loading.value = true
  taskMessage.value = '正在处理任务'
  progressBarRef.value.start()

  try {
    await new Promise((resolve) => window.setTimeout(resolve, 5000))
    await progressBarRef.value?.finish()
    taskMessage.value = '任务已完成'
  } catch (error) {
    progressBarRef.value?.reset()
    taskMessage.value = error instanceof Error ? error.message : '任务失败，请重试'
  } finally {
    loading.value = false
  }
}
</script>
```

## 代码示例

**Estimated Progress Bar 基础示例**

```vue
<template>
  <div class="task-progress">
    <el-button type="primary" @click="handleTask">开始任务</el-button>

    <EstimatedProgressBar
      ref="progressBarRef"
      text="正在生成报告，请稍候..."
      :duration-seconds="20"
      @progress="currentPercent = $event"
    />

    <div class="task-progress__meta">当前进度：{{ Math.round(currentPercent) }}%</div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import EstimatedProgressBar from '@/components/EstimatedProgressBar/index.vue'

const progressBarRef = ref<any>(null)
const currentPercent = ref(0)

const handleTask = async () => {
  progressBarRef.value?.start()

  try {
    await new Promise((resolve) => window.setTimeout(resolve, 5000))
    await progressBarRef.value?.finish()
  } catch (error) {
    progressBarRef.value?.reset()
  }
}
</script>

<style scoped>
.task-progress {
  display: grid;
  gap: 12px;
}

.task-progress__meta {
  font-size: 13px;
  color: #6b7280;
}
</style>
```

## 常见问题

### 为什么进度停在 99%？

这是组件的预期行为。模拟时长结束后仍然等待真实任务结果，只有调用方调用 `finish()` 才会推进到 100%。请检查业务成功分支是否调用了该方法。

### 请求失败或取消时怎么处理？

调用 `reset()` 停止动画、隐藏进度条并把进度恢复到 0，同时在业务界面展示失败或取消提示。`reset()` 只管理组件状态，不会取消网络请求；使用可取消请求时，调用方还需取消请求，并避免旧请求结束后再次调用 `finish()`。

### finish() 返回的 Promise 表示什么？

它用于等待补齐进度的动画结束，不代表业务请求完成。组件在 `start()` 重新开始、`reset()` 或卸载时也会结束正在等待的完成 Promise，因此业务成功状态必须以请求结果为准。启用 `hideOnComplete` 后，完成动画结束还会短暂保留再隐藏。

### 可以重复点击开始或完成吗？

`start()` 会重置进度并重新开始。调用方应在任务期间禁用重复提交，并在成功分支只调用一次 `finish()`，避免多次完成动画互相覆盖。

## 相关文档

-   [QyqForm 动态表单](http://docs.quyongqing.cn/components/qyq-form.html)：收集任务参数并在提交前校验。
-   [QyqTable 数据表格](http://docs.quyongqing.cn/components/qyq-table.html)：展示任务列表或处理结果。
-   [组件目录](http://docs.quyongqing.cn/components/)：按业务场景选择组件。

---

# Vue 3 组件目录

> 按使用场景查找 UI Docs 的 Vue 3 组件，包括动态表单、数据表格、预计进度条、雪花特效和滚动动画，并查看示例与参数。

原始页面：[Vue 3 组件目录](http://docs.quyongqing.cn/components/)

这里收录本项目的业务组件与视觉特效。每篇文档都提供使用说明、交互预览和代码示例，组件源码位于仓库的 `src/components/` 目录。

## 按场景选择组件

| 使用场景 | 组件 | 主要能力与边界 |
| --- | --- | --- |
| 查询筛选、录入编辑 | [QyqForm 动态表单](http://docs.quyongqing.cn/components/qyq-form.html) | 基于 Element Plus，通过字段配置生成表单，支持校验、日期金额和插槽扩展 |
| 后台列表、订单列表 | [QyqTable 数据表格](http://docs.quyongqing.cn/components/qyq-table.html) | 配置列、状态映射和分页；业务数据请求由调用方处理 |
| 无法获取真实进度的异步任务 | [EstimatedProgressBar 预计进度条](http://docs.quyongqing.cn/components/estimated-progress-bar.html) | 模拟推进到 99%，由调用方在任务成功后通知完成 |
| 节日活动、横幅背景 | [SnowEffect 雪花特效](http://docs.quyongqing.cn/components/snow-effect.html) | Canvas 背景特效，当前不提供配置项 |
| 品牌展示、作品集视觉区 | [ScrollAnimation 滚动动画](http://docs.quyongqing.cn/components/scroll-animation.html) | 基于 GSAP 的滚动翻转效果，图片与动画节奏在源码中配置 |

## 接入方式

当前仓库是组件源码与文档工程，尚未提供独立 npm 组件包。接入时需要复制对应组件及其本地依赖，按照各文档的说明配置 Vue、Element Plus 或 GSAP 等依赖；示例中的 `@/components/` 指向使用方的 `src/components/`。

可以先从 [QyqForm 的最小示例](http://docs.quyongqing.cn/components/qyq-form.html#%E5%BF%AB%E9%80%9F%E6%8E%A5%E5%85%A5)或[预计进度条的任务处理示例](http://docs.quyongqing.cn/components/estimated-progress-bar.html#%E5%9F%BA%E6%9C%AC%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95)开始，再查看完整参数与场景说明。

## 相关项目

[项目专题](http://docs.quyongqing.cn/projects/)介绍 AI 对话前端、业务后台与模型接入服务的技术实践。

---

# QyqForm 动态表单

> QyqForm 基于 Vue 3 与 Element Plus，通过字段配置构建查询和录入表单，提供接入示例、校验与重置说明、日期金额和自定义插槽用法。

原始页面：[QyqForm 动态表单](http://docs.quyongqing.cn/components/qyq-form.html)

## 说明

`QyqForm` 是基于 Vue 3 与 Element Plus 的动态表单组件，通过 `formOptions` 配置字段、通过 `v-model:modelValue` 绑定数据，适合后台查询筛选、客户录入和合同编辑。组件负责字段展示与校验，查询请求、保存接口和提交状态由调用方维护。

## 快速接入

当前组件通过仓库源码接入，尚未发布独立 npm 包。文档工程使用 Vue 3.5、Element Plus 2、`@element-plus/icons-vue` 和 dayjs；复制到其他项目时，需要保留整个 `src/components/qyq-form/` 目录与 `src/components/CardTitle.vue`，并注册 Element Plus、引入对应样式。下方示例假设 `@` 指向 `src`。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import QyqForm from '@/components/qyq-form/index.vue'
import type { FormItemProp } from '@/components/qyq-form/types'

const filters = ref({ keyword: '', status: '' })
const submittedFilters = ref({ ...filters.value })

const formOptions: FormItemProp[] = [
  { prop: 'keyword', label: '关键词', type: 'input', clearable: true },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '待处理', value: 'pending' },
      { label: '已完成', value: 'done' },
    ],
  },
]

function handleSearch() {
  // 可在这里使用 filters.value 请求列表接口，并处理加载与错误状态。
  submittedFilters.value = { ...filters.value }
}
</script>

<template>
  <QyqForm
    v-model:modelValue="filters"
    :form-options="formOptions"
    :columns="2"
    @search="handleSearch"
    @reset="handleSearch"
  />
  <pre>{{ submittedFilters }}</pre>
</template>
```

内置查询按钮先校验，通过后触发无参数的 `search` 事件，调用方从绑定的数据中读取条件。内置重置按钮重置后触发无参数的 `reset` 事件；上面的示例会在重置后同步查询条件。

## 适用场景与边界

| 场景 | 建议用法 |
| --- | --- |
| 列表查询 | 配置 `formOptions`，监听 `search` 与 `reset`，把条件传给 [QyqTable](http://docs.quyongqing.cn/components/qyq-table.html) 所在页面的数据请求 |
| 录入与编辑 | 使用 `required` 或 `rules`，在保存前调用 `validate()` |
| 特殊字段 | 使用 `type: 'custom'` 和以字段 `prop` 命名的插槽，自行绑定字段值 |
| 自定义操作区 | 使用 `elgsFormBtn` 插槽，并保持 `showBtn` 为 `true` |

该组件依赖 Element Plus 的表单行为。需要保留任意复杂布局或特殊业务流程时，可以用局部插槽或直接组合 Element Plus 表单项。

## 功能概览

查询筛选

适合列表页条件栏，支持列数、标签位置、查询重置与轻量搜索。

内置校验

支持 required、格式校验、自定义 rules 与暴露的验证方法。

日期金额

支持日期范围、快捷项、禁用日期、金额与金额区间格式化。

组合扩展

支持 selectInput、标题区 slot、按钮 slot、自定义字段 slot。

复杂录入

可组合 searchSelect、autocomplete、moneyrange 等能力构建产品级表单。

## 源码位置

`src/components/qyq-form/index.vue`

## 1\. 基础配置

这一段偏查询筛选场景，用来展示一行几列、标签位置、标签宽度、按钮位置、禁用态等基础能力。

**基础查询示例**

```vue
<script setup lang="ts">
import { ref } from 'vue'
import QyqForm from '@/components/qyq-form/index.vue'

const formData = ref({
  keyword: '',
  status: '',
  createdAt: [],
})

const formOptions = [
  { prop: 'keyword', label: '关键词', type: 'input', clearable: true },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '全部', value: '' },
      { label: '待处理', value: 'pending' },
      { label: '已完成', value: 'done' },
    ],
  },
  {
    prop: 'createdAt',
    label: '创建时间',
    type: 'daterange',
    dateValidateData: { isBefore: true, isShowShortcuts: true },
  },
]
</script>

<template>
  <QyqForm
    v-model:modelValue="formData"
    :form-options="formOptions"
    :columns="3"
    :show-btn="true"
    :form-label-info="{ labelPosition: 'top', labelWidth: '110px', showColon: false }"
    title="业务查询表单"
  />
</template>
```

前半部分文档都偏查询筛选场景，重点体现 `columns`、`formLabelInfo`、`showBtn`、`btnPosition` 和轻量检索能力。

## 2\. 内置校验

这一段偏录入编辑场景，重点展示 `required`、`rules`、文本格式校验以及组件暴露出来的校验方法。

**内置校验示例**

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { FormRules } from 'element-plus'
import QyqForm from '@/components/qyq-form/index.vue'

const formData = ref({
  customerName: '',
  phone: '',
  email: '',
})

const formOptions = [
  { prop: 'customerName', label: '客户名称', type: 'input', required: true },
  { prop: 'phone', label: '手机号', type: 'input' },
  { prop: 'email', label: '邮箱', type: 'input' },
]

const rules: FormRules = {
  phone: [
    { required: true, message: '请输入手机号', trigger: ['blur', 'change'] },
    {
      trigger: 'blur',
      validator: (_rule, value, callback) => {
        /^1\d{10}$/.test(String(value || ''))
          ? callback()
          : callback(new Error('请输入正确的手机号'))
      },
    },
  ],
}
</script>

<template>
  <QyqForm
    v-model:modelValue="formData"
    :form-options="formOptions"
    :rules="rules"
    :columns="2"
    title="客户录入校验"
  />
</template>
```

## 3\. 日期与金额逻辑

这一段专门展示组件的日期和金额封装能力，包括快捷时间、范围限制、禁用日期、金额自动格式化与金额区间；当前示例里，服务周期可选去年到明年，且起止最大跨度为 2 个月。

**日期与金额示例**

```vue
<script setup lang="ts">
import { ref } from 'vue'
import QyqForm from '@/components/qyq-form/index.vue'

const formData = ref({
  signDate: '',
  servicePeriod: [],
  budgetAmount: '',
  taxMin: '',
  taxMax: '',
})

const formOptions = [
  {
    prop: 'servicePeriod',
    label: '服务周期',
    type: 'daterange',
    required: true,
    dateValidateData: {
      isLimitRange: false,
      isBefore: false,
      validateType: 'months',
      validateNumber: 2,
      limitRangeArr: [
        { number: 1, type: 'year' },
        { number: 1, type: 'year' },
      ],
    },
    hint: {
      text: '可选去年到明年，且起止最大跨度为 2 个月。',
    },
  },
]
</script>

<template>
  <QyqForm
    v-model:modelValue="formData"
    :form-options="formOptions"
    :columns="2"
    title="日期与金额示例"
  />
</template>
```

## 4\. 组合输入与 Slot

这一段展示 `selectInput`、标题区插槽、字段提示插槽和按钮区扩展，同时也演示如何通过 `item.style` 让字段横跨多列布局。

**组合输入与 Slot 模板片段**

```vue
<template>
  <QyqForm
    v-model:modelValue="formData"
    :form-options="formOptions"
    :columns="2"
    title="组合输入与插槽"
  >
    <template #cardTitleInfo>
      <span>支持在标题右侧补充业务状态</span>
    </template>

    <template #addressTip>
      <span>此处可接地图选点或地址解析能力</span>
    </template>

    <template #previewAction>
      <el-button type="primary" plain>预览</el-button>
    </template>
  </QyqForm>
</template>
```

组合输入更适合“区号 + 电话”“币种 + 金额”这类高频业务字段；如果后面还有需要，依然可以继续通过 `item.style` 做 Grid 跨列布局。

## 5\. 综合复杂表单

这一段把查询和录入里常用的能力集中到一个正式业务案例里，采用“合同录入 / 编辑”场景，包含 `searchSelect`、`autocomplete`、日期、金额、组合输入、校验和自定义按钮。

**综合复杂表单模板片段**

```vue
<template>
  <QyqForm
    ref="formRef"
    v-model:modelValue="formData"
    :form-options="formOptions"
    :rules="rules"
    :columns="3"
    :show-btn="true"
    title="合同录入表单"
  >
    <template #elgsFormBtn>
      <el-button>取消</el-button>
      <el-button type="primary">保存草稿</el-button>
      <el-button type="success">提交审批</el-button>
    </template>
  </QyqForm>
</template>
```

## 6\. 暴露方法

`QyqForm` 暴露了常用的表单实例方法，适合在父组件里配合按钮、步骤条、抽屉页脚等外部操作一起使用。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `validate(callback?)` | `FormInstance["validate"]` | `-` | 触发整表校验；不传回调时使用 Promise，校验失败需要捕获拒绝。 |
| `resetFields(props?)` | `(string \| string[]) => void` | `-` | 重置整表或指定字段；普通字段恢复为表单项挂载时的初始值，复合字段见下方限制。 |
| `validateField(prop)` | `FormInstance["validateField"]` | `-` | 只校验指定字段，返回 Promise；校验失败需要捕获拒绝。 |
| `clearValidate(prop?)` | `(string \| string[]) => void` | `-` | 清理校验错误提示，适合回填数据、切换步骤或重置局部状态后调用。 |

**暴露方法示例**

```vue
<script setup lang="ts">
import { ref } from 'vue'
import QyqForm from '@/components/qyq-form/index.vue'

const formRef = ref<InstanceType<typeof QyqForm> | null>(null)
const formData = ref({ keyword: '', phone: '' })
const validationMessage = ref('')

const formOptions = [
  { prop: 'keyword', label: '关键词', type: 'input' },
  { prop: 'phone', label: '手机号', type: 'input', required: true },
]

async function handleValidate() {
  if (!formRef.value) return

  try {
    await formRef.value.validate()
    validationMessage.value = '校验通过'
  } catch {
    validationMessage.value = '请修正表单中的校验项'
  }
}

function handleResetKeyword() {
  formRef.value?.resetFields('keyword')
}

function handleClearPhoneError() {
  formRef.value?.clearValidate('phone')
}
</script>

<template>
  <QyqForm ref="formRef" v-model:modelValue="formData" :form-options="formOptions" />
  <button type="button" @click="handleValidate">校验</button>
  <button type="button" @click="handleResetKeyword">重置关键词</button>
  <button type="button" @click="handleClearPhoneError">清理手机号校验提示</button>
  <p role="status">{{ validationMessage }}</p>
</template>
```

## 参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | `object` | `{}` | 表单数据，使用 v-model:modelValue 绑定。 |
| `formOptions` | `array` | `[]` | 表单项配置。 |
| `rules` | `object` | `{}` | 表单校验规则。 |
| `formLabelInfo` | `object` | `{ labelPosition: 'top' }` | 标签位置、宽度、星号位置和冒号展示配置。 |
| `showBtn` | `boolean` | `true` | 是否显示查询和重置按钮。 |
| `btnPosition` | `string` | `'right'` | 默认按钮区域靠左或靠右。 |
| `columns` | `number` | `4` | 每行展示列数。 |
| `validateOnRuleChange` | `boolean` | `false` | 规则变更后是否立即触发表单校验。 |
| `disabled` | `boolean` | `false` | 是否禁用整张表单。 |
| `title` | `string` | `''` | 表单标题。 |
| `titleTip` | `string` | `''` | 标题右侧提示文案。 |
| `titleFontWeight` | `string \| number` | `'bold'` | 表单标题字重。 |
| `titleSize` | `number` | `16` | 表单标题字号。 |
| `selectOptions` | `object` | `{}` | 下拉选项映射，key 对应表单 prop。 |

## 常见问题

### 如何在保存前校验表单？

通过组件 `ref` 调用 `validate()`。不传回调时，校验通过返回成功结果，失败会拒绝 Promise；捕获校验失败后应停止保存。下面是保存按钮的处理片段，表单需已绑定 `ref="formRef"`：

```ts
async function handleSave() {
  if (!formRef.value) return

  try {
    await formRef.value.validate()
  } catch {
    return
  }

  // 在此调用保存接口，并单独处理接口失败。
}
```

`required: true` 用于声明必填，复杂规则通过 `rules` 传入。字段的 `prop`、数据对象的键和规则对象的键需要一致。

### 重置为什么没有把所有值清空？

普通字段沿用 Element Plus 的 `resetFields()` 行为，恢复为表单项挂载时记录的初始值。需要“清空为指定值”或“恢复最近一次接口回填”时，应由调用方设置数据，再调用 `clearValidate()` 清理提示。

复合字段另有配对值清理逻辑，当前对字段数组的处理与单字段不完全一致。重置金额区间或组合输入时，建议显式恢复两端的数据，不依赖 `resetFields(['字段一', '字段二'])` 自动同步配对值。直接调用 `resetFields()` 不会触发组件的 `reset` 事件，该事件由内置重置按钮触发。

### 为什么自定义按钮或字段没有显示？

按钮插槽 `elgsFormBtn` 位于 `showBtn` 控制的区域内，设置 `showBtn: false` 会连同插槽一起隐藏。自定义字段使用 `type: 'custom'`，插槽名要与 `formOptions` 中的 `prop` 一致，字段内部的 `v-model` 由调用方绑定。

### 输入内容可以包含空格吗？

普通文本输入默认去除首尾空格，并对输入中的空格进行校验。需要保留首尾空格时设置 `isNotTrim: true`；需要允许文本输入中的空格时设置 `allowSpecialChars: true`。两个配置分别控制输入修剪与校验，可按业务需要组合使用。

## 配置字典补充

-   `formOptions[].type`：当前文档已覆盖 `input`、`textarea`、`select`、`radioGroup`、`date`、`daterange`、`money`、`moneyrange`、`selectInput`、`searchSelect`、`autocomplete` 和自定义 slot。
-   `formOptions[].required`：适合快速声明必填；复杂格式校验建议配合 `rules` 使用。
-   `formOptions[].tip / hint`：适合补充字段说明、帮助文本和风险提示，既支持纯文本也支持 slot。
-   `formOptions[].propOption`：用于 `selectInput` 组合输入，适合区号 + 电话、币种 + 金额等复合场景。
-   `formOptions[].style`：会透传到字段容器上，适合做 `gridColumn`、`gridRow` 等跨列跨行布局。
-   `formLabelInfo`：统一控制标签布局，查询表单更常用 `top`，录入表单可根据字段密度切到 `left`。

---

# QyqTable 数据表格

> QyqTable 基于 Element Plus 展示后台列表数据，支持列配置、状态映射、斑马纹和分页，提供 Vue 3 使用示例与参数说明。

原始页面：[QyqTable 数据表格](http://docs.quyongqing.cn/components/qyq-table.html)

## 说明

用于列表数据展示的表格组件，适合组件清单、订单列表、配置列表等后台页面场景。

## 实时预览

当前文档页保留一组固定预览，直接展示常见表格列表样式。

如果业务场景需要分页、按钮列或更多操作，可以继续通过 \`columns\` 和外部数据请求逻辑扩展。

## 源码位置

`src/components/qyq-table/index.vue`

## 基本参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `data` | `array` | `[]` | 表格数据源。 |
| `columns` | `array` | `[]` | 列配置数组。 |
| `loading` | `boolean` | `false` | 加载状态。 |
| `border` | `boolean` | `false` | 是否显示边框。 |
| `stripe` | `boolean` | `false` | 是否显示斑马纹。 |
| `size` | `string` | `default` | 表格尺寸。 |
| `showPagination` | `boolean` | `true` | 是否显示分页。 |
| `currentPage` | `number` | `1` | 当前页码。 |
| `pageSize` | `number` | `10` | 每页条数。 |
| `total` | `number` | `0` | 总条数。 |

## 基本使用方法

```vue
<template>
  <QyqTable
    :data="rows"
    :columns="columns"
    :border="true"
    :stripe="true"
    :show-pagination="false"
  />
</template>

<script setup lang="ts">
import QyqTable from '@/components/qyq-table/index.vue'

const rows = [
  { id: 'cmp-001', name: 'Snow Effect', status: 1 },
  { id: 'cmp-002', name: 'Qyq Table', status: 1 },
]

const columns = [
  { prop: 'id', label: '组件编码' },
  { prop: 'name', label: '组件名称' },
  { prop: 'status', label: '状态', codeMap: { 0: '开发中', 1: '可用' } },
]
</script>
```

## 代码示例

**Qyq Table 基础示例**

```vue
<template>
  <QyqTable
    :data="rows"
    :columns="columns"
    :border="true"
    :stripe="true"
    :show-pagination="false"
  />
</template>

<script setup lang="ts">
import QyqTable from '@/components/qyq-table/index.vue'

const rows = [
  { id: 'cmp-001', name: 'Snow Effect', status: 1 },
  { id: 'cmp-002', name: 'Qyq Table', status: 1 },
]

const columns = [
  { prop: 'id', label: '组件编码' },
  { prop: 'name', label: '组件名称' },
  { prop: 'status', label: '状态', codeMap: { 0: '开发中', 1: '可用' } },
]
</script>
```

---

# ScrollAnimation 滚动翻转动画

> ScrollAnimation 使用 GSAP 与 ScrollTrigger 实现随滚动触发的 3D 分栏翻转动画，介绍视觉预览、滚动容器和源码接入方式。

原始页面：[ScrollAnimation 滚动翻转动画](http://docs.quyongqing.cn/components/scroll-animation.html)

## 说明

用于展示“随滚动触发的 3D 翻转分栏动画”，适合首页视觉区、品牌展示页、作品集封面或活动专题头图等偏氛围感场景。

## 实时预览

组件内部基于 `GSAP + ScrollTrigger` 实现，滚动时会先缩放，再依次翻转三个面板，最后恢复原始尺寸。

当前版本不提供外部参数，图片资源和动画节奏都写在组件内部，更适合固定视觉展示场景。

## 源码位置

`src/components/scroll-animation/ScrollAnimationSection.vue`

## 基本参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `无` | `-` | `-` | 当前版本为固定视觉动画组件，图片资源和滚动节奏均内置在组件内部。 |

## 使用说明

-   组件内部依赖 `gsap` 和 `gsap/ScrollTrigger`。
-   默认高度为 `200vh`，内部使用 `sticky + perspective` 构建滚动舞台。
-   当前会从本地图片资源中随机选两张图作为正反面贴图，每次刷新页面效果可能不同。
-   如果外层有自定义滚动容器，组件会优先尝试挂到最近的 `.terminal-effect-page-container`。

## 基本使用方法

```vue
<template>
  <section class="landing-section">
    <ScrollAnimationSection />
  </section>
</template>

<script setup lang="ts">
import ScrollAnimationSection from '@/components/scroll-animation/ScrollAnimationSection.vue'
</script>

<style scoped>
.landing-section {
  background: #000;
}
</style>
```

## 代码示例

**Scroll Animation 基础示例**

```vue
<template>
  <section class="landing-section">
    <ScrollAnimationSection />
  </section>
</template>

<script setup lang="ts">
import ScrollAnimationSection from '@/components/scroll-animation/ScrollAnimationSection.vue'
</script>

<style scoped>
.landing-section {
  background: #000;
}
</style>
```

---

# SnowEffect 雪花背景特效

> 使用 SnowEffect 为 Vue 3 首页横幅、活动专题与节日页面添加 Canvas 雪花背景，了解容器尺寸、定位要求和接入示例。

原始页面：[SnowEffect 雪花背景特效](http://docs.quyongqing.cn/components/snow-effect.html)

## 说明

用于页面氛围装饰的雪花特效组件，适合放在首页横幅、活动专题头图或节日场景背景中。

## 实时预览

当前组件不提供配置项，直接作为背景特效使用即可。

由于内部是绝对定位的 canvas，外层容器建议设置明确高度，并保持相对定位。

## 源码位置

`src/components/snow-effect/index.vue`

## 基本参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `无` | `-` | `-` | 当前版本为纯展示特效组件，直接使用即可。 |

## 基本使用方法

```vue
<template>
  <div class="hero-banner">
    <SnowEffect />
    <div class="hero-banner__content">
      <h2>Snow Effect</h2>
      <p>用于页面顶部或活动区域的雪花背景。</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import SnowEffect from '@/components/snow-effect/index.vue'
</script>

<style scoped>
.hero-banner {
  position: relative;
  min-height: 280px;
  overflow: hidden;
  border-radius: 16px;
  background: linear-gradient(180deg, #0f172a 0%, #1e293b 100%);
}

.hero-banner__content {
  position: relative;
  z-index: 2;
  display: grid;
  place-content: center;
  min-height: 280px;
  color: #fff;
  text-align: center;
}
</style>
```

## 代码示例

**Snow Effect 基础示例**

```vue
<template>
  <div class="hero-banner">
    <SnowEffect />
    <div class="hero-banner__content">
      <h2>Snow Effect</h2>
      <p>用于首页氛围装饰的雪花特效。</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import SnowEffect from '@/components/snow-effect/index.vue'
</script>

<style scoped>
.hero-banner {
  position: relative;
  min-height: 280px;
  overflow: hidden;
  border-radius: 16px;
  background: linear-gradient(180deg, #0f172a 0%, #1e293b 100%);
}

.hero-banner__content {
  position: relative;
  z-index: 2;
  display: grid;
  place-content: center;
  min-height: 280px;
  color: #fff;
  text-align: center;
}
</style>
```

---

# 项目专题

> 浏览 Ollama Chat App、Qyq Chat AI 和 Ollama Node，了解 Vue 3 聊天前端、业务后台与 Node.js 多模型服务的技术方案和功能边界。

原始页面：[项目专题](http://docs.quyongqing.cn/projects/)

这里整理 AI 对话产品的前端、业务后台与后端服务实践。各专题介绍项目定位、核心能力、技术方案和当前限制。

## 按项目选择

| 项目 | 定位 | 重点内容 |
| --- | --- | --- |
| [Ollama Chat App](http://docs.quyongqing.cn/projects/ollama-chat-app.html) | AI 对话与业务后台 | Vue 3 页面组合、用户权限、表单表格和文件处理 |
| [Qyq Chat AI](http://docs.quyongqing.cn/projects/qyq-chat-ai.html) | 多模型聊天前端 | 会话与模型联动、流式消息、图文上下文和聊天交互 |
| [Ollama Node](http://docs.quyongqing.cn/projects/ollama-node.html) | AI 对话后端服务 | 模型协议适配、SSE 事件、会话鉴权与文件处理 |

## 从开发问题开始

-   构建带表单、表格与权限的 AI 业务后台：查看 [Ollama Chat App](http://docs.quyongqing.cn/projects/ollama-chat-app.html)。
-   处理多会话切换和流式输出：查看 [Qyq Chat AI](http://docs.quyongqing.cn/projects/qyq-chat-ai.html)。
-   对接不同模型并统一后端事件：查看 [Ollama Node](http://docs.quyongqing.cn/projects/ollama-node.html)。

## 可复用组件

后台的查询筛选与录入可以参考 [QyqForm 动态表单](http://docs.quyongqing.cn/components/qyq-form.html)，列表展示可以参考 [QyqTable 数据表格](http://docs.quyongqing.cn/components/qyq-table.html)。无法获取真实进度的长耗时任务可以参考 [EstimatedProgressBar 预计进度条](http://docs.quyongqing.cn/components/estimated-progress-bar.html)。

---

# Ollama Chat App

> Ollama Chat App 将 AI 对话、用户权限、表单表格与文件处理整合到 Vue 3 前端工程，介绍核心功能、组件复用和技术边界。

原始页面：[Ollama Chat App](http://docs.quyongqing.cn/projects/ollama-chat-app.html)

`ollama-chat-app` 是一个基于 Vue 3 + TypeScript 构建的 AI 对话与后台业务融合项目，目标不是单纯的演示页，而是更接近正式产品形态的前端应用。

## 项目定位

-   面向 AI 对话与业务场景结合的中后台产品
-   在统一项目中承载对话、权限、表单、表格、文件处理等常见能力
-   兼顾页面体验、组件沉淀和后续业务扩展

## 核心能力

-   AI 对话：提供对话页面、消息交互和基础会话体验
-   用户系统：包含手机号密码登录、手机号验证码登录、注册、用户信息、角色菜单和权限相关页面
-   业务页面：覆盖数据概览、任务计划、系统管理、表单表格组合等场景
-   文件能力：支持文件上传、预览以及 `docx` 预览组件
-   复用组件：沉淀了 `qyq-form`、`qyq-table`、背景轮播、雪花特效等组件
-   交互能力：登录注册流程接入滑动验证码校验，并引入 DataV 与 GSAP 增强大屏展示和页面动效

## 技术栈

-   Vue 3
-   TypeScript
-   Vite
-   Element Plus
-   Pinia
-   Vue Router
-   Axios
-   DataV
-   GSAP
-   Supabase SDK

## 适合承载的场景

-   AI 助手或多模型对话前台
-   带用户体系的业务后台
-   需要沉淀通用组件能力的中小型产品
-   后续持续扩展页面和模块的正式项目

## 技术亮点

### 1\. AI 对话与业务后台放在同一项目中

-   不是单纯的聊天演示页，而是把 AI 对话、用户体系、后台页面和业务组件放在统一前端工程里
-   这种结构更适合长期演进，也更接近正式产品项目

### 2\. 通用业务组件沉淀比较完整

-   已经沉淀了 `qyq-form`、`qyq-table`、文件上传预览、背景轮播、雪花动效等组件
-   这些组件既能支撑业务页面，也能继续抽离成独立文档能力

### 3\. 页面类型覆盖比较全

-   不只是聊天页，还包含数据概览、任务计划、系统管理、表单表格组合等页面
-   说明项目已经具备比较完整的业务壳层能力

### 4\. 用户体系与菜单权限已接入前端

-   登录、用户信息、角色菜单、待办事项等能力已经和页面结构打通
-   对外看是一个聊天项目，对内其实已经具备中后台产品基础

### 5\. 登录注册流程接入了验证码校验

-   登录页支持手机号 + 密码、手机号 + 验证码两种登录方式
-   注册流程接入短信验证码发送与校验，提升账户注册和登录链路的完整度
-   验证码发送前增加滑动验证码校验，用于拦截批量请求和异常触发

### 6\. 引入 DataV 和 GSAP 增强展示与动效

-   DataV 主要用于数据分析大屏相关的装饰边框、视觉组件和大屏氛围构建
-   GSAP 主要用于页面动效、滚动展示和交互过渡，增强首页和特效区域的表现力

## 技术难点

### 1\. 项目边界比较宽

-   一个前端工程里同时放聊天、后台、组件、文件处理和交互效果，结构上更容易变复杂
-   如果后续不持续做模块边界控制，维护成本会逐步上升

### 2\. 多种页面范式共存

-   聊天页、后台页、表单页、组件演示页本质上是不同类型的页面
-   想同时保持体验统一和代码复用，需要持续做组件抽象和布局收敛

### 3\. 组件沉淀与业务开发需要平衡

-   组件抽得太早，容易过度设计
-   只做业务不沉淀，又会导致复用能力不足
-   这类项目真正难的地方，是在复用和交付之间找到合适平衡

## 项目特点

-   AI 对话与业务后台融合
-   通用业务组件沉淀
-   用户体系与菜单权限
-   滑动验证码与短信验证码登录注册流程
-   聊天、表单、表格、文件能力一体化

## 扩展方向

-   多模型能力继续增强
-   后台模块继续补充
-   组件体系继续抽离和沉淀
-   文件处理与预览能力继续扩展

## 项目地址

[http://quyongqing.cn/](http://quyongqing.cn/)

---

# Ollama Node

> Ollama Node 提供 Node.js AI 对话后端，介绍多模型协议适配、SSE 统一事件、会话鉴权、文件处理与业务接口。

原始页面：[Ollama Node](http://docs.quyongqing.cn/projects/ollama-node.html)

`ollama-node` 是一个 Node.js 后端项目，主要负责 AI 对话服务接入、模型分发、用户鉴权、文件处理和后台业务接口输出。

## 项目定位

-   面向 AI 对话产品的后端服务
-   承载模型调用、接口聚合和业务数据管理
-   作为前端聊天项目和后台系统的服务支撑层

## 核心能力

-   模型能力：支持本地 Ollama、OpenAI 兼容协议、Gemini 等模型接入与分发
-   对话能力：提供聊天、会话、模型、RAG 相关接口
-   用户能力：提供登录、注册、权限、角色和菜单等后台常见接口
-   文件能力：支持文件记录、对象存储和图片处理相关能力

## 技术栈

-   Node.js
-   Express
-   MongoDB
-   Mongoose
-   JWT
-   Axios

## 适合承载的场景

-   AI 对话后端
-   多模型统一接入层
-   带权限体系的业务 API 服务
-   聊天前端配套服务端项目

## 技术亮点

### 1\. 大模型分发层做了清晰解耦

-   模型能力不是写死在接口里，而是拆成“注册表 + 解析器 + 分发器 + handler”
-   新增模型时，通常只需要补模型注册信息和对应 handler
-   文本模型、图像模型、视频模型走的是统一入口，但内部执行链路彼此独立

### 2\. 同时兼容多种模型协议

-   本地 Ollama 走本地服务协议
-   OpenAI、DeepSeek、部分 Gemini 能力走 OpenAI 兼容协议
-   Gemini 原生思考链和图像能力又单独走原生协议处理
-   这意味着后端不是简单代理，而是做了一层真正的协议适配

### 3\. 图文上下文做了模型感知处理

-   不是所有模型都直接接收同一份消息结构
-   服务端会先判断当前模型是否支持 vision
-   对支持视觉的模型，再把 Markdown 图片转换成不同协议需要的结构
-   对不支持视觉的模型，会在入口阶段直接拦掉图片上下文，避免无效请求

### 4\. SSE 输出做了统一事件协议

-   服务端没有把不同模型的流直接原样透传给前端
-   而是统一整理成 `content`、`reasoning`、`progress`、`image`、`loading`、`error`、`done` 等事件
-   这样前端只需要认这一套协议，就能兼容多模型流式输出

### 5\. 对话、会话、权限是完整串起来的

-   聊天请求会先校验当前会话是否属于当前用户
-   会话和消息分别落表，便于历史记录和后续扩展
-   菜单、角色、管理员初始化也做了单独接口，具备中后台系统基础能力

### 6\. 图片结果做了对象存储归一化

-   模型返回的图片结果不会长期以内联 base64 方式保留
-   服务端会把结果上传到对象存储，再回写成可访问地址
-   这样更适合历史消息存储和前端渲染

## 技术难点

### 1\. 模型协议差异非常大

-   同样是“聊天接口”，不同模型返回的数据结构、流式格式、图像输入方式都不同
-   后端现在已经做了统一收口，但这块仍然是维护成本最高的区域之一

### 2\. 图文上下文需要按模型动态转换

-   OpenAI 兼容协议和 Gemini 原生协议对图片输入格式完全不同
-   有的模型吃 `image_url`
-   有的模型需要把远程图片先下载，再转成 base64 再发送
-   这部分不是普通 CRUD 代码，技术含量比较高

### 3\. 流式输出不只是“把文本吐出去”

-   不同模型的流式事件边界并不统一
-   有的返回文本增量
-   有的返回思考链
-   有的还带图片和进度事件
-   要统一成前端能稳定消费的 SSE 协议，服务端做了额外的解析和重组

### 4\. 鉴权和权限只是基础版完整，不是最终形态

-   当前 JWT、角色、菜单、管理员初始化这条链路已经可用
-   但如果继续往更复杂的企业权限体系演进，还会涉及按钮级权限、资源级权限和更细粒度的 RBAC/ABAC

## 项目特点

-   多模型统一接入与分发
-   OpenAI 兼容协议与本地 Ollama 并行支持
-   图文上下文按模型能力动态转换
-   SSE 统一事件协议
-   会话、消息、权限、菜单一体化后端能力

## 扩展方向

-   短信验证码登录
-   模型注册表扩展
-   图片生成与图片处理链路
-   RAG 相关接口接入

---

# Qyq Chat AI

> Qyq Chat AI 是 Vue 3 多模型聊天前端，介绍会话与模型联动、SSE 流式消息、图文上下文及当前功能限制。

原始页面：[Qyq Chat AI](http://docs.quyongqing.cn/projects/qyq-chat-ai.html)

`qyq-chat-ai` 是一个面向 AI 对话场景的前端项目，重点提供企业风格的聊天界面、模型选择、会话管理和用户交互体验。

## 项目定位

-   面向 AI 对话产品的前端应用
-   强调聊天体验、界面一致性和交互效率
-   适合作为多模型对话产品的前端壳层

## 核心能力

-   对话能力：支持聊天页、流式消息展示和会话切换
-   模型能力：支持模型选择、RAG 选择和文件选择等对话辅助能力
-   用户能力：包含登录弹窗、用户资料、头像下拉等常见账户功能
-   布局能力：包含侧边栏、顶部栏和聊天主区域的完整页面结构

## 技术栈

-   Vue 3
-   TypeScript
-   Vite
-   Element Plus
-   Pinia
-   Vue Router
-   Axios
-   UnoCSS

## 适合承载的场景

-   AI 对话前端
-   多模型聊天产品
-   企业内部 AI 助手界面
-   需要快速落地的聊天类项目

## 技术亮点

### 1\. 会话与模型联动

-   模型选择不是单独的 UI 状态，而是和当前会话绑定
-   切换会话时会自动同步当前会话模型，避免出现“界面显示一个模型、请求实际发到另一个模型”的错位
-   模型列表同时兼容文本、图像、视频等分类，后续扩模型时不需要推翻现有结构

### 2\. 流式输出做了协议兼容

-   前端不是只吃一种固定格式的 SSE，而是兼容普通文本流、OpenAI 风格 `delta`、进度事件和思考链事件
-   流式过程中把 `content`、`reasoning`、`progress` 等信息拆开处理，便于前端分别展示
-   输出阶段先插入 AI 空消息，再逐块追加内容，页面体验更稳定

### 3\. 图文上下文统一走 Markdown

-   图片不是作为特殊页面结构硬编码，而是先上传，再转成 Markdown 图片链接拼进上下文
-   文本消息、图片消息、历史回显共用一套 Markdown 渲染链路
-   这种做法代码量更小，也方便和后端统一协议

### 4\. 聊天页拆成默认页和详情页

-   默认页负责“先输入内容”
-   详情页负责“进入具体会话后真正发起流式请求”
-   这让新建会话和已有会话继续聊天分开处理，逻辑更清晰

### 5\. 布局与交互偏产品化

-   侧边栏、顶部栏、主聊天区做了清晰拆分
-   支持会话分组、会话切换、模型标签展示、快捷键新建对话
-   响应式折叠和宽度监听也单独抽成了 hook，便于后续扩展

## 技术难点

### 1\. 短信登录目前只完成协议预留

-   接口类型里已经预留了验证码登录和发送验证码能力
-   当前前端真正落地的是“手机号 + 密码登录”
-   如果后面补短信登录，还需要补发送验证码、倒计时、登录方式切换和异常提示这整套交互

### 2\. 流式协议不统一

-   不同模型、不同后端返回的流式事件格式并不一致
-   前端现在已经做了较多兼容分支，这部分是能体现技术能力的点，但后续维护成本也高

### 3\. 图文上下文目前偏务实方案

-   当前实现是“图片上传后转 Markdown 链接，再作为上下文发给后端”
-   这种方式简单有效，但还不是真正的多模态消息结构
-   如果后面后端统一升级成 `messages[].content[]` 这类结构，这里需要再做一轮重构

### 4\. 草稿跨页依赖本地存储

-   默认页和详情页之间的草稿传递依赖 `localStorage`
-   文本草稿链路比较直接
-   文件草稿和跨页恢复相对复杂，后续如果继续增强，需要重点看一致性

## 项目特点

-   多模型切换与会话绑定
-   图文上下文统一处理
-   SSE 流式输出兼容多协议
-   聊天页默认态与详情态拆分
-   产品化布局与响应式交互

## 扩展方向

-   短信验证码登录能力

## 项目地址

[http://chat.quyongqing.cn/](http://chat.quyongqing.cn/)