HarmonyOS基础学习文档搬运3(组件)

谢谢19
258 阅读19分钟

常用基础组件

1 组件介绍

组件（Component）是界面搭建与显示的最小单位，HarmonyOS ArkUI声明式开发范式为开发者提供了丰富多样的UI组件，我们可以使用这些组件轻松的编写出更加丰富、漂亮的界面。

组件根据功能可以分为以下五大类：基础组件、容器组件、媒体组件、绘制组件、画布组件。其中基础组件是视图层的基本组成单元，包括Text、Image、TextInput、Button、LoadingProgress等，例如下面这个常用的登录界面就是由这些基础组件组合而成。

下面我们将分别介绍这些常用基础组件的使用。

2 Text

Text组件用于在界面上展示一段文本信息，可以包含子组件Span。

文本样式

针对包含文本元素的组件，例如Text、Span、Button、TextInput等，可使用fontColor、fontSize、fontStyle、 fontWeight、fontFamily这些文本样式，分别设置文本的颜色、大小、样式、粗细以及字体，文本样式的属性如下表：

名称参数类型描述
fontColorResourceColor设置文本颜色。
fontSizeLengthResource设置文本尺寸，Length为number类型时，使用fp单位。
fontStyleFontStyle设置文本的字体样式。默认值：FontStyle.Normal。
fontWeightnumberFontWeightstring设置文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular”、“medium”，分别对应FontWeight中相应的枚举值。默认值：FontWeight.Normal。
fontFamilystringResource设置文本的字体列表。使用多个字体，使用“，”进行分割，优先级按顺序生效。例如：“Arial，sans-serif”。

下面示例代码中包含两个Text组件，第一个使用的是默认样式，第二个给文本设置了一些文本样式。

@Entry
@Component
struct TextDemo {
  build() {
    Row() {
      Column() {
        Text('HarmonyOS')
        Text('HarmonyOS')
          .fontColor(Color.Blue)
          .fontSize(20)
          .fontStyle(FontStyle.Italic)
          .fontWeight(FontWeight.Bold)
          .fontFamily('Arial')
      }
      .width('100%')
    }
    .backgroundColor(0xF1F3F5)
    .height('100%')
  }
}

效果图如下：

除了通用属性和文本样式设置，下面列举了一些Text组件的常用属性的使用。

设置文本对齐方式

使用textAlign属性可以设置文本的对齐方式，示例代码如下：

Text('HarmonyOS')
  .width(200)
  .textAlign(TextAlign.Start)
  .backgroundColor(0xE6F2FD)

textAlign参数类型为TextAlign，定义了以下几种类型：

  • Start（默认值）：水平对齐首部。

  • Center：水平居中对齐。

  • End：水平对齐尾部。

设置文本超长显示

当文本内容较多超出了Text组件范围的时候，您可以使用textOverflow设置文本截取方式，需配合maxLines使用，单独设置不生效，maxLines用于设置文本显示最大行数。下面的示例代码将textOverflow设置为Ellipsis ，它将显示不下的文本用 “...” 表示：

Text('This is the text content of Text Component This is the text content of Text Component')
  .fontSize(16)
  .maxLines(1)
  .textOverflow({overflow:TextOverflow.Ellipsis})
  .backgroundColor(0xE6F2FD)

效果图如下：

设置文本装饰线

使用decoration设置文本装饰线样式及其颜色，大家在浏览网页的时候经常可以看到装饰线，例如带有下划线超链接文本。decoration包含type和color两个参数，其中type用于设置装饰线样式，参数类型为TextDecorationType，color为可选参数。

下面的示例代码给文本设置了下划线，下划线颜色为黑色：

Text('HarmonyOS')
  .fontSize(20)
  .decoration({ type: TextDecorationType.Underline, color: Color.Black })
  .backgroundColor(0xE6F2FD)

效果图如下：

TextDecorationTyp包含以下几种类型：

  • None：不使用文本装饰线。

  • Overline：文字上划线修饰。

  • LineThrough：穿过文本的修饰线。

  • Underline：文字下划线修饰。

3 Image

Image组件用来渲染展示图片，它可以让界面变得更加丰富多彩。只需要给Image组件设置图片地址、宽和高，图片就能加载出来，示例如下：

Image($r("app.media.icon"))
  .width(100)
  .height(100)

效果图如下：

设置缩放类型

为了使图片在页面中有更好的显示效果，有时候需要对图片进行缩放处理。您可以使用objectFit属性设置图片的缩放类型，objectFit的参数类型为ImageFit。

现有原始图片如下：

将图片加载到Image组件，设置宽高各100，设置objectFit为Cover（默认值），设置图片背景色为灰色0xCCCCCC。示例代码如下：

Image($r("app.media.image2"))
  .objectFit(ImageFit.Cover)
  .backgroundColor(0xCCCCCC)
  .width(100)
  .height(100)

效果图如下：

ImageFit包含以下几种类型：

  • Contain：保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内。

  • Cover（默认值）：保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界。

  • Auto：自适应显示。

  • Fill：不保持宽高比进行放大缩小，使得图片充满显示边界。

  • ScaleDown：保持宽高比显示，图片缩小或者保持不变。

  • None：保持原有尺寸显示。

加载网络图片

比如浏览新闻的时候，图片一般从网络加载而来，Image组件支持加载网络图片，将图片地址换成网络图片地址进行加载。

Image('https://www.example.com/xxx.png')

为了成功加载网络图片，您需要在module.json5文件中申明网络访问权限。

{
    "module" : {
        "requestPermissions":[
           {
             "name": "ohos.permission.INTERNET"
           }
        ]
    }
}

应用访问网络需要申请ohos.permission.INTERNET权限，因为HarmonyOS提供了一种访问控制机制即应用权限，用来保证这些数据或功能不会被不当或恶意使用。关于应用权限的的详细信息开发者可以参考：访问控制。

4 TextInput

TextInput组件用于输入单行文本，响应输入事件。TextInput的使用也非常广泛，例如应用登录账号密码、发送消息等。和Text组件一样，TextInput组件也支持文本样式设置，下面的示例代码实现了一个简单的输入框：

TextInput()
  .fontColor(Color.Blue)
  .fontSize(20)
  .fontStyle(FontStyle.Italic)
  .fontWeight(FontWeight.Bold)
  .fontFamily('Arial')

效果图如下：

设置输入提示文本

当我们平时使用输入框的时候，往往会有一些提示文字。例如登录账号的时候会有“请输入账号”这样的文本提示，当用户输入内容之后，提示文本就会消失，这种提示功能使用placeholder属性就可以轻松的实现。您还可以使用placeholderColor和placeholderFont分别设置提示文本的颜色和样式，示例代码如下：

TextInput({ placeholder: '请输入帐号' })
  .placeholderColor(0x999999)
  .placeholderFont({ size: 20, weight: FontWeight.Medium, family: 'cursive', style: FontStyle.Italic })

效果图如下：

设置输入类型

可以使用type属性来设置输入框类型。例如密码输入框，一般输入密码的时候，为了用户密码安全，内容会显示为“......”，针对这种场景，将type属性设置为InputType.Password就可以实现。示例代码如下：

TextInput({ placeholder: '请输入密码' })
  .type(InputType.Password)

效果图如下：

type的参数类型为InputType，包含以下几种输入类型：

  • Normal：基本输入模式。支持输入数字、字母、下划线、空格、特殊字符。

  • Password：密码输入模式。

  • Email：e-mail地址输入模式。

  • Number：纯数字输入模式。

设置光标位置

可以使用TextInputController动态设置光位置，下面的示例代码使用TextInputController的caretPosition方法，将光标移动到了第二个字符后。

@Entry
@Component
struct TextInputDemo {
  controller: TextInputController = new TextInputController()
 
  build() {
    Column() {
      TextInput({ controller: this.controller })
      Button('设置光标位置')
        .onClick(() => {
          this.controller.caretPosition(2)
        })
    }
    .height('100%')
    .backgroundColor(0xE6F2FD)
  }
}

效果图如下：

获取输入文本

我们可以给TextInput设置onChange事件，输入文本发生变化时触发回调，下面示例代码中的value为实时获取用户输入的文本信息。

@Entry
@Component
struct TextInputDemo {
  @State text: string = ''
 
  build() {
    Column() {
      TextInput({ placeholder: '请输入账号' })
        .caretColor(Color.Blue)
        .onChange((value: string) => {
          this.text = value
        })
      Text(this.text)
    }
    .alignItems(HorizontalAlign.Center)
    .padding(12)
    .backgroundColor(0xE6F2FD)
  }
}

效果图如下：

5 Button

Button组件主要用来响应点击操作，可以包含子组件。下面的示例代码实现了一个“登录按钮”：

Button('登录', { type: ButtonType.Capsule, stateEffect: true })
  .width('90%')
  .height(40)
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .backgroundColor('#007DFF')

效果图如下：

设置按钮样式

type用于定义按钮样式，示例代码中ButtonType.Capsule表示胶囊形按钮；stateEffect用于设置按钮按下时是否开启切换效果，当状态置为false时，点击效果关闭，默认值为true。

我们可以设置多种样式的Button，除了Capsule可以以设置Normal和Circle：

  • Capsule：胶囊型按钮（圆角默认为高度的一半）。

  • Circle：圆形按钮。

  • Normal：普通按钮（默认不带圆角）。

设置按钮点击事件

可以给Button绑定onClick事件，每当用户点击Button的时候，就会回调执行onClick方法，调用里面的逻辑代码。

Button('登录', { type: ButtonType.Capsule, stateEffect: true })
  ...
  .onClick(() => {
  // 处理点击事件逻辑
  })

包含子组件

Button组件可以包含子组件，让您可以开发出更丰富多样的Button，下面的示例代码中Button组件包含了一个Image组件：

Button({ type: ButtonType.Circle, stateEffect: true }) {
  Image($r('app.media.icon_delete'))
    .width(30)
    .height(30)
}
.width(55)
.height(55)
.backgroundColor(0x317aff)

效果图如下：

6 LoadingProgress

LoadingProgress组件用于显示加载进展，比如应用的登录界面，当我们点击登录的时候，显示的“正在登录”的进度条状态。LoadingProgress的使用非常简单，只需要设置颜色和宽高就可以了。

LoadingProgress()
  .color(Color.Blue)
  .height(60)
  .width(60)

效果图如下：

7 使用资源引用类型

Resource是资源引用类型，用于设置组件属性的值。推荐大家优先使用Resource类型，将资源文件（字符串、图片、音频等）统一存放于resources目录下，便于开发者统一维护。同时系统可以根据当前配置加载合适的资源，例如，开发者可以根据屏幕尺寸呈现不同的布局效果，或根据语言设置提供不同的字符串。

例如下面的这段代码，直接在代码中写入了字符串和数字这样的硬编码。

Button('登录', { type: ButtonType.Capsule, stateEffect: true })
  .width(300)
  .height(40)
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .backgroundColor('#007DFF')

我们可以将这些硬编码写到entry/src/main/resources下的资源文件中。

在string.json中定义Button显示的文本。

{
  "string": [
    {
      "name": "login_text",
      "value": "登录"
    }
  ]
}

在float.json中定义Button的宽高和字体大小。

{
  "float": [
    {
      "name": "button_width",
      "value": "300vp"
    },
    {
      "name": "button_height",
      "value": "40vp"
    },
    {
      "name": "login_fontSize",
      "value": "18fp"
    }
  ]
}

在color.json中定义Button的背景颜色。

{
  "color": [
    {
      "name": "button_color",
      "value": "#1890ff"
    }
  ]
}

然后在Button组件通过“$r('app.type.name')”的形式引用应用资源。app代表应用内resources目录中定义的资源；type代表资源类型（或资源的存放位置），可以取“color”、“float”、“string”、“plural”、“media”；name代表资源命名，由开发者定义资源时确定。

Button($r('app.string.login_text'), { type: ButtonType.Capsule })
  .width($r('app.float.button_width'))
  .height($r('app.float.button_height'))
  .fontSize($r('app.float.login_fontSize'))
  .backgroundColor($r('app.color.button_color'))

8 参考资料

常用基础的组件的更多使用方法可以参考：

引用资源类型的使用可以参考：

Column&Row组件的使用

1 概述

一个丰富的页面需要很多组件组成，那么，我们如何才能让这些组件有条不紊地在页面上布局呢？这就需要借助容器组件来实现。

容器组件是一种比较特殊的组件，它可以包含其他的组件，而且按照一定的规律布局，帮助开发者生成精美的页面。容器组件除了放置基础组件外，也可以放置容器组件，通过多层布局的嵌套，可以布局出更丰富的页面。

ArkTS为我们提供了丰富的容器组件来布局页面，本文将以构建登录页面为例，介绍Column和Row组件的属性与使用。

2 组件介绍

布局容器概念

线性布局容器表示按照垂直方向或者水平方向排列子组件的容器，ArkTS提供了Column和Row容器来实现线性布局。

  • Column表示沿垂直方向布局的容器。
  • Row表示沿水平方向布局的容器。

主轴和交叉轴概念

在布局容器中，默认存在两根轴，分别是主轴和交叉轴，这两个轴始终是相互垂直的。不同的容器中主轴的方向不一样的。

  • 主轴：在Column容器中的子组件是按照从上到下的垂直方向布局的，其主轴的方向是垂直方向；在Row容器中的组件是按照从左到右的水平方向布局的，其主轴的方向是水平方向。

图2-1 Column容器&Row容器主轴

  • 交叉轴：与主轴垂直相交的轴线，如果主轴是垂直方向，则交叉轴就是水平方向；如果主轴是水平方向，则交叉轴是垂直方向。

图2-2 Column容器&Row容器交叉轴

属性介绍

了解布局容器的主轴和交叉轴，主要是为了让大家更好地理解子组件在主轴和交叉轴的排列方式。

接下来，我们将详细讲解Column和Row容器的两个属性justifyContent和alignItems。

属性名称描述
justifyContent设置子组件在主轴方向上的对齐格式。
alignItems设置子组件在交叉轴方向上的对齐格式。
  1. 主轴方向的对齐（justifyContent）

子组件在主轴方向上的对齐使用justifyContent属性来设置，其参数类型是FlexAlign。FlexAlign定义了以下几种类型：

  • Start：元素在主轴方向首端对齐，第一个元素与行首对齐，同时后续的元素与前一个对齐。

  • Center：元素在主轴方向中心对齐，第一个元素与行首的距离以及最后一个元素与行尾距离相同。

  • End：元素在主轴方向尾部对齐，最后一个元素与行尾对齐，其他元素与后一个对齐。

  • SpaceBetween：元素在主轴方向均匀分配弹性元素，相邻元素之间距离相同。 第一个元素与行首对齐，最后一个元素与行尾对齐。

  • SpaceAround：元素在主轴方向均匀分配弹性元素，相邻元素之间距离相同。 第一个元素到行首的距离和最后一个元素到行尾的距离是相邻元素之间距离的一半。

  • SpaceEvenly：元素在主轴方向等间距布局，无论是相邻元素还是边界元素到容器的间距都一样。

  1. 交叉轴方向的对齐（alignItems）

子组件在交叉轴方向上的对齐方式使用alignItems属性来设置。

Column容器的主轴是垂直方向，交叉轴是水平方向，其参数类型为HorizontalAlign（水平对齐），HorizontalAlign定义了以下几种类型：

  • Start：设置子组件在水平方向上按照起始端对齐。

  • Center（默认值）：设置子组件在水平方向上居中对齐。

  • End：设置子组件在水平方向上按照末端对齐。

Row容器的主轴是水平方向，交叉轴是垂直方向，其参数类型为VerticalAlign（垂直对齐），VerticalAlign定义了以下几种类型：

  • Top：设置子组件在垂直方向上居顶部对齐。

  • Center（默认值）：设置子组件在竖直方向上居中对齐。

  • Bottom：设置子组件在竖直方向上居底部对齐。

接口介绍

接下来，我们介绍Column和Row容器的接口。

容器组件接口
ColumnColumn(value?:{space?: stringnumber})
RowRow(value?:{space?: stringnumber})

Column和Row容器的接口都有一个可选参数space，表示子组件在主轴方向上的间距。

效果如下：

3 组件使用

我们来具体讲解如何高效的使用Column和Row容器组件来构建这个登录页面。

当我们从设计同学那拿到一个页面设计图时，我们需要对页面进行拆解，先确定页面的布局，再分析页面上的内容分别使用哪些组件来实现。

我们仔细分析这个登录页面。在静态布局中，组件整体是从上到下布局的，因此构建该页面可以使用Column来构建。在此基础上，我们可以看到有部分内容在水平方向上由几个基础组件构成，例如页面中间的短信验证码登录与忘记密码以及页面最下方的其他方式登录，那么构建这些内容的时候，可以在Column组件中嵌套Row组件，继而在Row组件中实现水平方向的布局。

根据上述页面拆解，在Column容器里，依次是Image、Text、TextInput、Button等基础组件，还有两组组件是使用Row容器组件来实现的，主要代码如下：

@Entry
@Component
export struct LoginPage {
  build() {
    Column() {
      Image($r('app.media.logo'))
        ...
      Text($r('app.string.login_page'))
        ...
      Text($r('app.string.login_more'))
        ...
      TextInput({ placeholder: $r('app.string.account') })
        ...
      TextInput({ placeholder: $r('app.string.password') })
        ...
      Row() {
        Text($r(…)) 
        Text($r(…)) 
      }
      Button($r('app.string.login'), { type: ButtonType.Capsule, stateEffect: true })
        ...
      Row() {
        this.imageButton($r(…))
        this.imageButton($r(…))
        this.imageButton($r(…))
      }
      ...
    }
    ...
  }
}

我们详细看一下使用Row容器的两组组件。

两个文本组件展示的内容是按水平方向布局的，使用两端对齐的方式。这里我们使用Row容器组件，并且需要配置主轴上（水平方向）的对齐格式justifyContent为FlexAlign.SpaceBetween（两端对齐）。

Row() {
  Text($r(…)) 
  Text($r(…)) 
  }
  .justifyContent(FlexAlign.SpaceBetween)
  .width('100%')

其他登录方式的三个按钮也是按水平方向布局的，同样使用Row容器组件。这里按钮的间距是一致的，我们可以通过配置可选参数space来设置按钮间距，使子组件间距一致。

Row({ space: CommonConstants.LOGIN_METHODS_SPACE }) {
  this.imageButton($r(…))
  this.imageButton($r(…))
  this.imageButton($r(…))
}

至此，你已经完成这个登录页面的简单布局实现了。你可以参考《常用组件与布局》这个Codelab验证一下页面效果。

另外，你也可以通过《常用布局容器对齐方式》这个Codelab来深入学习Column、Row、Flex、Stack容器组件的对齐方式，掌握更多布局容器的使用方法。

4 参考链接

List组件和Grid组件的使用

简介

在我们常用的手机应用中，经常会见到一些数据列表，如设置页面、通讯录、商品列表等。下图中两个页面都包含列表，“首页”页面中包含两个网格布局，“商城”页面中包含一个商品列表。

上图中的列表中都包含一系列相同宽度的列表项，连续、多行呈现同类数据，例如图片和文本。常见的列表有线性列表（List列表）和网格布局（Grid列表）：

为了帮助开发者构建包含列表的应用，ArkUI提供了List组件和Grid组件，开发者使用List和Grid组件能够很轻松的完成一些列表页面。

List组件的使用

List组件简介

List是很常用的滚动类容器组件，一般和子组件ListItem一起使用，List列表中的每一个列表项对应一个ListItem组件。

使用ForEach渲染列表

列表往往由多个列表项组成，所以我们需要在List组件中使用多个ListItem组件来构建列表，这就会导致代码的冗余。使用循环渲染（ForEach）遍历数组的方式构建列表，可以减少重复代码，示例代码如下：

@Entry@Componentstruct ListDemo {  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
  build() {    Column() {      List({ space: 10 }) {        ForEach(this.arr, (item: number) => {          ListItem() {            Text(`${item}`)              .width('100%')              .height(100)              .fontSize(20)              .fontColor(Color.White)              .textAlign(TextAlign.Center)              .borderRadius(10)              .backgroundColor(0x007DFF)          }        }, item => item)      }    }    .padding(12)    .height('100%')    .backgroundColor(0xF1F3F5)  }}

效果图如下：

设置列表分割线

List组件子组件ListItem之间默认是没有分割线的，部分场景子组件ListItem间需要设置分割线，这时候您可以使用List组件的divider属性。divider属性包含四个参数：

  • strokeWidth: 分割线的线宽。

  • color: 分割线的颜色。

  • startMargin：分割线距离列表侧边起始端的距离。

  • endMargin: 分割线距离列表侧边结束端的距离。

List列表滚动事件监听

List组件提供了一系列事件方法用来监听列表的滚动，您可以根据需要，监听这些事件来做一些操作：

  • onScroll：列表滑动时触发，返回值scrollOffset为滑动偏移量，scrollState为当前滑动状态。
  • onScrollIndex：列表滑动时触发，返回值分别为滑动起始位置索引值与滑动结束位置索引值。
  • onReachStart：列表到达起始位置时触发。
  • onReachEnd：列表到底末尾位置时触发。
  • onScrollStop：列表滑动停止时触发。

使用示例代码如下：

List({ space: 10 }) {  ForEach(this.arr, (item) => {    ListItem() {      Text(`${item}`)        ...    }  }, item => item)}.onScrollIndex((firstIndex: number, lastIndex: number) => {  console.info('first' + firstIndex)  console.info('last' + lastIndex)}).onScroll((scrollOffset: number, scrollState: ScrollState) => {  console.info('scrollOffset' + scrollOffset)  console.info('scrollState' + scrollState)}).onReachStart(() => {  console.info('onReachStart')}).onReachEnd(() => {  console.info('onReachEnd')}).onScrollStop(() => {  console.info('onScrollStop')})

设置List排列方向

List组件里面的列表项默认是按垂直方向排列的，如果您想让列表沿水平方向排列，您可以将List组件的listDirection属性设置为Axis.Horizontal。

listDirection参数类型是Axis，定义了以下两种类型：

  • Vertical（默认值）：子组件ListItem在List容器组件中呈纵向排列。

  • Horizontal：子组件ListItem在List容器组件中呈横向排列。

Grid组件的使用

Grid组件简介

Grid组件为网格容器，是一种网格列表，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。Grid组件一般和子组件GridItem一起使用，Grid列表中的每一个条目对应一个GridItem组件。

使用ForEach渲染网格布局

和List组件一样，Grid组件也可以使用ForEach来渲染多个列表项GridItem，我们通过下面的这段示例代码来介绍Grid组件的使用。

@Entry@Componentstruct GridExample {  // 定义一个长度为16的数组  private arr: string[] = new Array(16).fill('').map((_, index) => `item ${index}`);
  build() {    Column() {      Grid() {        ForEach(this.arr, (item: string) => {          GridItem() {            Text(item)              .fontSize(16)              .fontColor(Color.White)              .backgroundColor(0x007DFF)              .width('100%')              .height('100%')              .textAlign(TextAlign.Center)          }        }, item => item)      }      .columnsTemplate('1fr 1fr 1fr 1fr')      .rowsTemplate('1fr 1fr 1fr 1fr')      .columnsGap(10)      .rowsGap(10)      .height(300)    }    .width('100%')    .padding(12)    .backgroundColor(0xF1F3F5)  }}

示例代码中创建了16个GridItem列表项。同时设置columnsTemplate的值为'1fr 1fr 1fr 1fr'，表示这个网格为4列，将Grid允许的宽分为4等分，每列占1份；rowsTemplate的值为'1fr 1fr 1fr 1fr'，表示这个网格为4行，将Grid允许的高分为4等分，每行占1份。这样就构成了一个4行4列的网格列表，然后使用columnsGap设置列间距为10vp，使用rowsGap设置行间距也为10vp。示例代码效果图如下：

上面构建的网格布局使用了固定的行数和列数，所以构建出的网格是不可滚动的。然而有时候因为内容较多，我们通过滚动的方式来显示更多的内容，就需要一个可以滚动的网格布局。我们只需要设置rowsTemplate和columnsTemplate中的一个即可。

将示例代码中GridItem的高度设置为固定值，例如100；仅设置columnsTemplate属性，不设置rowsTemplate属性，就可以实现Grid列表的滚动：

Grid() {  ForEach(this.arr, (item: string) => {    GridItem() {      Text(item)        .height(100)        ...    }  }, item => item)}.columnsTemplate('1fr 1fr 1fr 1fr').columnsGap(10).rowsGap(10).height(300)

此外，Grid像List一样也可以使用onScrollIndex来监听列表的滚动。

列表性能优化

开发者在使用长列表时，如果直接采用循环渲染方式，会一次性加载所有的列表元素，从而导致页面启动时间过长，影响用户体验，推荐通过以下方式来进行列表性能优化：

使用数据懒加载

设置list组件的宽高

参考链接

  1. List组件的相关API参考：List组件。
  2. Grid组件的相关API参考：Grid组件。
  3. 循环渲染（ForEach）：循环渲染。

Tabs组件的使用

概述

在我们常用的应用中，经常会有视图内容切换的场景，来展示更加丰富的内容。比如下面这个页面，点击底部的页签的选项，可以实现“首页”和“我的”

两个内容视图的切换。

ArkUI开发框架提供了一种页签容器组件Tabs，开发者通过Tabs组件可以很容易的实现内容视图的切换。页签容器Tabs的形式多种多样，不同的页面设计页签不一样，可以把页签设置在底部、顶部或者侧边。

本文将详细介绍Tabs组件的使用。

Tabs组件的简单使用

Tabs组件仅可包含子组件TabContent，每一个页签对应一个内容视图即TabContent组件。下面的示例代码构建了一个简单的页签页面：

@Entry@Componentstruct TabsExample {  private controller: TabsController = new TabsController()
  build() {    Column() {      Tabs({ barPosition: BarPosition.Start, controller: this.controller }) {        TabContent() {          Column().width('100%').height('100%').backgroundColor(Color.Green)        }        .tabBar('green')
        TabContent() {          Column().width('100%').height('100%').backgroundColor(Color.Blue)        }        .tabBar('blue')
        TabContent() {          Column().width('100%').height('100%').backgroundColor(Color.Yellow)        }        .tabBar('yellow')
        TabContent() {          Column().width('100%').height('100%').backgroundColor(Color.Pink)        }        .tabBar('pink')      }      .barWidth('100%') // 设置TabBar宽度      .barHeight(60) // 设置TabBar高度      .width('100%') // 设置Tabs组件宽度      .height('100%') // 设置Tabs组件高度      .backgroundColor(0xF5F5F5) // 设置Tabs组件背景颜色    }    .width('100%')    .height('100%')  }}

效果图如下：

上面示例代码中，Tabs组件中包含4个子组件TabContent，通过TabContent的tabBar属性设置TabBar的显示内容。使用通用属性width和height设置了Tabs组件的宽高，使用barWidth和barHeight设置了TabBar的宽度和高度。

说明

  • TabContent组件不支持设置通用宽度属性，其宽度默认撑满Tabs父组件。
  • TabContent组件不支持设置通用高度属性，其高度由Tabs父组件高度与TabBar组件高度决定。

设置TabBar布局模式

因为Tabs的布局模式默认是Fixed的，所以Tabs的页签是不可滑动的。当页签比较多的时候，可能会导致页签显示不全，将布局模式设置为Scrollable的话，可以实现页签的滚动。

Tabs的布局模式有Fixed（默认）和Scrollable两种：

  • BarMode.Fixed：所有TabBar平均分配barWidth宽度（纵向时平均分配barHeight高度）,页签不可滚动，效果图如下：

  • BarMode.Scrollable：每一个TabBar均使用实际布局宽度，超过总长度（横向Tabs的barWidth，纵向Tabs的barHeight）后可滑动。

  • 当页签比较多的时候，可以滑动页签，下面的示例代码将barMode设置为BarMode.Scrollable，实现了可滚动的页签：

@Entry@Componentstruct TabsExample {  private controller: TabsController = new TabsController()
  build() {    Column() {      Tabs({ barPosition: BarPosition.Start, controller: this.controller }) {        TabContent() {          Column()            .width('100%')            .height('100%')            .backgroundColor(Color.Green)        }        .tabBar('green')
        TabContent() {          Column()            .width('100%')            .height('100%')            .backgroundColor(Color.Blue)        }        .tabBar('blue')
        ...
      }      .barMode(BarMode.Scrollable)      .barWidth('100%')      .barHeight(60)      .width('100%')      .height('100%')    }  }}

设置TabBar位置和排列方向

Tabs组件页签默认显示在顶部，某些场景下您可能希望Tabs页签出现在底部或者侧边，您可以使用Tabs组件接口中的参数barPosition设置页签位置。此外页签显示位置还与vertical属性相关联，vertical属性用于设置页签的排列方向，当vertical的属性值为false（默认值）时页签横向排列，为true时页签纵向排列。

barPosition的值可以设置为BarPosition.Start（默认值）和BarPosition.End：

  • BarPosition.Start

    vertical属性方法设置为false（默认值）时，页签位于容器顶部。

    Tabs({ barPosition: BarPosition.Start }) {  ...}.vertical(false) .barWidth('100%') .barHeight(60)

    效果图如下：

    vertical属性方法设置为true时，页签位于容器左侧。

    Tabs({ barPosition: BarPosition.Start }) {  ...}.vertical(true) .barWidth(100) .barHeight(200)

    效果图如下：

  • BarPosition.End

    vertical属性方法设置为false时，页签位于容器底部。

    Tabs({ barPosition: BarPosition.End }) {  ...}.vertical(false) .barWidth('100%') .barHeight(60)

    效果图如下：

    vertical属性方法设置为true时，页签位于容器右侧。

    Tabs({ barPosition: BarPosition.End}) {  ...}.vertical(true) .barWidth(100) .barHeight(200)

    效果图如下：

自定义TabBar样式

TabBar的默认显示效果如下所示：

往往开发过程中，UX给我们的设计效果可能并不是这样的，比如下面的这种底部页签效果：

TabContent的tabBar属性除了支持string类型，还支持使用@Builder装饰器修饰的函数。您可以使用@Builder装饰器，构造一个生成自定义TabBar样式的函数，实现上面的底部页签效果，示例代码如下：

@Entry@Componentstruct TabsExample {  @State currentIndex: number = 0;  private tabsController: TabsController = new TabsController();
  @Builder TabBuilder(title: string, targetIndex: number, selectedImg: Resource, normalImg: Resource) {    Column() {      Image(this.currentIndex === targetIndex ? selectedImg : normalImg)        .size({ width: 25, height: 25 })      Text(title)        .fontColor(this.currentIndex === targetIndex ? '#1698CE' : '#6B6B6B')    }    .width('100%')    .height(50)    .justifyContent(FlexAlign.Center)    .onClick(() => {      this.currentIndex = targetIndex;      this.tabsController.changeIndex(this.currentIndex);    })  }
  build() {    Tabs({ barPosition: BarPosition.End, controller: this.tabsController }) {      TabContent() {        Column().width('100%').height('100%').backgroundColor('#00CB87')      }      .tabBar(this.TabBuilder('首页', 0, $r('app.media.home_selected'), $r('app.media.home_normal')))
      TabContent() {        Column().width('100%').height('100%').backgroundColor('#007DFF')      }      .tabBar(this.TabBuilder('我的', 1, $r('app.media.mine_selected'), $r('app.media.mine_normal')))    }    .barWidth('100%')    .barHeight(50)    .onChange((index: number) => {      this.currentIndex = index;    })  }}

示例代码中将barPosition的值设置为BarPosition.End，使页签显示在底部。使用@Builder修饰TabBuilder函数，生成由Image和Text组成的页签。同时也给Tabs组件设置了TabsController控制器，当点击某个页签时，调用changeIndex方法进行页签内容切换。

最后还需要给Tabs添加onChange事件，Tab页签切换后触发该事件，这样当我们左右滑动内容视图的时候，页签样式也会跟着改变。

参考

  • Tabs组件的更多属性和参数的使用，可以参考API：Tabs。
  • @Builder装饰器的使用，可以参考：@Builder。

Video组件的使用

概述

在手机、平板或是智慧屏这些终端设备上，媒体功能可以算作是我们最常用的场景之一。无论是实现音频的播放、录制、采集，还是视频的播放、切换、循环，亦或是相机的预览、拍照等功能，媒体组件都是必不可少的。以视频功能为例，在应用开发过程中，我们需要通过ArkUI提供的Video组件为应用增加基础的视频播放功能。借助Video组件，我们可以实现视频的播放功能并控制其播放状态。常见的视频播放场景包括观看网络上的较为流行的短视频，也包括查看我们存储在本地的视频内容。

本文将结合《简易视频播放器（ArkTS）》这个Codelab，对Video组件的参数、属性及事件进行介绍，然后通过组件的属性调用和事件回调阐明Video组件的基本使用方法，最后结合Video组件使用过程中的常见问题讲解自定义控制器的使用。

Video组件用法介绍

Video组件参数介绍

Video组件的接口表达形式为：

Video(value: {src?: string | Resource, currentProgressRate?: number | string |PlaybackSpeed, previewUri?: string |PixelMap | Resource, controller?: VideoController})

其中包含四个可选参数，src、currentProgressRate、previewUri和controller。

  • src表示视频播放源的路径，可以支持本地视频路径和网络路径。使用网络地址时，如https，需要注意的是需要在module.json5文件中申请网络权限。在使用本地资源播放时，当使用本地视频地址我们可以使用媒体库管理模块medialibrary来查询公共媒体库中的视频文件，示例代码如下：
import mediaLibrary from '@ohos.multimedia.mediaLibrary';
async queryMediaVideo() {  let option = {    // 根据媒体类型检索    selections: mediaLibrary.FileKey.MEDIA_TYPE + '=?',    // 媒体类型为视频    selectionArgs: [mediaLibrary.MediaType.VIDEO.toString()]  };  let media = mediaLibrary.getMediaLibrary(getContext(this));  // 获取资源文件  const fetchFileResult = await media.getFileAssets(option);  // 以获取的第一个文件为例获取视频地址  let fileAsset = await fetchFileResult.getFirstObject();  this.source = fileAsset.uri}

为了方便功能演示，示例中媒体资源需存放在resources下的rawfile文件夹里。

  • currentProgressRate表示视频播放倍速，其参数类型为number，取值支持0.75，1.0，1.25，1.75，2.0，默认值为1.0倍速；
  • previewUri表示视频未播放时的预览图片路径；
  • controller表示视频控制器。

参数的具体描述如下表：

参数名参数类型必填
srcstringResource否
currentProgressRatenumberstringPlaybackSpeed8+否
previewUristringPixelMap8+Resource否
controllerVideoController否

说明

视频支持的规格是：mp4、mkv、webm、TS。

下面我们通过具体的例子来说明参数的使用方法，我们选择播放本地视频，视频未播放时的预览图片路径也为本地，代码实现如下：

@Componentexport struct VideoPlayer {  private source: string | Resource;  private controller: VideoController;  private previewUris: Resource = $r('app.media.preview');  ...
  build() {    Column() {      Video({        src: this.source,        previewUri: this.previewUris,        controller: this.controller      })        ...      VideoSlider({ controller: this.controller })    }  }}

效果如下：

Video组件属性介绍

除了支持组件的尺寸设置、位置设置等通用属性外，Video组件还支持是否静音、是否自动播放、控制栏是否显示、视频显示模式以及单个视频是否循环播放五个私有属性。

名称参数类型描述
mutedboolean是否静音。默认值：false
autoPlayboolean是否自动播放。默认值：false
controlsboolean控制视频播放的控制栏是否显示。默认值：true
objectFitImageFit设置视频显示模式。默认值：Cover
loopboolean是否单个视频循环播放。默认值：false

其中，objectFit 中视频显示模式包括Contain、Cover、Auto、Fill、ScaleDown、None 6种模式，默认情况下使用ImageFit.Cover（保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界），其他效果（如自适应显示、保持原有尺寸显示、不保持宽高比进行缩放等）可以根据具体使用场景/设备来进行选择。

在Codelab示例中体现了controls、autoplay和loop属性的配置，示例代码如下：

@Componentexport struct VideoPlayer {  private source: string | Resource;  private controller: VideoController;  ...  build() {    Column() {      Video({        controller: this.controller      })        .controls(false) //不显示控制栏         .autoPlay(false) // 手动点击播放         .loop(false) // 关闭循环播放         ...    }  }}

效果如下：

Video组件回调事件介绍

Video组件能够支持常规的点击、触摸等通用事件，同时也支持onStart、onPause、onFinish、onError等事件，具体事件的功能描述见下表：

事件名称功能描述
onStart(event:() => void)播放时触发该事件。
onPause(event:() => void)暂停时触发该事件。
onFinish(event:() => void)播放结束时触发该事件。
onError(event:() => void)播放失败时触发该事件。
onPrepared(callback:(event?: { duration: number }) => void)视频准备完成时触发该事件，通过duration可以获取视频时长，单位为s。
onSeeking(callback:(event?: { time: number }) => void)操作进度条过程时上报时间信息，单位为s。
onSeeked(callback:(event?: { time: number }) => void)操作进度条完成后，上报播放时间信息，单位为s。
onUpdate(callback:(event?: { time: number }) => void)播放进度变化时触发该事件，单位为s，更新时间间隔为250ms。
onFullscreenChange(callback:(event?: { fullscreen: boolean }) => void)在全屏播放与非全屏播放状态之间切换时触发该事件

在Codelab中我们以更新事件、准备事件、失败事件以及点击事件为回调为例进行演示，代码实现如下：

Video({ ... })  .onUpdate((event) => {    this.currentTime = event.time;    this.currentStringTime = changeSliderTime(this.currentTime); //更新事件   })  .onPrepared((event) => {    prepared.call(this, event); //准备事件   })  .onError(() => {    prompt.showToast({      duration: COMMON_NUM_DURATION, //播放失败事件       message: MESSAGE    });  ...  })

其中，onUpdate更新事件在播放进度变化时触发，从event中可以获取当前播放进度，从而更新进度条显示事件，比如视频播放时间从24秒更新到30秒。onError事件在视频播放失败时触发，在CommonConstants.ets中定义了常量类MESSAGE，所以在视频播放失败时会显示“请检查网络”。

const MESSAGE: string = '请检查网络'

自定义控制器的组成与实现

自定义控制器的组成

Video组件的原生控制器样式相对固定，当我们对页面的布局色调的一致性有所要求，或者在拖动进度条的同时需要显示其百分比进度时，原生控制器就无法满足需要了。如下图右侧的效果需要使用自定义控制器实现，接下来我们看一下自定义控制器的组成。

为了实现自定义控制器的进度显示等功能，我们需要通过Row容器实现控制器的整体布局，然后借由Text组件来显示视频的播放起始时间、进度时间以及视频总时长，最后通过滑动进度条Slider组件来实现视频进度条的效果，代码如下：

@Componentexport struct VideoSlider {  ...  build() {    Row(...) {      Image(...)      Text(...)      Slider(...)      Text(...)    }    ...  }}

自定义控制器的实现

自定义控制器容器内嵌套了视频播放时间Text组件、滑动器Slider组件以及视频总时长Text组件 3个横向排列的组件，其中Text组件在之前的基础组件课程中已经有过详细介绍，这里就不再进行赘述。需要强调的是两个Text组件显示的时长是由Slider组件的onChange(callback: (value: number, mode: SliderChangeMode) => void)回调事件来进行传递的，而Text组件的数值与视频播放进度数值value则是通过@Provide与 @Consume装饰器进行的数据联动，实现效果可见图片下方黑色控制栏部分，具体代码步骤及代码如下：

获取/计算视频时长

export function prepared(event) {  this.durationTime = event.duration;  let second: number = event.duration % COMMON_NUM_MINUTE;  let min: number = parseInt((event.duration / COMMON_NUM_MINUTE).toString());  let head = min < COMMON_NUM_DOUBLE ? `${ZERO_STR}${min}` : min;  let end = second < COMMON_NUM_DOUBLE ? `${ZERO_STR}${second}` : second;  this.durationStringTime = `${head}${SPLIT}${end}`;  ...};

设置进度条参数及属性

Slider({  value: this.currentTime,  min: 0,  max: this.durationTime,  step: 1,  style: SliderStyle.OutSet})  .blockColor($r('app.color.white'))  .width(STRING_PERCENT.SLIDER_WITH)  .trackColor(Color.Gray)  .selectedColor($r('app.color.white'))  .showSteps(true)  .showTips(true)  .trackThickness(this.isOpacity ? SMALL_TRACK_THICK_NESS : BIG_TRACK_THICK_NESS)  .onChange((value: number, mode: SliderChangeMode) => {...})

计算当前进度播放时间及添加onUpdate回调

最后，在我们播放视频时还需要更新显示播放的时间进度，也就是左侧的Text组件。在视频开始播放前，播放时间默认为00:00，随着视频播放，时间需要不断更新为当前进度时间。所以左侧的Text组件我们不仅需要读取时间，还需要为其添加数据联动。这里，我们就是通过为Video组件添加onUpdate事件来实现的，在视频播放过程中会不断调用changeSliderTime方法获取当前的播放时间并进行计算及单位转化，从而不断刷新进度条的值，也就是控制器左侧的播放进度时间Text组件。

Video({...})  ...  .onUpdate((event) => {    this.currentTime = event.time;    this.currentStringTime = changeSliderTime(this.currentTime)  }) 

export function changeSliderTime(value: number): string {  let second: number = value % COMMON_NUM_MINUTE;  let min: number = parseInt((value / COMMON_NUM_MINUTE).toString());  let head = min < COMMON_NUM_DOUBLE ? `${ZERO_STR}${min}` : min;  let end = second < COMMON_NUM_DOUBLE ? `${ZERO_STR}${second}` : second;  let nowTime = `${head}${SPLIT}${end}`;  return nowTime;};

指定视频播放进度及添加onChange事件回调

如需手动进行进度条的拖动，则需要在Slider组件中指定播放进度，并为Slider组件添加onChange事件回调。Slider滑动时就会触发该事件回调，从而实现将视频定位到进度条当前刷新位置，完成时长组件渲染与视频播放进度数据联动。

Slider({...})  .onChange((value: number, mode: SliderChangeMode) => {    sliderOnchange.call(this, value, mode);  })

export function sliderOnchange(value: number, mode: SliderChangeMode) {  this.currentTime = parseInt(value.toString());  this.controller.setCurrentTime(parseInt(value.toString()), SeekMode.Accurate);  ...};

到这里我们就实现了自定义控制器的构建，两个Text组件显示的时长是由Slider组件的onChange回调事件来进行传递的，而Text组件的数值与视频播放进度数值value则通过是onUpdate与onChange事件并借由@Provide @Consume装饰器进行的数据联动。

参考链接

  • Video组件的更多属性和参数的使用，可以参考API：Video。

给您的应用添加弹窗

概述

在我们日常使用应用的时候，可能会进行一些敏感的操作，比如删除联系人，这时候我们给应用添加弹窗来提示用户是否需要执行该操作，如下图所示：

弹窗是一种模态窗口，通常用来展示用户当前需要的或用户必须关注的信息或操作。在弹出框消失之前，用户无法操作其他界面内容。ArkUI为我们提供了丰富的弹窗功能，弹窗按照功能可以分为以下两类：

  • 确认类：例如警告弹窗AlertDialog。
  • 选择类：包括文本选择弹窗TextPickerDialog 、日期滑动选择弹窗DatePickerDialog、时间滑动选择弹窗TimePickerDialog等。

您可以根据业务场景，选择不同类型的弹窗。部分弹窗效果图如下：

此外，如果上述弹窗还不能满足您的需求，或者需要对弹窗的布局和样式进行自定义，您还可以使用自定义弹窗CustomDialog。

下文将分别介绍AlertDialog 、TextPickerDialog 、DatePickerDialog以及CustomDialog的使用。

警告弹窗

警告弹窗AlertDialog由以下三部分区域构成，对应下面的示意图：

  1. 标题区：为可选的。
  2. 内容区：显示提示消息。
  3. 操作按钮区：用户做”确认“或者”取消“等操作。

以下示例代码，演示了如何使用AlertDialog 实现上图所示的警告弹窗。AlertDialog可以设置两个操作按钮，示例代码中分别使用primaryButton和secondaryButton实现了“取消”和“删除”操作按钮，操作按钮可以通过action响应点击事件。

Button('点击显示弹窗')  .onClick(() => {    AlertDialog.show(      {        title: '删除联系人', // 标题        message: '是否需要删除所选联系人?', // 内容        autoCancel: false, // 点击遮障层时，是否关闭弹窗。        alignment: DialogAlignment.Bottom, // 弹窗在竖直方向的对齐方式        offset: { dx: 0, dy: -20 }, // 弹窗相对alignment位置的偏移量        primaryButton: {          value: '取消',          action: () => {            console.info('Callback when the first button is clicked');          }        },        secondaryButton: {          value: '删除',          fontColor: '#D94838',          action: () => {            console.info('Callback when the second button is clicked');          }        },        cancel: () => { // 点击遮障层关闭dialog时的回调          console.info('Closed callbacks');        }      }    )  })

此外，您还可以使用AlertDialog，构建只包含一个操作按钮的确认弹窗，使用confirm响应操作按钮回调。

AlertDialog.show(  {    title: '提示',    message: '提示信息',    autoCancel: true,    alignment: DialogAlignment.Bottom,    offset: { dx: 0, dy: -20 },    confirm: {      value: '确认',      action: () => {        console.info('Callback when confirm button is clicked');      }    },    cancel: () => {      console.info('Closed callbacks')    }  })

选择类弹窗

选择类弹窗用于方便用户选择相关数据，比如选择喜欢吃的水果、出生日期等等。下面我们以TextPickerDialog和DatePickerDialog为例，来介绍选择类弹窗的使用。

文本选择弹窗

TextPickerDialog为文本滑动选择器弹窗，根据指定的选择范围创建文本选择器，展示在弹窗上，例如下面这段示例代码使用TextPickerDialog实现了一个水果选择弹窗。示例代码中使用selected指定了弹窗的初始选择项索引为2，对应的数据为“香蕉”。当用户点击“确定”操作按钮后，会触发onAccept事件回调，在回调中将选中的值，传递给宿主中的select变量。

@Entry@Componentstruct TextPickerDialogDemo {  @State select: number = 2;  private fruits: string[] = ['苹果', '橘子', '香蕉', '猕猴桃', '西瓜'];
  build() {    Column() {      Button('TextPickerDialog')        .margin(20)        .onClick(() => {          TextPickerDialog.show({            range: this.fruits, // 设置文本选择器的选择范围            selected: this.select, // 设置初始选中项的索引值。            onAccept: (value: TextPickerResult) => { // 点击弹窗中的“确定”按钮时触发该回调。              // 设置select为按下确定按钮时候的选中项index，这样当弹窗再次弹出时显示选中的是上一次确定的选项              this.select = value.index;              console.info("TextPickerDialog:onAccept()" + JSON.stringify(value));            },            onCancel: () => { // 点击弹窗中的“取消”按钮时触发该回调。              console.info("TextPickerDialog:onCancel()");            },            onChange: (value: TextPickerResult) => { // 滑动弹窗中的选择器使当前选中项改变时触发该回调。              console.info('TextPickerDialog:onChange()' + JSON.stringify(value));            }          })        })    }    .width('100%')  }}

效果图如下：

日期选择弹窗

下面我们介绍另一种常用的选择类弹窗DatePickerDialog，它是日期滑动选择器弹窗，根据指定的日期范围创建日期滑动选择器，展示在弹窗上。DatePickerDialog的使用非常广泛，比如当我们需要输入个人出生日期的时候，就可以使用DatePickerDialog。下面的示例代码实现了一个日期选择弹窗：

@Entry@Componentstruct DatePickerDialogDemo {  selectedDate: Date = new Date('2010-1-1');
  build() {    Column() {      Button("DatePickerDialog")        .margin(20)        .onClick(() => {          DatePickerDialog.show({            start: new Date('1900-1-1'), // 设置选择器的起始日期            end: new Date('2023-12-31'), // 设置选择器的结束日期            selected: this.selectedDate, // 设置当前选中的日期            lunar: false,            onAccept: (value: DatePickerResult) => { // 点击弹窗中的“确定”按钮时触发该回调              // 通过Date的setFullYear方法设置按下确定按钮时的日期，这样当弹窗再次弹出时显示选中的是上一次确定的日期              this.selectedDate.setFullYear(value.year, value.month, value.day)              console.info('DatePickerDialog:onAccept()' + JSON.stringify(value))            },            onCancel: () => { // 点击弹窗中的“取消”按钮时触发该回调              console.info('DatePickerDialog:onCancel()')            },            onChange: (value: DatePickerResult) => { // 滑动弹窗中的滑动选择器使当前选中项改变时触发该回调              console.info('DatePickerDialog:onChange()' + JSON.stringify(value))            }          })        })    }    .width('100%')  }}

效果图如下：

自定义弹窗

自定义弹窗的使用更加灵活，适用于更多的业务场景，在自定义弹窗中您可以自定义弹窗内容，构建更加丰富的弹窗界面。自定义弹窗的界面可以通过装饰器@CustomDialog定义的组件来实现，然后结合CustomDialogController来控制自定义弹窗的显示和隐藏。下面我们通过一个兴趣爱好的选择框来介绍自定义弹窗的使用。

从上面的效果图可以看出，这个选择框是一个多选的列表弹窗，我们可以使用装饰器@CustomDialog，结合List组件来完成这个弹窗布局，实现步骤如下：

  1. 初始化弹窗数据。

    先准备好资源文件和数据实体类。其中资源文件stringarray.json创建在resources/base/element目录下，文件根节点为strarray。

    {  "strarray": [    {      "name": "hobbies_data",      "value": [        {          "value": "Soccer"        },        {          "value": "Badminton"        },        {          "value": "Travelling"        },        ...       ]    }  ]}

    实体类HobbyBean用来封装自定义弹窗中的"兴趣爱好"数据。

    export default class HobbyBean {  label: string;  isChecked: boolean;}

    然后创建一个ArkTS文件CustomDialogWidget，用来封装自定义弹窗，使用装饰器@CustomDialog修饰CustomDialogWidget表示这是一个自定义弹窗。使用资源管理对象manager获取数据，并将数据封装到hobbyBeans。

    @CustomDialogexport default struct CustomDialogWidget {  @State hobbyBeans: HobbyBean[] = [];
  aboutToAppear() {    let context: Context = getContext(this);    let manager = context.resourceManager;    manager.getStringArrayValue($r('app.strarray.hobbies_data'), (error, hobbyResult) => {      ...      hobbyResult.forEach((hobbyItem: string) => {        let hobbyBean = new HobbyBean();        hobbyBean.label = hobbyItem;        hobbyBean.isChecked = false;        this.hobbyBeans.push(hobbyBean);      });    });  }
  build() {...}}

  2. 创建弹窗组件。

    controller对象用于控制弹窗的控制和隐藏，hobbies表示弹窗选中的数据结果。setHobbiesValue方法用于筛选出被选中的数据，赋值给hobbies。

    @CustomDialogexport default struct CustomDialogWidget {  @State hobbyBeans: HobbyBean[] = [];  @Link hobbies: string;  private controller?: CustomDialogController;
  aboutToAppear() {...}
  setHobbiesValue(hobbyBeans: HobbyBean[]) {    let hobbiesText: string = '';    hobbiesText = hobbyBeans.filter((isCheckItem: HobbyBean) =>    isCheckItem?.isChecked)      .map((checkedItem: HobbyBean) => {        return checkedItem.label;      }).join(',');    this.hobbies = hobbiesText;  }
  build() {    Column() {      Text($r('app.string.text_title_hobbies'))...      List() {        ForEach(this.hobbyBeans, (itemHobby: HobbyBean) => {          ListItem() {            Row() {              Text(itemHobby.label)...              Toggle({ type: ToggleType.Checkbox, isOn: false })...                .onChange((isCheck) => {                  itemHobby.isChecked = isCheck;                })            }          }        }, itemHobby => itemHobby.label)      }
      Row() {        Button($r('app.string.cancel_button'))...          .onClick(() => {            this.controller?.close();          })        Button($r('app.string.definite_button'))...          .onClick(() => {            this.setHobbiesValue(this.hobbyBeans);            this.controller?.close();          })      }    }  }}

  3. 使用自定义弹窗。

    在自定义弹窗的使用页面HomePage中先定义一个变量hobbies，使用装饰器@State修饰，和自定义弹窗中的@Link 装饰器修饰的变量进行双向绑定。然后我们使用alignment和offset设置弹窗的位置在屏幕底部，并且距离底部20vp。最后我们在自定义组件TextCommonWidget（具体实现可以参考《构建多种样式弹窗》Codelab源码）的点击事件中，调用customDialogController的open方法，用于显示弹窗。

    @Entry@Componentstruct HomePage {  customDialogController: CustomDialogController = new CustomDialogController({    builder: CustomDialogWidget({      onConfirm: this.setHobbiesValue.bind(this),    }),    alignment: DialogAlignment.Bottom,    customStyle: true,    offset: { dx: 0,dy: -20 }  });
  setHobbiesValue(hobbyArray: HobbyBean[]) {...}
  build() {    ...      TextCommonWidget({        ...        title: $r('app.string.title_hobbies'),        content: $hobby,        onItemClick: () => {          this.customDialogController.open();        }      })    ...  }}

参考

关于更多弹窗，您可以参考：

警告弹窗

列表选择弹窗

自定义弹窗

日期滑动选择弹窗

时间滑动选择弹窗

文本滑动选择弹窗

avatar
文章
阅读
粉丝