核心组件

核心组件的定义是跟浏览器、Vue 中保持一致，如果只使用这些组件的话，可以直接跨浏览器。

a

该组件目前映射到终端 Text 组件，目前主要用于在 hippy-vue-router 中进行页面跳转。 一切同 p。

事件

button

[范例：demo-button.vue]

该组件映射到 View 组件，容器里面可以放图片、也可以放文本。但是因为 View 不能包裹文本，所以需要在 <button> 里包裹其它文本组件才能显示文字，这个跟浏览器不一样，浏览器的 <button> 也可以包裹 <span> 组件，开发时注意一下。一切同 div。

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

事件

div

[范例：demo-div.vue]

div 组件容器，默认不可以滚动。可以通过增加样式参数 overflow-y: scroll 切换为可以纵向滚动容器，或者增加样式参数 overflow-x: scroll 切换为水平滚动容器。在终端侧会被映射成 ScrollView，因此具备 ScrollView 通用的能力。

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

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

参数

• nestedScrollPriority 的参数含义：

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

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

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

• nestedScrollPriority 默认值的说明：

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

• 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;
    }
    

事件

方法

scrollTo

仅在 overflow-y/x: scroll 时适用

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

• x: number - X 偏移值
• y: number - Y 偏移值
• duration: number | boolean - 毫秒为单位的滚动时间, 默认 1000ms，false 等同 0ms

setPressed

[setPressed 范例]

最低支持版本 2.13.1

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

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

setHotspot

[setHotspot 范例]

最低支持版本 2.13.1

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

form

[范例：demo-div.vue]

容器组件。 一切同 div。

iframe

[范例：demo-iframe.vue]

内嵌网页容器。

参数

事件

img

[范例：demo-img.vue]

图片组件，和浏览器的一样。

• 注意: 必须指定样式中的宽度和高度，否则无法工作。
• 注意: Android 端默认会带上灰底色用于图片占位，可以加上 background-color: transparent 样式改为透明背景。

参数

2.8.1 版本后支持终端本地图片能力，可通过 webpack file-loader 加载。

样式内特殊属性

事件

input

[范例：demo-input.vue]

单行文本组件。

不建议手工双向绑定数据，建议通过 v-model 来绑定视图和数据。

差异性

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

• iOS 则是正常的遮住
• Android 的表现为页面会被键盘顶起，顶起的幅度取决于 input 的 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 开发文档。

参数

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

事件

方法

blur

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

clear

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

focus

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

getValue

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

setValue

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

• value: string - 文本框内容

isFocused

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

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

label

[范例：demo-p.vue]

显示文本。 一切同 p。

事件

ul

[范例：demo-list.vue]

Hippy 的重点功能，高性能的可复用列表组件，在终端侧会被映射成 ListView，包含 ListView 所有能力。里面第一层只能包含 <li>。

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

参数

• nestedScrollPriority 的参数含义：

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

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

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

• nestedScrollPriority 默认值的说明：

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

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

事件

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

方法

scrollTo

(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支持

li

ul 的子节点，终端层节点回收和复用的最小颗粒度。

[范例：demo-list.vue]

参数

当设置ul 的 :horizontal=true 启用横向无限列表时，需显式设置 li 样式宽度

p

[范例：demo-p.vue]

显示文本，不过因为 Hippy 下没有 display: inline 的显示模式，默认全部都是 flex 的。

事件

参数

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

whitespace 处理

2.15.3 版本前，Hippy 对模板中文本空格的处理行为默认采用 trim 的处理，即会将元素中开头和结尾的空格（包括特殊  ）均去除。

2.15.3 版本后，增加 Vue.config.trimWhitespace 配置，设为 false 可关闭 trim 的处理，其余遵循 Vue-Loader compilerOptions 本身的配置。

!> 注意：Vue2.x compilerOptions.whitespace 的默认值为 preserve

// entry file
// trimWhitespace default is  true
Vue.config.trimWhitespace = false; // close trim handler

// webpack script
rules: [
  {
    test: /\.vue$/,
    use: [
      {
        loader: vueLoader,
        options: {
          compilerOptions: {
            // whitespace handler, default is 'preserve'
            whitespace: 'condense',
          },
        },
      },
    ],
  },
]

span

[范例：demo-p.vue]

显示文本。 一切同 p。

事件

textarea

[范例：demo-p.vue]

多行文本输入框。 一切同 input。