SurfaceViewProps
扩展
ViewProps
属性
accessibilityActions?
optionalaccessibilityActions: readonlyReadonly<{label:string;name:string; }>[]
提供可用于无障碍功能的自定义操作数组。
继承自
ViewProps.accessibilityActions
accessibilityElementsHidden?
optionalaccessibilityElementsHidden:boolean
一个布尔值，表示屏幕阅读器是否隐藏了此无障碍功能元素中包含的无障碍功能元素。
平台
ios
继承自
ViewProps.accessibilityElementsHidden
accessibilityHint?
optionalaccessibilityHint:string
如果用户无法从辅助功能标签中明显看出，在对无障碍功能元素执行操作时会发生什么，无障碍功能提示有助于用户了解具体会发生什么。
继承自
ViewProps.accessibilityHint
accessibilityIgnoresInvertColors?
optionalaccessibilityIgnoresInvertColors:boolean
https://reactnative.dev/docs/accessibility#accessibilityignoresinvertcolorsios
平台
ios
继承自
ViewProps.accessibilityIgnoresInvertColors
accessibilityLabel?
optionalaccessibilityLabel:string
当用户与元素交互时，覆盖屏幕阅读器读取的文本。默认情况下，标签是通过遍历所有子项并累积所有以空格分隔的Text节点来构造的。
继承自
ViewProps.accessibilityLabel
accessibilityLabelledBy?
optionalaccessibilityLabelledBy:string|string[]
对用于构建复杂表单的另一个元素nativeID的引用。accessibilityLabelledBy的值应与相关元素的nativeID相匹配。
平台
android
继承自
ViewProps.accessibilityLabelledBy
accessibilityLanguage?
optionalaccessibilityLanguage:string
通过使用accessibilityLanguage属性，屏幕阅读器将了解在读取元素的标签、值和提示时要使用哪种语言。提供的字符串值必须遵循BCP 47规范 (https://www.rfc-editor.org/info/bcp47)。https://reactnative.dev/docs/accessibility#accessibilitylanguage-ios
平台
ios
继承自
ViewProps.accessibilityLanguage
accessibilityLiveRegion?
optionalaccessibilityLiveRegion:"none"|"polite"|"assertive"
向无障碍功能服务表明此视图更改时是否应通知用户。仅适用于>= 19的Android API。有关参考信息，请参阅http://developer.android.com/reference/android/view/View.html#attr_android:accessibilityLiveRegion（仅提供英文版）。
平台
android
继承自
ViewProps.accessibilityLiveRegion
accessibilityRole?
optionalaccessibilityRole:AccessibilityRole
无障碍功能角色将聚焦的元素类型告诉在iOS上使用VoiceOver或在Android系统上使用TalkBack的用户。
继承自
ViewProps.accessibilityRole
accessibilityState?
optionalaccessibilityState:AccessibilityState
无障碍功能状态将目前聚焦的元素状态告诉在iOS上使用VoiceOver或在Android系统上使用TalkBack的用户。
继承自
ViewProps.accessibilityState
accessibilityValue?
optionalaccessibilityValue:AccessibilityValue
表示组件的当前值。它可以是对组件值的文本描述。对于基于范围的组件，例如滑块和进度条，它包含范围信息（最小值、当前值和最大值）。
继承自
ViewProps.accessibilityValue
accessibilityViewIsModal?
optionalaccessibilityViewIsModal:boolean
一个布尔值，指示VoiceOver是否应忽略视图中与接收者为兄弟关系的元素。
平台
ios
继承自
ViewProps.accessibilityViewIsModal
accessible?
optionalaccessible:boolean
如果为true，则表示视图是无障碍功能元素。默认情况下，所有可触摸元素都可供访问。
继承自
ViewProps.accessible
aria-busy?
optionalaria-busy:boolean
accessibilityState的别名
参见https://reactnative.dev/docs/accessibility#accessibilitystate（仅提供英文版）
继承自
ViewProps.aria-busy
aria-checked?
optionalaria-checked:boolean|"mixed"
继承自
ViewProps.aria-checked
aria-disabled?
optionalaria-disabled:boolean
继承自
ViewProps.aria-disabled
aria-expanded?
optionalaria-expanded:boolean
继承自
ViewProps.aria-expanded
aria-hidden?
optionalaria-hidden:boolean
设置为该值时，指示此无障碍功能元素中包含的无障碍功能元素是否已隐藏。
继承自
ViewProps.aria-hidden
aria-label?
optionalaria-label:string
accessibilityLabel的别名https://reactnative.dev/docs/view#accessibilitylabel https://github.com/facebook/react-native/issues/34424
继承自
ViewProps.aria-label
aria-labelledby?
optionalaria-labelledby:string
表示关联标签文本的nativeID。当辅助技术聚焦于带这种属性的组件时，会大声朗读文本。
平台
android
继承自
ViewProps.aria-labelledby
aria-live?
optionalaria-live:"off"|"polite"|"assertive"
继承自
ViewProps.aria-live
aria-modal?
optionalaria-modal:boolean
继承自
ViewProps.aria-modal
aria-selected?
optionalaria-selected:boolean
继承自
ViewProps.aria-selected
aria-valuemax?
optionalaria-valuemax:number
继承自
ViewProps.aria-valuemax
aria-valuemin?
optionalaria-valuemin:number
继承自
ViewProps.aria-valuemin
aria-valuenow?
optionalaria-valuenow:number
继承自
ViewProps.aria-valuenow
aria-valuetext?
optionalaria-valuetext:string
继承自
ViewProps.aria-valuetext
children?
optionalchildren:ReactNode
继承自
ViewProps.children
collapsable?
optionalcollapsable:boolean
作为优化，可能会自动从原生层次结构中移除仅用于布局子视图或以其他方式不绘制任何内容的视图。将此属性设置为false可禁用此优化并确保该视图存在于原生视图层次结构中。
继承自
ViewProps.collapsable
focusable?
optionalfocusable:boolean
确定此View是否应使用非触摸输入设备设定焦点，例如使用硬件键盘获得焦点。
继承自
ViewProps.focusable
hasTVPreferredFocus?
optionalhasTVPreferredFocus:boolean
（仅限Apple TV） 可以设置为true以迫使Apple TV聚焦引擎将焦点移至该视图。
平台
ios
继承自
ViewProps.hasTVPreferredFocus
hitSlop?
optionalhitSlop:Insets
此项定义了触摸事件可以在距离视图多远的位置开始。典型的接口指南建议触摸目标应至少为每个密度无关像素30-40点。如果可触摸视图的高度为20，则可通过以下操作将其可触摸高度扩展至40。
hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}
注意 触摸区域永远不能超出父视图边界，并且如果触摸时触及两个重叠的视图，则兄弟视图的Z索引始终优先。
继承自
ViewProps.hitSlop
id?
optionalid:string
用于引用原生代码中的react托管视图。
继承自
ViewProps.id
importantForAccessibility?
optionalimportantForAccessibility:"auto"|"yes"|"no"|"no-hide-descendants"
[Android] 控制视图是否触发无障碍功能事件以及是否将其报告给无障碍功能服务。
继承自
ViewProps.importantForAccessibility
isTVSelectable?
optionalisTVSelectable:boolean
（仅限Apple TV） 当设置为true时，此视图通过Apple TV遥控器，将可设定焦点和导航。
平台
ios
继承自
ViewProps.isTVSelectable
nativeID?
optionalnativeID:string
用于引用原生代码中的react托管视图。
继承自
ViewProps.nativeID
needsOffscreenAlphaCompositing?
optionalneedsOffscreenAlphaCompositing:boolean
此View是否需要在屏幕外呈现并使用alpha进行合成，以保持100%正确的颜色和混合行为。默认值 (false) 会回退到组件及其子组件绘制，并在用于绘制每个元素的绘图上应用一个alpha，而不是在屏幕外呈现整个组件并使用alpha值将其合成回来。当您在其中设置不透明度的View有多个重叠元素时（例如，多个重叠的View或文本和背景），这个默认值可能明显不可取。
在屏幕外进行呈现以保持正确的alpha行为成本很高，对于非原生开发者来说很难进行调试，这就是默认情况下不打开它的原因。如果您确实需要为动画启用此属性，并且视图内容是静态的（即不需要重新绘制每帧），可以考虑将其与renderToHardwareTextureAndroid结合使用。如果启用该属性，则此View将在屏幕外呈现一次，保存在硬件纹理中，然后以每帧一个alpha合成到屏幕上，无需在GPU上切换呈现目标。
继承自
ViewProps.needsOffscreenAlphaCompositing
onAccessibilityAction()?
optionalonAccessibilityAction: (event) =>void
当accessible为true时，如果用户执行无障碍功能自定义操作，系统将尝试引用此函数。
参数
event
AccessibilityActionEvent
返回值
void
继承自
ViewProps.onAccessibilityAction
onAccessibilityEscape()?
optionalonAccessibilityEscape: () =>void
当accessible为true时，如果用户执行退出手势（用两根手指推移）时，系统将调用此函数。
返回值
void
平台
ios
继承自
ViewProps.onAccessibilityEscape
onAccessibilityTap()?
optionalonAccessibilityTap: () =>void
当accessible为true时，如果用户执行无障碍功能点击手势，系统将尝试引用此函数。
返回值
void
平台
ios
继承自
ViewProps.onAccessibilityTap
onComponentDidMount?
optionalonComponentDidMount:Function
简述
将SurfaceView挂载到渲染树时调用的事件回调。
onComponentWillUnmount?
optionalonComponentWillUnmount:Function
简述
将SurfaceView从渲染树取消挂载时调用的事件回调。
onLayout()?
optionalonLayout: (event) =>void
在挂载和布局发生变化时通过
{nativeEvent: { layout: {x, y, width, height}}}来引用。
参数
event
LayoutChangeEvent
返回值
void
继承自
ViewProps.onLayout
onMagicTap()?
optionalonMagicTap: () =>void
当accessible为true时，如果用户执行魔法点击手势，系统将引用此函数。
返回值
void
平台
ios
继承自
ViewProps.onMagicTap
onMoveShouldSetResponder()?
optionalonMoveShouldSetResponder: (event) =>boolean
当视图不是响应器时，为视图上的每个触摸移动调用：此视图是否要“声明”触摸响应能力？
参数
event
GestureResponderEvent
返回值
boolean
继承自
ViewProps.onMoveShouldSetResponder
onMoveShouldSetResponderCapture()?
optionalonMoveShouldSetResponderCapture: (event) =>boolean
使用冒泡模式调用onStartShouldSetResponder和onMoveShouldSetResponder，其中最深的节点最先被调用。这意味着，当*ShouldSetResponder处理程序的多个视图返回true时，最深的组件将成为响应器。在大多数情况下，这是可取的，因为这样可以确保所有控件和按钮都可用。
但是，有时父项会希望确保自身成为响应器。这可以通过使用捕获阶段来处理。在响应器系统从位置最深的组件处上移之前，它将执行捕获阶段，触发on*ShouldSetResponderCapture。因此，如果父视图想要防止子项在触摸启动时成为响应器，它应该有一个返回true的处理程序onStartShouldSetResponderCapture。
参数
event
GestureResponderEvent
返回值
boolean
继承自
ViewProps.onMoveShouldSetResponderCapture
onPointerCancel()?
optionalonPointerCancel: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerCancel
onPointerCancelCapture()?
optionalonPointerCancelCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerCancelCapture
onPointerDown()?
optionalonPointerDown: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerDown
onPointerDownCapture()?
optionalonPointerDownCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerDownCapture
onPointerEnter()?
optionalonPointerEnter: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerEnter
onPointerEnterCapture()?
optionalonPointerEnterCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerEnterCapture
onPointerLeave()?
optionalonPointerLeave: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerLeave
onPointerLeaveCapture()?
optionalonPointerLeaveCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerLeaveCapture
onPointerMove()?
optionalonPointerMove: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerMove
onPointerMoveCapture()?
optionalonPointerMoveCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerMoveCapture
onPointerUp()?
optionalonPointerUp: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerUp
onPointerUpCapture()?
optionalonPointerUpCapture: (event) =>void
参数
event
PointerEvent
返回值
void
继承自
ViewProps.onPointerUpCapture
onResponderEnd()?
optionalonResponderEnd: (event) =>void
如果View返回true并尝试成为响应器，则会发生以下情况之一：
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderEnd
onResponderGrant()?
optionalonResponderGrant: (event) =>void
视图现在正在响应触摸事件。此时会突出显示并向用户展示正在发生的情况
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderGrant
onResponderMove()?
optionalonResponderMove: (event) =>void
用户正在移动其手指
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderMove
onResponderReject()?
optionalonResponderReject: (event) =>void
现在还有其他项为响应者，不会将其释放
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderReject
onResponderRelease()?
optionalonResponderRelease: (event) =>void
触摸结束时触发，即“touchUp”
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderRelease
onResponderStart()?
optionalonResponderStart: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderStart
onResponderTerminate()?
optionalonResponderTerminate: (event) =>void
已从视图中删除响应者。响应器角色可能在调用onResponderTerminationRequest后被其他视图获取，也可能在未经询问的情况下被操作系统获取（iOS上的控制中心/通知中心会发生这种情况）
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onResponderTerminate
onResponderTerminationRequest()?
optionalonResponderTerminationRequest: (event) =>boolean
还有其他项希望成为响应者。这个视图应该释放响应器角色吗？ 如果返回true，则允许释放
参数
event
GestureResponderEvent
返回值
boolean
继承自
ViewProps.onResponderTerminationRequest
onStartShouldSetResponder()?
optionalonStartShouldSetResponder: (event) =>boolean
这个视图是否希望在触摸开始时成为响应器？
参数
event
GestureResponderEvent
返回值
boolean
继承自
ViewProps.onStartShouldSetResponder
onStartShouldSetResponderCapture()?
optionalonStartShouldSetResponderCapture: (event) =>boolean
使用冒泡模式调用onStartShouldSetResponder和onMoveShouldSetResponder，其中最深的节点最先被调用。这意味着，当*ShouldSetResponder处理程序的多个视图返回true时，最深的组件将成为响应器。在大多数情况下，这是可取的，因为这样可以确保所有控件和按钮都可用。
但是，有时父项会希望确保自身成为响应器。这可以通过使用捕获阶段来处理。在响应器系统从位置最深的组件处上移之前，它将执行捕获阶段，触发on*ShouldSetResponderCapture。因此，如果父视图想要防止子项在触摸启动时成为响应器，它应该有一个返回true的处理程序onStartShouldSetResponderCapture。
参数
event
GestureResponderEvent
返回值
boolean
继承自
ViewProps.onStartShouldSetResponderCapture
onSurfaceViewCreated()?
optionalonSurfaceViewCreated: (surfaceViewHandle) =>void
参数
surfaceViewHandle
string
返回值
void
简述
一个事件回调，在创建底层原生表面视图时
- 调用。
- @param[in]
surfaceViewHandle
onSurfaceViewDestroyed()?
optionalonSurfaceViewDestroyed: (surfaceViewHandle) =>void
参数
surfaceViewHandle
string
返回值
void
简述
以及在底层原生表面视图被销毁时调用的事件回调。@param[in] surfaceViewHandle提供给播放器以渲染视频的表面视图句柄。
onTouchCancel()?
optionalonTouchCancel: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onTouchCancel
onTouchEnd()?
optionalonTouchEnd: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onTouchEnd
onTouchEndCapture()?
optionalonTouchEndCapture: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onTouchEndCapture
onTouchMove()?
optionalonTouchMove: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onTouchMove
onTouchStart()?
optionalonTouchStart: (event) =>void
参数
event
GestureResponderEvent
返回值
void
继承自
ViewProps.onTouchStart
pointerEvents?
optionalpointerEvents:"auto"|"box-none"|"none"|"box-only"
在没有auto属性的情况下，没有一项可以像CSS的none值一样。box-none就如同应用了CSS类一样：
.box-none { pointer-events: none; } .box-none * { pointer-events: all; }
box-only等同于
.box-only { pointer-events: all; } .box-only * { pointer-events: none; }
但是由于pointerEvents不影响布局/外观，而且我们已经通过添加其他模式而偏离规范，因此我们选择在style上不包含pointerEvents。在某些平台上，无论如何我们都需要将其实现为className。是否使用style是平台的实现细节。
继承自
ViewProps.pointerEvents
removeClippedSubviews?
optionalremoveClippedSubviews:boolean
这是RCTView公开的特殊性能属性，当有许多子视图（其中大多数在屏幕外）时，对于滚动内容很有用。要使此属性生效，必须将其应用于包含许多扩展到其边界之外的子视图的视图。子视图还必须有overflow: hidden，包含视图（或其superview之一）也是如此。
继承自
ViewProps.removeClippedSubviews
renderToHardwareTextureAndroid?
optionalrenderToHardwareTextureAndroid:boolean
此视图是否应将自身（及其所有子视图）渲染为GPU上的单个硬件纹理。
在Android上，这对于仅修改不透明度、旋转、平移和/或比例的动画和交互非常有用：在这些情况下，无需重绘视图，也不需要重新执行显示列表。纹理可以重复使用，并使用不同的参数进行重新合成。缺点是这会占用有限的视频内存，因此应在交互/动画结束时将此属性设置回false。
继承自
ViewProps.renderToHardwareTextureAndroid
role?
optionalrole:Role
指示无障碍功能服务将用户界面组件视为特定角色。
继承自
ViewProps.role
scalingmode?
optionalscalingmode:"fill"|"none"|"fit"|"strech"
简述
为渲染的视频配置缩放模式。缩放模式支持如下所示项。“none”： 不缩放。它保留输入大小。“fit”： 缩放缓冲区以匹配窗口大小，同时保持宽高比和中心位置。“strech”： 缩放缓冲区以适应窗口，最初不进行裁剪。向上扩展到窗口边界之外将拉伸dst rect，多余部分将裁剪到窗口边界。宽高比和中心位置保持 “fill”： 缩放缓冲区以填充整个窗口，保持其宽高比并在顶部/底部/左侧/右侧隐藏任何溢出部分。默认值：“strech”
shouldRasterizeIOS?
optionalshouldRasterizeIOS:boolean
在合成之前，是否应将此视图渲染为位图。
在iOS上，这对于不修改此组件尺寸或其子组件的动画和交互非常有用；例如，在转换静态视图的位置时，栅格化允许渲染器重用静态视图的缓存位图并在每一帧期间快速合成该位图。
栅格化会产生屏幕外绘制过程，位图会消耗内存。使用此属性时进行测试和测量。
继承自
ViewProps.shouldRasterizeIOS
style?
optionalstyle:StyleProp<ViewStyle>
继承自
ViewProps.style
testID?
optionaltestID:string
用于在端到端测试中定位此视图。
继承自
ViewProps.testID
tvParallaxMagnification?
optionaltvParallaxMagnification:number
（仅限Apple TV） 可用于在该视图获得焦点或失焦时更改Apple TV视差效果的外观。默认值为1.0。
平台
ios
继承自
ViewProps.tvParallaxMagnification
tvParallaxProperties?
optionaltvParallaxProperties:TVParallaxProperties
（仅限Apple TV） 具有控制Apple TV视差效果的属性的对象。
平台
ios
继承自
ViewProps.tvParallaxProperties
tvParallaxShiftDistanceX?
optionaltvParallaxShiftDistanceX:number
（仅限Apple TV） 可用于在该视图获得焦点或失焦时更改Apple TV视差效果的外观。默认值为2.0。
平台
ios
继承自
ViewProps.tvParallaxShiftDistanceX
tvParallaxShiftDistanceY?
optionaltvParallaxShiftDistanceY:number
（仅限Apple TV） 可用于在该视图获得焦点或失焦时更改Apple TV视差效果的外观。默认值为2.0。
平台
ios
继承自
ViewProps.tvParallaxShiftDistanceY
tvParallaxTiltAngle?
optionaltvParallaxTiltAngle:number
（仅限Apple TV） 可用于在该视图获得焦点或失焦时更改Apple TV视差效果的外观。默认值为0.05。
平台
ios
继承自
ViewProps.tvParallaxTiltAngle
Last updated: 2025年10月2日
