From df67bd3b13fba674345eb0e678f8e45b57a4b66a Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Tue, 13 Oct 2026 04:56:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20UI=E5=85=A8=E5=B1=80=E4=B8=BB=E9=A2=98?= =?UTF-8?q?=E6=89=B9=E9=9C=80=E6=B1=82=E5=8D=A1=E7=89=87v1.0=E6=88=90?= =?UTF-8?q?=E6=96=87+06=E4=B8=A4=E5=A4=84=E7=99=BB=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 三裁点用户同日已落定：载体=.tres主题文件(乙案,弃程序化甲案)/未在役控件(CheckBox/CheckButton/OptionButton)预盖/滑轨两段对比度顺手修并销号第三层细节修①。卡片十节全备：红线四条(Button类型词条零接触/零美术素材/纹理过滤不动/旧实现同批删除)+色值提案表(全取ui_kit既有常量)+验证闸V1-V5+白名单五项；零待裁点，开工门=U0。06全局主题条挂卡片指针；第三层细节修条①互认认领(含代码面暖石/深棕与诊断描述不符的疑点披露)。现状事实13条均file:line实查；关键发现=tooltip_theme仅标题屏挂载ui_assembler:105全站不生效/styled_slider滑柄未盖/debug双轨裸HSlider。 --- design/gdd/06-待办清单.md | 4 +- .../需求卡片-UI全局主题批-2026-10-13.md | 125 ++++++++++++++++++ 2 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 design/research/需求卡片-UI全局主题批-2026-10-13.md diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index 598a6883..f9d2eeac 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -10,7 +10,7 @@ **归属**：呈现层表现批（纯工程改动，不动任何美术素材，也不改动 [美术圣经](../art/art-bible.md) §7 的定稿规格） -**状态**：待办（**Alpha 阶段需完成**）——UI 美化三层诊断分三层推进，本条属第一层「系统性缺口」；**用户 2026-10-13 已指定最先动这一层**。 +**状态**：待办（**Alpha 阶段需完成**）——UI 美化三层诊断分三层推进，本条属第一层「系统性缺口」；**用户 2026-10-13 已指定最先动这一层**。**需求卡片已写**：[需求卡片-UI全局主题批-2026-10-13](../research/需求卡片-UI全局主题批-2026-10-13.md) v1.0（2026-10-13 三裁点用户已落定：载体＝.tres 主题文件 / 未在役控件预盖 / 滑轨两段对比度顺手修；待 grilling 复核＋用户卡审，零待裁点，开工门＝U0）。 #### UI 按钮状态矩阵缺档——悬停没有反馈、危险钮按下没有反馈、键盘焦点全站空白（2026-10-13 登记，UI 美化三层诊断 · 第一层） @@ -66,7 +66,7 @@ **归属**：呈现层表现批 -**状态**：待办（**Alpha 阶段需完成**）——①②③是观感改动，④只需关闭或移进调试浮窗，成本很低，可以顺手带上。 +**状态**：待办（**Alpha 阶段需完成**）——①②③是观感改动，④只需关闭或移进调试浮窗，成本很低，可以顺手带上。**①已由「UI 全局主题批」认领顺手修**（2026-10-13 用户裁「顺手修掉」，随该批滑轨词条迁主题时重配两段对比度，销号随该批收口；另：代码面两段色实为暖石/深棕两值，与诊断「同一深棕」描述不符，实机复核随批目检——见该批卡片 §2 疑点披露）。 #### 旧行为 MC 行为锚全数作废——重锚归数值批（2026-10-06 登记） diff --git a/design/research/需求卡片-UI全局主题批-2026-10-13.md b/design/research/需求卡片-UI全局主题批-2026-10-13.md new file mode 100644 index 00000000..79b87523 --- /dev/null +++ b/design/research/需求卡片-UI全局主题批-2026-10-13.md @@ -0,0 +1,125 @@ +# 需求卡片：UI 全局主题批（引擎原生控件接管皮肤） + +- 版本：v1.0（2026-10-13 成文，三裁点已由用户同日落定，待 grilling 复核 + 用户卡审） +- 来源：[06-待办清单](../gdd/06-待办清单.md)「UI 全局主题资源缺失——引擎原生控件没有接管皮肤」（2026-10-13 登记，UI 美化三层诊断 · 第一层）；[08-Alpha版本标准](../gdd/08-Alpha版本标准.md) 三·界面表同名行 +- 归属：呈现层表现批（纯工程改动，零美术素材，不动美术圣经 §7 定稿规格） +- 排期：待编入迭代（卡片状态＝待编入） + +## 1. 目标与完成定义 + +建一套全局主题资源（.tres 文件，挂 `project.godot` 的 `gui/theme/custom`），覆盖全部引擎自带控件的皮肤词条，使未被呈现层逐实例手工盖皮的控件不再显示引擎默认灰色圆角现代风。同时把既有两处局部做法（tooltip 主题、滑轨样式）迁入全局主题单点并退役旧挂载方式；顺手修掉设置面音量滑轨「已填充段与未填充段难分辨」缺陷（第三层细节修①，本批销号）。 + +**完成定义**：工程内不再存在引擎默认皮肤的可见控件（本批范围清单内）；冒烟＋单元＋探针全绿；新增主题词条断言入冒烟；目检项登记 07（用户自排，登记不阻塞）；06 两条销号、08 表行回填。 + +## 2. 现状事实（2026-10-13 代码级实查） + +- `game/project.godot:30` 界面样式相关仅一行 `theme/custom_font`（全局字体）；**无 `gui/theme/custom`，全库零 Theme 资源文件**。引擎版本 4.7（`project.godot:15`）。 +- `game/presentation/main.gd:32` main extends Control，是全部覆盖层的祖先；全局主题走 project 设置，不依赖挂载点代码。 +- **tooltip 主题只覆盖标题屏**：`ui_kit.gd:753` `tooltip_theme()`（深底气泡＋暖白字 14px 程序化 Theme），唯一挂载点 `ui_assembler.gd:105`（标题屏 overlay）。主题沿树向下传播，其余各屏（营地/商店/设置/暂停/生涯/图例/结算/调试）均不生效，气泡为引擎默认灰。全站 10+ 文件挂 `tooltip_text`。 +- **滑轨两处做法不一致**：`ui_kit.gd:735` `styled_slider()` 盖了 HSlider 的 `slider`（槽轨暖石 #B8A582）与 `grabber_area`（填充深棕 #7A5232）两个词条（`ui_kit.gd:743-746`），**滑柄未盖＝引擎默认灰圆**；`debug_overlay.gd:277` `_slider_row` 未走该工厂，裸 `HSlider.new()` 整条默认。 +- **滚动条裸奔清单**：营地 3 处滚动容器（`camp_overlay_view.gd:101` camp_scroll 横滚兜底、`:114` tree_scroll、`:152` ws_scroll）、调试浮窗 2 处 ScrollContainer（`debug_overlay.gd`）、战斗日志与结算回看 RichTextLabel 的自动滚动条（`battle_log_view.gd:50` scroll_active、`settlement_review_overlay.gd:18`）。营地右侧浅灰圆角滚动条＝登记条目的实机例证。 +- **分隔线**：HSeparator 全站 15 处（ui_assembler 1、battle_end 1、settings 2、legend 3、confirm_dialog 1、pause 2、debug_overlay 5），引擎默认灰线；VSeparator 零使用。 +- **调试面输入件**：LineEdit 种子框（`debug_overlay.gd:215`）、SpinBox 批量模拟数（`:246`）、RichTextLabel 输出（`:257`）全部默认皮肤。 +- **未在役控件**：OptionButton / CheckBox / CheckButton / TextEdit / ProgressBar / ItemList / Tree 游戏代码零使用（ProgressBar 已退役，`standee_body.gd:80` 仅存注释）；CheckButton 仅冒烟探针 `probe_ui_util.gd` 使用（非玩家面）。 +- **素材库无滚动条/滑轨/勾选类贴图**（`game/assets/art/ui/` 仅按钮/面板/背景/图标），皮肤只能纯色程序化生成。 +- **冒烟探针零主题断言**（smoke 全目录 grep 零命中），无撞红风险；`ui_tune_probe.gd:213` 有一处 VScrollBar/HScrollBar 引擎滚动机构豁免注释（行为探针，非皮肤断言，不受影响）。 +- **按钮全部逐实例盖皮**（`ui_kit.gd:541` `_apply_button_skin` / `:575` primary / `:591` danger），`add_theme_stylebox_override` 优先级高于全局主题——本批不碰 Button 类型词条则按钮观感零变化。 +- **第三层①疑点披露**：诊断称音量滑轨「已填段与未填段同一个深棕色」，但代码面两段分别为暖石 #B8A582 与深棕 #7A5232（`ui_kit.gd:743-746`），差异明显；且默认值 100（`settings_overlay.gd:59`）时无未填段。诊断描述与代码面不符，需实机复核——本批不依赖该结论：滑轨词条迁主题时直接重配两段对比度，以「拖到中点一眼可辨」为准绳，重构即修复。 + +## 3. 设计契约（红线，违反＝L3 停机呈报） + +- 🔴 **Button 类型词条零接触**：全局主题不得定义 `Button` 类型的任何词条。按钮五态矩阵（含悬停做法、键盘焦点）是 06 第一层第二条待办的地盘，其悬停态有未裁点（甲重产贴图/乙常态提亮），本批先行设默认必踩车。OptionButton 为独立主题类型，不受此条约束（预盖件）。 +- 🔴 **不新增美术素材、不改美术圣经 §7**：全部皮肤用纯色 StyleBoxFlat＋脚本生成的纯色/几何小位图，色值一律取自 [ui_kit.gd](../../game/presentation/views/ui_kit.gd) 既有常量（色值表见 §6/T0）；组件规格是否立条款入 §7 走反哺点（§5）。 +- 🔴 **全局纹理过滤不动**：本批不设置 `rendering/textures/canvas_textures/default_texture_filter`，那是 06 第一层第三条待办的地盘。生成的小位图各自单点设邻近采样（沿用 `ui_kit.gd:214` load_tex 同款做法），不等全局批。 +- 🔴 **旧实现同批删除**（2026-10-11 用户明令）：`tooltip_theme()` 函数与 `ui_assembler.gd:105` 挂载行、`styled_slider()` 的样式词条段必须随批退役，禁止新旧并存。 +- 键盘焦点视觉零定义：主题不写 `focus` 词条（维持引擎默认描边），焦点态整体纪律归按钮状态矩阵批＋「棋盘战斗键盘/手柄输入」连带裁决点③，本批不预支。 + +## 4. 范围边界 + +**做**：VScrollBar / HScrollBar / ScrollContainer(panel) / HSlider / VSlider / TooltipPanel / TooltipLabel / LineEdit / SpinBox / HSeparator / VSeparator 的默认词条；CheckBox / CheckButton / OptionButton 预盖（用户 2026-10-13 裁：预盖，未来新控件自动继承正确皮肤）；音量滑轨两段对比度重配（销号第三层①）。 + +**不做**（去向）： +- 按钮五态/焦点态 → 06 第一层第二条「UI 按钮状态矩阵缺档」（未裁点随其卡片）。 +- 全局邻近采样 → 06 第一层第三条「全局纹理过滤未设为邻近采样」。 +- RichTextLabel 正文字色不动（现状深底可读，未在登记清单；只随全局词条被动接管其滚动条）。 +- 营地滚动条观感之外的营地布局问题（第三层③留白失衡）→ 06 第三层条目。 + +## 5. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| [06-待办清单](../gdd/06-待办清单.md) | ①「UI 全局主题资源缺失」条；②「UI 元素细节修」条之①（滑轨两段难辨） | 两条随批收口销号（事项解决即移除）；「UI 元素细节修」余下②③④保留。**机械面，随批** | +| [08-Alpha版本标准](../gdd/08-Alpha版本标准.md) | 三·界面表「UI 全局主题资源（引擎原生控件接管皮肤）」行状态＝待做 | 入库后回填。**机械面，随批** | +| [07-体验验证清单](../gdd/07-体验验证清单.md) | 本批新增目检观测项 | 随批登记：滚动条/滑轨/气泡/输入件全屏巡检＋音量滑轨拖到中点两段一眼可辨＋预盖件无实役（登记注记）。**机械面，随批**（登记不阻塞） | +| active.md | 批收口快照惯例 | 收口批登记。**机械面，随批** | +| roadmap | 本批尚未编入迭代行 | 编入时随编入批更新；本卡不动 roadmap | +| [美术圣经](../art/art-bible.md) §7 | 滚动条/滑轨/气泡/输入件组件规格目前无条款；本批实现色值＝临时权威 | **反哺点**：迭代实现报告列「上述组件规格是否立条款入 §7」＋「第三层①诊断描述与代码面不符」两点待用户裁决，另批落文。**设计权威文档，不随批更新** | + +## 6. 任务卡 + +### T0 主题资源与词条（≈0.5d） + +1. 新建 `game/assets/theme/main_theme.tres`（路径进 §9 白名单），头注释写色值溯源表（每个字面量 ↔ ui_kit 常量名）。 +2. 一次性生成脚本产出小位图（滚动条柄 3 态、滑轨柄 3 态、SpinBox 箭头、勾选框空框/选中）至 `game/assets/art/ui/gen/`，纯色/几何、各自邻近采样，头注释注明生成脚本出处；脚本入 `tools/` 留档可重跑。 +3. 词条落位（色值提案表，卡审逐值可否）： + +| 词条 | 提案值 | 出处 | +|---|---|---| +| 滚动条槽 scroll | BG_OVERLAY #362B20 α0.35，直角 | BG_OVERLAY | +| 滚动条柄（常/悬/按） | PANEL_BORDER #786E58 / STONE_FAINT #8C7C64 / STONE_DEEP #554D41，约 8×8 方形 | 三常量 | +| 滑轨槽 slider | 暖石 #B8A582＋PANEL_BORDER 边（承现值） | styled_slider 现值 | +| 已填段 grabber_area(+highlight) | **BG_ROOT #3A2E22（换色——对槽 ≈5.4:1，顺手修③层①）** | BG_ROOT | +| 滑轨柄（常/悬/按） | **CANDLE #F6C667 方柄＋PANEL_BORDER 描边（换——弃引擎灰圆）**/ 提亮档 / GOLD_DEEP #B07A14 | CANDLE 等 | +| TooltipPanel / TooltipLabel | 承 `tooltip_theme()` 现值原样迁入（深底 0.96＋边 #5A5044＋WARM 字 14） | ui_kit.gd:757-760 | +| LineEdit normal/focus | PANEL_DATA #E9D9B8 底＋PANEL_BORDER 边＋INK 字；focus=金深边 | PANEL_DATA 等 | +| SpinBox | 底同 LineEdit；箭头=生成 INK 色三角 | 同上 | +| HSeparator/VSeparator | PANEL_BORDER α0.6 单线 | PANEL_BORDER | +| CheckBox/CheckButton | 空框=PANEL_DATA＋PANEL_BORDER 14×14；选中=INK 实心/对勾（生成图） | 同上 | +| OptionButton | normal/hover/pressed=button_stone 九宫格（与手盖按钮同观感，`_tex_sb` 8px 同参）＋INK 字；弹层 popup=PANEL_DATA 面板词条＋INK 字 | 既有贴图与常量 | + +4. `project.godot` 挂 `gui/theme/custom="res://assets/theme/main_theme.tres"`。 + +### T1 换代退役与消费方收口（≈0.25d） + +1. 删 `ui_kit.gd` `tooltip_theme()` 函数与 `_tip_theme` 缓存、`styled_slider()` 的两个 stylebox 段（几何/量程职责并回两处消费方或删函数，两消费方仅 settings_overlay 与 debug_overlay `_slider_row`）。 +2. 删 `ui_assembler.gd:105` 挂载行及其注释行引用。 +3. `debug_overlay._slider_row` 改走与设置屏一致的构建方式（消双轨）。 + +### T2 断言、文档同步闸与全闸（≈0.25d） + +1. 冒烟新增主题词条断言（见 §7）。 +2. 文档同步闸：§5 机械面四件更新完毕＋反哺点两条列明。 +3. 批末四闸全绿合并。 + +**估时合计 0.5–1d**。切分预案：若生成脚本在 headless 受阻（.godot 缓存坑在册），预案＝手写最小 PNG（工具脚本本机跑一次），不动估时软盒。 + +## 7. 验证闸（逐需求点验收清单） + +**能力验证（自动化，随批）**——冒烟新增断言： +- V1 挂载：`ThemeDB.get_project_theme()` 非空且类型集覆盖 §4「做」清单全部类型（`has_stylebox/has_color/has_font_size` 抽查关键词条）。 +- V2 滑轨修复：grabber_area 与 slider 词条色值断言（对 ≈5.4:1 的两常量）。 +- V3 预盖件：临时实例化 CheckBox 读 `get_theme_icon("checked")` 非空（无实役控件的运行时证词）。 +- V4 换代退役：`UiKit.styled_slider` / `tooltip_theme` 引用全库零残留（删函数后编译期即闸）＋ `ui_assembler` 无 `overlay.theme` 残留。 +- V5 回归：冒烟全绿（基线 834/0）——按钮/面板逐实例 override 优先级保证存量观感零变化，存量断言即回归网。 + +**正常流程体验（用户目检，登记 07 不阻塞）**：营地滚动条、战斗日志滚动条、设置音量滑轨拖动全程、全屏悬停气泡、调试浮窗输入件、分隔线——巡检无引擎默认灰残留；音量滑轨拖到中点两段一眼可辨。 + +## 8. 异常分级 + +- L1（自救）：手写 .tres 语法错导致加载失败/词条名拼错（Godot 4 词条名以引擎文档为准，拼写错=静默回退默认）——冒烟 V1 立红即修。 +- L2（记录继续）：生成位图观感不佳（边缘锯齿/尺寸手感）——登记 07 目检项，值微调随批内迭代。 +- L3（停机呈报）：触碰 §3 任一红线；或改全局设置后发现存量界面观感意外变化（说明有未盘点到的默认皮肤依赖面）——先停，实机截图呈报再动。 + +## 9. 代拍板白名单（超清单必呈报） + +1. 主题文件路径＝`game/assets/theme/main_theme.tres`；生成位图目录＝`game/assets/art/ui/gen/`。 +2. 生成位图的尺寸/圆角细节（8×8 柄、14×14 勾选框等微观值）。 +3. `styled_slider` 退役形态（删函数、几何内联两消费方）——两处消费方为上限，超出的新消费方走主题默认。 +4. 词条内字号沿用既有档位（tooltip 14 / 输入件 16），不新设字号档。 +5. 生成脚本落 `tools/` 的文件名与参数形态。 + +## 10. 待裁点 + +**零待裁点，开工门＝U0**。三个范围裁点已由用户 2026-10-13 落定：①载体＝.tres 主题文件（乙案，弃程序化甲案——代价＝色值字面量与 ui_kit 常量双处存在，缓解＝.tres 头注释溯源表＋§6 色值表）；②未在役控件预盖；③滑轨两段对比度顺手修（并销号第三层细节修①）。 + +卡片成立前置：grilling 复核门（含验收清单三问）＋用户卡审。§6 色值提案表随卡审逐值可否，否决不改批结构。