前言

Pura X Max 的首页、工作台、功能入口、统计面板，很容易遇到同一个问题：卡片数量不少，但不同窗口宽度下应该展示几列并不一样。

外屏空间有限，一列最稳。展开态内屏空间更大，如果还保持一列，页面会显得松散；如果直接写死三列，中等窗口又会被挤得很难看。卡片列表适合交给栅格系统处理，让它根据窗口宽度自动决定每张卡片占多少列。

Pura X Max 外屏为 5.4 英寸，内屏为 7.7 英寸，外屏分辨率为 1848 × 1264，内屏分辨率为 2584 × 1828，系统版本为 HarmonyOS 6.1。这个尺寸变化非常适合用栅格来处理卡片自适应。

ArkUI 的 GridRow 和 GridCol 正是为这类响应式栅格准备的。GridRow 作为栅格容器，直接子组件需要使用 GridCol，而 GridCol 可以通过 span 控制不同断点下占用的列数。

卡片列表更适合用栅格管理

卡片列表和普通长列表不一样。

普通长列表强调顺序阅读，一条接一条往下看。卡片列表更强调信息聚合，比如首页统计卡、工作台入口、快捷功能、项目概览。它们之间相对独立，用户更关心一屏能看到多少内容。

这种页面如果手动判断宽度，再分别写一列、两列、三列，代码会很快变散。

比如：

if (width < 600) {
  // 一列
} else if (width < 900) {
  // 两列
} else {
  // 三列
}

这样写当然能工作，但每个卡片容器都要自己处理列数，后续改间距、改断点、改卡片宽度时，维护成本会越来越高。

GridRow 的思路更适合这类页面。先把整体栅格分成 12 列，再让每个 GridCol 在不同断点下占用不同列数。

小屏下，一张卡片占 12 列，一行 1 张。

中屏下，一张卡片占 6 列，一行 2 张。

大屏下，一张卡片占 4 列，一行 3 张。

写起来就是：

GridCol({ span: { xs: 12, sm: 6, md: 4 } }) {
  // 卡片内容
}

这个写法比手动写三套布局干净。卡片本身只关心内容，列数交给栅格系统。

用 GridRow 控制 1 列、2 列、3 列

栅格布局里有三个关键点。

第一个是总列数。

columns: 12

12 列比较常见，适合做 1、2、3、4 等多种分割。对于工作台卡片来说，1、2、3 列都能比较自然地落到 12 列体系里。

第二个是间距。

gutter: { x: 12, y: 12 }

x 控制横向间距，y 控制纵向间距。卡片列表最怕贴得太紧，尤其展开态下，如果卡片之间没有合适留白，页面会显得很挤。

第三个是断点。

breakpoints: {
  value: ['520vp', '820vp'],
  reference: BreakpointsReference.ComponentSize
}

这里使用 ComponentSize，目的是让栅格根据当前组件容器宽度切换断点。Pura X Max 的真实开合可以验证外屏和展开态，页面里额外放了几个演示宽度按钮，用来观察中间状态。真实项目里可以把演示按钮去掉，让容器直接跟随窗口宽度。

这组断点会形成三档：

低于 520vp，进入 xs。

520vp 到 820vp，进入 sm。

大于等于 820vp，进入 md。

配合 span: { xs: 12, sm: 6, md: 4 }，页面就会得到 1 列、2 列、3 列三种效果。

把工作台卡片跑起来

下面这个页面模拟了一个整理类应用的工作台，有统计卡片、功能入口和当前选中卡片。页面可以放到 entry/src/main/ets/pages/Index.ets 运行。

为了在 Pura X Max 模拟器里更稳定地观察 1 列、2 列、3 列，页面顶部加了自动、1 列、2 列、3 列几个按钮。选择自动时，栅格跟随真实窗口宽度；选择其他按钮时，只改变内容容器宽度，用来观察不同断点下的卡片排列。

interface WorkbenchCard {
  id: number;
  title: string;
  value: string;
  unit: string;
  desc: string;
  status: string;
}

@Entry
@Component
struct Index {
  @State private pageWidth: number = 0;
  @State private previewWidth: number = 0;
  @State private selectedId: number = 1;

  private readonly cards: WorkbenchCard[] = [
    {
      id: 1,
      title: '待处理材料',
      value: '12',
      unit: '条',
      desc: '来自拍照整理、相册导入和文本记录',
      status: '需要处理'
    },
    {
      id: 2,
      title: '今日提醒',
      value: '5',
      unit: '项',
      desc: '从通知、会议和预约信息中提取',
      status: '即将开始'
    },
    {
      id: 3,
      title: '已整理记录',
      value: '48',
      unit: '条',
      desc: '本周已经完成结构化整理的内容',
      status: '稳定'
    },
    {
      id: 4,
      title: '待确认摘要',
      value: '7',
      unit: '条',
      desc: '需要人工确认识别结果和行动项',
      status: '待确认'
    },
    {
      id: 5,
      title: '图片识别',
      value: '23',
      unit: '张',
      desc: '来自原图预览和 OCR 处理流程',
      status: '处理中'
    },
    {
      id: 6,
      title: '会议记录',
      value: '9',
      unit: '场',
      desc: '包含会议纪要、行动项和关联项目',
      status: '已同步'
    },
    {
      id: 7,
      title: '收藏内容',
      value: '16',
      unit: '条',
      desc: '长期保留的关键资料和常用信息',
      status: '稳定'
    },
    {
      id: 8,
      title: '异常识别',
      value: '3',
      unit: '条',
      desc: '需要重新确认图片清晰度和文字结构',
      status: '待确认'
    },
    {
      id: 9,
      title: '本周新增',
      value: '31',
      unit: '条',
      desc: '本周新增的材料、通知和会议记录',
      status: '增长中'
    }
  ];

  private getEffectiveWidth(): number {
    if (this.previewWidth > 0) {
      return this.previewWidth;
    }

    return this.pageWidth;
  }

  private getModeText(): string {
    const width = this.getEffectiveWidth();

    if (width >= 820) {
      return 'md · 三列卡片';
    }

    if (width >= 520) {
      return 'sm · 双列卡片';
    }

    return 'xs · 单列卡片';
  }

  private getModeDesc(): string {
    const width = this.getEffectiveWidth();

    if (width >= 820) {
      return '当前容器进入三列状态，适合 Pura X Max 展开态、平板和更宽的工作台页面。';
    }

    if (width >= 520) {
      return '当前容器进入双列状态，适合中等宽度窗口和部分分屏场景。';
    }

    return '当前容器进入单列状态，适合外屏、窄窗口和小尺寸悬浮窗。';
  }

  private getContentWidth(): Length {
    if (this.previewWidth > 0) {
      return this.previewWidth;
    }

    return '100%';
  }

  private getPagePadding(): number {
    const width = this.getEffectiveWidth();

    if (width >= 820) {
      return 24;
    }

    if (width >= 520) {
      return 20;
    }

    return 16;
  }

  private getTitleSize(): number {
    const width = this.getEffectiveWidth();

    if (width >= 820) {
      return 28;
    }

    if (width >= 520) {
      return 25;
    }

    return 22;
  }

  private getSelectedCard(): WorkbenchCard {
    const found = this.cards.find((item: WorkbenchCard) => item.id === this.selectedId);
    return found ? found : this.cards[0];
  }

  private getStatusColor(status: string): string {
    if (status === '需要处理' || status === '待确认') {
      return '#B25E00';
    }

    if (status === '处理中' || status === '即将开始' || status === '增长中') {
      return '#7C3AED';
    }

    return '#276749';
  }

  private getStatusBgColor(status: string): string {
    if (status === '需要处理' || status === '待确认') {
      return '#FFF4E5';
    }

    if (status === '处理中' || status === '即将开始' || status === '增长中') {
      return '#F1EAFE';
    }

    return '#E7F5EE';
  }

  private setPreview(width: number) {
    this.previewWidth = width;
  }

  @Builder
  private HeaderPanel() {
    Column({ space: 10 }) {
      Row() {
        Column({ space: 4 }) {
          Text('GridRow 卡片自适应布局')
            .fontSize(this.getTitleSize())
            .fontWeight(FontWeight.Bold)
            .fontColor('#111827')

          Text(this.getModeText())
            .fontSize(14)
            .fontColor('#2F8F83')
        }
        .layoutWeight(1)

        Text('窗口 ' + Math.round(this.pageWidth).toString() + 'vp')
          .fontSize(12)
          .fontColor('#374151')
          .padding({ left: 10, right: 10, top: 6, bottom: 6 })
          .backgroundColor('#FFFFFF')
          .borderRadius(999)
      }
      .width('100%')

      Text('栅格容器宽度：' + Math.round(this.getEffectiveWidth()).toString() + 'vp。' + this.getModeDesc())
        .fontSize(14)
        .fontColor('#6B7280')
        .lineHeight(21)

      Row({ space: 8 }) {
        this.PreviewButton('自动', 0)
        this.PreviewButton('1 列', 420)
        this.PreviewButton('2 列', 680)
        this.PreviewButton('3 列', 960)
      }
      .width('100%')
    }
    .width('100%')
  }

  @Builder
  private PreviewButton(text: string, width: number) {
    Text(text)
      .fontSize(12)
      .fontColor(this.previewWidth === width ? '#FFFFFF' : '#2F8F83')
      .textAlign(TextAlign.Center)
      .padding({ left: 10, right: 10, top: 7, bottom: 7 })
      .backgroundColor(this.previewWidth === width ? '#2F8F83' : '#E6F4F1')
      .borderRadius(999)
      .onClick(() => {
        this.setPreview(width);
      })
  }

  @Builder
  private StatusPill(status: string) {
    Text(status)
      .fontSize(12)
      .fontColor(this.getStatusColor(status))
      .padding({ left: 8, right: 8, top: 4, bottom: 4 })
      .backgroundColor(this.getStatusBgColor(status))
      .borderRadius(999)
  }

  @Builder
  private WorkbenchCardView(item: WorkbenchCard) {
    Column({ space: 12 }) {
      Row() {
        this.StatusPill(item.status)

        Blank()

        if (this.selectedId === item.id) {
          Text('当前')
            .fontSize(12)
            .fontColor('#2F8F83')
        }
      }
      .width('100%')

      Column({ space: 4 }) {
        Text(item.title)
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .fontColor('#111827')
          .maxLines(1)
          .textOverflow({ overflow: TextOverflow.Ellipsis })

        Row({ space: 6 }) {
          Text(item.value)
            .fontSize(32)
            .fontWeight(FontWeight.Bold)
            .fontColor('#111827')

          Text(item.unit)
            .fontSize(14)
            .fontColor('#6B7280')
            .margin({ top: 12 })
        }
        .alignItems(VerticalAlign.Top)
      }
      .width('100%')
      .alignItems(HorizontalAlign.Start)

      Text(item.desc)
        .fontSize(13)
        .fontColor('#6B7280')
        .lineHeight(19)
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .width('100%')
    .padding(16)
    .backgroundColor(this.selectedId === item.id ? '#EEF7F5' : '#FFFFFF')
    .borderRadius(20)
    .border({
      width: this.selectedId === item.id ? 1.5 : 1,
      color: this.selectedId === item.id ? '#2F8F83' : '#E5E7EB'
    })
    .shadow({
      radius: this.selectedId === item.id ? 12 : 8,
      color: '#12000000',
      offsetX: 0,
      offsetY: 4
    })
    .onClick(() => {
      this.selectedId = item.id;
    })
  }

  @Builder
  private GridCardArea() {
    Scroll() {
      GridRow({
        columns: 12,
        gutter: { x: 12, y: 12 },
        breakpoints: {
          value: ['520vp', '820vp'],
          reference: BreakpointsReference.ComponentSize
        }
      }) {
        ForEach(this.cards, (item: WorkbenchCard) => {
          GridCol({ span: { xs: 12, sm: 6, md: 4 } }) {
            this.WorkbenchCardView(item)
          }
        }, (item: WorkbenchCard) => item.id.toString())
      }
      .width('100%')
      .padding({ bottom: 18 })
    }
    .layoutWeight(1)
    .width('100%')
    .edgeEffect(EdgeEffect.Spring)
  }

  @Builder
  private SelectedPanel() {
    Column({ space: 10 }) {
      Row() {
        Text('当前选中')
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .fontColor('#111827')

        Blank()

        this.StatusPill(this.getSelectedCard().status)
      }
      .width('100%')

      Text(this.getSelectedCard().title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor('#111827')
        .maxLines(1)
        .textOverflow({ overflow: TextOverflow.Ellipsis })

      Text(this.getSelectedCard().desc)
        .fontSize(14)
        .fontColor('#4B5563')
        .lineHeight(21)
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })

      Row({ space: 10 }) {
        Button('处理')
          .fontSize(14)
          .fontColor('#FFFFFF')
          .height(40)
          .layoutWeight(1)
          .backgroundColor('#2F8F83')
          .borderRadius(20)

        Button('详情')
          .fontSize(14)
          .fontColor('#2F8F83')
          .height(40)
          .layoutWeight(1)
          .backgroundColor('#E6F4F1')
          .borderRadius(20)
      }
      .width('100%')
    }
    .width('100%')
    .padding(16)
    .backgroundColor('#FFFFFF')
    .borderRadius(22)
    .shadow({
      radius: 10,
      color: '#10000000',
      offsetX: 0,
      offsetY: 4
    })
  }

  build() {
    Column() {
      Column({ space: 16 }) {
        this.HeaderPanel()
        this.SelectedPanel()
        this.GridCardArea()
      }
      .width(this.getContentWidth())
      .height('100%')
      .padding({
        left: this.getPagePadding(),
        right: this.getPagePadding(),
        top: 18,
        bottom: 16
      })
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
    .backgroundColor('#F6F7F9')
    .onAreaChange((_: Area, newValue: Area) => {
      const width = Number(newValue.width);
      if (!Number.isNaN(width) && width > 0) {
        this.pageWidth = width;
      }
    })
  }
}

关键实现点和运行结果

页面运行后，选择“自动”时，栅格会跟随真实窗口宽度。Pura X Max 外屏通常会落到单列或较窄状态，展开态会更容易进入三列状态。中间宽度不一定能通过普通开合稳定触发，所以页面顶部提供了 1 列、2 列、3 列按钮，用来观察栅格在不同容器宽度下的变化。

点击 1 列，内容容器限制为 420vp。所有工作台卡片从上到下排列，比较接近外屏或窄窗口。这个状态下，一屏能看到的卡片数量少一些，但阅读和点击都稳定。

点击 2 列，内容容器限制为 680vp。卡片变成两列，适合中等窗口。这个状态常见于分屏、平板窄窗口或自由窗口，不一定是 Pura X Max 普通开合里的固定形态。

点击 3 列，内容容器限制为 960vp。卡片变成三列，更接近 Pura X Max 展开态或大屏工作台。统计卡片一屏能展示更多内容，用户可以更快扫到整体状态。

关键逻辑集中在 GridRow 和 GridCol。

GridRow({
  columns: 12,
  gutter: { x: 12, y: 12 },
  breakpoints: {
    value: ['520vp', '820vp'],
    reference: BreakpointsReference.ComponentSize
  }
}) {
  GridCol({ span: { xs: 12, sm: 6, md: 4 } }) {
    this.WorkbenchCardView(item)
  }
}

columns: 12 定义整体栅格列数。span: { xs: 12, sm: 6, md: 4 } 决定每张卡片在不同断点下占多少列。xs 状态下每张卡片占 12 列，所以一行一张；sm 状态下每张卡片占 6 列，所以一行两张；md 状态下每张卡片占 4 列，所以一行三张。

reference: BreakpointsReference.ComponentSize 让断点跟随栅格容器宽度变化。这个设置很适合组件化页面。比如工作台卡片区放在页面左侧、右侧、弹层或不同窗口里时，栅格可以根据自身容器宽度重新排列，而不是只看整个窗口宽度。

真实项目里，演示按钮可以去掉，保留 GridRow 自己的响应式能力。首页统计卡、功能入口、快捷操作、看板卡片，都适合用这种方式处理。

需要注意的是，GridRow 更适合高度接近、结构相似的卡片。如果卡片高度差异很大，比如有的卡片只有一行文字，有的卡片包含长文本和图片，普通栅格容易出现行高不一致的问题。这类场景更适合单独评估 WaterFlow 或者重新控制卡片内容高度。

总结

Pura X Max 上的卡片列表，不适合只用固定宽度或固定列数处理。

GridRow 和 GridCol 可以把列数变化交给栅格系统。小屏一列，中屏两列，大屏三列，页面结构会随着容器宽度自然变化。对首页、工作台、功能入口和统计卡片来说，这种方式比手写多套布局更稳，也更容易迁移到分屏、自由窗口、平板和 2in1 场景。

真正落到项目里，重点不在于追求列数越多越好，而是保证每张卡片在当前宽度下仍然可读、可点、可比较。外屏先保证稳定，展开态再提高信息密度，卡片布局才能真正适配 Pura X Max 的窗口变化。