4. React Native 基础视图组件

View

View是构建UI最基础的组件，支持flexbox、style、触摸事件处理、以及无障碍使用操作等。View组件会自动映射到React Native所运行的平台上的基础视图控件。

合成触摸事件

View响应时，会有一个event对象作为函数参数传递，该对象有一个nativeEvent属性，类型为对象，格式为：

• nativeEvent:
  • changedTouches: 自上一次事件之后所有的触摸事件数组
  • identifier: 触摸事件ID
  • locationX: 响应事件的组件内触发点x坐标
  • locationY: 响应事件的组件内触发点y坐标
  • pageX: 响应事件触发点在根组件内x坐标
  • pageY: 响应事件触发点在根组件内y坐标
  • target: 接收触摸事件的元素节点id
  • timestamp: 触摸事件时间标记，对速度计算很有用
  • 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~1
• underlayColor：按钮被点击高亮时，底部要展示的颜色。默认为#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：文本字体是否随给定容器的约束限制而缩放。非必需，仅限iOS
• allowFontScaling：控制字体是否要根据系统的“字体大小”辅助选项来进行缩放，默认为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, 仅iOS
• returnKeyType：回车键类型，枚举。通用：done,go,next,search,send; Android：none,previous; iOS：default, emergency-call, google, join, route, yahoo
• returnKeyLabel：自定义回车键文案，仅Android
• secureTextEntry：安全文本输入
• spellCheck：拼写检查，会继承autoCorrect的值
• autoCorrect：自动修正拼写，默认为true
• autoFocus：自动聚焦，当组件的componentDidMount执行完之后激活
• autoCompleteType：自动补全类型，例如邮件、地址、电话号码等信息自动提示补全
• autoCapitalize：自动首字母大写，枚举类型。某些类型键盘不支持。赋值：none, sentences, words, characters
• clearButtonMode：清除按钮类型，枚举。取值：never, while-editing, unless-editing, always
• clearTextOnFocus：聚焦时清空内容，默认为false，仅iOS
• blurOnSubmit：点击回车时解除焦点。单行输入时为true，多行时为false。如果设置为true，在多行输入时，点击回车会自动提交内容并解除焦点而不会换行。
• caretHidden：是否隐藏光标，默认为否
• enablesReturnKeyAutomatically：根据是否有文本内容自动调整回车键可用状态，默认为false，仅iOS
• dataDetectorTypes：文本类型自动检测，如链接、邮箱、地址、电话等。仅限于多行显示不可编辑状态(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：判断当前输入框是否已获得焦点