「华为鸿蒙应用开发 14」JavaScript UI全部容器组件的基本用法汇总

前面的章节已经介绍了常用容器组件List、Dialog、Form、Stepper、Tabs和基础组件Text、Button、Input、Picker、Image，本章节将进一步介绍鸿蒙应用程序开发的方舟界面（ArkUI）框架中所有的前面章节中没有介绍到的全部容器组件，了解其基本用法。这样就可以在以后的实际项目开发中做到心中有数。

1 badge：应用中如果有需用户关注的新事件提醒，可以采用新事件标记来标识。

badge除支持通用属性外，还支持如下属性：

名称

类型

默认值

必填

描述

placement

string

rightTop

否

事件提醒的数字标记或者圆点标记的位置，可选值为：

right：位于组件右边框。rightTop：位于组件边框右上角。left：位于组件左边框。

count

number

0

否

设置提醒的消息数，默认为0。当设置相应的提醒消息数大于0时，消息提醒会变成数字标记类型，未设置消息数或者消息数不大于0时，消息提醒将采用圆点标记。

说明

当数字设置为大于maxcount时，将使用maxcount显示。

count属性最大支持整数值为2147483647。

visible

boolean

false

否

是否显示消息提醒，当收到新信息提醒时可以设置该属性为true，显示相应的消息提醒，如果需要使用数字标记类型，同时需要设置相应的count属性。

maxcount

number

99

否

最大消息数限制，当收到新信息提醒大于该限制时，标识数字会进行省略，仅显示maxcount 。

说明

maxcount属性最大支持整数值为2147483647。

config

BadgeConfig

-

否

设置新事件标记相关配置属性。

label

string

-

否

设置新事件提醒的文本值。

说明

使用该属性时，count和maxcount属性不生效。

BadgeConfig的相关配置属性：

名称

类型

默认值

必填

描述

badgeColor

<color>

#fa2a2d

否

新事件标记背景色。

textColor

<color>

#ffffff

否

数字标记的数字文本颜色。

textSize

<length>

10px

否

数字标记的数字文本大小。

badgeSize

<length>

6px

否

圆点标记的默认大小

示例：

<!-- badgepage.hml --><div class="container"><badge config="{{badgeConfig}}" visible="true" count="100" maxcount="99" placement="right"><text class="text1">示例</text></badge><badge visible="true" count="0"><text class="text2">示例</text></badge></div>

/* badgepage.css */.container {flex-direction: column;align-items: center;width: 100%;}badge {width: 50%;margin-top: 100px;}text {font-size: 50px;}.text1 {background-color: orange;}.text2 {background-color: aqua;}

// badgepage.jsexport default {data: {badgeConfig: {badgeColor: '#0a59f7',textSize: '20px',badgeSize: '25px'}}}

2 panel：可滑动面板。提供一种轻量的内容展示的窗口，可方便的在不同尺寸中切换。属于弹出式组件。仅支持手机，平板。

除支持通用属性外，还支持如下属性：

名称

类型

默认值

必填

描述

type

string

foldable

是

设置可滑动面板类型，不可动态变更，可选值有：

minibar：提供minibar和类全屏展示切换效果。foldable：内容永久展示类，提供大（类全屏）、中（类半屏）、小三种尺寸展示切换效果。temporary：内容临时展示区，提供大（类全屏）、中（类半屏）两种尺寸展示切换效果。

mode

string

full

否

设置初始状态，mode参数可选值为：

mini：类型为minibar和foldable时，为最小状态；类型为temporary，则不生效。half: 类型为foldable和temporary时，为类半屏状态；类型为minibar，则不生效。full: 类全屏状态。

dragbar

boolean

true

否

设置是否存在dragbar，true表示存在，false表示不存在。

fullheight

<length>

-

否

指定full状态下的高度，默认为屏幕尺寸 - 8px。

halfheight

<length>

-

否

指定half状态下的高度，默认为屏幕尺寸的一半。

miniheight

<length>

-

否

指定mini状态下的高度，默认为48px。

说明

不支持渲染属性，包括for、if和show。不支持focusable和disabled属性。

仅支持如下事件：

名称

参数

描述

sizechange

{ size: { height: heightLength, width: widthLength }, mode: modeStr }

当可滑动面板发生状态变化时触发，mode参数可选值为：

mini：类型为minibar和foldable时，处于最小状态；half: 类型为foldable时，处于类半屏状态；full: 类全屏状态。说明返回的height值为内容区高度值，当dragbar属性为true时，panel本身的高度值为dragbar高度加上内容区高度。

仅支持如下方法：

名称

参数

描述

show

-

弹出panel可滑动面板。

close

-

关闭panel可滑动面板。

示例：

<!-- panelpage.hml --><div class="container"><button type="capsule" value="打开面板" onclick="showPanel"></button><panel id="panel" type="foldable" mode="half" @sizechange="changeMode" miniheight="200px"><div class="panel-div"><div class="inner-txt"><text class="txt">面板类型为： {{modeFlag}}</text></div><div class="inner-btn"><button type="capsule" value="关闭面板" onclick="closePanel"></button></div></div></panel></div>

/* panelpage.css */.container {flex-direction: column;justify-content: center;align-items: center;}button {height: 50px;font-size: 30px;}text {font-size: 40px;}.panel-div {flex-direction: column;align-items: center;}.inner-txt {width: 100%;height: 160px;justify-content: center;}.inner-btn {width: 100%;height: 120px;justify-content: center;}

// panelpage.jsexport default {data: {modeFlag: 'half'},showPanel() {this.$element('panel').show();},closePanel() {this.$element('panel').close();},changeMode(e) {this.modeFlag = e.mode;}}

3 popup：气泡指示。在点击绑定的控件后会弹出相应的气泡提示来引导用户进行操作。

弹出窗口位置placement。可选值为：

left：位于目标元素左边；right：位于目标元素右边；top：位于目标元素上边；bottom：位于目标元素下边；topLeft：位于目标元素左上角；topRight：位于目标元素右上角；bottomLeft：位于目标元素左下角；bottomRight：位于目标元素右下角。

除支持通用事件外，还支持事件

名称

参数

描述

visibilitychange

{ visibility: boolean }

当气泡弹出和消失时会触发该回调函数。

仅支持如下方法：

名称

参数

描述

show

-

弹出气泡提示。

hide

-

取消气泡提示。

<!-- popuppage.hml --><div class="container"><div class="container"><text id="text">这里会显示气泡弹窗</text><!-- popup supports single child of any type5--><popup id="popup" class="popup" target="text" placement="top" keepalive="true" clickable="true" arrowoffset="100px" @visibilitychange="visibilityChange" @click="hidePopup"><text class="text">我是气泡弹窗</text></popup><button class="button" onclick="showPopup">显示气泡弹窗</button></div></div>

/* popuppage.css */.container {flex-direction: column;align-items: center;padding-top: 200px;}.popup {mask-color: gray;}.text {color: white;}.button {width: 220px;height: 70px;margin-top: 50px;font-size: 30px;}

// popuppage.jsimport prompt from '@system.prompt'export default {visibilityChange(e) {prompt.showToast({message: '气泡弹窗的可见性为: ' e.visibility,duration: 3000,});},showPopup() {this.$element("popup").show();},hidePopup() {this.$element("popup").hide();}}// popuppage.jsimport prompt from '@system.prompt'export default {visibilityChange(e) {prompt.showToast({message: '气泡弹窗的可见性为: ' e.visibility,duration: 3000,});},showPopup() {this.$element("popup").show();},hidePopup() {this.$element("popup").hide();}}

4 refresh：下拉刷新容器。

除支持通用属性外，还支持如下属性：

名称

类型

默认值

必填

描述

offset

<length>

-

否

刷新组件静止时距离父组件顶部的距离。

refreshing

boolean

false

否

用于标识刷新组件当前是否正在刷新。

type

string

auto

否

设置组件刷新时的动效。两个可选值，不支持动态修改。

auto: 默认效果，列表界面拉到顶后，列表不移动，下拉后有转圈弹出。pulldown: 列表界面拉到顶后，可以继续往下滑动一段距离触发刷新，刷新完成后有回弹效果（如果子组件含有list，防止下拉效果冲突，需将list的scrolleffect设置为no）。

lasttime

boolean

false

否

是否显示上次更新时间，字符串格式为：“上次更新时间：XXXX ”，XXXX 按照时间日期显示规范显示，不可动态修改（建议type为pulldown时使用，固定距离位于内容下拉区域底部，使用时注意offset属性设置，防止出现重叠）。

timeoffset

<length>

-

否

设置更新时间距离父组件顶部的距离。

friction

number

手机：42

智能穿戴：62

否

下拉摩擦系数，取值范围：0-100，数值越大refresh组件跟手性高，数值越小refresh跟手性低。

说明

仅手机、平板和智能穿戴设备支持。

除支持通用样式外，还支持如下样式：

名称

类型

默认值

必填

描述

background-color

<color>

手机：white

智能穿戴：black

否

用于设置刷新组件的背景颜色。

progress-color

<color>

手机：black

智能穿戴：white

否

用于设置刷新组件的loading颜色。

仅支持如下事件：

名称

参数

描述

refresh

{ refreshing: refreshingValue }

下拉刷新状态变化时触发。可能值：

false：当前处于下拉刷新过程中。true：当前未处于下拉刷新过程中。

pulldown

{ state: string }

下拉开始和松手时触发。可能值：

start：表示开始下拉。end：表示结束下拉。

<!-- refreshpage.hml --><div class="container"><refresh refreshing="{{fresh}}" onrefresh="refresh"><list class="list" scrolleffect="no"><list-item class="listitem" for="list"><div class="content"><text class="text">{{$item}}</text></div></list-item></list></refresh></div>

/* refreshpage.css */.container {flex-direction: column;align-items: center;width: 100%;height: 100%;}.list {width: 100%;height: 100%;}.listitem {width: 100%;height: 150px;}.content {width: 100%;height: 100%;flex-direction: column;align-items: center;justify-content: center;}.text {font-size: 35px;font-weight: bold;}

import prompt from '@system.prompt';export default {data: {list:[],fresh:false},onInit() {this.list = [];for (var i = 0; i <= 3; i) {var item = '列表元素' i;this.list.push(item);}},refresh: function (e) {prompt.showToast({message: '刷新中...'})var that = this;that.fresh = e.refreshing;setTimeout(function () {that.fresh = false;var addItem = '更新元素';that.list.unshift(addItem);prompt.showToast({message: '刷新完成!'})}, 2000)}}

5 stack：堆叠容器，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。

示例：

<!-- stackpage.hml --><stack class="stack-parent"><div class="back-child bd-radius"></div><div class="positioned-child bd-radius"></div><div class="front-child bd-radius"></div></stack>

/* stackpage.css */.stack-parent {width: 400px;height: 400px;background-color: #ffffff;border-width: 1px;border-style: solid;}.back-child {width: 300px;height: 300px;background-color: #3f56ea;}.front-child {width: 100px;height: 100px;background-color: #00bfc9;}.positioned-child {width: 100px;height: 100px;left: 50px;top: 50px;background-color: #47cc47;}.bd-radius {border-radius: 16px;}

6 swiper：滑动容器，提供切换子组件显示的能力。支持除<list>之外的子组件。

除支持通用属性外，还支持如下属性：

名称

类型

默认值

必填

描述

index

number

0

否

当前在容器中显示的子组件的索引值。

autoplay

boolean

false

否

子组件是否自动播放，自动播放状态下，导航点不可操作。

interval

number

3000

否

使用自动播放时播放的时间间隔，单位为ms。

indicator

boolean

true

否

是否启用导航点指示器，默认true。

digital

boolean

false

否

是否启用数字导航点，默认为false。

说明

必须设置indicator时才能生效数字导航点。

indicatormask

boolean

false

否

是否采用指示器蒙版，设置为true时，指示器会有渐变蒙版出现。

说明

手机上不生效。

indicatordisabled

boolean

false

否

指示器是否禁止用户手势操作，设置为true时，指示器不会响应用户的点击拖拽。

loop

boolean

true

否

是否开启循环滑动。

duration

number

-

否

子组件切换的动画时长。

vertical

boolean

false

否

是否为纵向滑动，纵向滑动时采用纵向的指示器。

cachedsize

number

-1

否

swiper延迟加载时item最少缓存数量。-1表示全部缓存。

scrolleffect

string

spring

否

滑动效果。目前支持如下：

spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发送一定的变化none：滑动到边缘后无效果。 说明该属性仅在loop属性为false时生效。

displaymode

string

stretch

否

设置当swiper容器在主轴上尺寸（水平滑动时为宽度，纵向滑动时为高度）大于子组件时，在swiper里的呈现方式。可选值：

"stretch":拉伸子组件主轴上尺寸与Swiper容器一样大。

"autoLinear":保持子组件本身大小线性排列在Swiper容器里。

除支持通用样式外，还支持如下样式：

名称

类型

默认值

必填

描述

indicator-color

<color>

-

否

导航点指示器的填充颜色。

indicator-selected-color

<color>

手机：#ff007dff

智慧屏：#ffffffff

智能穿戴：#ffffffff

否

导航点指示器选中的颜色。

indicator-size

<length>

4px

否

导航点指示器的直径大小。

indicator-top|left|right|bottom

<length> | <percentage>

-

否

导航点指示器在swiper中的相对位置。

next-margin

<length> | <percentage>

-

否

后边距，用于露出后一项的一小部分。

previous-margin

<length> | <percentage>

-

否

前边距，用于露出前一项的一小部分。

除支持通用事件外，还支持如下事件：

名称

参数

描述

change

{ index: currentIndex }

当前显示的组件索引变化时触发该事件。

rotation

{ value: rotationValue }

智能穿戴表冠旋转事件触发时的回调。

animationfinish7

-

动画结束时触发该事件。

除支持通用方法外，还支持如下方法：

名称

参数

描述

swipeTo

{ index: number(指定位置) }

切换到index位置的子组件。

showNext

无

显示下一个子组件。

showPrevious

无

显示上一个子组件。

rotation

FocusParam

组件请求或者取消旋转表冠焦点，该方法参数可缺省，缺省时默认请求旋转表冠焦点。

说明

旋转表冠为穿戴设备特有硬件，用户可以通过旋转电源键来进行页面交互。

FocusParam对象说明

属性

类型

说明

focus

boolean

focus为true时，表示请求焦点，focus为false时，表示取消焦点。

示例：

<!-- swiperpage.hml --><div class="container"><swiper class="swiper" id="swiper" index="0" indicator="true"loop="true" digital="false" cachedsize="-1"scrolleffect="spring"><div class = "swiperContent1" ><text class = "text">First screen</text></div><div class = "swiperContent2"><text class = "text">Second screen</text></div><div class = "swiperContent3"><text class = "text">Third screen</text></div></swiper><input class="button" type="button" value="swipeTo" @click="swipeTo"></input><input class="button" type="button" value="showNext" @click="showNext"></input><input class="button" type="button" value="showPrevious" @click="showPrevious"></input></div>

/* swiperpage.css */.container {flex-direction: column;width: 100%;height: 100%;align-items: center;}.swiper {flex-direction: column;align-content: center;align-items: center;width: 70%;height: 130px;border: 1px solid #000000;indicator-color: #cf2411;indicator-size: 14px;indicator-bottom: 20px;indicator-right: 30px;margin-top: 100px;next-margin:20px;previous-margin:20px;}.swiperContent1{height: 100%;justify-content: center;background-color: #007dff;}.swiperContent2{height: 100%;justify-content: center;background-color: #ff7500;}.swiperContent3{height: 100%;justify-content: center;background-color: #41ba41;}.button {width: 70%;margin: 10px;}.text {font-size: 40px;}

// swiperpage.jsexport default {swipeTo() {this.$element('swiper').swipeTo({index: 2});},showNext() {this.$element('swiper').showNext();},showPrevious() {this.$element('swiper').showPrevious();}}