整理 ArkUI控件及其使用方法

整理 ArkUI（HarmonyOS 基于 ArkTS 的声明式 UI 框架），涵盖基础组件、布局容器、交互控件、功能型组件等核心类型，并附上简洁的使用示例，方便快速查阅和使用。

下面我会按照控件功能分类，系统梳理 ArkUI 所有常用控件，每个类别包含核心组件、关键属性和极简示例，兼顾全面性和实用性（基于 HarmonyOS 4.0+ 版本）。

---

ArkUI 控件分类大全

ArkUI 遵循 "声明式" 设计理念，所有组件均支持链式调用属性（如 .width()/.backgroundColor()），核心分为基础组件、布局组件、交互组件、功能组件、容器组件五大类。

一、基础文本与图像组件

1. Text（文本）

最基础的文本展示组件，支持样式定制、富文本、文本溢出处理。

typescript

运行

@Entry
@Component
struct TextDemo {
  build() {
    Column() {
      // 基础文本
      Text("Hello ArkUI")
        .fontSize(24)          // 字体大小（默认单位 vp）
        .fontWeight(FontWeight.Bold) // 字重
        .fontColor(Color.Blue)  // 文字颜色
        .backgroundColor(Color.LightGray)
        .padding(10)
      
      // 多行文本与溢出处理
      Text("这是一段超长的测试文本，用于展示文本溢出时的处理方式，支持省略号截断")
        .fontSize(16)
        .maxLines(2)           // 最大行数
        .textOverflow({ overflow: TextOverflow.Ellipsis }) // 尾部省略
        .width(200)
        .margin(10)
      
      // 富文本（Span 嵌套）
      Text() {
        Span("普通文本").fontColor(Color.Black)
        Span("红色文本").fontColor(Color.Red).fontSize(18)
        Span("加粗文本").fontWeight(FontWeight.Bold)
      }
    }
    .padding(20)
  }
}

2. Image（图像）

支持本地图片、网络图片、矢量图（SVG）、系统图标，适配鸿蒙多设备。

typescript

运行

@Component
struct ImageDemo {
  build() {
    Column() {
      // 本地图片（resource 目录下）
      Image($r("app.media.logo")) // 引用 media 目录下的 logo 图片
        .width(150)
        .height(150)
        .objectFit(ImageFit.Contain) // 缩放模式：contain/cover/fill 等
        .borderRadius(10) // 圆角
        .margin(10)
      
      // 网络图片（需配置网络权限：ohos.permission.INTERNET）
      Image("https://example.com/image.jpg")
        .width(150)
        .height(150)
        .placeholder($r("app.media.placeholder")) // 加载占位图
        .error($r("app.media.error")) // 加载失败图
        .margin(10)
      
      // 系统矢量图标（鸿蒙内置）
      Image($r("sys.media.ic_public_favorite_filled"))
        .width(40)
        .height(40)
        .fillColor(Color.Red) // 矢量图填充色
    }
  }
}

3. TextField / TextArea（单行 / 多行输入框）

文本输入组件，支持类型限制、输入过滤、焦点控制。

typescript

运行

@Component
struct InputDemo {
  @State private var username: string = ""
  @State private var password: string = ""
  @State private var desc: string = ""

  build() {
    Column() {
      // 单行输入框（用户名）
      TextField("请输入用户名", $username)
        .width('100%')
        .padding(12)
        .border({ width: 1, color: Color.Grey, radius: 8 })
        .inputType(InputType.Normal) // 输入类型：Normal/Password/Email 等
        .margin(5)
      
      // 密码输入框
      TextField("请输入密码", $password)
        .width('100%')
        .padding(12)
        .border({ width: 1, color: Color.Grey, radius: 8 })
        .inputType(InputType.Password)
        .margin(5)
      
      // 多行文本框
      TextArea({ placeholder: "请输入描述", text: $desc })
        .width('100%')
        .height(100)
        .padding(12)
        .border({ width: 1, color: Color.Grey, radius: 8 })
        .margin(5)
    }
    .padding(20)
  }
}

二、核心布局容器组件

ArkUI 布局体系以 Flex 弹性布局 为核心，以下是最常用的布局容器：

1. Column / Row（线性布局）

• Column：垂直排列子组件（主轴为垂直方向）
• Row：水平排列子组件（主轴为水平方向）

typescript

运行

@Component
struct FlexLayoutDemo {
  build() {
    Column() {
      // 水平布局：主轴居中，交叉轴居中
      Row() {
        Text("左侧")
          .width(80)
          .height(40)
          .backgroundColor(Color.LightBlue)
        Text("中间")
          .width(80)
          .height(40)
          .backgroundColor(Color.LightGreen)
        Text("右侧")
          .width(80)
          .height(40)
          .backgroundColor(Color.LightPink)
      }
      .justifyContent(FlexAlign.Center) // 主轴对齐：center/start/end/spaceBetween 等
      .alignItems(ItemAlign.Center)     // 交叉轴对齐
      .width('100%')
      .height(100)
      .backgroundColor(Color.Grey)
      .margin(10)
      
      // 垂直布局：自动换行
      Column({ space: 10 }) { // 子组件间距 10vp
        ForEach(0..<5, (index) => {
          Text("Item \(index)")
            .width(80)
            .height(40)
            .backgroundColor(Color.Orange)
        })
      }
      .flexWrap(FlexWrap.Wrap) // 自动换行
      .width(200)
      .backgroundColor(Color.LightGray)
    }
    .padding(20)
  }
}

2. Stack（层叠布局）

子组件层叠排列，支持绝对定位、对齐方式。

typescript

运行

@Component
struct StackDemo {
  build() {
    Stack({ alignContent: Alignment.Center }) { // 默认居中对齐
      // 底层背景
      Image($r("app.media.background"))
        .width(300)
        .height(200)
        .objectFit(ImageFit.Cover)
      
      // 中层蒙版
      Text()
        .width('100%')
        .height('100%')
        .backgroundColor(Color.Black.opacity(0.5))
      
      // 上层文本（绝对定位）
      Text("层叠布局示例")
        .fontSize(20)
        .fontColor(Color.White)
        .position({ x: 50, y: 50 }) // 相对于 Stack 左上角定位
    }
    .borderRadius(10)
  }
}

3. List / Grid（列表 / 网格）

用于展示大量数据，支持懒加载、下拉刷新、上拉加载。

List（列表）

typescript

运行

@Component
struct ListDemo {
  private readonly fruits: string[] = ["苹果", "香蕉", "橙子", "葡萄", "草莓"]

  build() {
    List({ space: 10 }) { // 子项间距 10vp
      // 列表分组头部
      ListGroupHeader() {
        Text("水果列表")
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .padding(10)
      }

      // 循环渲染列表项
      ForEach(this.fruits, (item) => {
        ListItem() {
          Row({ space: 10 }) {
            Image($r("sys.media.ic_public_food"))
              .width(30)
              .height(30)
            Text(item)
              .fontSize(16)
          }
          .padding(15)
          .backgroundColor(Color.White)
          .borderRadius(8)
        }
        .onClick(() => {
          console.log("点击了：" + item)
        })
      })
    }
    .width('100%')
    .height(300)
    .backgroundColor(Color.LightGray)
    .padding(10)
    // 下拉刷新
    .refresh({ refreshing: false }, () => {
      // 刷新逻辑
    })
  }
}

Grid（网格）

typescript

运行

@Component
struct GridDemo {
  build() {
    Grid() {
      // 网格分组
      GridGroup() {
        ForEach(0..<6, (index) => {
          GridItem() {
            Text("Item \(index)")
              .width('100%')
              .height(80)
              .backgroundColor(Color.Blue.opacity(0.7))
              .fontColor(Color.White)
              .textAlign(TextAlign.Center)
              .borderRadius(8)
          }
        })
      }
    }
    .columnsTemplate("1fr 1fr 1fr") // 3列，每列占 1 份
    .rowsTemplate("1fr 1fr")        // 2行，每行占 1 份
    .columnsGap(10)                  // 列间距
    .rowsGap(10)                     // 行间距
    .width('100%')
    .height(200)
    .padding(10)
  }
}

4. ScrollView（滚动视图）

支持垂直 / 水平滚动，可嵌套复杂布局。

typescript

运行

@Component
struct ScrollViewDemo {
  build() {
    ScrollView() { // 默认垂直滚动，可指定 ScrollDirection.Horizontal 水平滚动
      Column({ space: 10 }) {
        ForEach(0..<10, (index) => {
          Text("滚动项 \(index)")
            .width('100%')
            .height(60)
            .backgroundColor(Color.Orange.opacity(0.8))
            .textAlign(TextAlign.Center)
            .borderRadius(8)
        })
      }
      .padding(10)
    }
    .width('100%')
    .height(200)
    .backgroundColor(Color.LightGray)
  }
}

三、交互控件

用于响应用户操作（点击、选择、滑动等）。

1. Button（按钮）

支持基础按钮、图标按钮、自定义样式按钮。

typescript

运行

@Component
struct ButtonDemo {
  build() {
    Column({ space: 10 }) {
      // 基础按钮
      Button("普通按钮")
        .onClick(() => {
          console.log("普通按钮点击")
        })
        .width(150)
        .height(40)
        .backgroundColor(Color.Blue)
        .fontColor(Color.White)
        .borderRadius(8)
      
      // 图标按钮
      Button() {
        Row({ space: 5 }) {
          Image($r("sys.media.ic_public_add"))
            .width(20)
            .height(20)
            .fillColor(Color.White)
          Text("添加")
        }
      }
      .onClick(() => {
        console.log("图标按钮点击")
      })
      .width(150)
      .height(40)
      .backgroundColor(Color.Green)
      .borderRadius(8)
      
      // 禁用按钮
      Button("禁用按钮")
        .width(150)
        .height(40)
        .backgroundColor(Color.Grey)
        .fontColor(Color.White)
        .borderRadius(8)
        .enabled(false)
    }
    .padding(20)
  }
}

2. Toggle（开关 / 复选框 / 单选框）

支持三种样式：Switch（开关）、Checkbox（复选框）、Radio（单选框）。

typescript

运行

@Component
struct ToggleDemo {
  @State private var isSwitchOn: boolean = false
  @State private var isCheckboxChecked: boolean = false
  @State private var radioValue: string = "option1"

  build() {
    Column({ space: 20 }) {
      // 开关
      Toggle({ type: ToggleType.Switch, isOn: $isSwitchOn }) {
        Text("开启功能：\(this.isSwitchOn ? "是" : "否")")
      }
      
      // 复选框
      Toggle({ type: ToggleType.Checkbox, isOn: $isCheckboxChecked }) {
        Text("同意协议：\(this.isCheckboxChecked ? "是" : "否")")
      }
      
      // 单选框组
      Column({ space: 10 }) {
        Toggle({ type: ToggleType.Radio, isOn: this.radioValue === "option1" }) {
          Text("选项1")
        }
        .onChange((isOn) => {
          if (isOn) this.radioValue = "option1"
        })
        
        Toggle({ type: ToggleType.Radio, isOn: this.radioValue === "option2" }) {
          Text("选项2")
        }
        .onChange((isOn) => {
          if (isOn) this.radioValue = "option2"
        })
      }
    }
    .padding(20)
  }
}

3. Slider / Rating（滑块 / 评分）

用于数值调整、星级评分。

typescript

运行

@Component
struct SliderRatingDemo {
  @State private var sliderValue: number = 50
  @State private var ratingValue: number = 3

  build() {
    Column({ space: 20 }) {
      // 滑块
      Slider({
        value: $sliderValue,
        min: 0,
        max: 100,
        step: 1
      })
      .width('80%')
      .blockColor(Color.Red) // 滑块颜色
      .trackColor(Color.Grey) // 轨道颜色
      .selectedColor(Color.Red) // 已选轨道颜色
      Text("滑块值：\(this.sliderValue)")
      
      // 评分控件
      Rating({
        rating: $ratingValue,
        indicator: false // 是否仅展示（false 可交互）
      })
      .starsCount(5) // 总星数
      .stepSize(1)   // 步长
      .foregroundColor(Color.Yellow) // 选中星颜色
      .secondaryColor(Color.Grey)    // 未选中星颜色
      .Text("评分：\(this.ratingValue) 星")
    }
    .padding(20)
  }
}

4. Picker（选择器）

支持文本选择、日期选择、时间选择，适配鸿蒙多设备形态。

typescript

运行

@Component
struct PickerDemo {
  @State private var selectedFruit: number = 0
  @State private var selectedDate: Date = new Date()
  private readonly fruits: string[] = ["苹果", "香蕉", "橙子"]

  build() {
    Column({ space: 20 }) {
      // 文本选择器
      Picker({
        range: this.fruits,
        value: $selectedFruit
      })
      .width('80%')
      .height(40)
      .backgroundColor(Color.White)
      .border({ width: 1, color: Color.Grey, radius: 8 })
      Text("选中：\(this.fruits[this.selectedFruit])")
      
      // 日期选择器
      DatePicker({
        start: new Date(2020, 0, 1),
        end: new Date(2030, 11, 31),
        selected: $selectedDate
      })
      .width('80%')
      .onChange((value: DatePickerResult) => {
        console.log("选中日期：", value.year, value.month, value.day)
      })
    }
    .padding(20)
  }
}

四、功能型组件

提供特定业务功能（弹窗、导航、进度、加载等）。

1. ProgressBar / LoadingProgress（进度条 / 加载动画）

typescript

运行

@Component
struct ProgressDemo {
  @State private var progressValue: number = 0.7

  build() {
    Column({ space: 20 }) {
      // 线性进度条
      ProgressBar({
        value: this.progressValue,
        total: 1,
        type: ProgressBarType.Linear
      })
      .width('80%')
      .height(10)
      .color(Color.Blue) // 进度颜色
      
      // 圆形进度条
      ProgressBar({
        value: this.progressValue,
        total: 1,
        type: ProgressBarType.Ring
      })
      .width(60)
      .height(60)
      .color(Color.Green)
      
      // 加载动画
      LoadingProgress()
        .width(40)
        .height(40)
        .color(Color.Red)
    }
    .padding(20)
  }
}

2. Dialog / Toast（弹窗 / 提示）

typescript

运行

@Component
struct DialogDemo {
  @State private var showDialog: boolean = false

  build() {
    Column() {
      Button("显示弹窗")
        .onClick(() => {
          this.showDialog = true
          
          // 显示 Toast 提示
          prompt.showToast({
            message: "操作提示",
            duration: 2000
          })
        })
    }
    .padding(20)
    // 弹窗
    .dialog(this.showDialog, {
      title: "提示",
      message: "这是一个弹窗示例",
      confirm: {
        value: "确定",
        action: () => {
          this.showDialog = false
        }
      },
      cancel: () => {
        this.showDialog = false
      }
    })
  }
}

3. Navigation（导航栏）

用于页面导航，支持标题、菜单、返回按钮。

typescript

运行

@Entry
@Component
struct NavigationDemo {
  build() {
    Navigation() {
      List() {
        ListItem() {
          Text("首页内容")
            .padding(20)
        }
      }
    }
    .title("首页") // 导航栏标题
    .titleMode(NavigationTitleMode.Mini) // 标题模式
    .toolbar({
      // 导航栏右侧按钮
      items: [
        {
          value: "设置",
          icon: $r("sys.media.ic_public_setting"),
          action: () => {
            console.log("点击设置")
          }
        }
      ]
    })
    .backgroundColor(Color.White)
  }
}

4. Tabs（标签栏）

底部 / 顶部标签切换，适配鸿蒙多设备。

typescript

运行

@Entry
@Component
struct TabsDemo {
  @State private var selectedIndex: number = 0

  build() {
    Tabs({ barPosition: BarPosition.End, controller: TabsController() }) { // End 表示底部标签
      TabContent() {
        Text("首页内容")
          .width('100%')
          .height('100%')
          .textAlign(TextAlign.Center)
      }
      .tabBar({
        icon: $r("sys.media.ic_public_home"),
        text: "首页",
        selectedIcon: $r("sys.media.ic_public_home_filled")
      })

      TabContent() {
        Text("我的内容")
          .width('100%')
          .height('100%')
          .textAlign(TextAlign.Center)
      }
      .tabBar({
        icon: $r("sys.media.ic_public_person"),
        text: "我的",
        selectedIcon: $r("sys.media.ic_public_person_filled")
      })
    }
    .width('100%')
    .height('100%')
    .backgroundColor(Color.White)
    .onChange((index: number) => {
      this.selectedIndex = index
    })
  }
}

五、辅助组件

1. Spacer（空白占位）

占据容器剩余空间，调整组件间距。

typescript

运行

@Component
struct SpacerDemo {
  build() {
    Row() {
      Text("左侧")
        .width(80)
        .height(40)
        .backgroundColor(Color.LightBlue)
      
      Spacer() // 占据中间所有剩余空间
      
      Text("右侧")
        .width(80)
        .height(40)
        .backgroundColor(Color.LightPink)
    }
    .width('100%')
    .height(100)
    .backgroundColor(Color.LightGray)
    .padding(10)
  }
}

2. Divider（分割线）

水平 / 垂直分割线，支持自定义样式。

typescript

运行

@Component
struct DividerDemo {
  build() {
    Column({ space: 10 }) {
      Text("上部分内容")
      Divider()
        .width('80%')
        .height(2)
        .color(Color.Grey)
      Text("下部分内容")
    }
    .padding(20)
  }
}

---

总结

1. 核心布局体系 ：ArkUI 以 Column/Row（Flex 布局）为基础，Stack（层叠）、List/Grid（列表 / 网格）是构建复杂界面的核心；
2. 交互控件特色 ：Toggle 集成开关 / 复选框 / 单选框，Picker 支持多类型选择，适配鸿蒙全场景设备；
3. 鸿蒙专属能力：ArkUI 控件天然支持 "分布式布局"（跨设备渲染）、"多态样式"（适配折叠屏 / 手表 / 车机），这是区别于 Flutter/SwiftUI 的核心优势；
4. 版本兼容 ：建议基于 HarmonyOS 4.0+ 开发，部分新控件（如 DatePicker 高级特性）需注意设备系统版本适配。

所有 ArkUI 控件均支持通过 .adaptScreenSize() 等属性适配不同屏幕尺寸，结合 @Media 装饰器可实现多设备形态的精准适配。