View
View
是构建UI最基础的组件,支持flexbox
、style
、触摸事件处理、以及无障碍使用操作等。View
组件会自动映射到React Native所运行的平台上的基础视图控件。
合成触摸事件
View
响应时,会有一个event
对象作为函数参数传递,该对象有一个nativeEvent
属性,类型为对象,格式为:
nativeEvent
:changedTouches
: 自上一次事件之后所有的触摸事件数组identifier
: 触摸事件IDlocationX
: 响应事件的组件内触发点x坐标locationY
: 响应事件的组件内触发点y坐标pageX
: 响应事件触发点在根组件内x坐标pageY
: 响应事件触发点在根组件内y坐标target
: 接收触摸事件的元素节点idtimestamp
: 触摸事件时间标记,对速度计算很有用touches
: 当前屏幕上所有的触摸事件集合layout
: {x, y, width, height}
属性
onLayout
:当布局被重新计算时调用此属性指定的函数(新布局可能还并未被展示)。函数类型,非必需,赋值类型为event => {}
onStartShouldSetResponder
:当用户点击开始时,是否需要将组建设置为响应者。不设置默认为false
。父子组件同时实现此函数,子组件优先响应。函数类型,非必需,赋值:event => [true | false]
onStartShouldSetResponderCapture
:当点击开始时,父组件是否需要截获此点击事件。如果返回true
,则子组件无法响应此事件。父组件实现了此函数返回true
截获点击事件,则子组件的此函数均无效。函数类型,非必需,赋值:event => [true | false]
onMoveShouldSetResponder
:当用户执行滑动操作时,组件是否需要成为响应者。父组件实现了此函数,可以在滑动时截获子组件的响应而成为响应者。如果父组件先成为了响应者,即使子组件实现了此函数,子组件也不会成为响应者。函数类型,非必需,赋值:event => [true | false]
onMoveShouldSetResponderCapture
:当用户执行滑动操作时,组件是否需要截获此事件成为响应者。父子组件同时实现,父组件优先截获。函数类型,非必需,赋值:event => [true | false]
onResponderGrant
:组件获取到触摸事件焦点时的回调。函数类型,非必需,赋值:event => {}
onResponderMove
:用户执行滑动操作时的持续回调。函数类型,非必需,赋值:event => {}
onResponderRelease
:触摸事件结束时的回调。函数类型,非必需,赋值:event => {}
onResponderTerminate
:触摸事件意外终止时的回调函数(例如接到电话)。函数类型,非必需,赋值:event => {}
accessible
:是否支持无障碍操作。boolean
类型,非必需,默认false
pointerEvents
:组件响应类型,枚举类型,非必需。取值:auto
:此组件可以成为事件响应者none
:此组件不可以成为事件响应者box-none
:此组件不可以成为响应者,但其子组件可以成为响应者box-only
:此组件可以成为响应者,但其子组件不可以成为响应者
Button
对于需要高度自定义化的Button
,使用TouchableOpacity
或TouchableNativeNeedFeedback
。基础的Button
仅支持轻微的自订化。
属性
onPress
:一次完整的点击事件(从按下到松开)触发结束后执行的回调函数。函数类型,必需title
:按钮标题文字color
:按钮文字颜色disabled
:是否禁用点击交互accessibilityLabel
:盲人模式无障碍操作提示内容,string
类型,非必需
TouchableHighlight
让多个视图组件可以正确响应触摸事件的容器。当组件被按下时,被包括的内容的透明度会降低,从而让底色被显示出来,从而展示出高亮效果。
此组件在被包裹组件之外有一个underlay
组件,用以展示高亮时的颜色。如果使用不正确,可能会有意外的视觉效果。
TouchableHighlight
需要有且仅有一个子节点。如果需要包含多个子组件,可以用一个容器包起来。
属性
onLayout
:同View
onPress
:同Button
onPressIn
:点击事件触发用户刚刚按下时的回调函数。此函数在onPress
之前被调用,可以在这里执行网络请求相关操作。函数类型,非必需。赋值event => {}
onPressOut
:点击事件结束用户松开时的回调函数。此函数在onPress
之后调用。函数类型,非必需。赋值event => {}
onLongPress
:用户执行了长按操作后的回调函数。同时设置了长按与点击,当长按事件触发时,点击事件不会被触发。函数类型,非必需。赋值event => {}
disabled
:同Button
activeOpacity
:组件被点击时,对子组件的透明度执行的改变值,范围0~1underlayColor
:按钮被点击高亮时,底部要展示的颜色。默认为#000000
onShowUnderlay
:按钮点击高亮,高亮底层被展示时的回调。函数类型onHideUnderlay
:按钮点击结束高亮底层隐藏时的回调。函数类型
TouchableOpacity
类似于TouchableHighlighted
,不同处在于,此组件没有underlayColor
,当用户点击时,仅仅是对被包裹的内容执行淡化操作(修改透明度)。
透明度控制是通过将内容包裹在一个动画组件(AnimatedView
)中实现的。这可能会影响到布局。
属性
属性基本与TouchableHighlight
一致
-
setOpacityTo
:以动画形式修改组件的透明度setOpacityTo((value: number), (duration: number));
TouchableNativeFeedback
仅限安卓
Text
React中用于显示文字的组件。Text
支持嵌套、样式化和触摸事件。文本的样式支持继承,例如:
// 外部Text设置基础样式,里面的Text会自动继承此基础样式,且支持额外的自身定制化
<Text style={styles.baseText}>
<Text style={styles.titleText} onPress={this.onPressTitle}>
{this.state.titleText}{'\n'}{'\n'}
</Text>
<Text numberOfLines={5}>
{this.state.bodyText}
</Text>
</Text>
Nested Text (富文本)
给各段文本添加不同的样式,然后由系统自动进行拼接,从而实现富文本功能,类似于文本。
<Text style={{ fontWeight: 'bold' }}>
I am bold
// 此处会继承上面的'bold'样式
<Text style={{ color: 'red' }}>
and red
</Text>
</Text>
Text容器
当Text
作为容器组件时,其内部布局不再使用flexbox
布局,而是使用text layout
布局。这意味着处于Text
容器内的组件,当遇到行尾时,会自动换行。
严格样式继承
在React中,所有的文本都必需被包在Text
组件中。React不支持为整个文本子树设置默认字体。推荐使用自定义的文本组件来实现统一字体与字号功能。
RN也有样式继承的概念,但是仅限于在Text子树中。
属性
adjustsFontSizeToFit
:文本字体是否随给定容器的约束限制而缩放。非必需,仅限iOSallowFontScaling
:控制字体是否要根据系统的“字体大小”辅助选项来进行缩放,默认为true
,非必需dataDetectorType
:自动检测文本类型,如电话、链接、邮箱等等,默认不检测。枚举类型,非必需,取值:phoneNumber
,link
,email
,none'
,all
ellipsizeMode
:类似于iOS中的lineBreakMode,取值类型为枚举:head
,middle
,tail
,clip
maxFontSizeMultiplier
:字体放大最大倍率。null/undefined
: 从父节点处继承或使用全局默认0
: 不执行放大>=1
: 赋值
minimumFontScale
:当允许字体自动缩放时,最小缩放比例,取值区间0.01~1.0
numberOfLines
:指定文本行数,超出部分进行省略。和ellipsizeMode
搭配使用selectable
:是否支持选中文字(以便于使用原生的复制粘贴等功能)style
:除支持View
的style
属性外,还支持以下属性color
: 文本颜色fontFamily
: 字体名称fontSize
: 字号大小fontStyle
: 枚举,取值:normal
(默认),italic
(斜体)fontWeight
: 枚举,取值:normal
,bold
,100
,200
, ... ,900
。除了normal
和bold
,剩余的数值选项不是所有字体都支持,系统会默认选取最接近的。lineHeight
: 行高letterSpacing
: 字间距,默认为0.textAlign
: 对齐方式,枚举:auto
,left
,right
,center
,justify
textAlignVertical
: 文本垂直方向对齐(仅安卓),枚举:top
,center
,bottom
,auto
textDecorationLine
: 文字加划线,枚举:none
,underline
,line-through
,underline line-through
(下划线+中划线)textDecorationColor
: 划线颜色(仅iOS)textDecorationStyle
: 划线样式(仅iOS),枚举:solid
(单划线),double
(双划线),dotted
(点线),dashed
(虚线)textShadowOffset
: 对象类型,形如: {width: num, height: num}textShadowColor
: 文本阴影颜色textShadowRadius
: 文本阴影弧度textTransform
: 文本转换,枚举:none
,uppercase
,lowercase
,capitalize
writingDirection
: 文本方向(仅iOS),枚举:auto
,ltr
,rtl
实测无效
suppressHighlighting
:禁止文字点击时高亮,默认为false
。
其他布局、触摸事件属性与View
组件相同
Image
React中用来显示图片的组件,包括网络图片、静态图片、临时图片、相册等。
属性
-
source
: 图片来源(远程URL或本地文件)。
此属性可以同时赋值多个远端URL,本地会根据image容器的尺寸自动选择尺寸最合适的uri对应的图片来展示。可以配置cache
属性来控制网络请求的缓存策略。
当前可支持的图片类型有:jpg
,png
,jpeg
,bmp
,gif
,webp
(安卓),psd
(iOS)
source的三种赋值类型:- 图片对象:
require('imagePath')
。路径必须为常量,不能带有变量 - 网络链接:
{uri: 'a_img_web_url'}
。 - 网络图片数据:
{uri: 'data:image/png;....'}
- 图片对象:
-
style
:除支持View
的style
属性外,还支持以下属性opacity
: 不透明度backgroundColor
: 相框底色tintColor
: 所有非透明像素点的渲染色(无用,设置会影响图片显示)borderRadius
: 相框圆角半径borderTopLeftRadius
: 相框左上角圆角borderTopRightRadius
: 相框右上角圆角borderBottomLeftRadius
: 相框左下角圆角borderBottomRightRadius
: 相框右下角圆角borderWidth
: 边线宽度borderColor
: 边线颜色
-
resizeMode
:当图片无法填满image相框时执行的拉伸模式,枚举类型center
: 居中显示,图片超出相框时会等比缩小,宽高均小于相框宽高时,居中显示contain
: 保持原比例居中显示,并保持一个方向刚好铺满(AspectFit)stretch
: 拉伸图片铺满相框,相框宽高比例与图片不一致时,图片变形(ScaleToFill)cover
: 等比例缩放铺满整个相框,并保持一个方向刚好铺满(AspectFill)repeat
: 重复铺满,此选项会使动图失去动态效果
-
onLoadStart
: 读取图片开始回调 -
onLoad
: 读取图片完成回调 -
onLoadEnd
: 读取图片结束回调(onLoad之后调用) -
onError
: 读取图片错误回调 -
defaultSource
:读取图片前展示的静态图片,类似于placeholder
占位图。
可以传递静态图片对象,如require('xxx.png')
,也可以传递一个对象,格式为:{uri: string, width: number, height: number, scale: number}
,其中scale
为占位图缩放比例,默认为1. -
onPartialLoad
:图片部分加载时的回调 -
onProgress
:图片加载进度回调,此函数通过event
的nativeEvent
回传当前已加载的数据loaded
和总数据total
,由此来获取读取进度。onProgress={(event) => { console.log(`Loading progress: ${(event.nativeEvent.loaded / event.nativeEvent.total).toFixed(2)}`); }}
方法
-
getSize()
:在展示图片之前获取图片的尺寸。为了获取图片的尺寸,图片需要先被加载或下载,然后进行缓存。因此,可以使用这个方法预获取图片,但不推荐这样做。Image.getSize(uri, success, [failure]);
相关参数:
uri
: 图片的地址,success
: 下载成功并获取到宽高后的回调(必需),failure
: 下载失败后的回调(非必需) -
getSizeWithHeaders()
: 通过自定义请求头获取图片尺寸,功能类似于getSize()
。但不要将此方法用于静态本地资源。Image.getSizeWithHeaders(uri, headers, success, [failure]);
相关参数:
headers
: 下载图片的请求头,其他同getSize()
-
prefetch()
:预下载图片并保存到本地缓存Image.prefetch(url);
-
queryCache()
:此方法返回图片URL与cache的缓存状态映射表。如果不存在映射关系,则说明不存在对应的图片缓存。Image.queryCache(urls); // urls为图片链接数组
TextInput
基础文本输入组件,并提供有一些可配置的特性,如自动修正、自动大写、占位文本和设置键盘类型等。
最基础的用法就是直接使用一个TextInput
组件然后监听它的onChangeText
事件来读取用户输入。还有其他的事件例如onSubmitEditing
、onFocus
等也可以被监听。
属性
value
:相当于text
,文本框内容defaultValue
:键盘初始文本内容style
:TextInput
支持Text
的绝大部分属性,但不支持设置边线宽度和圆角editable
:是否支持编辑,默认为true
multiline
:是否支持多行显示(类似于UITextView
),默认为false
。设置输入框多行显示时,iOS默认文字顶部对齐,而Android为垂直居中,需要额外设置textAlignVertical
以便保持一致numberOfLines
:文本输入显示的行数,和multiline
搭配使用maxLength
:最大输入长度,使用此属性代替JS控制逻辑以免文本框内容闪烁placeholder
:占位文本placeholderTextColor
:占位文本颜色keyboardType
:键盘类型,枚举。常用的平台通用类型:default
,number-pad
,decimal-pad
,numeric
,email-address
,phone-pad
keyboardAppearance
:键盘外观,枚举类型。取值:default
,light
,dark
, 仅iOSreturnKeyType
:回车键类型,枚举。通用:done
,go
,next
,search
,send
; Android:none
,previous
; iOS:default
,emergency-call
,google
,join
,route
,yahoo
returnKeyLabel
:自定义回车键文案,仅AndroidsecureTextEntry
:安全文本输入spellCheck
:拼写检查,会继承autoCorrect
的值autoCorrect
:自动修正拼写,默认为true
autoFocus
:自动聚焦,当组件的componentDidMount
执行完之后激活autoCompleteType
:自动补全类型,例如邮件、地址、电话号码等信息自动提示补全autoCapitalize
:自动首字母大写,枚举类型。某些类型键盘不支持。赋值:none
,sentences
,words
,characters
clearButtonMode
:清除按钮类型,枚举。取值:never
,while-editing
,unless-editing
,always
clearTextOnFocus
:聚焦时清空内容,默认为false
,仅iOSblurOnSubmit
:点击回车时解除焦点。单行输入时为true
,多行时为false
。如果设置为true
,在多行输入时,点击回车会自动提交内容并解除焦点而不会换行。caretHidden
:是否隐藏光标,默认为否enablesReturnKeyAutomatically
:根据是否有文本内容自动调整回车键可用状态,默认为false
,仅iOSdataDetectorTypes
:文本类型自动检测,如链接、邮箱、地址、电话等。仅限于多行显示不可编辑状态(multiline: true, editable: false
)textContentType
:文本内容类型,可以让系统根据此类型的值对用户的输入内容进行语义补全。枚举类型,包括none
、链接、地址、邮箱、电话等。allowFontScaling
:允许字体随系统文字大小设置而缩放,默认为true
scrollEnabled
:是否允许滚动,仅限多行selectTextOnFocus
:是否在输入框获得焦点时自动选中所有文字rejectResponderTermination
:是否允许输入框将触摸事件传递给父组件。例如当文本输入框处在可滑动的视图组件中时,如果此属性为true
,则在文本框上滑动,会响应父组件的滑动事件。仅iOS,Android默认支持。默认为true
。selection
:文本选中区段,类型为object: {start: number,end: number}
。可以将start
和end
设置为相同的值以定位光标selectionColor
:光标和高亮文字的颜色onFocus
:当文本框获得焦点成为第一响应者时的回调onBlur
:文本框失去焦点时的回调onChange
:文本输入内容改变时的回调,传参类型为{ nativeEvent: { eventCount, target, text} }
onChangeText
:文本输入内容改变时的回调,改变后的文本内容作为单一参数传入此函数onEndEditing
:输入结束回调onKeyPress
:当有按键按下时的回调,传参为{ nativeEvent: { key: keyValue } }
,当按键为回车、退格以及空格时,keyValue
分别为'Enter'
、'Backspace'
和' '
。此回调在onChange
回调之前调用onContentSizeChange
:多行输入时,输入文本内容尺寸变化时的回调onSubmitEditing
:用户点击提交时的回调,传参为{nativeEvent: {text, eventCount, target}}
。多行输入时无效onScroll
:多行输入时,滚动文本内容的回调,传参为{ nativeEvent: { contentOffset: { x, y } } }
onLayout
:同View
,传参为{ nativeEvent: {layout: {x, y, width, height}, target } }
方法
clear
:清空内容isFocused
:判断当前输入框是否已获得焦点