ArkTSUI框架入门学习指南

一、前言

ArkTSUI是一套用于HarmonyOS应用开发的用户界面（UI）开发框架，它基于ArkTS编程语言，为开发者提供了便捷、高效且灵活的方式来创建HarmonyOS应用的用户界面。本说明文档旨在帮助初学者快速了解和掌握ArkTSUI框架的基础知识，包括常用组件和容器组件的相关内容，并通过详细的说明和代码示例让大家更好地理解其使用方法。

二、常用组件介绍

（一）文本组件（Text）

• 功能说明：用于在界面上展示文本信息，是构建应用UI时最基本的元素之一，可呈现各种格式、样式的文字内容，比如标题、正文、提示语等。
• 主要属性及用法：
  • text：通过该属性设置要显示的具体文本内容，是必须设置的关键属性，示例如下：

    // 定义一个显示“欢迎使用ArkTSUI”的文本组件
    Text('欢迎使用ArkTSUI')

  • fontSize：用来指定文本的字号大小，单位可以根据实际需求和设计规范调整，常见的是像素，示例代码：

    // 将文本字号设置为16像素
    Text('示例文本').fontSize(16)

  • color：设置文本的颜色，支持常见的颜色表示方式，如直接使用预定义的颜色常量（例如Color.Red表示红色）或者通过十六进制颜色码等形式来指定，示例如下：

    // 把文本颜色设置为红色
    Text('示例文本').color(Color.Red)

  • textAlign：规定文本的对齐方式，有左对齐（TextAlign.Start）、居中对齐（TextAlign.Center）、右对齐（TextAlign.End）等选项，代码示例如下：

    // 让文本在水平方向上居中显示
    Text('示例文本').textAlign(TextAlign.Center)

（二）按钮组件（Button）

• 功能说明：作为交互元素，用户可通过点击按钮触发相应的操作，常用于提交表单、执行命令、切换页面等场景，是提升应用交互性的关键组件。
• 主要属性及用法：
  • text：定义按钮上显示的文字，直观地告知用户按钮的功能，示例如下：

    // 创建一个显示“确认”字样的按钮
    Button('确认')

  • onClick：绑定点击按钮时要执行的函数逻辑，当用户点击按钮时，就会执行与之绑定的函数，示例代码如下：

    Button('点击我')
    .onClick(() => {
    console.log('按钮被点击了');
    })

  • type：可以设置按钮的类型，不同类型有不同的外观样式，常见的有默认类型（ButtonType.Normal）、主要按钮类型（ButtonType.Primary）等，示例如下：

    // 让按钮呈现出符合主要按钮风格的视觉效果
    Button('主要按钮').type(ButtonType.Primary)

（三）输入框组件（TextInput）

• 功能说明：供用户输入文本内容，常用于登录、注册、搜索、留言等需要用户手动输入信息的场景，方便获取用户输入的数据。
• 主要属性及用法：
  • placeholder：设置输入框的占位提示文本，当输入框为空时显示，提醒用户输入的内容要求，示例如下：

    // 设置输入框的占位提示文本为“请输入用户名”
    TextInput({ placeholder: '请输入用户名' })

  • text：可以获取或设置输入框内当前的文本内容，便于在代码中对用户输入的数据进行处理，例如通过相应的逻辑函数获取text属性的值来判断用户输入了什么内容，代码示例如下：

    let inputValue: string;
    TextInput({ placeholder: '请输入搜索关键词' })
    .onChange((value: string) => {
    inputValue = value;
    })

  • onChange：绑定输入框内容改变时触发的函数，用于实时监测用户输入情况并做出响应，示例如下：

    TextInput({ placeholder: '请输入搜索关键词' })
    .onChange((value: string) => {
    console.log('输入内容发生变化，当前内容为：', value);
    })

（四）图像组件（Image）

• 功能说明：用于在界面上展示图片，能够加载本地图片或者网络图片资源，让应用界面更加生动形象，常用于展示产品图片、用户头像、背景图等场景。
• 主要属性及用法：
  • src：指定图片的来源，可以是本地文件路径（相对路径或绝对路径，取决于项目的图片资源组织方式），也可以是网络图片的URL地址，示例如下：

    // 展示项目中common/images目录下的logo.png本地图片
    Image({ src: '/common/images/logo.png' })

  • width 和 height：分别用于设置图片的宽度和高度，可按照界面设计需求调整图片的尺寸大小，示例如下：

    // 把图片尺寸限定为宽高均100像素
    Image({ src: '/common/images/logo.png', width: 100, height: 100 })

（五）列表组件（List）

• 功能说明：以列表形式展示多条数据，方便用户浏览和查看相关信息，常用于展示文章列表、商品列表、消息列表等场景，具备良好的滚动和数据展示性能。
• 主要属性及用法：
  • for：通过该属性结合数据集合来循环生成列表项，示例如下：
    假设有一个数组let dataArray = [ { name: '商品1', price: 100 }, { name: '商品2', price: 200 } ];，使用列表组件展示数据的代码如下：

    List({ space: 10 }) {
    ForEach(dataArray, (item) => {
    ListItem() {
        Text(item.name).fontSize(14)
        Text('价格：' + item.price).fontSize(12)
    }
    })
    }

  • scrollable：设置列表是否可滚动，当数据量较多超出屏幕显示范围时，可设置为true使其具备滚动功能，方便用户查看全部内容，比如：

    // 设置列表可滚动
    List({ scrollable: true })

（六）卡片组件（Card）

• 功能说明：将相关内容进行整合，以卡片的形式呈现，有清晰的边界和布局，常用于展示独立的信息块，如一篇文章的简要介绍、一个商品的详情、一条通知内容等，使界面层次更加分明。
• 主要属性及用法：
  • width 和 height：可以自定义卡片的尺寸大小，以适配界面整体布局和设计风格，示例如下：

    // 定义一个宽200像素、高150像素的卡片
    Card({ width: 200, height: 150 })

  • onClick：同样可以绑定点击卡片时触发的逻辑，比如在展示商品信息的卡片上绑定点击逻辑，点击后跳转到商品详情页面等，示例如下：

    Card({ width: 200, height: 150 }) {
    // 卡片内填充相关的文本、图像等组件
    Text('商品示例')
    Image({ src: '/common/images/product.jpg' })
    }
    .onClick(() => {
    // 执行跳转到商品详情页面的逻辑
    })

三、容器组件介绍

（一）Column（列容器）组件

• 功能说明：主要用于将其子组件按照垂直方向依次排列，形成列布局，适用于创建诸如表单、垂直导航栏、内容列表等需要纵向排列组件的界面场景，能让界面元素在垂直维度上呈现出清晰、有序的布局效果。
• 主要属性及用法：
  • space：用于设置子组件之间在垂直方向上的间距大小，单位通常为像素，可根据界面设计的疏密程度合理调整该值，使界面看起来更加协调美观，示例如下：

    // 设置子组件之间垂直间隔为10像素
    Column({ space: 10 }) {
    Text('文本1')
    Text('文本2')
    }

  • alignItems：确定子组件在水平方向上的对齐方式，有多种可选值，如AlignItems.Start（左对齐）、AlignItems.Center（居中对齐）、AlignItems.End（右对齐）等，示例如下：

    Column({ space: 10, alignItems: AlignItems.Center }) {
    Text('文本1')
    Text('文本2')
    }

    在上述代码中，两个文本组件在垂直方向依次排列，且在水平方向上居中对齐。

  • justifyContent：用来控制子组件在垂直方向上的对齐方式，可选值包含JustifyContent.Start（顶部对齐）、JustifyContent.Center（居中对齐）、JustifyContent.End（底部对齐）、JustifyContent.SpaceBetween（两端对齐，子组件之间等间距分布）等，可根据实际需求灵活设置，示例如下：

    Column({ space: 10, justifyContent: JustifyContent.SpaceBetween }) {
    Text('文本1')
    Text('文本2')
    Text('文本3')
    }

    这段代码使得三个文本组件在垂直方向等间距分布，两端对齐。

（二）Row（行容器）组件

• 功能说明：将子组件按照水平方向依次排列，构建出水平布局的效果，常用于创建菜单栏、按钮组、图片横向展示等需要横向排列组件的界面情况，有助于实现界面元素在水平维度上的合理布局。
• 主要属性及用法：
  • space：和Column组件中的该属性类似，不过这里是设置子组件之间在水平方向上的间距大小，例如：

    // 设置子组件间水平间隔为8像素
    Row({ space: 8 }) {
    Text('文本1')
    Text('文本2')
    }

  • alignItems：同样用于确定子组件在垂直方向上的对齐方式，可选值与Column组件中的一致，比如：

    Row({ space: 8, alignItems: AlignItems.Center }) {
    Text('文本1')
    Text('文本2')
    }

    能让子组件在垂直方向上居中对齐，使水平排列的组件看起来更加整齐。

  • justifyContent：控制子组件在水平方向上的对齐方式，其可选值和功能与Column组件中相应属性类似，像：

    Row({ space: 8, justifyContent: JustifyContent.SpaceEvenly }) {
    Text('文本1')
    Text('文本2')
    }

    会使子组件在水平方向上均匀分布，各部分间距相等，呈现出均匀的布局效果。

（三）Flex（弹性容器）组件

• 功能说明：提供了更加灵活的布局方式，它基于弹性盒子模型，能够根据子组件的大小、权重以及容器的可用空间等因素，自适应地调整子组件的大小和位置，适用于多种复杂的界面布局需求，尤其是在需要灵活分配空间、应对不同屏幕尺寸的场景下表现出色。
• 主要属性及用法：
  • direction：用于指定弹性布局的方向，可取值为FlexDirection.Row（水平方向布局，类似Row组件）或FlexDirection.Column（垂直方向布局，类似Column组件），示例如下：

    // 创建一个水平方向的弹性布局，两个文本组件将按此方向排列
    Flex({ direction: FlexDirection.Row }) {
    Text('文本1')
    Text('文本2')
    }

  • justifyContent：该属性在Flex组件中同样用于控制子组件在主轴方向（由direction属性确定的方向）上的对齐方式，可选值与前面Column、Row组件中的类似，比如：

    // 使子组件在水平方向上居中对齐
    Flex({ direction: FlexDirection.Row, justifyContent: JustifyContent.Center })

  • alignItems：用于确定子组件在交叉轴方向（与主轴方向垂直的方向）上的对齐方式，可选值也和之前的组件一致，例如：

    // 在垂直方向的弹性布局下，让子组件在水平方向（交叉轴方向）上左对齐
    Flex({ direction: FlexDirection.Column, alignItems: AlignItems.Start })

  • flexGrow：可以为子组件设置弹性生长因子，用于决定子组件在有多余空间时如何分配这些空间来进行伸展，数值越大，分配到的空间相对越多，示例如下：

    Flex({ direction: FlexDirection.Row }) {
    Text('文本1').flexGrow(1)
    Text('文本2').flexGrow(2)
    }

    在上述水平方向的弹性布局中，当容器有多余空间时，“文本2”会分配到相对更多的空间，因为其flexGrow值更大。

（四）Stack（堆叠容器）组件

• 功能说明：允许将子组件按照堆叠的方式进行排列，后添加的子组件会覆盖在前面子组件之上，就像把一张张图片叠放在一起一样，常用于创建一些需要重叠效果的界面，比如图片叠加展示、弹出层覆盖在基础界面之上等场景。
• 主要属性及用法：
  • alignContent：用来确定子组件整体在容器内的对齐方式，可选值有AlignContent.Start（左上角对齐）、AlignContent.Center（正中心对齐）、AlignContent.End（右上角对齐）等，示例如下：

    Stack({ alignContent: AlignContent.Center }) {
    Image({ src: '/common/images/bg.jpg' })
    Text('叠加的文字').fontSize(24).color(Color.White)
    }

    在上述代码中，文本组件会叠加在图片组件之上，并且整体在容器的正中心对齐。

  • alignItems：与其他容器组件类似，用于控制子组件在交叉轴方向上的对齐方式，比如在水平方向上对齐子组件等，根据具体堆叠布局的需求进行设置。

（五）Grid（网格容器）组件

• 功能说明：能够将子组件按照网格的形式进行排列，通过定义行数、列数以及各子组件对应的行列位置等属性，实现整齐、规则的界面布局，常用于展示图片九宫格、商品展示矩阵等场景，使界面呈现出规整的网格状效果。
• 主要属性及用法：
  • columns：指定网格的列数，例如：

    // 创建一个具有3列的网格布局
    Grid({ columns: 3 })

  • rows：确定网格的行数，比如：

    // 创建一个3列2行的网格容器，一共可以放置6个子组件，各子组件会按行列顺序分布在相应位置
    Grid({ columns: 3, rows: 2 })

  • columnGap：设置列与列之间的间距大小，单位通常为像素，方便控制网格在水平方向上的疏密程度，像：

    // 使各列之间间隔10像素
    Grid({ columns: 3, columnGap: 10 })

  • rowGap：用于设定行与行之间的间距大小，同样以像素为单位，例如：

    // 让各行之间有8像素的间隔，使网格布局更加协调美观
    Grid({ columns: 3, rows: 2, rowGap: 8 })

希望这份学习指南能帮助初学者快速入门ArkTSUI框架，在HarmonyOS应用开发中更好地构建出美观且功能完善的用户界面。大家可以通过不断实践、参考官方文档以及探索更多实际案例来深入掌握该框架的使用技巧哦。
ArkTS（方舟编程语言）
ArkUI（方舟UI框架）
ArkWeb（方舟Web）