跳到主要内容

View

作为构建 UI 最基础的组件,View 是一个容器,支持使用 flexbox 进行布局、样式触摸事件处理无障碍功能控制。View 直接映射到 React Native 运行平台上的原生视图等效项,无论是 UIView<div>android.view 等等。

View 被设计为可以嵌套在其他视图中,并且可以拥有 0 到多个任意类型的子组件。

这个示例创建了一个 View,它包裹了两个带颜色的方块和一个文本组件,它们以带内边距的行排列。

View 组件设计用于与 StyleSheet 一起使用以提高清晰度和性能,但也支持内联样式。

合成触摸事件

对于 View 响应器 props(例如 onResponderMove),传递给它们的合成触摸事件是 PressEvent 形式。


参考

Props


accessibilityActions

无障碍操作允许辅助技术以编程方式调用组件的操作。accessibilityActions 属性应包含一个操作对象列表。每个操作对象应包含字段名和标签。

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

类型
数组

accessibilityElementsHidden
iOS

一个布尔值,表示此无障碍元素中包含的无障碍元素是否被隐藏。默认为 false

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

类型
bool

accessibilityHint

无障碍提示可帮助用户理解在无障碍元素上执行操作时会发生什么,尤其当操作结果从无障碍标签中不明确时。

类型
string

accessibilityLanguage
iOS

一个布尔值,指示当用户与元素交互时,屏幕阅读器应使用的语言。它应遵循 BCP 47 规范

更多信息请参见 iOS accessibilityLanguage 文档

类型
string

accessibilityIgnoresInvertColors
iOS

一个布尔值,指示此视图在颜色反转开启时是否应反转。值为 true 表示即使颜色反转开启,视图也不应反转。

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

类型
bool

accessibilityLabel

覆盖屏幕阅读器在用户与元素交互时朗读的文本。默认情况下,标签是通过遍历所有子组件并将所有 Text 节点用空格分隔累积而成的。

类型
string

accessibilityLiveRegion
Android

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

  • 'none' - 无障碍服务不应宣布此视图的更改。
  • 'polite' - 无障碍服务应宣布此视图的更改。
  • 'assertive' - 无障碍服务应中断正在进行的语音,立即宣布此视图的更改。

更多信息请参见Android View 文档

类型
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 添加进/出网格的宣布。
类型
string

accessibilityState

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

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

类型
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}

accessibilityValue

表示组件的当前值。它可以是组件值的文本描述,或者对于基于范围的组件(如滑块和进度条),它包含范围信息(最小值、当前值和最大值)。

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

类型
object: {min: number, max: number, now: number, text: string}

accessibilityViewIsModal
iOS

一个布尔值,指示 VoiceOver 是否应忽略接收者同级视图中的元素。默认为 false

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

类型
bool

accessible

当为 true 时,表示该视图是一个无障碍元素,并且可被屏幕阅读器和硬件键盘等辅助技术发现。默认情况下,所有可触摸元素都是可访问的。

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


aria-busy

指示元素正在被修改,辅助技术可能希望等待更改完成后再通知用户有关更新。

类型默认值
booleanfalse

aria-checked

指示可选中元素的状态。此字段可以接受布尔值或字符串 "mixed" 来表示混合状态的复选框。

类型默认值
boolean, 'mixed'false

aria-disabled

指示元素可感知但已禁用,因此不可编辑或以其他方式操作。

类型默认值
booleanfalse

aria-expanded

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

类型默认值
booleanfalse

aria-hidden

指示此无障碍元素中包含的无障碍元素是否被隐藏。

例如,在一个包含同级视图 AB 的窗口中,将视图 Baria-hidden 设置为 true 会导致 VoiceOver 忽略视图 B 中的元素。

类型默认值
booleanfalse

aria-label

定义一个字符串值,用作交互元素的标签。

类型
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>
类型
string

aria-live
Android

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

  • off 无障碍服务不应宣布此视图的更改。
  • polite 无障碍服务应宣布此视图的更改。
  • assertive 无障碍服务应中断正在进行的语音,立即宣布此视图的更改。
类型默认值
enum('assertive', 'off', 'polite')'off'

aria-modal
iOS

布尔值,指示 VoiceOver 是否应忽略接收者同级视图中的元素。优先级高于 accessibilityViewIsModal prop。

类型默认值
booleanfalse

aria-selected

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

类型
boolean

aria-valuemax

表示基于范围的组件(如滑块和进度条)的最大值。优先级高于 accessibilityValue prop 中的 max 值。

类型
number

aria-valuemin

表示基于范围的组件(如滑块和进度条)的最小值。优先级高于 accessibilityValue prop 中的 min 值。

类型
number

aria-valuenow

表示基于范围的组件(如滑块和进度条)的当前值。优先级高于 accessibilityValue prop 中的 now 值。

类型
number

aria-valuetext

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

类型
string

collapsable

仅用于布局其子组件或不绘制任何内容的视图可能会作为优化自动从原生层级结构中移除。将此属性设置为 false 可禁用此优化,并确保此 View 存在于原生视图层级结构中。

类型默认值
booleantrue

collapsableChildren

设置为 false 可以防止视图的直接子组件从原生视图层级结构中移除,类似于在每个子组件上设置 collapsable={false} 的效果。

类型默认值
booleantrue

focusable
Android

View 是否应可使用非触摸输入设备(例如通过硬件键盘接收焦点)。

类型
boolean

hitSlop

这定义了触摸事件可以从视图开始的距离。典型的界面指南建议触摸目标至少为 30-40 点/密度无关像素。

例如,如果一个可触摸视图的高度为 20,可以使用 hitSlop={{top: 10, bottom: 10, left: 0, right: 0}} 将可触摸高度扩展到 40。

触摸区域永远不会超出父视图边界,如果触摸命中了两个重叠的视图,同级视图的 Z 轴顺序始终优先。

类型
object: {top: number, left: number, bottom: number, right: number}

id

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

这会为此视图禁用“仅布局视图移除”优化!

类型
string

importantForAccessibility
Android

控制视图对于无障碍功能的重要性,即它是否触发无障碍事件以及是否向查询屏幕的无障碍服务报告。仅适用于 Android。

可能的值:

  • 'auto' - 系统决定视图对于无障碍功能是否重要 - 默认值(推荐)。
  • 'yes' - 视图对于无障碍功能很重要。
  • 'no' - 视图对于无障碍功能不重要。
  • 'no-hide-descendants' - 视图及其任何后代视图对于无障碍功能都不重要。

更多信息请参见Android importantForAccessibility 文档

类型
enum('auto', 'yes', 'no', 'no-hide-descendants')

nativeID

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

这会为此视图禁用“仅布局视图移除”优化!

类型
string

needsOffscreenAlphaCompositing

View 是否需要离屏渲染并使用 alpha 合成,以保留 100% 正确的颜色和混合行为。默认值(false)会回退到对用于绘制每个元素的画笔应用 alpha 值来绘制组件及其子组件,而不是将整个组件离屏渲染并使用 alpha 值重新合成。在您设置不透明度的 View 包含多个重叠元素(例如多个重叠的 View 或文本和背景)的情况下,此默认设置可能会很明显且不受欢迎。

为了保留正确的 alpha 行为而进行离屏渲染非常耗费资源,并且对于非原生开发者来说很难调试,这就是默认不开启它的原因。如果确实需要在动画中启用此属性,并且视图内容是静态的(即不需要每帧重新绘制),请考虑将其与 renderToHardwareTextureAndroid 结合使用。如果启用该属性,此 View 将离屏渲染一次,保存在硬件纹理中,然后在每帧使用 alpha 合成到屏幕上,而无需在 GPU 上切换渲染目标。

类型
bool

nextFocusDown
Android

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

类型
number

nextFocusForward
Android

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

类型
number

nextFocusLeft
Android

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

类型
number

nextFocusRight
Android

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

类型
number

nextFocusUp
Android

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

类型
number

onAccessibilityAction

用户执行无障碍操作时调用。此函数唯一的参数是包含要执行的操作名称的事件。

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

类型
function

onAccessibilityEscape
iOS

accessibletrue 时,系统会在用户执行退出手势时调用此函数。

类型
function

onAccessibilityTap
iOS

accessible 为 true 时,系统会在用户执行无障碍点击手势时尝试调用此函数。

类型
function

onLayout

在挂载和布局更改时调用。

此事件在布局计算完成后立即触发,但在接收到事件时,新的布局可能尚未反映在屏幕上,尤其是在布局动画正在进行时。

类型
({nativeEvent: LayoutEvent}) => void

onMagicTap
iOS

accessibletrue 时,系统会在用户执行魔法点击手势时调用此函数。

类型
function

onMoveShouldSetResponder

此视图是否希望“声明”触摸响应能力?当 View 不是响应者时,每次触摸移动都会调用此函数。

类型
({nativeEvent: PressEvent}) => boolean

onMoveShouldSetResponderCapture

如果父 View 希望阻止子 View 在移动时成为响应者,它应该具有此处理程序并返回 true

类型
({nativeEvent: PressEvent}) => boolean

onResponderGrant

View 现在正在响应触摸事件。这是高亮显示并向用户展示正在发生什么的时机。

在 Android 上,从此回调返回 true 可以防止任何其他原生组件成为响应者,直到此响应者终止。

类型
({nativeEvent: PressEvent}) => void | boolean

onResponderMove

用户正在移动手指。

类型
({nativeEvent: PressEvent}) => void

onResponderReject

另一个响应者已经活跃,不会将其释放给请求成为响应者的 View

类型
({nativeEvent: PressEvent}) => void

onResponderRelease

在触摸结束时触发。

类型
({nativeEvent: PressEvent}) => void

onResponderTerminate

响应者已从 View 中被取走。可能在调用 onResponderTerminationRequest 后被其他视图取走,或者可能由操作系统在未询问的情况下取走(例如,在 iOS 上使用控制中心/通知中心时发生)。

类型
({nativeEvent: PressEvent}) => void

onResponderTerminationRequest

其他 View 希望成为响应者,并请求此 View 释放其响应者。返回 true 允许释放。

类型
({nativeEvent: PressEvent}) => void

onStartShouldSetResponder

此视图是否希望在触摸开始时成为响应者?

类型
({nativeEvent: PressEvent}) => boolean

onStartShouldSetResponderCapture

如果父 View 希望阻止子 View 在触摸开始时成为响应者,它应该具有此处理程序并返回 true

类型
({nativeEvent: PressEvent}) => boolean

pointerEvents

控制 View 是否可以成为触摸事件的目标。

  • 'auto': View 可以成为触摸事件的目标。
  • 'none': View 永远不是触摸事件的目标。
  • 'box-none': View 永远不是触摸事件的目标,但其子视图可以是。其行为类似于该视图在 CSS 中具有以下类:
css
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': View 可以成为触摸事件的目标,但其子视图不能。其行为类似于该视图在 CSS 中具有以下类:
css
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}
类型
enum('box-none', 'none', 'box-only', 'auto')

removeClippedSubviews

这是 RCTView 公开的保留性能属性,在有许多子视图(其中大部分在屏幕外)的情况下滚动内容时非常有用。为了使此属性生效,必须将其应用于包含许多超出其边界的子视图的视图。子视图还必须具有 overflow: hidden 样式,包含视图(或其父视图之一)也应如此。

类型
bool

renderToHardwareTextureAndroid
Android

View 是否应将其自身(及其所有子组件)渲染到 GPU 上的单个硬件纹理中。

在 Android 上,这对于仅修改不透明度、旋转、平移和/或缩放的动画和交互很有用:在这些情况下,视图无需重新绘制,显示列表也无需重新执行。纹理可以重复使用并以不同的参数重新合成。缺点是这会占用有限的显存,因此在交互/动画结束时应将此 prop 设置回 false。

类型
bool

role

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

类型
Role

shouldRasterizeIOS
iOS

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

在 iOS 上,这对于不修改此组件尺寸及其子组件的动画和交互很有用;例如,当平移静态视图的位置时,光栅化允许渲染器重用静态视图的缓存位图,并在每帧期间快速合成。

光栅化会产生一次离屏绘制过程,并且位图会消耗内存。使用此属性时请测试和测量。

类型
bool

style

类型
View 样式

tabIndex
Android

View 是否应可使用非触摸输入设备(例如通过硬件键盘接收焦点)。支持以下值:

  • 0 - View 可聚焦
  • -1 - View 不可聚焦
类型
enum(0, -1)

testID

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

这会为此视图禁用“仅布局视图移除”优化!

类型
string