502 lines
11 KiB
Markdown
502 lines
11 KiB
Markdown
# 学业邑规划 - 组件文档
|
||
|
||
本文档定义了小程序中需要开发的公共组件和业务组件。
|
||
|
||
---
|
||
|
||
## 一、组件分类
|
||
|
||
```
|
||
components/
|
||
├── common/ # 通用组件（与业务无关）
|
||
├── business/ # 业务组件（与业务相关）
|
||
└── layout/ # 布局组件
|
||
```
|
||
|
||
---
|
||
|
||
## 二、通用组件
|
||
|
||
### 2.1 AppButton 按钮
|
||
|
||
**文件**：`components/common/AppButton.vue`
|
||
|
||
**功能**：统一的按钮组件，支持多种样式和状态
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| type | string | 'primary' | 按钮类型：primary / secondary / text |
|
||
| size | string | 'medium' | 按钮大小：small / medium / large |
|
||
| disabled | boolean | false | 是否禁用 |
|
||
| loading | boolean | false | 是否加载中 |
|
||
| block | boolean | false | 是否块级按钮 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppButton type="primary" @click="handleSubmit">提交</AppButton>
|
||
<AppButton type="secondary" size="small">取消</AppButton>
|
||
<AppButton :disabled="!isValid" :loading="submitting">
|
||
支付￥99元 开始测评
|
||
</AppButton>
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 AppModal 弹窗
|
||
|
||
**文件**：`components/common/AppModal.vue`
|
||
|
||
**功能**：统一的弹窗组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| visible | boolean | false | 是否显示 |
|
||
| title | string | '' | 标题 |
|
||
| showClose | boolean | true | 是否显示关闭按钮 |
|
||
| maskClosable | boolean | true | 点击遮罩是否关闭 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| update:visible | boolean | 显示状态变化 |
|
||
| close | - | 关闭事件 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppModal v-model:visible="showModal" title="提示">
|
||
<text>确定要退出登录吗？</text>
|
||
<template #footer>
|
||
<AppButton type="secondary" @click="showModal = false">取消</AppButton>
|
||
<AppButton type="primary" @click="handleConfirm">确定</AppButton>
|
||
</template>
|
||
</AppModal>
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 AppEmpty 空状态
|
||
|
||
**文件**：`components/common/AppEmpty.vue`
|
||
|
||
**功能**：列表为空时的占位组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| image | string | 默认图片 | 空状态图片 |
|
||
| text | string | '暂无数据' | 提示文字 |
|
||
| showButton | boolean | false | 是否显示按钮 |
|
||
| buttonText | string | '' | 按钮文字 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppEmpty text="暂无订单" />
|
||
<AppEmpty
|
||
text="暂无测评记录"
|
||
:showButton="true"
|
||
buttonText="去测评"
|
||
@click="goAssessment"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 2.4 AppLoading 加载
|
||
|
||
**文件**：`components/common/AppLoading.vue`
|
||
|
||
**功能**：加载状态组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| loading | boolean | false | 是否加载中 |
|
||
| text | string | '加载中...' | 加载文字 |
|
||
| fullscreen | boolean | false | 是否全屏 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppLoading :loading="isLoading" />
|
||
<AppLoading :loading="isLoading" text="报告生成中..." :fullscreen="true" />
|
||
```
|
||
|
||
---
|
||
|
||
### 2.5 AppNavbar 导航栏
|
||
|
||
**文件**：`components/common/AppNavbar.vue`
|
||
|
||
**功能**：自定义导航栏（用于 navigationStyle: custom 的页面）
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| title | string | '' | 标题 |
|
||
| showBack | boolean | true | 是否显示返回按钮 |
|
||
| showHome | boolean | false | 是否显示首页按钮 |
|
||
| bgColor | string | '#fff' | 背景色 |
|
||
| textColor | string | '#333' | 文字颜色 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppNavbar title="测评结果" :showBack="true" />
|
||
<AppNavbar title="首页" :showBack="false" bgColor="transparent" textColor="#fff" />
|
||
```
|
||
|
||
---
|
||
|
||
### 2.6 AppInput 输入框
|
||
|
||
**文件**：`components/common/AppInput.vue`
|
||
|
||
**功能**：统一的输入框组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| modelValue | string | '' | 输入值 |
|
||
| type | string | 'text' | 输入类型 |
|
||
| placeholder | string | '' | 占位文字 |
|
||
| disabled | boolean | false | 是否禁用 |
|
||
| maxlength | number | -1 | 最大长度 |
|
||
| error | string | '' | 错误提示 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppInput
|
||
v-model="form.name"
|
||
placeholder="请输入姓名"
|
||
:error="errors.name"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 2.7 AppPicker 选择器
|
||
|
||
**文件**：`components/common/AppPicker.vue`
|
||
|
||
**功能**：统一的选择器组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| modelValue | any | null | 选中值 |
|
||
| options | array | [] | 选项列表 |
|
||
| placeholder | string | '请选择' | 占位文字 |
|
||
| labelKey | string | 'label' | 显示字段 |
|
||
| valueKey | string | 'value' | 值字段 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppPicker
|
||
v-model="form.age"
|
||
:options="ageOptions"
|
||
placeholder="请选择年龄"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 2.8 AppRegionPicker 地区选择器
|
||
|
||
**文件**：`components/common/AppRegionPicker.vue`
|
||
|
||
**功能**：省市区三级联动选择器
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| province | string | '' | 省份 |
|
||
| city | string | '' | 城市 |
|
||
| district | string | '' | 区县 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| change | { province, city, district } | 选择变化 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AppRegionPicker
|
||
:province="form.province"
|
||
:city="form.city"
|
||
:district="form.district"
|
||
@change="handleRegionChange"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
## 三、业务组件
|
||
|
||
### 3.1 UserAvatar 用户头像
|
||
|
||
**文件**：`components/business/UserAvatar.vue`
|
||
|
||
**功能**：用户头像展示组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| src | string | '' | 头像地址 |
|
||
| size | string | 'medium' | 大小：small / medium / large |
|
||
| showLevel | boolean | false | 是否显示等级标识 |
|
||
| level | number | 1 | 用户等级 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<UserAvatar :src="userInfo.avatar" size="large" />
|
||
<UserAvatar :src="userInfo.avatar" :showLevel="true" :level="userInfo.userLevel" />
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 OrderCard 订单卡片
|
||
|
||
**文件**：`components/business/OrderCard.vue`
|
||
|
||
**功能**：订单列表项组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| order | OrderItem | required | 订单数据 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| action | { type, order } | 操作按钮点击 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<OrderCard
|
||
v-for="order in orderList"
|
||
:key="order.id"
|
||
:order="order"
|
||
@action="handleOrderAction"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 AssessmentCard 测评入口卡片
|
||
|
||
**文件**：`components/business/AssessmentCard.vue`
|
||
|
||
**功能**：首页测评入口组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| assessment | AssessmentType | required | 测评类型数据 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| click | AssessmentType | 点击事件 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<AssessmentCard
|
||
v-for="item in assessmentList"
|
||
:key="item.id"
|
||
:assessment="item"
|
||
@click="handleAssessmentClick"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 PlannerCard 规划师卡片
|
||
|
||
**文件**：`components/business/PlannerCard.vue`
|
||
|
||
**功能**：规划师列表项组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| planner | PlannerInfo | required | 规划师数据 |
|
||
| selected | boolean | false | 是否选中 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| select | PlannerInfo | 选择事件 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<PlannerCard
|
||
v-for="planner in plannerList"
|
||
:key="planner.id"
|
||
:planner="planner"
|
||
:selected="selectedId === planner.id"
|
||
@select="handleSelect"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 QuestionItem 题目组件
|
||
|
||
**文件**：`components/business/QuestionItem.vue`
|
||
|
||
**功能**：测评答题页的题目组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| question | Question | required | 题目数据 |
|
||
| answer | number | null | 当前答案 |
|
||
| index | number | required | 题目序号 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| change | { questionId, value } | 答案变化 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<QuestionItem
|
||
v-for="(question, index) in questionList"
|
||
:key="question.id"
|
||
:question="question"
|
||
:answer="answers[question.id]"
|
||
:index="index"
|
||
@change="handleAnswerChange"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 InviteRecord 邀请记录项
|
||
|
||
**文件**：`components/business/InviteRecord.vue`
|
||
|
||
**功能**：邀请记录列表项组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| record | InviteRecord | required | 邀请记录数据 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<InviteRecord
|
||
v-for="record in recordList"
|
||
:key="record.id"
|
||
:record="record"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 WithdrawRecord 提现记录项
|
||
|
||
**文件**：`components/business/WithdrawRecord.vue`
|
||
|
||
**功能**：提现记录列表项组件
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| record | WithdrawRecord | required | 提现记录数据 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<WithdrawRecord
|
||
v-for="record in withdrawList"
|
||
:key="record.id"
|
||
:record="record"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
## 四、布局组件
|
||
|
||
### 4.1 PageContainer 页面容器
|
||
|
||
**文件**：`components/layout/PageContainer.vue`
|
||
|
||
**功能**：统一的页面容器，处理安全区域
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| safeBottom | boolean | true | 是否适配底部安全区域 |
|
||
| bgColor | string | '#f5f5f5' | 背景色 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<PageContainer>
|
||
<!-- 页面内容 -->
|
||
</PageContainer>
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 ListContainer 列表容器
|
||
|
||
**文件**：`components/layout/ListContainer.vue`
|
||
|
||
**功能**：带下拉刷新和上拉加载的列表容器
|
||
|
||
**Props**：
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| loading | boolean | false | 是否加载中 |
|
||
| finished | boolean | false | 是否加载完成 |
|
||
| emptyText | string | '暂无数据' | 空状态文字 |
|
||
|
||
**Emits**：
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| refresh | - | 下拉刷新 |
|
||
| loadMore | - | 上拉加载 |
|
||
|
||
**使用示例**：
|
||
```vue
|
||
<ListContainer
|
||
:loading="loading"
|
||
:finished="finished"
|
||
@refresh="handleRefresh"
|
||
@loadMore="handleLoadMore"
|
||
>
|
||
<OrderCard v-for="order in orderList" :key="order.id" :order="order" />
|
||
</ListContainer>
|
||
```
|
||
|
||
---
|
||
|
||
## 五、组件开发规范
|
||
|
||
### 5.1 组件命名
|
||
|
||
- 通用组件以 `App` 开头：`AppButton`, `AppModal`
|
||
- 业务组件使用业务名词：`UserAvatar`, `OrderCard`
|
||
- 布局组件以 `Container` 结尾：`PageContainer`, `ListContainer`
|
||
|
||
### 5.2 Props 规范
|
||
|
||
- 使用 TypeScript 接口定义
|
||
- 必填属性标注 `required`
|
||
- 提供合理的默认值
|
||
- 添加 JSDoc 注释
|
||
|
||
### 5.3 样式规范
|
||
|
||
- 使用 BEM 命名
|
||
- 使用 `scoped` 限制作用域
|
||
- 引用全局变量
|
||
- 避免使用 `!important`
|
||
|
||
### 5.4 事件规范
|
||
|
||
- 使用 `emit` 定义类型
|
||
- 事件名使用 kebab-case
|
||
- 提供完整的事件参数类型
|