mirror of https://github.com/ialley-workshop-open/uni-halo.git synced 2026-09-12 16:40:40 +08:00

Files

T

小莫唐尼 beaf2c39ca feat: 实现全站布局偏好系统，支持多页面独立配置

本次提交完成了完整的偏好设置体系重构：
1. 新增preferences.md文档说明布局偏好设计与映射规则
2. 重构布局配置结构，按页面分组管理列表布局与卡片样式
3. 实现后端preferences字段到本地配置的自动映射转换
4. 完成首页、文章列表、归档页的布局动态切换逻辑
5. 重构投票组件样式绑定，改用unocss类名实现样式分离
6. 新增偏好设置页面，支持按页面配置布局参数
7. 兼容旧版布局参数的自动归一化转换
8. 补充完整的单元测试用例覆盖新旧数据迁移场景

2026-09-09 14:48:55 +08:00

4.8 KiB

Raw Blame History

偏好设置(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. 布局偏好结构(按页面分组)

/** 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}`;设置页增加「布局 / 功能」分段器与页面分组设置项;三个消费页面联动卡片

4.8 KiB Raw Blame History