diff --git a/README.md b/README.md index e8bcef6..30da9fd 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,11 @@ pnpm build # 生产构建 ## 更新日志 +### v1.0.8 + +- 设置页改用 Halo 官方 VPageHeader / VCard / VDescription / VTag 组件,与官方页面风格统一 +- 精简插件自身 CSS 变量,仅保留设置页所需变量 + ### v1.0.7 - 移除设置页方向键切换、roving tabindex 与 ARIA 单选组语义,保留原生按钮点击切换 diff --git a/docs/plan-settings-officialization-2026-08-08.md b/docs/plan-settings-officialization-2026-08-08.md new file mode 100644 index 0000000..511d3fb --- /dev/null +++ b/docs/plan-settings-officialization-2026-08-08.md @@ -0,0 +1,175 @@ +# 改进交接单:设置页官方化改造(2026-08-08) + +> 审查窗口调研产出,**交付开发窗口执行**;审查窗口不修改代码。 +> 调研来源:Halo 官方仓库 `halo-dev/halo`(commit `815292f`)+ 本地代码 + 线上 `blog.liuhangyv.top/console` 实证(已登录)。 +> 本文档为**唯一交付文件**(已合并此前两份调研文档)。 + +## 〇、需求与结论总览 + +| # | 需求 | 结论 | +| --- | --- | --- | +| 1 | 侧边栏「深色模式」入口状态反馈 | **不做改动**(依据见第一节) | +| 2 | 设置页顶部缺官方风格标题栏 | **要改**:使用官方 `VPageHeader`(第二节) | +| 3 | 尽量用官方组件实现 | 组件全景与复用方案见第三、四节 | + +## 一、侧边栏「深色模式」入口状态反馈(结论:保持现状,不动) + +### 1.1 现象 + +点击「深色模式」后界面切换为深色,但侧边栏「深色模式」入口(菜单项)文案没有随之变化;用户曾疑问是否应显示"白天模式 / 深色模式 / 跟随系统模式"。 + +### 1.2 调研结论(证据) + +1. **Halo 菜单是静态导航**:`use-route-menu-generator.ts` 一次性从 `router.getRoutes()` 按 `meta.menu` 生成菜单,无业务状态联动。 +2. **菜单名是静态字符串**:`RoutesMenu.tsx` 中 `title={t(item.name, item.name)}`,官方机制不支持动态文案;所有官方/插件菜单项均为固定名称。 +3. **激活高亮已生效**:`active={route.matched.includes(item.path)}`;线上实证进入 `/console/dark-mode-settings` 后,菜单项 `class="active menu-item-title"`。 +4. **平台惯例**:窗口内改设置、侧边栏入口不变化,是 Halo 全站一致行为(菜单是入口,不是状态开关)。 + +### 1.3 结论 + +- 动态菜单文案不可直接实现(需 DOM hack,不推荐)。 +- 保持静态「深色模式」菜单名,激活高亮现状即符合平台标准。 +- 当前模式信息继续由设置页内「当前生效」展示(第四节中会优化展示形式)。 + +## 二、设置页顶部标题栏(需改造) + +### 2.1 现象 + +`/console/dark-mode-settings` 顶部为自定义 `h1 + p`;官方页面(`/console/theme`、`/console/plugins`)顶部有统一白底标题栏。线上实证:设置页 `document.querySelectorAll('.page-header').length === 0`。 + +### 2.2 官方 `VPageHeader` 组件(`@halo-dev/components` 已导出) + +结构(源码 `ui/packages/components/src/components/header/PageHeader.vue`): + +```html + +``` + +官方用法(`PluginList.vue`): + +```html + + + + +
+``` + +## 三、官方组件库全景(21 类)与插件对照 + +### 3.1 组件清单 + +| 目录 | 导出名 | 用途 | 设置页可用 | +| --- | --- | --- | --- | +| header | `VPageHeader` | 页面标题栏 | ✅ | +| card | `VCard`(title / bodyClass;slot header) | 内容卡片 | ✅ | +| description | `VDescription` / `VDescriptionItem`(label / content / verticalCenter) | 键值展示 | ✅ | +| tag | `VTag`(theme / rounded;slot leftIcon) | 标签/徽标 | ✅ | +| status | `VStatusDot`(state / text / animate) | 状态点 | ✅ | +| button | `VButton`(type / size / block / ghost / loading / route;slot icon) | 按钮 | ✅ | +| space | `VSpace` | 间距布局 | ✅ | +| alert | `VAlert` | 提示条 | 可选 | +| switch | `VSwitch` | 开关 | 未来扩展 | +| menu | `VMenu` / `VMenuItem` / `VMenuLabel` | 菜单 | — | +| entity | `VEntity` / `VEntityContainer` / `VEntityField` | 列表实体 | — | +| modal / dialog | `VModal` / `VDialog` | 模态/确认 | — | +| dropdown | `VDropdownItem` / `VDropdownDivider` | 下拉 | — | +| tabs | `VTabs` / `VTabItem` / `VTabbar` | 标签页 | — | +| pagination / empty / loading | `VPagination` / `VEmpty` / `VLoading` | 分页/空态/加载 | — | +| avatar | `VAvatar` / `VAvatarGroup` | 头像 | — | +| toast / tooltip | `toast` 函数 / `vTooltip` 指令(非 V 组件) | 提示 | 可选 | + +> **注意:官方组件库没有 radio / radio group 单选组件** —— 三个模式选项保持语义化 `