命中测试的几何前提：SwiftUI 容器为什么需要 contentShape 才能整体可点

我们对"点击区域"有一个朴素到从不细想的假设：一个视图占多大，它的可点区域就有多大。在大多数 UI 框架里这个假设成立，于是我们把 onTap 挂到一行的容器上，理所当然地以为整行可点。SwiftUI 在这里有一条不同的、且更底层的几何前提：它的命中测试默认只覆盖可见 leaf 子视图所占的像素，而不是容器声明的整个 frame。容器里那些"看起来是它的一部分"的空隙（Spacer、leading 和 trailing 之间的间距），在命中测试看来是死区。

本文不讲某个设置行怎么写，而是想拆清楚这条几何前提：为什么"可见区域"和"可命中区域"在 SwiftUI 里是两个分开的概念、contentShape 是连接它们的那座桥、以及为什么这座桥必须架在 gesture 之前。理解这一点，你面对的就不只是一个设置行的 bug，而是一整类"声明的 frame ≠ 实际的命中区域"的交互陷阱。

现象：只有右半边有反应

设置菜单里有用户反馈"点了半天才打开"。实际不是慢——是点左半边没反应，只有点右侧（箭头那块）才打开。用户反复点、大部分落空，主观体验就成了"屏幕半天才响应"。这些行用 @expo/ui/swift-ui 的 SwiftUI 桥接渲染（isLiquidGlassAvailable() 为 true 的分支）。

一个标准设置行：左边一个 label、右边一个 accessory（箭头），中间一大片空隙。onTapGesture 挂在容器上，但没有 content shape：

const modifiers = []
if (onPress) {
  modifiers.push(onTapGesture(onPress)) // 只有 leaf 子视图被 hit-test
}

;<LabeledContent label={<Label title="Flow Meter" systemImage="gauge" />} modifiers={modifiers}>
  <SUIImage systemName="chevron.right" />
</LabeledContent>
// 点行的左 / 中部什么都不发生。

机制：可见区域 ≠ 可命中区域

把 onTapGesture(...) 挂到 SwiftUI 的容器视图（LabeledContent、HStack、VStack、带 Spacer 的行）上，并不会让整行可点。原因是 SwiftUI 命中测试的默认几何：它只 hit-test 可见的 leaf 子视图（Text / Label / Image），而容器本身——以及它内部由 Spacer 撑开的空隙——没有可命中的几何。

这就把"可见"和"可命中"劈成了两件事。视觉上，这一行从左到右是连续的一块；命中测试上，它是"leading label 的几个字 + trailing 箭头"两座孤岛，中间整片空隙是死区。只有点击恰好落在某个可见子视图上才注册，而设置行里唯一总在右侧的可见子视图就是那个箭头——这精确解释了"只有右半边有反应"。

容器在 SwiftUI 里默认是"布局意义上的存在、命中意义上的透明"。它定义了子视图怎么排，但不主张自己那片 frame 应该接收点击。要让它主张，你得显式给它一个命中形状。

修复：用 contentShape 把整个 frame 声明为命中区域

contentShape(shapes.rectangle()) 的作用，就是把可命中区域显式定义成视图的整个 frame，包括 spacer 和空隙——它把"可命中区域"这件事从"默认跟随可见子视图"改写成"等于我声明的形状"。

import { contentShape, onTapGesture, shapes } from '@expo/ui/swift-ui/modifiers'

// 顺序很重要：先 contentShape，再 gesture。
modifiers.push(contentShape(shapes.rectangle()), onTapGesture(onPress))

这正是 @expo/ui 自己 contentShape 文档注释强调的：

"This modifier is essential for making entire view areas (including Spacer or empty space) interactive. Without it, only visible elements like Text or Image respond to tap gestures."

完整的正确形态：

const modifiers = []
if (onPress) {
  modifiers.push(
    contentShape(shapes.rectangle()), // 整个 frame 变成可命中
    onTapGesture(onPress)
  )
}

;<LabeledContent label={<Label title="Flow Meter" systemImage="gauge" />} modifiers={modifiers}>
  <SUIImage systemName="chevron.right" />
</LabeledContent>
// 整行可点。

为什么顺序不能反：modifier 是一条有方向的管线

contentShape 必须排在 onTapGesture 之前，这不是风格约定，而是 SwiftUI modifier 求值方向的直接后果。SwiftUI 由外向内（outside-in）应用 modifiers：写在前面的先扩展视图、写在后面的在已扩展的基础上工作。gesture 要正确生效，必须"看到"一个已经被扩展过的 content shape——所以扩展形状的 contentShape 必须先到。

把 contentShape 放到 onTapGesture 之后，gesture 在它生效时看到的还是默认的、只覆盖 leaf 的命中几何，等于这个 contentShape 没加。这是一个典型的"声明顺序即语义"的 API——两个 modifier 都在、拼写都对，仅仅因为顺序反了就静默失效。

按结果落到几档：

• Good：LabeledContent 设置行，[contentShape(shapes.rectangle()), onTapGesture(onPress)]。整行可点，和视觉可供性（整行高亮 / 箭头）一致。
• Base：leaf Text/Image 加 onTapGesture 不加 content shape——没问题，因为 leaf 没有空的内部，它的 frame 本就等于内容。换句话说，只有当 frame 大于可见内容时，这条几何前提才咬人。
• Bad：容器加 onTapGesture 但没 contentShape——空隙是死区。
• Bad：contentShape 放在 onTapGesture 之后——顺序反了，等于没加。

验证：单测在这里是哑的

这个分支（isLiquidGlassAvailable() 为 true）渲染 SwiftUI 桥接，Vitest 渲染不了——而 RN fallback 路径（Pressable）没有这个 bug，所以单测全绿什么都证明不了。必须在真机 / "Designed for iPad on Mac" 上验，而且要专门去点每个可点行的前缘和中部，不能只点尾部 accessory——因为尾部恰好落在唯一的可见 leaf 上，点它永远成功，会把死区问题完全掩盖。如果某行"时灵时不灵"，先怀疑漏了 contentShape，再去假设性能 / 导航问题。

可用 modifiers 在 @expo/ui/build/swift-ui/modifiers/ 下：contentShape、shapes（rectangle/roundedRectangle/capsule/…）、onTapGesture、disabled 都有暴露。

可迁移的那一层

抛开 SwiftUI 和 @expo/ui 的具体 API，真正可迁移的认知有两条。

"可见区域"和"可命中/可交互区域"是两个独立的几何，不要假设它们重合。 SwiftUI 的容器命中陷阱只是一例——CSS 里 pointer-events、透明元素挡住下层点击、padding 算不算点击区、SVG 的 fill: none 路径不接收事件，全是同一类问题：你看到的边界和事件系统认的边界是两套几何。设计可点的复合控件时，先问一句：这个区域里有多少是"看得见但点不到"的空隙？我有没有显式声明整块都可命中？

当 API 的语义依赖声明顺序时，顺序错误是一种静默失效。 contentShape 必须在 onTapGesture 前，本质和很多"管线式"API（中间件顺序、CSS 层叠、shader pass 顺序）一样——元素都在，顺序错了就无声地不工作。遇到这类 API，记住编译器和单测往往都拦不住顺序错误，唯一的守卫是理解它的求值方向。