组件

Hippy-React SDK 提供了常用的 UI 组件，语法上接近终端

Image

[Image 范例]

图片组件，用于显示单张图片。

• 必须指定样式中的宽度和高度，否则无法工作。
• Android 端默认会带上灰底色用于图片占位，可以加上 backgroundColor: transparent 样式改为透明背景。(2.14.1 版本后 Image 默认背景色修改成 transparent)

基本用法

直接加载远程图片：

<Image
  style={{ width: 200, height: 200 }}
  source={{ uri: 'http://xxx/qb_icon_new.png' }}
  resizeMode={Image.resizeMode.cover}
/>;

或者使用本地图片加载能力：

import icon from './qb_icon_new.png';

<Image
  style={{ width: 200, height: 200 }}
  source={{ uri: icon }}
  resizeMode={Image.resizeMode.cover}
/>

• 本地图片可通过加载时定义 Loader，或者 webpack 配置 url-loader 转换成 base64 加载。
• 2.8.1 版本后支持终端本地图片能力，可通过配置 webpack file-loader 加载。

参数

方法

getSize

(uri: string, success: (width: number, height: number) => void, failure?: ErrorFunction) => void 在显示图片前获取图片的宽高(以像素为单位)。如果图片地址不正确或下载失败, 此方法也会失败。

要获取图片的尺寸, 首先需要加载或下载图片(同时会被缓存起来)。这意味着理论上可以用这个方法来预加载图片，但是更好的预加载方案是使用下面 prefetch 预加载方法。

不适用于静态图片资源。

• uri: string - 图片的地址
• success: (width: number, height: number) => void - 此函数会在获取图片与其宽高成功后被回调
• failure: ErrorFunction - 此函数会在如获取图片失败等异常情况被回调

prefetch

(url: string) => void 预加载一张远程图片，将其下载到本地磁盘缓存。

• uri: string - 图片的地址

ListView

[ListView 范例]

可复用垂直列表功能，尤其适合大量条目的数据渲染。

Android 2.14.0 版本后会采用 RecyclerView 替换原有 ListView

参数

• nestedScrollPriority 的参数含义：

  • self：当前组件优先，滚动事件将先由当前组件消费，剩余部分传递给父组件消费；

  • parent：父组件优先，滚动事件将先由父组件消费，剩余部分再由当前组件消费；

  • none：不允许嵌套滚动，滚动事件将不会传递给父组件。

• nestedScrollPriority 默认值的说明：

  如未设置任何滚动优先级时，iOS平台的默认值为none，即与系统默认行为保持一致。当指定任意一方向的优先级后，其他方向默认值为self； Android平台默认值始终为self。

• 请注意，由于底层组件实现变化，原iOS 2.9版本起支持的侧滑删除相关属性（ editable、delText、delete ）在升级3.x后已不再默认内置支持，如需使用，可通过自定义组件实现。

方法

scrollToContentOffset

(xOffset: number, yOffset: number, animated: boolean) => void 通知 ListView 滑动到某个具体坐标偏移值(offset)的位置。

• xOffset: number - 滑动到 X 方向的 offset
• yOffset: number - 滑动到 Y 方向的 offset
• animated: boolean - 滑动过程是否使用动画

scrollToIndex

(xIndex: number, yIndex: number, animated: boolean) => void 通知 ListView 滑动到第几个 item。

• xIndex: number - 滑动到 X 方向的第 xIndex 个 item
• yIndex: number - 滑动到 Y 方向的 yIndex 个 item
• animated: boolean - 滑动过程是否使用动画
• scrollAlign: enum(start,center,end,auto) - 滑动对齐类型 只有Ohos支持

collapsePullHeader

(otions: { time: number }) => void 收起刷新条 PullHeader。当设置了renderPullHeader后，每当下拉刷新结束需要主动调用该方法收回 PullHeader。

options 参数，最低支持版本 2.14.0

• time: number: 可指定延迟多久后收起 PullHeader，单位ms

expandPullHeader

最低支持版本 2.14.0

() => void 展开顶部下拉刷新条 PullHeader。当设置了renderPullHeader后，可以通过该方法来主动触发下拉刷新的效果。

collapsePullFooter

最低支持版本 2.14.0

() => void 收起底部上拉刷新条 PullFooter。当设置了renderPullFooter后，每当上拉刷新结束需要主动调用该方法收回 PullFooter。

Modal

[Modal 范例]

模态弹窗组件。

参数

RefreshWrapper

[RefreshWrapper 范例]

包裹住 ListView 提供下滑刷新功能的组件.

RefreshWrapper 现在只支持包裹一个 ListView 组件，暂不支持别的组件的下滑刷新功能。

参数

方法

refreshCompleted

() => void 调用此方法，告知 RefreshWrapper 已经刷新完毕，RefreshWrapper 将会收起刷新栏。

startRefresh

() => void 调用此方法，手工告知 RefreshWrapper 开始刷新，展开刷新栏。

ScrollView

[Scroll 范例]

滚动视图组件，用于展示不确定高度的内容，它可以将一系列不确定高度的子组件装到一个确定高度的容器中，使用者可通过上下或左右滚动操作查看组件宽高之外的内容。

一个包装了平台的 ScrollView（滚动视图）的组件，同时还集成了触摸锁定的“响应者”系统。

• 注意：记住 ScrollView 必须有一个确定的高度才能正常工作，因为它实际上所做的就是将一系列不确定高度的子组件装进一个确定高度的容器（通过滚动操作）。要给一个 ScrollView 确定一个高度的话，要么直接给它设置高度（不建议），要么确定所有的父容器都有确定的高度。一般来说我们会给 ScrollView 设置 flex: 1 以使其自动填充父容器的空余空间，但前提条件是所有的父容器本身也设置了flex或者指定了高度，否则就会导致无法正常滚动，你可以使用元素查看器来查找问题的原因。
• 注意： ScrollView 无法使用 onTouch 系列事件监听触屏行为，但可以用 onScroll 监听滚动行为。

参数

• nestedScrollPriority 的参数含义：

  • self（默认值）：当前组件优先，滚动事件将先由当前组件消费，剩余部分传递给父组件消费；

  • parent：父组件优先，滚动事件将先由父组件消费，剩余部分再由当前组件消费；

  • none：不允许嵌套滚动，滚动事件将不会传递给父组件。

• nestedScrollPriority 默认值的说明：

  如未设置任何滚动优先级时，iOS平台的默认值为none，即与系统默认行为保持一致。当指定任意一方向的优先级后，其他方向默认值为self； Android平台默认值始终为self。

方法

scrollTo

(x: number, y: number, animated: boolean) => void 滚动到指定的 X，Y 偏移值，第三个参数为是否启用平滑滚动动画。

• x: number - X 偏移值
• y: number - Y 偏移值
• animated: boolean - 是否启用平滑滚动动画。

scrollToWithDuration

(x: number, y: number, duration: number) => void 经过指定的时间平滑滚动到 X、Y 偏移值。

• x: number - X 偏移值
• y: number - Y 偏移值
• duration: number - 毫秒为单位的滚动时间，默认 1000ms

TextInput

[TextInput 范例]

输入文本的基本组件。

本组件的属性提供了多种特性的配置，譬如自动完成、自动大小写、占位文字，以及多种不同的键盘类型（如纯数字键盘）等等。

差异性

由于系统组件层的差异，如果 TextInput 处于会被键盘遮住的位置，在呼出键盘后：

• iOS 则是正常的遮住
• Android 的表现为页面会被键盘顶起，顶起的幅度取决于 TextInput 的 Y 轴位置决定

关于解决此间的平台差异性，我们仍在讨论。

若有 iOS 对齐 Android 的键盘顶起的需求，建议参考 StackOverflow，在业务层解决。

Android 弹出后盖住界面的解决办法

在部分 Android 机型上，键盘弹出后也可能会产生盖住界面的情况，一般情况下可以通过修改 AndroidMainfest.xml 文件，在 activity 上增加 android:windowSoftInputMode="adjustPan" 解决。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.tencent.mtt.hippy.example"
>
    <application
        android:allowBackup="true"
        android:label="@string/app_name"
    >
        <!-- 注意 android:windowSoftInputMode="adjustPan" 写在 activity 的参数里-->
        <activity android:name=".MyActivity"
            android:windowSoftInputMode="adjustPan"
            android:label="@string/activity_name"
            android:configChanges="orientation|screenSize"
        >
        </activity>
    </application>
</manifest>

该参数的意义是：

• adjustResize: resize the page content
• adjustPan: move page content without resizing page content

详情请参考 Android 开发文档。

参数

• breakStrategy 的参数含义：
  • simple（默认值）：简单折行，每一行显示尽可能多的字符，直到这一行不能显示更多字符时才进行换行，这种策略下不会自动折断单词（当一行只有一个单词并且宽度显示不下的情况下才会折断）；
  • high_quality：高质量折行，针对整段文本的折行进行布局优化，必要时会自动折断单词，比其他两种策略略微影响性能，通常比较适合只读文本；
  • balanced：平衡折行，尽可能保证一个段落的每一行的宽度相同，必要时会折断单词。

方法

blur

() => void 让指定的 input 或 View 组件失去光标焦点，与 focus() 的作用相反。

clear

() => void 清空输入框的内容。

focus

() => void 指派 TextInput 获得焦点。

getValue

() => Promise<string> 获得文本框中的内容。注意，由于是异步回调，收到回调时值可能已经改变。

setValue

(value: string) => void 设置文本框内容。

• value: string - 文本框内容

isFocused

最低支持版本 2.14.1。hippy-react-web 不支持。

() => Promise<boolean> 获得文本框的焦点状态。注意，由于是异步回调，收到回调时值可能已经改变。

Text

[Text 范例]

文本组件。

属性

• ellipsizeMode 的参数含义：
  • clip - 超过指定行数的文字会被直接截断，不显示“...”；（Android 2.14.1以上、iOS）
  • head - 文字将会从头开始截断，保证字符串的最后的文字可以正常显示在 Text 组件的最后，而从开头给截断的文字，将以 “...” 代替，例如 “...wxyz”；（Android 2.14.1 以上、iOS全支持）
  • middle - "文字将会从中间开始截断，保证字符串的最后与最前的文字可以正常显示在Text组件的响应位置，而中间给截断的文字，将以 “...” 代替，例如 “ab...yz”；（Android 2.14.1 以上、iOS全支持）
  • tail（默认值） - 文字将会从最后开始截断，保证字符串的最前的文字可以正常显示在 Text 组件的最前，而从最后给截断的文字，将以 “...” 代替，例如 “abcd...”；
• breakStrategy 的参数含义：
  • simple（默认值）：简单折行，每一行显示尽可能多的字符，直到这一行不能显示更多字符时才进行换行，这种策略下不会自动折断单词（当一行只有一个单词并且宽度显示不下的情况下才会折断）；
  • high_quality：高质量折行，针对整段文本的折行进行布局优化，必要时会自动折断单词，比其他两种策略略微影响性能，通常比较适合只读文本；
  • balanced：平衡折行，尽可能保证一个段落的每一行的宽度相同，必要时会折断单词。

View

[View 范例]

最基础的容器组件，它是一个支持Flexbox布局、样式、一些触摸处理、和一些无障碍功能的容器，并且它可以放到其它的视图里，也可以有任意多个任意类型的子视图。不论在什么平台上，View 都会直接对应一个平台的原生视图。

新特性：现已支持 iOS 26+ Liquid Glass（液态玻璃）效果，详见glassEffect 相关API说明。

!> Android 具有节点优化的特性，请注意 collapsable 属性的使用

属性

• pointerEvents 的参数含义：

  • auto（默认值） - 视图可以是触摸事件的目标；

  • none - 视图永远不是触摸事件的目标；

  • box-none - 视图不是触摸事件的目标，但它的子视图可以是。其行为类似视图在CSS中有以下类:

    cssCopy

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

  • box-only - 视图可以是触摸事件的目标，但它的子视图不能。其行为类似视图在CSS中有以下类:

    cssCopy

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

方法

setPressed

[setPressed 范例]

最低支持版本 2.13.1。hippy-react-web、Web-Renderer 不支持

(pressed: boolean) => void 通过传入一个布尔值，通知终端当前是否需要显示水波纹效果

• pressed: boolean - true 显示水波纹，false 收起水波纹

setHotspot

[setHotspot 范例]

最低支持版本 2.13.1 hippy-react-web、Web-Renderer 不支持

(x: number, y: number) => void 通过传入一个 x, y 坐标值，通知终端设置当前波纹中心位置

ViewPager

[ViewPager 范例]

支持横滑翻页的容器，它的每一个子容器组件会被视作一个单独的页面，并且会被拉伸宽度至 ViewPager 本身宽度。

参数

方法

setPage

(index: number) => void 通过传入一个index 值（数字），滑动到第 index 个页面（有动画）

• index: number - 指定滑动页面

setPageWithoutAnimation

(index: number) => void 通过传入一个index 值（数字），滑动到第 index 个页面（无动画）

• index: number - 指定滑动页面

WaterfallView

最低支持版本 2.9.0。hippy-react-web 不支持

[WaterfallView 范例]

瀑布流组件。

参数

方法

scrollToIndex

(obj: { index: number, animated: boolean }) => void 通知 Waterfall 滑动到第几个 item。

• index: number - 滑动到的第 index 个 item
• animated: boolean - 滑动过程是否使用动画, 默认 true

scrollToContentOffset

(obj: { xOffset: number, yOffset: number, animated: boolean }) => void 通知 Waterfall 滑动到某个具体坐标偏移值(offset)的位置。

• xOffset: number - 滑动到 X 方向的 offset
• yOffset: number - 滑动到 Y 方向的 offset
• animated: boolean - 滑动过程是否使用动画，默认 true

WebView

[WebView 范例]

WebView组件。

参数