卡片多规格适配：一个避不开的现实问题

HarmonyOS NEXT的Form Kit推出后，卡片开发变得比以前灵活得多，但也引入了一个很具体的问题：同一个卡片，怎么在不同尺寸的桌面上都保持布局合理、内容完整？

很多人第一次做卡片适配时，习惯性地用固定的宽高和position布局。结果1x2的卡片塞进2x2的空间里，内容被拉伸变形；或者2x2的卡片缩到1x2里，文字被截断、按钮叠在一起。

这个问题在HarmonyOS开发里比较常见，尤其是当你需要让一个卡片同时支持多种尺寸规格（1x2、2x2、2x4、4x4）的时候。官方文档虽然提到了维度信息，但没有讲清楚不同尺寸下如何动态调整内容和样式。

它解决什么问题

卡片多规格适配的核心问题就两个：

1. 布局自适应：不同尺寸下，容器的大小不同，内部元素需要根据可用空间重新排列。
2. 内容智能调整：空间大的时候展示更多信息（如未来几天的天气预报），空间小的时候只展示核心信息（如当前温度）。

适合的场景：天气卡片、日程卡片、快捷控制卡片、股票行情卡片等需要在桌面上提供快速预览的Widget类应用。

不适合的场景：内容极度复杂的交互式应用，比如需要在卡片内完成表单填写或绘图操作，这种场景卡片本身就不合适。

官方方案对比：

方案	布局灵活性	代码复杂度	推荐场景
GridRow + GridCol	高，支持响应式断点	中等	多维度网格布局
Flex	高，方向可控	低	简单列表或单行排列
position + 固定宽高	低	最低	快速原型，不推荐生产

实际项目里，我会优先选择GridRow + Flex的组合，前者负责整体行/列划分，后者负责内部元素的伸缩排列。固定布局几乎不用，因为桌面尺寸一旦变化，适配成本极高。

环境说明

DevEco Studio 版本：DevEco Studio 5.0.1 及以上
HarmonyOS SDK 版本：HarmonyOS 5.0.0 Release 及以上
目标设备：手机

核心技术：用GridRow做骨架，Flex做血肉

1. 卡片配置：注册多规格

在form_config.json里声明需要支持的尺寸：

{
  "forms": [{
    "name": "weather_card",
    "displayName": "天气卡片",
    "description": "显示当前天气",
    "src": "FormCard/pages/WeatherCard",
    "uiSyntax": "arkts",
    "window": {
      "designWidth": 720,
      "autoDesignWidth": true
    },
    "colorMode": "auto",
    "isDefault": true,
    "updateEnabled": true,
    "scheduleUpdateEnabled": false,
    "updateDuration": 60,
    "defaultDimension": "1*2",
    "supportDimensions": ["1*2", "2*2"]
  }]
}

注意supportDimensions字段只声明了1x2和2x2，这决定了用户在桌面上可以拖拽到哪些尺寸范围。如果只声明了这两种，用户拖不到2x4去。

2. 卡片UI主文件，核心适配逻辑

// WeatherCard.ets
import { formInfo, formStore } from '@kit.FormKit';

// 定义尺寸枚举，便于后续判断
enum CardSize {
  SMALL = 1, // 1*2
  MEDIUM = 2 // 2*2
}

@Entry
@Component
struct WeatherCard {
  @State city: string = '北京';
  @State temp: string = '26°C';
  @State weatherIcon: string = '🌤️';
  @State currentWidth: number = 0;
  @State currentHeight: number = 0;
  @State futureDays: string[] = ['27°C', '25°C', '28°C', '24°C'];

  private cardSize: CardSize = CardSize.SMALL;

  aboutToAppear() {
    // 这里获取卡片实际尺寸，但注意这个尺寸是dp值，不是规格名称
    // 需要通过width/height来判断属于哪个规格
    // 实际开发中这个逻辑可以提前封装成一个工具函数
  }

  build() {
    // 核心：根据实际宽高判断当前尺寸规格
    // 1*2 宽度约144vp，高度约144vp（实际值略有浮动）
    // 2*2 宽度约312vp，高度约312vp
    // 这里为了演示，直接传入模拟值
    this.cardSize = this.currentWidth > 200 ? CardSize.MEDIUM : CardSize.SMALL;

    Column() {
      // 内容区域
      this.buildContent()
    }
    .padding(this.getPadding())
    .height('100%')
    .width('100%')
    .backgroundColor('#FFFFFF')
    .borderRadius(24)
  }

  @Builder
  buildContent() {
    if (this.cardSize === CardSize.SMALL) {
      // 1*2 尺寸：只显示核心温度
      this.buildCompactContent()
    } else {
      // 2*2 尺寸：显示完整信息
      this.buildFullContent()
    }
  }

  @Builder
  buildCompactContent() {
    Column({ space: 8 }) {
      Text(this.weatherIcon)
        .fontSize(36)
      Text(this.temp)
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .lineHeight(32)
      Text(this.city)
        .fontSize(14)
        .fontColor('#666666')
        .lineHeight(18)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }

  @Builder
  buildFullContent() {
    Column({ space: 8 }) {
      // 第一行：城市 + 温度
      Row({ space: 8 }) {
        Text(this.city)
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .lineHeight(22)
        Text(this.temp)
          .fontSize(36)
          .fontWeight(FontWeight.Bold)
          .lineHeight(42)
          .layoutWeight(1)
      }
      .width('100%')

      // 第二行：未来几天预报
      Row({ space: 8 }) {
        ForEach(this.futureDays, (day: string, index: number) => {
          Column({ space: 4 }) {
            Text('Day ' + (index + 1))
              .fontSize(12)
              .fontColor('#999999')
              .lineHeight(16)
            Text(day)
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .lineHeight(18)
          }
          .layoutWeight(1)
          .alignItems(HorizontalAlign.Center)
        })
      }
      .width('100%')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  // 不同尺寸有不同的内边距，避免内容紧贴边缘
  getPadding(): Padding {
    if (this.cardSize === CardSize.SMALL) {
      return { left: 8, right: 8, top: 8, bottom: 8 }
    } else {
      return { left: 16, right: 16, top: 16, bottom: 16 }
    }
  }
}

这段代码里两个关键点：

• 根据实际宽高判断规格：currentWidth > 200是一个简化的判断逻辑。实际项目里，建议在aboutToAppear中通过formInfo拿到width和height，然后映射到具体的规格名称。因为不同设备上dp到物理像素的转换可能会略有差异，直接判断宽高更稳定。
• @Builder拆分UI：把不同尺寸的UI封装成独立的@Builder方法，避免在build()里写大量if-else。这样代码可读性更好，也方便后续增加新的尺寸规格。

3. 另一种方案：用Flex + layoutWeight自适应

如果不想写显式的尺寸判断，也可以利用Flex的layoutWeight属性让子元素自动按比例伸缩。这种方式更“声明式”一些，但可控性稍弱：

@Builder
buildAdaptiveContent() {
  Column({ space: 8 }) {
    Flex({ direction: FlexDirection.Row, wrap: FlexWrap.Wrap }) {
      // 温度始终展示
      Text(this.temp)
        .fontSize(32)
        .fontWeight(FontWeight.Bold)
        .flexShrink(0)  // 不收缩
      
      // 未来预报根据空间自动换行，数量不固定
      ForEach(this.futureDays, (day: string, index: number) => {
        Text(day)
          .fontSize(14)
          .padding({ left: 4, right: 4 })
          .flexShrink(1)  // 允许收缩
      })
    }
    .width('100%')
    
    Text(this.city)
      .fontSize(14)
      .fontColor('#666666')
  }
  .width('100%')
  .height('100%')
  .justifyContent(FlexAlign.Center)
}

这种方式的好处是不需要手动判断尺寸，子元素会自适应。但缺点也很明显：内容可能会被压缩到不可读的程度，尤其在小尺寸卡片上。所以我更推荐第一种“显式判断尺寸 + 切换Builder”的方案。

常见问题 1：卡片配置文件里明明声明了多个规格，但用户只能拖出一个尺寸

现象：supportDimensions字段里写了好几种尺寸，但用户在桌面上长按卡片后，发现只能调整到其中一种，其他规格完全不可见。

原因：这是卡片存在多个Form实例时的限制。如果同一个Form ID对应多个规格，系统只会展示第一个匹配到的规格。更常见的原因是defaultDimension和supportDimensions中的尺寸名称不匹配（比如写成了1*2和1×2，注意运算符不一样）。

解决方案：

1. 严格使用半角*号，不要用×或x。
2. 确保defaultDimension的值在supportDimensions数组里。
3. 如果一张卡片有多个Form实例，每个实例的supportDimensions应该一致，或者逐一检查。
4. 清理桌面缓存：设置 > 应用 > 桌面 > 存储 > 清除缓存。这一步经常被忽略。

常见问题 2：2x2尺寸下内容显示不全，部分组件被切掉

现象：2x2的卡片里，如果文本行数超过了容器的maxLines，或者lineHeight设置过大，部分文字就被截断了。尤其在汉字的场景下，中文字符的lineHeight往往比英文字符高，更容易超出。

原因：Text组件的lineHeight会占用垂直空间，如果lineHeight大于父容器分配给它的高度（尤其是在Column的space加上之后），就会出现裁剪。ArkUI的Text在超出时会自动截断，没有滚动行为。

解决方案：

• 合理设置lineHeight的值，不要超过字体大小的1.4倍。如果行数较多，建议使用maxLines配合textOverflow。
• 在buildFullContent的Row和Column里不要使用固定高度，尽量用layoutWeight或flexGrow。
• 多测试不同分辨率的设备，因为dp到px的换算可能会有细微差异。

// 推荐写法，避免裁剪
Row({ space: 8 }) {
  Text(this.city)
    .fontSize(16)
    .lineHeight(20) // 明确控制，不要用默认
    .maxLines(1)
    .textOverflow({ overflow: TextOverflow.Ellipsis })
}
.height(22) // 明确Row的高度，让子元素垂直居中

最佳实践

1. 不要依赖系统默认的边距，手动设置padding：ArkUI的Column和Row默认没有padding，内容贴着边缘会显得很挤。建议至少给8vp的padding，具体值根据卡片尺寸动态设置（参考上面的getPadding方法）。

2. 用@State管理卡片状态，避免在build()里频繁计算：把尺寸判断、内容过滤等逻辑放到aboutToAppear或onPageShow里，build()只负责渲染。如果每次构建都重新计算，性能会变差。

3. 文本内容优先使用lineHeight和maxLines控制，而不是固定高度：固定高度在适配不同字体大小（用户可以在系统设置中调整字体）时容易出问题。lineHeight + maxLines可以保证文字在任何字号下都显示完整，且容器高度自适应。

完整示例入口

// pages/Index.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      // 这里只是占位，实际开发中卡片UI不需要手动渲染
      // 卡片由桌面系统通过form_info拉起
      Text('卡片示例内容见 FormCard 目录')
        .fontSize(20)
        .fontColor('#333333')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

实际开发的卡片入口文件在FormCard/pages/WeatherCard.ets，不需要手动在路由跳转中调用。

FAQ

Q：为什么我在模拟器上测试卡片尺寸和真机不一致？

A：模拟器不会真实模拟桌面系统的卡片布局算法，建议始终在真机上测试。不同分辨率的真机，1x2的实际vp值会有微小差异，判断尺寸时不要用硬编码阈值，可以用formInfo.width动态获取。

Q：卡片里的图片资源怎么适配不同尺寸？

A：建议使用SVG矢量图，ArkUI原生支持。如果必须用位图，按照设备的分辨率（如320dpi、480dpi）提供对应倍率的资源，并在Image组件里设置objectFit: ImageFit.Contain。

Q：卡片的点击事件在1x2和2x2下有没有区别？

A：没有区别。点击事件绑定的逻辑不变，只是点击区域根据卡片尺寸改变了。如果需要在不同尺寸下响应不同的操作，可以在事件回调里根据this.cardSize判断。

Q：2x2卡片里用了GridRow，为什么在1x2下元素重叠了？

A：GridRow会根据容器宽度自动调整列数，但不会自动隐藏内容。如果在1x2下还保留了GridRow的2列，内容就会挤在一起。解决方案是：先在buildContent里根据cardSize选择不同的布局策略，不要在同一个GridRow下尝试兼容所有尺寸（这个问题我在多个项目里都遇到过，最稳妥的方式就是分Builder）。

示例代码地址：项目地址