mirror of
https://github.com/ialley-workshop-open/uni-halo.git
synced 2026-09-12 16:40:40 +08:00
小莫唐尼
beaf2c39ca
本次提交完成了完整的偏好设置体系重构： 1. 新增preferences.md文档说明布局偏好设计与映射规则 2. 重构布局配置结构，按页面分组管理列表布局与卡片样式 3. 实现后端preferences字段到本地配置的自动映射转换 4. 完成首页、文章列表、归档页的布局动态切换逻辑 5. 重构投票组件样式绑定，改用unocss类名实现样式分离 6. 新增偏好设置页面，支持按页面配置布局参数 7. 兼容旧版布局参数的自动归一化转换 8. 补充完整的单元测试用例覆盖新旧数据迁移场景
90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# 偏好设置(Preferences)
|
|
|
|
> 本文档定义客户端偏好设置的数据结构、取值约定与后端插件 `getConfigs.preferences` 下发字段的映射关系,
|
|
> 供「偏好设置」页面、各消费页面与后端插件配置同步参考。
|
|
> 详细设计(含与旧值体系差异)见 `.docs/preferences.md`。
|
|
|
|
## 1. 数据流(两层偏好)
|
|
|
|
读取优先级:**本地差异 > 站点默认(L0)> 客户端内置默认**。
|
|
|
|
- L0 站点默认:插件 `getConfigs` 下发,由 `collectSiteDefaults`(`src/utils/preference.ts`)收集为差异形状;
|
|
- L1 本地差异:storage key `uh_pref_local_v1`,只存与站点默认不同的字段(字段级覆盖,本地优先),值缺省/删除即回退跟随站点默认;
|
|
- 内置默认:`src/config/appSettings.ts` 的 `DefaultAppSettings`(无 L0 下发时的兜底)。
|
|
|
|
## 2. 布局偏好结构(按页面分组)
|
|
|
|
```ts
|
|
/** src/config/appSettings.ts */
|
|
interface IPageLayoutPref {
|
|
/** 列表布局:single=单列 / double=双列 */
|
|
listLayout: string
|
|
/** 卡片样式(组件 layout 值):image_top=上图下文 / image_right=左文右图 / image_bottom=上文下图(社交卡片) / image_left=左图右文 */
|
|
cardType: string
|
|
}
|
|
|
|
layout: {
|
|
home: IPageLayoutPref // 首页
|
|
articles: IPageLayoutPref // 文章列表页
|
|
archives: IPageLayoutPref // 文章归档页
|
|
}
|
|
```
|
|
|
|
### 取值约定
|
|
|
|
| 字段 | 可选值 | 说明 |
|
|
|------|--------|------|
|
|
| `listLayout` | `single` / `double` | 单列 / 双列;「默认」= 跟随站点默认(本地不覆盖) |
|
|
| `cardType` | `image_top` / `image_right` / `image_bottom` / `image_left` | 上图下文 / 左文右图 / 上文下图(社交卡片) / 左图右文,与 `uh-article-card` 组件 layout 值一一对应 |
|
|
|
|
> 旧值体系(`lr_image_text` / `lr_text_image` / `tb_image_text` / `tb_text_image`)已废弃,统一改用组件 layout 值。
|
|
|
|
### 内置默认值(DefaultAppSettings)
|
|
|
|
| 页面 | listLayout | cardType |
|
|
|------|-----------|----------|
|
|
| home(首页) | `single` | `image_bottom` |
|
|
| articles(文章列表) | `double` | `image_bottom` |
|
|
| archives(文章归档) | `single` | `image_bottom` |
|
|
|
|
## 3. 后端插件字段映射(getConfigs.preferences)
|
|
|
|
`collectSiteDefaults` 维护以下映射(字段缺省则跳过,不产生覆盖):
|
|
|
|
| 后端 `preferences` 字段 | 本地路径 | 说明 |
|
|
|------------------------|---------|------|
|
|
| `homeListLayout` | `layout.home.listLayout` | 兼容旧值 `h_row_col1/2`,归一化为 `single/double` |
|
|
| `homeCardType` | `layout.home.cardType` | 值为 `image_top/image_right/image_bottom/image_left` |
|
|
| `articlesListLayout` | `layout.articles.listLayout` | 新增 |
|
|
| `articleCardType` | `layout.articles.cardType` | 沿用旧字段名(兼容既有下发) |
|
|
| `archivesListLayout` | `layout.archives.listLayout` | 新增 |
|
|
| `archivesCardType` | `layout.archives.cardType` | 新增 |
|
|
| `avatarRadius` | `isAvatarRadius` | 评论头像是否圆形 |
|
|
|
|
> 后端新增字段建议统一命名 `{页面}ListLayout` / `{页面}CardType`;
|
|
> 列表布局值建议直接下发 `single/double`,旧值 `h_row_col1/h_row_col2` 前端会归一化兼容;
|
|
> 卡片样式值直接下发组件 layout 值(4 个 `image_*`)。
|
|
|
|
## 4. 消费方
|
|
|
|
| 位置 | 消费内容 |
|
|
|------|---------|
|
|
| `src/pages-blog/setting/setting.vue` | 顶部分段器(布局 / 功能);「布局」按页面分组设置「列表布局 / 卡片样式」 |
|
|
| `src/pages/tabbar/home/home.vue` | `layout.home.listLayout` 决定容器单/双列;卡片 `from="home"` 读 `layout.home.cardType` |
|
|
| `src/pages-blog/articles/articles.vue` | `layout.articles.listLayout` 决定容器与 `variant`(grid/list);卡片 `from="articles"` |
|
|
| `src/pages-blog/archives/archives.vue` | `layout.archives.listLayout` 决定归档时间线内单/双列;卡片 `from="archives"` |
|
|
| `src/components/uh-article-card/uh-article-card.vue` | 按 `from` 读取对应页面 `cardType` 作为 layout;grid/双列窄列自动回退 `image_top`;非法值兜底 `image_bottom` |
|
|
|
|
## 5. 设置页枚举(「默认」= 跟随站点默认)
|
|
|
|
- 列表布局:跟随站点默认 / 单列(`single`)/ 双列(`double`)
|
|
- 卡片样式:跟随站点默认 / 上图下文(`image_top`)/ 左文右图(`image_right`)/ 上文下图(`image_bottom`)/ 左图右文(`image_left`)
|
|
- 选择「跟随站点默认」时写入差异 `null`(删除本地覆盖),回退 L0 站点默认;无 L0 时回退内置默认。
|
|
|
|
## 6. 变更记录
|
|
|
|
| 版本 | 变更 |
|
|
|------|------|
|
|
| v2.4 | 卡片样式值体系由旧 `lr_*/tb_*` 改为组件 layout 值 `image_top/image_right/image_bottom/image_left`;内置默认 cardType 统一为 `image_bottom`;移除 `uh-article-card` 旧值映射(`CARD_TYPE_TO_LAYOUT`),非法值兜底 `image_bottom` |
|
|
| v2.3 | 布局偏好由全局 `layout.home` / `layout.cardType`(字符串)重构为按页面分组 `layout.{home,articles,archives}.{listLayout,cardType}`;设置页增加「布局 / 功能」分段器与页面分组设置项;三个消费页面联动卡片 |
|