266 lines
8.3 KiB
Markdown
266 lines
8.3 KiB
Markdown
# 建页操作模板
|
||
|
||
这份文档用于活动页创建和后续迭代时对齐规则。页面目录里的 `页面创建信息.md` 是当前页面的需求源；通用规则变更先更新 `docs/活动页/建页/`，再同步到页面目录文档和 Vue 代码。
|
||
|
||
## 1. 推荐流程
|
||
|
||
第一次只需要告诉页面名和创建位置，例如：
|
||
|
||
```text
|
||
新建活动页：WorldCup
|
||
创建位置：src/views/Activities/WorldCup
|
||
```
|
||
|
||
Codex 会先做准备阶段：
|
||
|
||
```text
|
||
1. 创建页面目录。
|
||
2. 在页面目录中创建 页面创建信息.md。
|
||
3. 根据 页面创建信息.md 创建 page.config.js 初始配置。
|
||
4. 按需要创建本地 OSS 图片目录。
|
||
5. 写入 route path、security 白名单和 permissionManager 页面列表。
|
||
6. 预填 route、OSS、图片清单、预加载和模块配置。
|
||
7. 不生成 index.vue，除非用户明确要求继续创建页面。
|
||
```
|
||
|
||
专属页面信息 md 优先放在页面目录里：
|
||
|
||
```text
|
||
src/views/Activities/WorldCup/页面创建信息.md
|
||
```
|
||
|
||
后续用户逐步补充模块时，先同步页面 md，再同步 Vue；如果用户明确说“按当前 Vue 同步到 md”，则以 Vue 当前实现为准反向更新 md。
|
||
|
||
## 2. 通用建页规则
|
||
|
||
- 没填的字段，初版页面先不猜。
|
||
- `页面创建信息.md` 是 `page.config.js` 和 `index.vue` 的生成来源；后续补需求先改 md，再同步代码。
|
||
- 每轮可以指定同步方向：`md -> vue` 或 `vue -> md`；方向不明确且两边冲突时，先确认再改。
|
||
- 新建页面只要生成 `index.vue`，都必须带统一加载动画：先展示 `LoadingContent`，关键图片预加载完成后再展示正式页面；loading 只针对图片，不等待业务接口。
|
||
- 页面只要使用接口，就必须引入 `connectToApp` 并先完成 App 连接；初始化接口统一放在 `connectToApp(() => { loadInitialPageData() })` 成功回调后执行，确保请求头已设置。图片预加载方法和接口初始化方法必须分离。
|
||
- 页面根容器推荐固定 `height: 100vh`、`overflow: hidden`，内部主内容容器负责 `overflow-y: auto` 垂直滚动并隐藏滚动条。
|
||
- 页面任何模块都不要出现可见滚动条。
|
||
- 页面模块布局可以使用 flex column，模块间距按需求设置，常见活动页默认可用 `gap: 2vw`。
|
||
- 能用内联样式直接表达的固定布局、尺寸、间距、定位，优先使用内联样式，方便实时调位置。
|
||
- 可复用样式、伪类、媒体查询、RTL 规则和复杂状态样式可以写 class。
|
||
- 动态选中态、显隐和尺寸变化可以使用方法返回内联 style 字符串；如果复用明显，再抽 class。
|
||
- 普通业务模块一般不要提前设置 `min-height` 和 `line-height`；`min-height` 只在基础页面容器（如 `.full-page` / `.fullPage`）中按需使用，`itemCenter` 的 `min-height` 只在页面开发完成后确实需要稳定图片容器高度时再补；补充时同步设置接近的 `max-height`，默认可按 `max-height = min-height + 1vw`，例如 `min-height: 21vw; max-height: 22vw`。
|
||
- `itemCenter` 承载大背景图时，宽度优先写 `100vw`，父级从上往下 flex 排列。
|
||
- `v-smart-img` 只用于项目自身静态图片，例如通过 `src/config/imagePaths.js` 中 `getPngUrl`、`getWebpUrl` 等方法，或活动页 `imageUrl`、`webpUrl` 等封装得到的图片地址。
|
||
- 接口返回的远程图片链接不要使用 `v-smart-img`，直接用原生 `<img :src="接口字段">` 展示，不走本地图片缓存或智能图片指令。
|
||
- 页面展示字号默认使用 `font-size: 1em`，跟随页面响应式基础字号变化。
|
||
- 页面后续更新模块、接口或方法时，新增或调整的方法和关键模块逻辑都要添加简短中文注释。
|
||
- 模板里的主要 `div`、`section`、`itemCenter` 等结构模块也要补中文注释，说明当前块负责的视觉区域或业务含义。
|
||
- 对接 POST 接口时，如果接口没有业务参数，也必须传空对象 `{}`，不要省略 body。
|
||
- 多 tab 或多分类列表不要共用同一个承载数组；每个 tab 使用独立数据源，避免接口慢返回或快速切换时数据混用。
|
||
- 多 tab 列表请求建议使用每个 tab 独立的请求序号或 token，只忽略同 tab 内更旧的响应，不影响其他 tab 的缓存。
|
||
- 多 tab 列表如果内部有大量固定图片、`itemCenter` 背景图或本地 OSS 图标，tab 内容容器优先使用 `v-show` 保留 DOM，避免每次切换时因 `v-if` 销毁重建导致固定图片反复加载；接口仍可在切换时重新请求最新数据。
|
||
- 弹窗统一使用公共组件 `src/components/MaskLayer.vue`。规则、奖励、历史、结果等弹窗内容放在 `MaskLayer` 默认插槽内；需要点击空白关闭时，在插槽内包一层全屏容器并使用 `@click.self` 关闭。
|
||
|
||
## 3. 页面信息 md 模板
|
||
|
||
````md
|
||
# 页面创建信息
|
||
|
||
## 0. 建页规则关联
|
||
|
||
- 页面改动、模块补充、接口对接、样式同步和文档同步，都需要先联系 `docs/活动页/建页/` 下的建页规则执行。
|
||
- 如果建页规则变化，先更新 `docs/活动页/建页/` 下的建页 md，再同步当前页面的 `页面创建信息.md` 和 Vue 代码。
|
||
|
||
## 1. 基础信息
|
||
|
||
- 页面类型：Activities / Ranking
|
||
- 页面名称：
|
||
- 页面目录：
|
||
- 页面入口：
|
||
- 页面配置：
|
||
- 专用接口：
|
||
- 参考页面：
|
||
- 备注：
|
||
|
||
## 2. 路由和权限
|
||
|
||
- route path：
|
||
- route name：
|
||
- 是否需要登录：是 / 否
|
||
- 是否加入 `src/config/security.js`：是 / 否
|
||
- 是否加入 `src/utils/permissionManager.js`：是 / 否
|
||
|
||
### 2.1 路由代码片段
|
||
|
||
```js
|
||
// 由 Codex 按 route path、route name 和页面目录生成
|
||
```
|
||
|
||
## 3. OSS 图片目录
|
||
|
||
- OSS 相对路径：
|
||
- 本地开发目录：
|
||
- 是否需要 Codex 自动创建本地开发目录：是 / 否
|
||
- 图片是否已放入本地目录：是 / 否
|
||
|
||
说明：本地 OSS 图片目录只作为开发期图片镜像使用，发布时图片由用户上传到真实 OSS；目录内图片和空目录占位文件不作为 Git 提交内容。
|
||
|
||
### 3.1 图片清单
|
||
|
||
| 图片名 | 支持语言 | 备注 |
|
||
| --- | --- | --- |
|
||
| | 默认 | |
|
||
|
||
### 3.2 阻塞预加载图片
|
||
|
||
| 图片名 | 是否包含多语言 | 备注 |
|
||
| --- | --- | --- |
|
||
| | 否 | |
|
||
|
||
### 3.3 后台预加载图片
|
||
|
||
| 图片名 | 是否包含多语言 | 备注 |
|
||
| --- | --- | --- |
|
||
| | 否 | |
|
||
|
||
## 4. 模块配置
|
||
|
||
没有填写的模块，初版页面先不处理。
|
||
|
||
### 4.1 标签页模块
|
||
|
||
```json
|
||
{
|
||
"enabled": false,
|
||
"defaultValue": "",
|
||
"items": []
|
||
}
|
||
```
|
||
|
||
### 4.2 页面区块模块
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "header",
|
||
"enabled": true,
|
||
"apis": [],
|
||
"images": [],
|
||
"remark": "头部模块",
|
||
"children": {}
|
||
},
|
||
{
|
||
"name": "ranking",
|
||
"enabled": false,
|
||
"apis": [],
|
||
"images": [],
|
||
"remark": "排行榜模块",
|
||
"children": {}
|
||
},
|
||
{
|
||
"name": "reward",
|
||
"enabled": false,
|
||
"apis": [],
|
||
"images": [],
|
||
"remark": "奖励模块",
|
||
"children": {}
|
||
},
|
||
{
|
||
"name": "task",
|
||
"enabled": false,
|
||
"apis": [],
|
||
"images": [],
|
||
"remark": "任务模块",
|
||
"children": {}
|
||
}
|
||
]
|
||
```
|
||
|
||
### 4.3 弹窗模块
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "rule",
|
||
"enabled": false,
|
||
"triggerImage": "",
|
||
"backgroundImage": "",
|
||
"component": "src/components/MaskLayer.vue",
|
||
"remark": "规则弹窗"
|
||
},
|
||
{
|
||
"name": "reward",
|
||
"enabled": false,
|
||
"triggerImage": "",
|
||
"backgroundImage": "",
|
||
"component": "src/components/MaskLayer.vue",
|
||
"remark": "奖励弹窗"
|
||
}
|
||
]
|
||
```
|
||
|
||
## 5. 接口参数
|
||
|
||
```json
|
||
{
|
||
"activityId": "",
|
||
"activityCode": "",
|
||
"activityType": "",
|
||
"rankingActivityType": "",
|
||
"rewardActivityType": "",
|
||
"otherParams": {}
|
||
}
|
||
```
|
||
|
||
## 6. 组件需求
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "itemCenter",
|
||
"enabled": "",
|
||
"remark": "图片背景容器"
|
||
},
|
||
{
|
||
"name": "TopUser",
|
||
"enabled": "",
|
||
"remark": "前三名用户展示"
|
||
},
|
||
{
|
||
"name": "MaskLayer",
|
||
"enabled": "",
|
||
"remark": "公共弹窗遮罩"
|
||
}
|
||
]
|
||
```
|
||
|
||
## 7. 建页后记录
|
||
|
||
### 7.1 已完成
|
||
|
||
-
|
||
|
||
### 7.2 后续补充
|
||
|
||
-
|
||
|
||
### 7.3 待微调
|
||
|
||
-
|
||
|
||
### 7.4 验证结果
|
||
|
||
- `npm run build`：
|
||
- 备注：
|
||
````
|
||
|
||
## 4. 初版页面完成后检查
|
||
|
||
```text
|
||
页面能打开
|
||
图片路径无 404
|
||
路由能进入
|
||
security 和 permissionManager 已补
|
||
LoadingContent 展示和关闭正常
|
||
页面内部滚动正常且无可见滚动条
|
||
弹窗能打开和关闭
|
||
多 tab 列表数据不混用
|
||
npm run build 通过
|
||
```
|