feat(theme): 状态态补齐背景渐变 + 覆盖层支持（几何仍冻结避免跳动）

huanfeng · huanfeng · commit 2cbd02bb78ca · 2026-06-05T20:21:41.000+08:00
selected/hover 此前只合并颜色/背景图/边框/字体，渐变与覆盖层被静默丢弃。补齐：
- effectiveNode 合并 BgGradient + Layers；applyNodeBox 门控纳入 BgGradient
  （顺带修复基态只配渐变无底色时不生效）。
- buildCandidateItem 装饰层来源由 rv.Item.Layers 改 effItem.Layers（状态可覆盖层）。
- resolveState「有无覆盖」判定纳入渐变/层（只配渐变/层的状态 patch 不再被当空丢弃）。

几何（padding/margin/font_size）仍刻意不随状态变——状态毫秒级切换若改几何会致候选框
跳动，故 state_geometry 保持 unsupported。能力模型收敛为「状态支持除几何外的全部视觉
能力」，capabilities.json 无新增键。

守护：TestEffectiveNode_StateGradientLayers（合并）+ TestResolveState_GradientLayersKept
（保留渐变/层、丢弃纯几何）。
diff --git a/docs/design/theme-capability-schema.md b/docs/design/theme-capability-schema.md
@@ -99,9 +99,13 @@ JSON 形态（稳定、语言无关）：
 
 ### 状态态覆盖范围的处理（澄清）
 
-状态态 patch（`selected`/`hover`/`disabled`）schema 上是完整 `ViewNode`，但**渲染只消费颜色/边框/字重覆盖**——`resolveState` 的"有无覆盖"判定不看几何、`effectiveNode` 合并时也不碰 `padding`/`margin`/`font_size`。即"选中态改间距/字号"是声明可写、渲染必忽略的假字段。
+状态态 patch（`selected`/`hover`/`disabled`）schema 上是完整 `ViewNode`。**渲染消费状态态的颜色/背景图/渐变/边框/字体/层覆盖**（`effectiveNode` 合并这些、`resolveState` 据此判定"有无覆盖"）；**唯几何（`padding`/`margin`/`font_size`）不渲染**——状态改几何会牵动行高/列宽致候选框跳动，故刻意不支持。
 
-故新增单一能力键 `state_geometry`（粒度="状态态能否改几何"，非每个几何叶子 × 每个状态，避免矩阵爆炸），在所有有状态的 view（`item`/`index`/`text`/`comment`/`menu.item`）标 `unsupported`。编辑器据此在状态态编辑器里隐藏/灰显几何控件，只留颜色/边框/字重。转 `supported` 须先补齐 `resolveState`+`effectiveNode` 的几何消费并重做 golden。详见 `theme-dimension-inheritance.md`。
+故用单一能力键 `state_geometry`（粒度="状态态能否改几何"，非每个几何叶子 × 每个状态，避免矩阵爆炸）在所有有状态的 view（`item`/`index`/`text`/`comment`/`menu.item`）标 `unsupported`。编辑器据此在状态态编辑器里隐藏/灰显**几何**控件，保留颜色/背景图/渐变/边框/字体/层。转 `supported` 须先补齐 `resolveState`+`effectiveNode` 的几何消费并重做 golden。
+
+> 状态态背景四件套（色/图/渐变）+ 层与默认态对齐：`effectiveNode` 合并 `BgColor`/`BgImage`/`BgGradient`/`Layers`，`applyNodeBox` 门控含 `BgGradient`，候选项装饰层取 `effItem.Layers`（非基态）。
+
+详见 `theme-dimension-inheritance.md`。
 
 ## 五、回归判据
 
diff --git a/wind_input/internal/ui/viewbox_build.go b/wind_input/internal/ui/viewbox_build.go
@@ -172,15 +172,21 @@ func effectiveNode(n theme.RVNode, selected, hover bool) theme.RVNode {
 	if st == nil {
 		return n
 	}
-	// 仅合并颜色/边框/字重/字体族（状态态的有意范围）；padding/margin/font_size 不合并
-	// （capability `state_geometry`=unsupported）。需要状态态改几何时，在此补合并 + 放开 resolveState 判定。
+	// 合并颜色/背景图/渐变/边框/字体/覆盖层（状态态的有意范围）；唯几何（padding/margin/font_size）
+	// 不合并——状态改几何会牵动行高/列宽致候选框跳动（capability `state_geometry`=unsupported）。
 	out := n
 	if st.BgColor != nil {
 		out.BgColor = st.BgColor
 	}
 	if st.BgImage != nil {
 		out.BgImage = st.BgImage
 	}
+	if st.BgGradient != nil {
+		out.BgGradient = st.BgGradient
+	}
+	if st.Layers != nil {
+		out.Layers = st.Layers // 整组替换（与 mergeViewNode 一致）
+	}
 	if st.BorderColor != nil {
 		out.BorderColor = st.BorderColor
 	}
@@ -205,8 +211,8 @@ func effectiveNode(n theme.RVNode, selected, hover bool) theme.RVNode {
 // applyNodeBox 把有效节点的背景 + 边框应用到 View——**仅配置了才设**，未配=不动（纯文本/无框，零回归）。
 // index/text/comment/item 统一经此上盒模型；padding 由各自构建处控制（item 行内边距含 rail 逻辑，不在此覆盖）。
 func (r *Renderer) applyNodeBox(v *View, eff theme.RVNode, scale float64) {
-	if eff.BgColor != nil || eff.BgImage != nil {
-		v.Background = r.fillFor(eff.BgColor, eff.BgImage, eff.BgGradient) // 高亮位图优先于底色
+	if eff.BgColor != nil || eff.BgImage != nil || eff.BgGradient != nil {
+		v.Background = r.fillFor(eff.BgColor, eff.BgImage, eff.BgGradient) // 优先级：底色 < 渐变 < 背景图
 	}
 	if eff.BorderColor != nil || eff.BorderWidth != (theme.Dimension{}) || eff.BorderRadius != (theme.Dimension{}) {
 		v.Border = Border{Color: eff.BorderColor, Width: eff.BorderWidth.Scaled(scale), Radius: eff.BorderRadius.Scaled(scale)}
@@ -354,7 +360,7 @@ func (r *Renderer) buildCandidateItem(cand Candidate, sel, hov bool, st *candIte
 		Children: itemChildren,
 	}
 	r.applyNodeBox(item, effItem, scale)          // 统一：item 行背景 + 边框（含选中/悬停态）
-	r.appendThemeLayers(item, rv.Item.Layers, sc) // P7-C：候选项装饰层
+	r.appendThemeLayers(item, effItem.Layers, sc) // P7-C：候选项装饰层（effItem→状态态可覆盖 layers）
 	return item
 }
 
diff --git a/wind_input/internal/ui/viewbox_element_state_test.go b/wind_input/internal/ui/viewbox_element_state_test.go
@@ -49,3 +49,26 @@ func TestEffectiveNode(t *testing.T) {
 		t.Errorf("hover 态 bg 应=red, got %v", eff.BgColor)
 	}
 }
+
+// TestEffectiveNode_StateGradientLayers 守护状态态补齐：选中态可覆盖背景渐变 + 覆盖层
+// （几何仍不随状态变，见 TestEffectiveNode）。
+func TestEffectiveNode_StateGradientLayers(t *testing.T) {
+	grad := &theme.RVGradient{Type: "linear", Stops: []theme.RVGradientStop{
+		{Color: color.RGBA{1, 2, 3, 255}, Pos: 0}, {Color: color.RGBA{4, 5, 6, 255}, Pos: 1},
+	}}
+	base := theme.RVNode{TextColor: color.RGBA{0, 0, 0, 255}}
+	base.Selected = &theme.RVNode{BgGradient: grad, Layers: []theme.RVImage{{Ref: "wm", Z: 1}}}
+
+	// 基态：不应带 selected 的渐变/层。
+	if eff := effectiveNode(base, false, false); eff.BgGradient != nil || eff.Layers != nil {
+		t.Errorf("基态不应有 selected 的渐变/层, got grad=%v layers=%v", eff.BgGradient, eff.Layers)
+	}
+	// 选中态：渐变 + 层被合并。
+	eff := effectiveNode(base, true, false)
+	if eff.BgGradient != grad {
+		t.Errorf("选中态渐变未合并, got %v", eff.BgGradient)
+	}
+	if len(eff.Layers) != 1 || eff.Layers[0].Ref != "wm" {
+		t.Errorf("选中态覆盖层未合并, got %v", eff.Layers)
+	}
+}
diff --git a/wind_input/pkg/theme/candidate_views.go b/wind_input/pkg/theme/candidate_views.go
@@ -172,15 +172,17 @@ func ResolveCandidateViews(views Views, pal ResolvedPalette) ResolvedViews {
 // 复用 resolveViewNode 做完整 ViewNode→RVNode 解析（含几何/边框/字体），再注入该态的 palette
 // 默认底色/文字色（defBg/defText，nil=无默认）。全空且无 palette 默认 → 返回 nil（该态无覆盖）。
 //
-// nil-gating：仅当 patch 显式提供了 bg/bgImage/text/border 色/border 宽/字重，或存在 palette
-// 默认色时，才视为「有覆盖」并返回非 nil（与旧 RVState 语义一致，守 golden）。
+// nil-gating：仅当 patch 显式提供了 bg/bgImage/渐变/层/text/border 色/border 宽/字重，或存在
+// palette 默认色时，才视为「有覆盖」并返回非 nil。
 //
-// 有意不看几何：padding/margin/font_size 不计入"有无覆盖"判定——状态态几何当前不渲染
-// （capability `state_geometry`=unsupported）。即只改 padding 的 selected 态会被视为空 patch 而丢弃。
+// 有意不看几何：padding/margin/font_size 不计入"有无覆盖"判定——状态态几何**刻意不渲染**
+// （状态改几何会牵动行高/列宽致候选框跳动，capability `state_geometry`=unsupported）。
+// 即只改 padding 的 selected 态会被视为空 patch 而丢弃；但只改渐变/层的会保留（已支持）。
 func resolveState(node *ViewNode, defBg, defText color.Color, resolveColor func(ColorRef) color.Color) *RVNode {
 	has := defBg != nil || defText != nil
 	if node != nil {
 		if resolveColor(node.Background.Color) != nil || node.Background.Image != nil ||
+			(node.Background.Gradient != nil && len(node.Background.Gradient.Stops) > 0) || len(node.Layers) > 0 ||
 			resolveColor(node.Color) != nil || resolveColor(node.Border.Color) != nil ||
 			node.Border.Width != nil || node.FontWeight != nil {
 			has = true
diff --git a/wind_input/pkg/theme/capability.go b/wind_input/pkg/theme/capability.go
@@ -36,23 +36,23 @@ const (
 	CapStateHover         = "state_hover"
 	CapStateDisabled      = "state_disabled"
 	// CapStateGeometry：状态态（selected/hover/disabled）能否覆盖几何（padding/margin/字号）。
-	// 当前渲染消费仅限颜色/边框/字重——resolveState 判定不看几何、effectiveNode 也不合并几何，
-	// 故状态态的 padding/margin/font_size 在 schema 可写但不渲染（假字段）→ 有状态的 view 标 unsupported。
-	CapStateGeometry = "state_geometry"
-	CapLayers             = "layers"
-	CapShadowOffset       = "shadow_offset"
-	CapShadowBlurSpread   = "shadow_blur_spread"
-	CapLineSpacing        = "line_spacing"
-	CapColGap             = "col_gap"
-	CapTitleGap           = "title_gap"
-	CapItemSpacing        = "item_spacing"
-	CapBandGap            = "band_gap"
-	CapRowGap             = "row_gap"
-	CapIndexLabels        = "index_labels"
-	CapAccentBar          = "accent_bar"
-	CapFooterArrowImage   = "footer_arrow_image"
-	CapPager              = "pager"
-	CapModeStates         = "mode_states"
+	// 状态态支持颜色/背景图/渐变/边框/字体/层覆盖，**唯几何不支持**——状态改几何会牵动行高/列宽
+	// 致候选框跳动（effectiveNode 不合并几何、resolveState 判定不看几何）→ 有状态的 view 标 unsupported。
+	CapStateGeometry    = "state_geometry"
+	CapLayers           = "layers"
+	CapShadowOffset     = "shadow_offset"
+	CapShadowBlurSpread = "shadow_blur_spread"
+	CapLineSpacing      = "line_spacing"
+	CapColGap           = "col_gap"
+	CapTitleGap         = "title_gap"
+	CapItemSpacing      = "item_spacing"
+	CapBandGap          = "band_gap"
+	CapRowGap           = "row_gap"
+	CapIndexLabels      = "index_labels"
+	CapAccentBar        = "accent_bar"
+	CapFooterArrowImage = "footer_arrow_image"
+	CapPager            = "pager"
+	CapModeStates       = "mode_states"
 )
 
 // capabilityKeys 能力键白名单。
@@ -120,7 +120,7 @@ var ThemeCapabilities = []ViewCapability{
 		CapBackgroundColor: CapSupported, CapBackgroundImage: CapSupported, CapLayers: CapSupported,
 		CapStateSelected: CapSupported, CapStateHover: CapSupported,
 		CapStateDisabled:      CapUnsupported, // 候选项无禁用业务语义（Candidate 无 disabled 字段）
-		CapStateGeometry:      CapUnsupported, // 状态态仅覆盖颜色/边框/字重，几何不渲染
+		CapStateGeometry:      CapUnsupported, // 几何不随状态变（避免跳动）；色/图/渐变/边框/字体/层可覆盖
 		CapBackgroundGradient: CapSupported,
 	}},
 	{"index", map[string]CapabilityStatus{
@@ -129,18 +129,18 @@ var ThemeCapabilities = []ViewCapability{
 		CapBackgroundShape: CapSupported, CapIndexLabels: CapSupported,
 		CapStateSelected: CapSupported, CapStateHover: CapSupported,
 		CapStateDisabled:      CapUnsupported,
-		CapStateGeometry:      CapUnsupported, // 状态态仅覆盖颜色/边框/字重，几何不渲染
+		CapStateGeometry:      CapUnsupported, // 几何不随状态变（避免跳动）；色/图/渐变/边框/字体/层可覆盖
 		CapBackgroundGradient: CapSupported,
 	}},
 	{"text", map[string]CapabilityStatus{
 		CapMargin: CapSupported, CapTextColor: CapSupported, CapFont: CapSupported,
 		CapStateSelected: CapSupported, CapStateHover: CapSupported, CapStateDisabled: CapUnsupported,
-		CapStateGeometry: CapUnsupported, // 状态态仅覆盖颜色/字重，几何不渲染
+		CapStateGeometry: CapUnsupported, // 几何不随状态变（避免跳动）；色/图/渐变/边框/字体可覆盖
 	}},
 	{"comment", map[string]CapabilityStatus{
 		CapMargin: CapSupported, CapTextColor: CapSupported, CapFont: CapSupported,
 		CapStateSelected: CapSupported, CapStateHover: CapSupported, CapStateDisabled: CapUnsupported,
-		CapStateGeometry: CapUnsupported, // 状态态仅覆盖颜色/字重，几何不渲染
+		CapStateGeometry: CapUnsupported, // 几何不随状态变（避免跳动）；色/图/渐变/边框/字体可覆盖
 	}},
 	{"accent_bar", map[string]CapabilityStatus{
 		CapAccentBar: CapSupported, CapBackgroundColor: CapSupported,
@@ -187,7 +187,7 @@ var ThemeCapabilities = []ViewCapability{
 		CapPadding: CapSupported, CapBorder: CapSupported,
 		CapBackgroundColor: CapSupported, CapTextColor: CapSupported, CapFont: CapSupported,
 		CapStateHover: CapSupported, CapStateDisabled: CapSupported,
-		CapStateGeometry: CapUnsupported, // 状态态仅覆盖颜色/边框/字重，几何不渲染
+		CapStateGeometry: CapUnsupported, // 几何不随状态变（避免跳动）；色/图/渐变/边框/字体/层可覆盖
 	}},
 	{"menu.separator", map[string]CapabilityStatus{
 		CapBackgroundColor: CapSupported, // 作分隔线色
diff --git a/wind_input/pkg/theme/viewstate_test.go b/wind_input/pkg/theme/viewstate_test.go
@@ -0,0 +1,34 @@
+package theme
+
+import (
+	"image/color"
+	"testing"
+)
+
+// TestResolveState_GradientLayersKept 守护状态态补齐：只配渐变/层的状态 patch 不再被
+// "有无覆盖"判定当空 patch 丢弃（渐变/层已支持）；只配几何的仍丢弃（state_geometry unsupported）。
+func TestResolveState_GradientLayersKept(t *testing.T) {
+	noColor := func(ColorRef) color.Color { return nil } // 颜色全 nil，隔离出渐变/层/几何的判定
+
+	// 只配渐变 → 保留（非 nil）。
+	gradOnly := &ViewNode{Background: ViewFill{Gradient: &ViewGradient{Stops: []ViewGradientStop{{}, {}}}}}
+	if resolveState(gradOnly, nil, nil, noColor) == nil {
+		t.Error("只配渐变的状态 patch 不应被丢弃")
+	}
+
+	// 只配覆盖层 → 保留。
+	layerOnly := &ViewNode{Layers: []ViewImage{{Ref: "x"}}}
+	rv := resolveState(layerOnly, nil, nil, noColor)
+	if rv == nil {
+		t.Fatal("只配 layers 的状态 patch 不应被丢弃")
+	}
+	if len(rv.Layers) != 1 {
+		t.Errorf("状态 patch 应解析出 Layers, got %d", len(rv.Layers))
+	}
+
+	// 只配几何（padding）→ 仍丢弃（几何不随状态变，避免跳动）。
+	geomOnly := &ViewNode{Padding: ViewEdges{Top: dimp(4)}}
+	if resolveState(geomOnly, nil, nil, noColor) != nil {
+		t.Error("只配几何的状态 patch 应被丢弃（state_geometry unsupported）")
+	}
+}
