HarmonyOS6 RcImage 组件填充模式与形状系统设计（一）

对外暴露字符串类型以降低使用门槛，内部转换为系统枚举确保兼容性。默认值设为 cover，防止异常情况下组件不可用。

private getImageFit(): ImageFit {
  switch (this.imageFit) {
    case 'contain': return ImageFit.Contain;
    case 'cover': return ImageFit.Cover;
    case 'fill': return ImageFit.Fill;
    case 'none': return ImageFit.None;
    case 'scale-down': return ImageFit.ScaleDown;
    default: return ImageFit.Cover;
  }
}

// 应用到 Image 组件
Image(this.imageSrc).objectFit(this.getImageFit())

contain 模式深度解析

工作原理

核心特性是保持图片宽高比，完整显示内容，多余空间通过留白处理。

RcImage({ 
  imageSrc: 'https://example.com/photo.jpg', // 原图 800×600 
  imageWidth: 400, 
  imageHeight: 400, 
  imageFit: 'contain'
})

计算逻辑如下：

1. 比较容器与图片的宽高比。本例中容器 1:1，图片 4:3。
2. 以宽度为基准缩放：比例 = 400 / 800 = 0.5。
3. 缩放后高度 = 600 * 0.5 = 300。
4. 垂直居中，上下各留白 50px。

适用场景

• 证件照展示：必须完整显示人脸，配合背景色填充留白区域。
• 商品详情图：展示完整商品轮廓。
• 艺术品展示：保持原始比例，黑色背景衬托。

// 证件照示例
RcImage({ 
  imageSrc: $r('app.media.idPhoto'), 
  imageWidth: 120, 
  imageHeight: 160, 
  imageFit: 'contain', 
  bgColor: '#f5f5f5' 
})

cover 模式深度解析

工作原理

保持宽高比填满容器，超出部分自动裁剪。这是移动端最常用的模式。

RcImage({ 
  imageSrc: 'https://example.com/landscape.jpg', // 原图 1920×1080 
  imageWidth: 400, 
  imageHeight: 300, 
  imageFit: 'cover'
})

计算逻辑：

1. 容器 4:3，图片 16:9。
2. 以高度为基准缩放：比例 = 300 / 1080 ≈ 0.278。
3. 缩放后宽度 = 1920 * 0.278 ≈ 533。
4. 水平居中裁剪，左右各裁掉约 66.5px。

适用场景

• 用户头像：通常配合圆形容器，必须填满。
• 卡片封面：统一尺寸，容忍局部裁剪。
• 背景大图：铺满屏幕。

// 用户头像示例
RcImage({ 
  imageSrc: $r('app.media.avatar'), 
  imageWidth: 80, 
  imageHeight: 80, 
  imageFit: 'cover', 
  imageShape: 'circle'
})

fill 模式深度解析

工作原理

强制拉伸图片填满容器，不保持宽高比。这会导致图像失真。

RcImage({ 
  imageSrc: 'https://example.com/banner.jpg', 
  imageWidth: 600, 
  imageHeight: 400, 
  imageFit: 'fill'
})

警告与建议

• ⚠️ 避免用于照片：人物或风景会产生明显变形。
• ✅ 仅用于特殊场景：纯色背景、重复纹理或装饰性图形。
• 💡 优先选择 cover：大多数情况下 cover 或 contain 体验更好。

none 与 scale-down 模式

none 模式

保持图片原始尺寸，不进行缩放，居中显示。

RcImage({ 
  imageSrc: 'https://example.com/logo.png', // 原图 64×64 
  imageWidth: 200, 
  imageHeight: 200, 
  imageFit: 'none'
})

适用于小图标或需要像素级精度的二维码展示。

scale-down 模式

智能决策：如果原图尺寸小于容器，则等同于 none；否则等同于 contain。

/** scale-down 决策逻辑 */
if (图片原始尺寸 <= 容器尺寸) {
  使用 none 模式 // 显示原始尺寸
} else {
  使用 contain 模式 // 缩小以适应容器
}

非常适合缩略图预览，既能保证大图不被过度放大，又能让小图保持清晰。

形状系统设计

除了填充模式，图片的形状控制同样关键。

类型定义

/** 图片形状类型 */
export type RcImageShape = 'square' | 'circle' | 'round'

圆角计算实现

private getBorderRadius(): string | number {
  switch (this.imageShape) {
    case 'circle': return '50%'; // 圆形：自动适应尺寸
    case 'round': return getSizeByUnit(this.imageRadius); // 自定义值
    case 'square': default: return 0; // 方形：无圆角
  }
}

// 应用到容器
Stack()
  .borderRadius(this.getBorderRadius())
  .clip(true) // 关键：裁剪溢出内容

关键技术点包括百分比圆角自动适配、clip 属性确保裁剪生效，以及单位转换的统一处理。

后续章节将详细讲解响应式布局策略及更多高级用法。