版本：0.78

视图

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

作为构建用户界面的最基础组件，View 是一个支持通过弹性盒布局、样式、触摸事件处理以及无障碍功能进行布局的容器。View 会直接映射到 React Native 所运行平台的原生视图上，无论是 UIView、<div> 还是 android.view 等等。

View 设计用于嵌套在其他视图中，并且可以包含任意类型、数量从零到多个的子组件。

以下示例创建了一个 View，它在一行中包裹了两个带颜色的方块和一个文本组件，并带有内边距。

为了清晰性和性能，View 设计为与 StyleSheet 一起使用，不过也支持内联样式。

合成触摸事件

对于 View 的响应者属性（例如 onResponderMove），传递给它们的合成触摸事件以 PressEvent 的形式出现。

参考

属性

`accessibilityActions`

辅助操作允许辅助技术以编程方式触发组件的操作。accessibilityActions 属性应包含操作对象列表，每个对象需包含 name 和 label 字段。

详见辅助功能指南。

Type
array

`accessibilityElementsHidden`
iOS

指示此无障碍元素内包含的无障碍元素是否隐藏的布尔值，默认值为 false。

更多信息请参阅无障碍功能指南。

Type
bool

`accessibilityHint`

当无障碍标签无法明确操作结果时，无障碍提示可帮助用户理解在无障碍元素上执行操作将产生的效果。

Type
string

`accessibilityLanguage`
iOS

该值指示屏幕阅读器在用户与元素交互时应使用的语言，必须遵循 BCP 47 规范。

更多信息请参阅 iOS accessibilityLanguage 文档。

Type
string

`accessibilityIgnoresInvertColors`
iOS

该值决定在开启颜色反转时，此视图是否应被反转。设置为 true 表示即使开启颜色反转，视图也不会被反转。

更多信息请参阅无障碍功能指南。

Type
bool

`accessibilityLabel`

覆盖屏幕阅读器在用户与元素交互时读取的文本内容。默认情况下，标签会通过遍历所有子元素并拼接所有 Text 节点的文本（以空格分隔）来生成。

Type
string

`accessibilityLiveRegion`
Android

指示无障碍服务在此视图更改时是否应通知用户的枚举值，仅适用于 Android API >= 19。可选值：

'none' - 无障碍服务不应播报此视图的更改
'polite' - 无障碍服务应播报此视图的更改
'assertive' - 无障碍服务应中断当前语音以立即播报此视图的更改

参考 Android View 文档。

Type
enum('none', 'polite', 'assertive')

`accessibilityRole`

accessibilityRole 向辅助技术用户传达组件的用途。

accessibilityRole 可选值包括：

'none' - 元素无特定角色时使用
'button' - 元素应作为按钮处理时使用
'link' - 元素应作为链接处理时使用
'search' - 文本字段元素需同时作为搜索框处理时使用
'image' - 元素应作为图像处理时使用（例如可与按钮或链接组合）
'keyboardkey' - 元素充当键盘按键时使用
'text' - 元素应作为不可更改的静态文本处理时使用
'adjustable' - 元素支持数值调整时使用（如滑块）
'imagebutton' - 元素同时作为按钮和图像处理时使用
'header' - 元素作为内容区块标题时使用（例如导航栏标题）
'summary' - 当元素可用于在应用首次启动时提供当前状态的快速摘要时使用。
'alert' - 当元素包含需要向用户展示的重要文本时使用。
'checkbox' - 当元素代表可被选中、未选中或混合选中状态的复选框时使用。
'combobox' - 当元素代表组合框（允许用户从多个选项中选择）时使用。
'menu' - 当组件是选择菜单时使用。
'menubar' - 当组件是多个菜单的容器时使用。
'menuitem' - 用于表示菜单内的单个选项。
'progressbar' - 用于表示任务进度的组件。
'radio' - 用于表示单选按钮。
'radiogroup' - 用于表示一组单选按钮。
'scrollbar' - 用于表示滚动条。
'spinbutton' - 用于表示可展开选项列表的按钮。
'switch' - 用于表示可开关的切换按钮。
'tab' - 用于表示标签页。
'tablist' - 用于表示标签页列表。
'timer' - 用于表示计时器。
'toolbar' - 用于表示工具栏（操作按钮或组件的容器）。
'grid' - 与 ScrollView、VirtualizedList、FlatList 或 SectionList 结合使用表示网格布局（为 Android GridView 添加网格内/外播报功能）

Type
string

`accessibilityState`

向辅助技术用户描述组件的当前状态。

更多信息请参阅无障碍功能指南。

Type
object: `{disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}`

`accessibilityValue`

表示组件的当前值。可以是组件值的文本描述，对于基于范围的组件（如滑块和进度条），则包含范围信息（最小值、当前值和最大值）

更多信息请参阅辅助功能指南。

Type
object: `{min: number, max: number, now: number, text: string}`

`accessibilityViewIsModal`
iOS

指示 VoiceOver 是否应忽略接收器同级视图中的元素，默认值为 false。

更多信息请参阅无障碍功能指南。

Type
bool

`accessible`

当设置为 true 时，表示该视图是无障碍元素，可通过屏幕阅读器和硬件键盘等辅助技术发现。默认情况下所有可触摸元素均具备无障碍特性。

更多信息请参阅无障碍功能指南。

`aria-busy`

表示元素正在更新中，辅助技术可能需要等待变更完成后再通知用户。

Type	Default
boolean	false

`aria-checked`

表示可勾选元素的状态。该字段可接受布尔值或 "mixed" 字符串（表示混合状态的复选框）。

Type	Default
boolean, 'mixed'	false

`aria-disabled`

表示元素可见但处于禁用状态，因此不可编辑或操作。

Type	Default
boolean	false

`aria-expanded`

指示可展开元素当前是展开还是折叠状态。

Type	Default
boolean	false

`aria-hidden`

表示此无障碍元素内包含的子元素是否隐藏

例如：在包含兄弟视图 A 和 B 的窗口中，将视图 B 的 aria-hidden 设为 true 会使 VoiceOver 忽略视图 B 内的元素。

Type	Default
boolean	false

`aria-label`

定义用于标记交互元素的字符串值。

Type
string

`aria-labelledby`
Android

标识标记当前元素的关联元素。aria-labelledby 的值应匹配关联元素的 nativeID：

tsx
<View>
  <Text nativeID="formLabel">Label for Input Field</Text>
  <TextInput aria-label="input" aria-labelledby="formLabel" />
</View>

Type
string

`aria-live`
Android

表示元素将被更新，并描述用户代理、辅助技术和用户可以从实时区域中预期的更新类型。

off 辅助服务不应播报此视图的变更
polite 辅助服务应播报此视图的变更
assertive 无障碍服务应中断当前语音播报，立即宣布该视图的变更。

Type	Default
enum(`'assertive'`, `'off'`, `'polite'`)	`'off'`

`aria-modal`
iOS

布尔值，指示 VoiceOver 是否应忽略接收器同级视图内的元素。优先级高于 accessibilityViewIsModal 属性。

Type	Default
boolean	false

`aria-selected`

指示可选元素当前是否被选中。

Type
boolean

`aria-valuemax`

表示基于范围的组件（如滑块和进度条）的最大值。优先级高于 accessibilityValue 属性中的 max 值。

Type
number

`aria-valuemin`

表示基于范围的组件（如滑块和进度条）的最小值。优先级高于 accessibilityValue 属性中的 min 值。

Type
number

`aria-valuenow`

表示基于范围的组件（如滑块和进度条）的当前值。优先级高于 accessibilityValue 属性中的 now 值。

Type
number

`aria-valuetext`

表示组件的文本描述。优先级高于 accessibilityValue 属性中的 text 值。

Type
string

`collapsable`

仅用于布局子元素或不绘制任何内容的视图，可能会作为优化项自动从原生层级中移除。将此属性设为 false 可禁用此优化，确保该 View 保留在原生视图层级中。

Type	Default
boolean	true

`collapsableChildren`

设为 false 可阻止该视图的直接子元素从原生视图层级中移除，效果等同于为每个子元素设置 collapsable={false}。

Type	Default
boolean	true

`focusable`
Android

是否允许此 View 通过非触摸输入设备（如硬件键盘）获取焦点。

Type
boolean

`hitSlop`

定义触摸事件可超出视图边界的触发范围。典型界面规范建议触摸目标至少为 30-40 点/密度无关像素。

例如：若可触摸视图高度为 20，通过设置 hitSlop={{top: 10, bottom: 10, left: 0, right: 0}} 可将可触摸高度扩展至 40

触摸区域永远不会超出父视图边界，当触摸点命中两个重叠视图时，兄弟视图的 Z-index 始终优先

Type
object: `{top: number, left: number, bottom: number, right: number}`

`id`

用于从原生类定位此视图。优先级高于 nativeID 属性。

这将禁用对此视图的"仅布局视图移除"优化！

Type
string

`importantForAccessibility`
Android

控制视图对无障碍功能的重要性（是否触发无障碍事件/是否被无障碍服务检测）。仅适用于 Android。

可选值：

'auto' - 由系统决定视图对无障碍功能的重要性（默认推荐）
'yes' - 视图对无障碍功能重要
'no' - 视图对无障碍功能不重要
'no-hide-descendants' - 视图及其所有子视图对无障碍功能均不重要

参考 Android importantForAccessibility 文档。

Type
enum('auto', 'yes', 'no', 'no-hide-descendants')

`nativeID`

用于从原生类定位此视图。

这将禁用对此视图的"仅布局视图移除"优化！

Type
string

`needsOffscreenAlphaCompositing`

此 View 是否需要离屏渲染并通过 alpha 合成来确保颜色和混合行为的 100% 准确性。默认值 (false) 会回退为：在绘制每个元素时直接应用 alpha 值（而非将整个组件离屏渲染后再通过 alpha 合成）。当设置透明度的 View 包含多个重叠元素（如多个重叠 Views 或文本与背景）时，默认行为可能导致可见瑕疵。

为了保留正确的 alpha 行为而进行离屏渲染的代价极高，且对非原生开发者难以调试，因此默认未启用此功能。如果确实需要为动画启用此属性，请考虑在视图内容为静态（即不需要每帧重绘）时与 renderToHardwareTextureAndroid 结合使用。启用该属性后，该视图将离屏渲染一次并保存为硬件纹理，随后每帧通过 alpha 合成到屏幕上，无需在 GPU 上切换渲染目标。

Type
bool

`nextFocusDown`
Android

指定用户向下导航时接收焦点的下一个视图。详见 Android 文档。

Type
number

`nextFocusForward`
Android

指定用户向前导航时接收焦点的下一个视图。详见 Android 文档。

Type
number

`nextFocusLeft`
Android

指定用户向左导航时接收焦点的下一个视图。详见 Android 文档。

Type
number

`nextFocusRight`
Android

指定用户向右导航时接收焦点的下一个视图。详见 Android 文档。

Type
number

`nextFocusUp`
Android

指定用户向上导航时接收焦点的下一个视图。详见 Android 文档。

Type
number

`onAccessibilityAction`

当用户执行辅助操作时触发，该函数接收的唯一参数是包含要执行操作名称的事件对象。

详见辅助功能指南。

Type
function

`onAccessibilityEscape`
iOS

当 accessible 为 true 时，用户执行返回手势（escape gesture）将触发此函数。

Type
function

`onAccessibilityTap`
iOS

当 accessible 为 true 时，用户执行无障碍点击手势（accessibility tap）将尝试触发此函数。

Type
function

`onLayout`

在挂载时和布局变化时触发。

该事件在布局计算完成后立即触发，但由于布局动画可能仍在进行中，屏幕显示可能尚未更新为新布局。

Type
`({nativeEvent: LayoutEvent}) => void`

`onMagicTap`
iOS

当 accessible 为 true 时，用户执行魔法点击手势（magic tap）将触发此函数。

Type
function

`onMoveShouldSetResponder`

该视图是否希望“声明”触摸响应？当View不是响应者时，每次在其上的触摸移动都会触发此回调。

Type
`({nativeEvent: PressEvent}) => boolean`

`onMoveShouldSetResponderCapture`

若父 View 希望阻止子 View 在移动时成为响应者，应设置此处理函数并返回 true。

Type
`({nativeEvent: PressEvent}) => boolean`

`onResponderGrant`

视图已开始响应触摸事件。此时应高亮显示并向用户展示交互反馈。

在 Android 上，从此回调返回 true 可阻止其他原生组件在此响应终止前成为响应者。

Type
`({nativeEvent: PressEvent}) => void ｜ boolean`

`onResponderMove`

用户移动手指时触发。

Type
`({nativeEvent: PressEvent}) => void`

`onResponderReject`

另一个响应器已处于活动状态，且不会释放给请求成为响应器的 View。

Type
`({nativeEvent: PressEvent}) => void`

`onResponderRelease`

触摸结束时触发。

Type
`({nativeEvent: PressEvent}) => void`

`onResponderTerminate`

View 的响应者身份已被剥夺。可能因 onResponderTerminationRequest 调用后被其他视图获取，也可能被系统直接剥夺（例如 iOS 控制中心/通知中心触发时）。

Type
`({nativeEvent: PressEvent}) => void`

`onResponderTerminationRequest`

当其他 View 请求成为响应器并要求当前 View 释放响应权时触发。返回 true 表示允许释放。

Type
`({nativeEvent: PressEvent}) => void`

`onStartShouldSetResponder`

该视图是否希望在触摸开始时成为响应器？

Type
`({nativeEvent: PressEvent}) => boolean`

`onStartShouldSetResponderCapture`

若父 View 需要阻止子 View 在触摸开始时成为响应器，应设置此处理程序并返回 true。

Type
`({nativeEvent: PressEvent}) => boolean`

`pointerEvents`

控制 View 是否可以接收触摸事件

'auto': 视图可接收触摸事件
'none': 视图永不接收触摸事件
'box-none'：视图本身不会成为触摸事件目标，但其子视图可以。行为类似 CSS 中的：

css
.box-none {
  pointer-events: none;
}
.box-none * {
  pointer-events: auto;
}

'box-only'：视图本身可成为触摸事件目标，但其子视图不可。行为类似 CSS 中的：

css
.box-only {
  pointer-events: auto;
}
.box-only * {
  pointer-events: none;
}

Type
enum('box-none', 'none', 'box-only', 'auto')

`removeClippedSubviews`

这是 RCTView 公开的保留性能属性，适用于包含大量子视图（多数在屏幕外）的滚动场景。要使此属性生效：

必须应用于包含越界子视图的容器视图
子视图需设置 overflow: hidden
容器视图（或其父视图）也需设置 overflow: hidden

Type
bool

`renderToHardwareTextureAndroid`
Android

该 View 是否应在 GPU 上将其自身（及所有子元素）渲染为单个硬件纹理。

在 Android 上，此属性适用于仅改变透明度/旋转/平移/缩放的场景：此时视图无需重绘且显示列表无需重新执行，纹理可复用并通过不同参数重新合成。注意这会消耗有限的显存，建议在交互/动画结束后重置为 false。

Type
bool

`role`

role 向辅助技术用户传达组件用途，优先级高于 accessibilityRole 属性。

Type
Role

`shouldRasterizeIOS`
iOS

该 View 是否应在合成前渲染为位图。

在 iOS 上，此属性适用于不改变组件尺寸和子元素的场景（如平移静态视图位置）：栅格化允许渲染器复用缓存位图并在每帧快速合成。

栅格化会产生离屏绘制且位图消耗内存，使用前请充分测试和评估性能。

Type
bool

`style`

Type
View Style

`tabIndex`
Android

该 View 是否应可通过非触摸输入设备（例如硬件键盘）获得焦点。支持以下值：

0 - 视图可聚焦
-1 - 视图不可聚焦

Type
enum(0, -1)

`testID`

用于在端到端测试中定位此视图。

这将禁用对此视图的"仅布局视图移除"优化！

Type
string

合成触摸事件
属性

合成触摸事件​

参考

属性​

accessibilityActions​

accessibilityElementsHidden iOS​

accessibilityHint​

accessibilityLanguage iOS​

accessibilityIgnoresInvertColors iOS​

accessibilityLabel​

accessibilityLiveRegion Android​

accessibilityRole​

accessibilityState​

accessibilityValue​

accessibilityViewIsModal iOS​

accessible​

aria-busy​

aria-checked​

aria-disabled​

aria-expanded​

aria-hidden​

aria-label​

aria-labelledby Android​

aria-live Android​

aria-modal iOS​

aria-selected​

aria-valuemax​

aria-valuemin​

aria-valuenow​

aria-valuetext​

collapsable​

collapsableChildren​

focusable Android​

hitSlop​

id​

importantForAccessibility Android​

nativeID​

needsOffscreenAlphaCompositing​

nextFocusDown Android​

nextFocusForward Android​

nextFocusLeft Android​

nextFocusRight Android​

nextFocusUp Android​

onAccessibilityAction​

onAccessibilityEscape iOS​

onAccessibilityTap iOS​

onLayout​

onMagicTap iOS​

onMoveShouldSetResponder​

onMoveShouldSetResponderCapture​

onResponderGrant​

onResponderMove​

onResponderReject​

onResponderRelease​

onResponderTerminate​

onResponderTerminationRequest​

onStartShouldSetResponder​

onStartShouldSetResponderCapture​

pointerEvents​

removeClippedSubviews​

renderToHardwareTextureAndroid Android​

role​

shouldRasterizeIOS iOS​

style​

tabIndex Android​

testID​

合成触摸事件

属性

`accessibilityActions`

`accessibilityElementsHidden`
iOS

`accessibilityHint`

`accessibilityLanguage`
iOS

`accessibilityIgnoresInvertColors`
iOS

`accessibilityLabel`

`accessibilityLiveRegion`
Android

`accessibilityRole`

`accessibilityState`

`accessibilityValue`

`accessibilityViewIsModal`
iOS

`accessible`

`aria-busy`

`aria-checked`

`aria-disabled`

`aria-expanded`

`aria-hidden`

`aria-label`

`aria-labelledby`
Android

`aria-live`
Android

`aria-modal`
iOS

`aria-selected`

`aria-valuemax`

`aria-valuemin`

`aria-valuenow`

`aria-valuetext`

`collapsable`

`collapsableChildren`

`focusable`
Android

`hitSlop`

`id`

`importantForAccessibility`
Android

`nativeID`

`needsOffscreenAlphaCompositing`

`nextFocusDown`
Android

`nextFocusForward`
Android

`nextFocusLeft`
Android

`nextFocusRight`
Android

`nextFocusUp`
Android

`onAccessibilityAction`

`onAccessibilityEscape`
iOS

`onAccessibilityTap`
iOS

`onLayout`

`onMagicTap`
iOS

`onMoveShouldSetResponder`

`onMoveShouldSetResponderCapture`

`onResponderGrant`

`onResponderMove`

`onResponderReject`

`onResponderRelease`

`onResponderTerminate`

`onResponderTerminationRequest`

`onStartShouldSetResponder`

`onStartShouldSetResponderCapture`

`pointerEvents`

`removeClippedSubviews`

`renderToHardwareTextureAndroid`
Android

`role`

`shouldRasterizeIOS`
iOS

`style`

`tabIndex`
Android

`testID`