[HarmonyOSNext鸿蒙开发]11.ArkUI框架：Swiper、Grid布局与代码复用实战指南

ArkUI框架：Swiper、Grid布局与样式结构重用实战指南

本文将深入解析ArkUI框架中Swiper轮播组件、Grid网格布局的核心用法，以及三种高效的样式结构重用技术（@Builder、@Extend、@Styles），助你构建高性能的鸿蒙应用界面。

一、Swiper轮播组件实战

1.1 适用场景与基本用法

Swiper组件提供滑动轮播显示能力，适用于：

图片轮播展示
多内容分页展示
引导页切换
广告位展示

基础实现：

ts 复制代码

Swiper() {
  ForEach(this.imageList, (item: Resource) => {
    Image(item)
      .width('100%')
      .height('100%')
  })
  .width('100%')
  .height(160)
}

1.2 核心属性配置

ts 复制代码

Swiper({
  loop: true,          // 开启循环
  autoPlay: true,      // 自动播放
  interval: 4000,      // 4秒间隔
  vertical: false      // 横向滑动（默认）
}) {
  // 内容
}

1.3 导航点定制化

通过indicator属性实现导航点定制：

ts 复制代码

Swiper() {
  // 内容
  .indicator(

    DotIndicator()
      .itemWidth(10)           // 默认圆点宽度
      .itemHeight(4)           // 默认圆点高度
      .selectedItemWidth(30)    // 选中状态宽度
      .selectedItemHeight(4)   // 选中状态高度
      .selectedColor(Color.White) // 选中颜色
      .bottom(10)              // 底部距离
  )
}

1.4 小米有品轮播实战案例

ts 复制代码

@Entry
@Component
struct XiaomiSwiper {
  private imageList: Resource[] = [
    $r('app.media.banner1'),
    $r('app.media.banner2'),
    $r('app.media.banner3')
  ]
  build() {

    Swiper({
      loop: true,
      autoPlay: true,
      interval: 4000
    }) {
      ForEach(this.imageList, (item: Resource) => {
        Image(item)
          .width('100%')
          .height(160)
      })
      .width('100%')

      .height(160)
      .indicator(
        DotIndicator()
          .itemWidth(10)
          .itemHeight(4)
          .selectedItemWidth(30)
          .selectedItemHeight(4)
          .selectedColor(Color.White)
          .bottom(10)
      )
    }
  }
}

二、样式与结构重用技术

2.1 @Styles：样式复用

抽取通用样式属性，不支持参数传递：

ts 复制代码

// 全局定义
@Styles function commonTextStyle() {
  .fontSize(16)
  .fontColor(Color.Black)
}

// 组件内定义
@Component
struct MyComponent {
  @Styles commonButtonStyle() {
    .width(100)
    .height(40)
    .backgroundColor(Color.Blue)
  }
  build() {

    Column() {
      Text('Hello').commonTextStyle()
      Button('Click').commonButtonStyle()
    }
  }
}

2.2 @Extend：扩展组件样式

全局定义，支持参数传递：

ts 复制代码

@Extend(Text) function textExtend(size: number, color: Color) {
  .fontSize(size)
  .fontColor(color)
  .margin(5)
}

// 使用
Text('ArkUI').textExtend(20, Color.Red)

2.3 @Builder：结构复用（重点）

实现结构、样式、事件的全方位复用：

ts 复制代码

// 全局Builder
@Builder function GlobalItem(title: string) {
  Column() {
    Image($r('app.media.icon'))
      .width(40)
      .height(40)
    Text(title)
      .fontSize(14)
      .margin({ top: 10 })
  }
}

// 组件内Builder
@Component
struct MyComponent {
  @Builder ItemBuilder(title: string) {
    Column() {
      // 结构内容
    }
    .onClick(() => {
      AlertDialog.show({ message: ${title} clicked! })
    })
  }
  build() {

    Row() {
      GlobalItem('Global')
      this.ItemBuilder('Local')
    }
  }
}

2.4 三种技术对比

技术	适用场景	参数支持	访问组件属性
@Styles	基础样式复用	❌	仅组件内可以
@Extend	扩展特定组件样式	✅	❌
@Builder	结构+样式+事件复用	✅	组件内可通过this访问

三、Grid网格布局实战

3.1 固定行列布局

ts 复制代码

Grid() {
  ForEach(Array.from({ length: 9 }), (_, index) => {
    GridItem() {
      Text(Item ${index + 1})
        .fontSize(16)
    }
  })
  .columnsTemplate('1fr 1fr 1fr') // 3列等宽
  .rowsTemplate('1fr 1fr 1fr')   // 3行等高
  .columnsGap(10)                // 列间距
  .rowsGap(10)                   // 行间距
  .height(300)
}

3.2 行列合并技巧

通过rowStart/rowEnd和columnStart/columnEnd实现：

ts 复制代码

Grid() {
  // 常规项目
  GridItem().columnStart(1).columnEnd(2) // 跨两列
  
  // 特殊项目（跨两行）
  GridItem()
    .rowStart(3)
    .rowEnd(4)
    .columnStart(1)
    .columnEnd(4) // 跨三列
}
.columnsTemplate('1fr 1fr 1fr')
.rowsTemplate('1fr 1fr 1fr 1fr')

3.3 可滚动网格布局

垂直滚动：

ts 复制代码

Grid() {
  ForEach(this.dataList, item => {
    GridItem() { / 内容 / }
  })
  .columnsTemplate('1fr 1fr') // 只设置列模板
  .height(300)                // 固定高度
  .scrollBar(BarState.On)     // 开启滚动条
}

水平滚动：

ts 复制代码

Grid() {
  ForEach(this.dataList, item => {
    GridItem() { / 内容 / }
  })
  .rowsTemplate('1fr 1fr')    // 只设置行模板
  .width('100%')              // 固定宽度
}

3.4 控制器与自定义滚动条

ts 复制代码

// 创建控制器
scroller: Scroller = new Scroller()

build() {
  Column() {
    // 网格布局
    Grid(this.scroller) {
      // 内容
      .scrollBar(BarState.Off) // 禁用默认滚动条

      // 自定义滚动条
      ScrollBar({
        scroller: this.scroller,
        direction: ScrollBarDirection.Horizontal
      }) {
        Circle()
          .width(10)
          .height(10)
          .fill(Color.Blue)
      }
    }
  }
}

3.5 小米有品导航实战

ts 复制代码

@Entry
@Component
struct XiaomiGrid {
  private navList = [...] // 导航数据
  
  // 创建Builder复用结构
  @Builder NavItem(item: any) {
    Column() {
      Image(item.icon)
        .width('80%')
        .aspectRatio(1)
      Text(item.title)
        .fontSize(12)
        .margin({ top: 5 })
    }
  }

  build() {
    Grid() {
      ForEach(this.navList, item => {
        GridItem() {
          this.NavItem(item)
        }
      })
      .rowsTemplate('1fr 1fr 1fr 1fr') // 4行
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr') // 5列
      .columnsGap(10)
      .rowsGap(15)
      .height(160)
      .width('100%')
    }
  }
}

四、总结与最佳实践

Swiper最佳实践：

重要内容放在前3屏
自动播放间隔建议3-5秒
移动端优先横向滑动

Grid布局技巧：

优先使用columnsTemplate/rowsTemplate定义布局
需要滚动时只设置一个方向模板
Complex layouts use row and column merging功能

重用技术选择：

简单样式复用 → @Styles
组件样式扩展 → @Extend
复杂结构复用 → @Builder

性能优化：

大数据集使用LazyForEach懒加载
设置cachedCount优化滚动体验
避免在循环渲染中执行复杂计算

掌握这些核心组件的使用技巧和重用技术，能够显著提升鸿蒙应用开发效率和界面性能。在实际项目中，建议根据具体场景灵活组合这些技术，构建出既美观又高效的UI界面。

参考资料

HarmonyOS开发文档