HarmonyOS5鸿蒙开发常用组件介绍

一、文本类组件​​

1. ​​Text​​

   • ​​用途​​：显示纯文本内容，支持样式自定义（字体、颜色、对齐等）

   • ​​示例​​：

     Text("Hello HarmonyOS")
       .fontSize(20)
       .fontColor(Color.Black)
       .textAlign(TextAlign.Center)
     

2. ​​TextInput​​

   • ​​用途​​：单行文本输入框，支持密码模式、占位符提示等

   • ​​关键属性​​：

     TextInput({ placeholder: "请输入内容" })
       .type(InputType.Password)  // 密码输入
       .placeholderColor(Color.Gray)
     

3. ​​TextArea​​

   • ​​用途​​：多行文本输入框，支持自动换行和字数统计

   • ​​示例​​：

     TextArea()
       .height(100)
       .maxLength(200)  // 限制输入长度
       .showCounter(true)  // 显示字数统计
     

---

🕹️ ​​二、交互类组件​​

1. ​​Button​​

   • ​​用途​​：触发操作的按钮，支持样式定制和点击事件

   • ​​示例​​：

     Button("提交", { type: ButtonType.Normal })
       .backgroundColor(0x317aff)
       .onClick(() => { /* 处理逻辑 */ })
     

2. ​​Toggle​​

   • ​​用途​​：开关控件，支持勾选框/开关样式切换

   • ​​示例​​：

     Toggle({ type: ToggleType.Switch, isOn: true })
       .onChange((isOn) => { console.log(`开关状态: ${isOn}`) })
     

3. ​​CheckBox & Radio​​

   • ​​用途​​：多选框（CheckBox）和单选框（Radio），用于选项选择

   • ​​示例​​：

     // 多选框
     CheckBox({ name: 'option1' }).select(true)
     // 单选框
     Radio({ value: 'A', group: 'choices' }).checked(true)
     

---

🧩 ​​三、布局容器组件​​

1. ​​Column & Row​​

   • ​​用途​​：纵向（Column）和横向（Row）排列子组件，支持主轴/交叉轴对齐

   • ​​示例​​：

     Column() {
       Text("顶部文本")
       Button("底部按钮")
     }.justifyContent(FlexAlign.SpaceBetween)  // 两端对齐
     

2. ​​List​​

   • ​​用途​​：滚动列表容器，适用于长列表数据展示（需配合 ListItem 使用）

   • ​​示例​​：

     List() {
       ForEach(dataArray, (item) => {
         ListItem() { Text(item.name) }
       })
     }.scrollBar(BarState.Off)  // 隐藏滚动条
     

3. ​​Swiper​​

   • ​​用途​​：轮播图容器，支持自动播放和循环切换

   • ​​示例​​：

     Swiper() {
       ForEach(bannerList, (item) => {
         Image(item.imageSrc).objectFit(ImageFit.Contain)
       })
     }.autoPlay(true).loop(true)
     

4. ​​Scroll​​

   • ​​用途​​：可滚动容器，当内容超出可视区域时支持滚动

   • ​​注意​​：嵌套 List 时需明确指定子组件宽高以优化性能。

---

🖼️ ​​四、媒体与图像组件​​

1. ​​Image​​

   • ​​用途​​：显示本地或网络图片，支持缩放和裁剪模式

   • ​​示例​​：

     Image($r('app.media.logo'))  // 加载资源图片
       .objectFit(ImageFit.Cover)  // 覆盖整个容器
       .borderRadius(10)  // 圆角
     

---

📊 ​​五、高级容器组件​​

1. ​​Grid & GridItem​​

   • ​​用途​​：网格布局（Grid）及其子项容器（GridItem），用于瀑布流展示

   • ​​限制​​：GridItem 必须作为 Grid 的子组件使用。

2. ​​WaterFlow & FlowItem​​

   • ​​用途​​：瀑布流布局（WaterFlow）及其子项（FlowItem），适用于不规则内容排列

---

⚙️ ​​六、自定义组件​​

通过 ​​@Component​​ 装饰器创建可复用的 UI 单元，组合系统组件实现业务逻辑

@Component
struct CustomCard {
  build() {
    Column() {
      Text("自定义卡片标题").fontSize(18)
      Button("详情").onClick(() => { /* 跳转逻辑 */ })
    }
  }
}

---

💎 ​​核心组件总结表​​

​​类别​​	​​组件​​	​​核心功能​​	​​典型场景​​
​​文本输入​​	Text, TextInput	显示/编辑文本内容	表单输入、内容展示
​​交互控制​​	Button, Toggle	触发操作、状态切换	提交表单、开关设置
​​布局容器​​	Column, List	排列子组件、支持滚动	列表页、详情页布局
​​媒体展示​​	Image, Swiper	图片/轮播图展示	Banner 广告、商品图集
​​高级容器​​	Grid, WaterFlow	网格/瀑布流布局	图片墙、商品分类页

更多组件用法详见 HarmonyOS 官方文档 或参考 ArkUI 组件指南。实际开发中可组合使用（如 List + ListItem 构建动态列表，Swiper + Image 实现轮播图）