HarmonyOS7 ArkUI 实战：ImageFit 填充模式、圆角头像与滤镜效果

文章目录

• • • 前言
    • 代码讲解
    • • 页面入口怎么安排
      • 数据模型先稳住
      • 状态变量控制页面反馈
      • 布局代码不要从样式开始读
      • Builder 和方法承担复用
      • 使用方式
    • 完整代码
    • 关键代码解析
    • • `interface` 不是摆设
      • `@State` 是交互的开关
      • 列表和卡片要靠数据驱动
      • 事件回调要短一点
      • 样式参数别急着抽常量
    • 总结

前言

图片展示最容易踩裁剪和拉伸问题，ImageFit、圆角和滤镜最好放在一起看。

我建议把这篇当成一个可以直接改造的 ArkUI 页面模板来看。先跑起来，确认页面展示和交互都正常；再把里面的模拟数据替换成接口数据；最后再调整颜色、间距和业务字段。这样改起来比较稳，不容易一边改样式一边把状态逻辑弄乱。

这篇文章会按「页面意图、数据结构、状态流转、布局组织、交互细节」这条线来读代码。你不用从第一行样式硬看到最后，先抓住主线，后面的细节会轻松很多。

代码讲解

页面入口怎么安排

代码里的入口组件是ImageFitAndEffectsPage。如果你把它当成单独页面预览，保留@Entry就可以；如果要塞进现有工程的路由体系，通常会去掉@Entry，再由外层页面或路由模块统一管理。

这个习惯很重要。一个项目里入口页面太多，预览时容易混，后期拆组件也会麻烦。我的做法是：案例阶段保留入口，接业务时只保留真正需要被路由访问的页面。

数据模型先稳住

本案例涉及的数据模型主要有：ImageDemo、FilterCard、fitModesParmas、ShapeCardParams。

这些interface的作用不是为了“看起来规范”，而是给 UI 层划边界。比如列表项需要标题、描述、颜色、选中态，就应该在模型里说清楚。后续从接口拿数据时，可以在请求层做字段映射，别让后端字段名直接污染页面代码。

如果你准备接真实业务，建议把模拟数组替换成接口返回后的 ViewModel。页面只关心自己要渲染什么，不关心接口原始字段长什么样。

状态变量控制页面反馈

本案例里的关键状态包括：selectedFit、blurRadius、grayAmount、opacityValue、borderRadiusValue、selectedFilter。

@State的职责是让 UI 对用户操作有反馈。比如选中某个卡片、切换分类、展开内容、修改输入值、控制加载中状态，这些都应该由状态驱动。状态一变，相关 UI 自动刷新，这也是 ArkUI 声明式开发最核心的体验。

这里有个容易踩的坑：不要把所有数据都塞进@State。静态配置用普通数组就够了，只有用户会改、接口会更新、页面需要重新渲染的数据，才适合放进状态里。

布局代码不要从样式开始读

这个页面里比较关键的组件有：

• Row：横向排列、左右分栏、按钮组或卡片行都依赖它来控制水平方向的节奏。
• Column：纵向组织标题、内容、操作区，适合搭页面主骨架。
• Stack：负责图层叠放，常见于角标、遮罩、封面文字压图。
• Scroll：用于长内容容器，锚点跳转和返回顶部都离不开滚动控制。
• Image：图片组件要特别注意裁剪、填充、圆角和滤镜的组合效果。
• Slider：滑块适合做实时预览，状态值应该直接反映到样式上。

读布局时，我更建议先找大容器，再看内部如何拆块。比如一个页面通常会先用Column纵向放标题区、内容区、操作区；内容区里再用Row、Grid、List或其他容器细分。这样看代码，层级会比逐行看.padding()、.fontSize()清楚得多。

如果页面显示错位，优先检查容器关系，而不是马上改像素。很多问题不是某个.margin()不对，而是外层容器的宽高、滚动方向、权重分配或对齐方式没想清楚。

Builder 和方法承担复用

这篇没有额外拆出 Builder，页面结构主要集中在build()中。

辅助方法不多，逻辑主要写在事件回调和渲染表达式里。

@Builder更适合复用 UI 片段，比如卡片、列表行、头部区域、按钮组。普通方法更适合放计算逻辑，比如筛选列表、统计数量、切换状态、生成颜色。两者分清楚后，页面会干净很多。

我不建议把所有东西都塞进build()。刚开始代码少还行，需求一多，build()会变成几百行，后面改一个按钮都要找半天。

使用方式

把下面的完整代码放到 ArkTS 页面文件里即可运行。文章中的组件名已经是语义化命名，不包含编号式案例名称，接路由时直接使用ImageFitAndEffectsPage就行。

如果你要改成业务页面，优先改三处：数据模型、状态变量、事件方法。样式可以后调，先保证数据流和交互是通的。

完整代码

// ImageFitAndEffectsPage: 图片组件详解 - Image 各种填充模式与效果 // 知识点: Image、ImageFit、objectFit、borderRadius、colorFilter、blur、grayscale interface ImageDemo { demoId: number demoTitle: string demoEmoji: string demoBg: string demoWidth: number demoHeight: number fitMode: ImageFit fitLabel: string } interface FilterCard { filterId: number filterName: string filterEmoji: string filterBg: string blurValue: number grayValue: number opacity: number } interface fitModesParmas{ label: string, value: ImageFit, desc: string } interface ShapeCardParams { shape: string, radius: number, emoji: string, bg: string } @Entry @Component struct ImageFitAndEffectsPage { @State selectedFit: ImageFit = ImageFit.Cover @State blurRadius: number = 0 @State grayAmount: number = 0 @State opacityValue: number = 1.0 @State borderRadiusValue: number = 0 private fitModes:fitModesParmas[] = [ { label: 'Cover', value: ImageFit.Cover, desc: '等比缩放填满，可能裁剪' }, { label: 'Contain', value: ImageFit.Contain, desc: '等比缩放完整显示，可能留白' }, { label: 'Fill', value: ImageFit.Fill, desc: '拉伸填满，可能变形' }, { label: 'None', value: ImageFit.None, desc: '原始尺寸，可能溢出或留白' }, { label: 'ScaleDown', value: ImageFit.ScaleDown, desc: '等比缩放，不放大只缩小' }, { label: 'Auto', value: ImageFit.Auto, desc: '自适应，根据容器决定' }, ] private filterCards: FilterCard[] = [ { filterId: 1, filterName: '原图', filterEmoji: '🖼️', filterBg: '#E3F2FD', blurValue: 0, grayValue: 0, opacity: 1.0 }, { filterId: 2, filterName: '模糊', filterEmoji: '🌫️', filterBg: '#F3E5F5', blurValue: 8, grayValue: 0, opacity: 1.0 }, { filterId: 3, filterName: '灰度', filterEmoji: '🔲', filterBg: '#ECEFF1', blurValue: 0, grayValue: 1, opacity: 1.0 }, { filterId: 4, filterName: '半透明', filterEmoji: '👻', filterBg: '#FFF8E1', blurValue: 0, grayValue: 0, opacity: 0.4 }, { filterId: 5, filterName: '磨砂', filterEmoji: '✨', filterBg: '#E0F7FA', blurValue: 4, grayValue: 0.5, opacity: 0.8 }, { filterId: 6, filterName: '朦胧', filterEmoji: '🌅', filterBg: '#FCE4EC', blurValue: 12, grayValue: 0, opacity: 0.6 }, ] @State selectedFilter: FilterCard = this.filterCards[0] build() { Column({ space: 0 }) { Row({ space: 0 }) { Text('Image 图片组件') .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') } .width('100%') .height(52) .padding({ left: 16, right: 16 }) .backgroundColor('#FFFFFF') .border({ width: { bottom: 1 }, color: '#F0F0F0' }) Scroll() { Column({ space: 12 }) { // 一、ImageFit 填充模式对比 Column({ space: 10 }) { Text('一、ImageFit 填充模式对比') .fontSize(15) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') .width('100%') Text('点击选择填充模式，查看效果差异') .fontSize(13) .fontColor('#888888') .width('100%') // 模式选择 Column({ space: 6 }) { Row({ space: 8 }) { ForEach(this.fitModes.slice(0, 3), (mode: fitModesParmas) => { Text(mode.label) .fontSize(13) .fontColor(this.selectedFit === mode.value ? '#FFFFFF' : '#555555') .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .backgroundColor(this.selectedFit === mode.value ? '#007DFF' : '#F0F0F0') .borderRadius(16) .layoutWeight(1) .textAlign(TextAlign.Center) .onClick(() => { this.selectedFit = mode.value }) }, (mode:fitModesParmas) => mode.label) } .width('100%') Row({ space: 8 }) { ForEach(this.fitModes.slice(3, 6), (mode: fitModesParmas) => { Text(mode.label) .fontSize(13) .fontColor(this.selectedFit === mode.value ? '#FFFFFF' : '#555555') .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .backgroundColor(this.selectedFit === mode.value ? '#007DFF' : '#F0F0F0') .borderRadius(16) .layoutWeight(1) .textAlign(TextAlign.Center) .onClick(() => { this.selectedFit = mode.value }) }, (mode:fitModesParmas) => mode.label) } .width('100%') } // 预览区 Column({ space: 8 }) { // 用大 Emoji 模拟图片 Stack({ alignContent: Alignment.BottomEnd }) { Column() { Text('🏔️') .fontSize(80) } .width(200) .height(120) .backgroundColor('#E3F2FD') .clip(true) .borderRadius(8) .border({ width: 2, color: '#007DFF', style: BorderStyle.Dashed }) Text(`[${this.fitModes.find(m => m.value === this.selectedFit)?.label}]`) .fontSize(11) .fontColor('#FFFFFF') .padding({ left: 6, right: 6, top: 2, bottom: 2 }) .backgroundColor('#007DFF') .borderRadius({ topLeft: 6, bottomRight: 8 }) } Text(this.fitModes.find(m => m.value === this.selectedFit)?.desc ?? '') .fontSize(13) .fontColor('#666666') .textAlign(TextAlign.Center) } .alignItems(HorizontalAlign.Center) } .width('100%') .padding(16) .backgroundColor('#FFFFFF') .borderRadius(12) // 二、圆角图片 Column({ space: 10 }) { Text('二、圆角控制（borderRadius）') .fontSize(15) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') .width('100%') Row({ space: 0 }) { Text('圆角值') .fontSize(13) .fontColor('#555555') .width(60) Slider({ value: this.borderRadiusValue, min: 0, max: 60, step: 4 }) .layoutWeight(1) .onChange((val: number) => { this.borderRadiusValue = val }) Text(`${this.borderRadiusValue}px`) .fontSize(13) .fontColor('#007DFF') .width(50) .textAlign(TextAlign.End) } .width('100%') .alignItems(VerticalAlign.Center) Row({ space: 16 }) { // 方形 Column({ space: 6 }) { Text('🌸') .fontSize(48) .width(80) .height(80) .textAlign(TextAlign.Center) .backgroundColor('#FCE4EC') .borderRadius(this.borderRadiusValue) Text('圆角').fontSize(12).fontColor('#888888') } .alignItems(HorizontalAlign.Center) // 矩形 Column({ space: 6 }) { Text('🌺') .fontSize(48) .width(120) .height(80) .textAlign(TextAlign.Center) .backgroundColor('#FFF0F6') .borderRadius(this.borderRadiusValue) Text('矩形').fontSize(12).fontColor('#888888') } .alignItems(HorizontalAlign.Center) } .width('100%') .justifyContent(FlexAlign.Center) Text('（borderRadius = 50% → 圆形效果）') .fontSize(12) .fontColor('#AAAAAA') .width('100%') .textAlign(TextAlign.Center) } .width('100%') .padding(16) .backgroundColor('#FFFFFF') .borderRadius(12) // 三、滤镜效果 Column({ space: 10 }) { Text('三、图片滤镜效果') .fontSize(15) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') .width('100%') // 预览 Stack({ alignContent: Alignment.BottomStart }) { Text('🌅') .fontSize(80) .width('100%') .height(160) .textAlign(TextAlign.Center) .backgroundColor('#FFE0B2') .borderRadius(12) .blur(this.selectedFilter.blurValue) .grayscale(this.selectedFilter.grayValue) .opacity(this.selectedFilter.opacity) Text(this.selectedFilter.filterName) .fontSize(14) .fontColor('#FFFFFF') .fontWeight(FontWeight.Bold) .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .backgroundColor('rgba(0,0,0,0.4)') .borderRadius({ topLeft: 0, topRight: 8, bottomLeft: 12, bottomRight: 0 }) } .width('100%') // 滤镜选择 Row({ space: 8 }) { ForEach(this.filterCards, (filter: FilterCard) => { Column({ space: 4 }) { Text(filter.filterEmoji) .fontSize(18) .width(44) .height(44) .textAlign(TextAlign.Center) .backgroundColor(filter.filterBg) .borderRadius(10) .border({ width: this.selectedFilter.filterId === filter.filterId ? 2 : 0, color: '#007DFF' }) .blur(filter.blurValue / 2) .grayscale(filter.grayValue) .opacity(filter.opacity + 0.2 < 1 ? filter.opacity + 0.2 : 1) Text(filter.filterName) .fontSize(10) .fontColor(this.selectedFilter.filterId === filter.filterId ? '#007DFF' : '#888888') } .alignItems(HorizontalAlign.Center) .layoutWeight(1) .onClick(() => { this.selectedFilter = filter }) }, (filter: FilterCard) => filter.filterId.toString()) } .width('100%') } .width('100%') .padding(16) .backgroundColor('#FFFFFF') .borderRadius(12) // 四、头像形状展示 Column({ space: 10 }) { Text('四、头像常见形状') .fontSize(15) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') .width('100%') Row({ space: 16 }) { ForEach([ { shape: '圆形', radius: 32, emoji: '👦', bg: '#E3F2FD' }, { shape: '圆角矩形', radius: 12, emoji: '👧', bg: '#FCE4EC' }, { shape: '微信头像', radius: 8, emoji: '😊', bg: '#E8F5E9' }, { shape: '方形', radius: 0, emoji: '🤓', bg: '#FFF8E1' }, ] , (item:ShapeCardParams) => { Column({ space: 6 }) { Text(item.emoji) .fontSize(32) .width(64) .height(64) .textAlign(TextAlign.Center) .backgroundColor(item.bg) .borderRadius(item.radius) Text(item.shape) .fontSize(11) .fontColor('#888888') .textAlign(TextAlign.Center) } .alignItems(HorizontalAlign.Center) .layoutWeight(1) }, (item: ShapeCardParams) => item.shape) } .width('100%') .justifyContent(FlexAlign.SpaceAround) } .width('100%') .padding(16) .backgroundColor('#FFFFFF') .borderRadius(12) } .padding({ left: 12, right: 12, top: 12, bottom: 24 }) } .scrollBar(BarState.Off) .layoutWeight(1) } .width('100%') .height('100%') .backgroundColor('#F5F6FA') } }

关键代码解析

interface不是摆设

很多新手写 ArkUI 页面时，会直接在ForEach里使用一堆临时对象。页面小的时候没问题，但字段一多，就很难知道每个字段到底用于哪里。本案例把数据结构提前声明出来，读代码时能很快判断每个 UI 区块依赖哪些字段。

后续如果接接口，也建议保留这层结构。接口可以变，页面模型尽量稳定。这样页面不会因为后端多返回一个字段、少返回一个字段就跟着大改。

@State是交互的开关

本案例的交互反馈都围绕状态展开。点击、切换、输入、刷新这类行为，本质上都是修改某个状态值，然后让 UI 重新计算显示结果。

写这类代码时有一个简单判断：如果某个值变化后，页面应该立刻变，那它大概率应该是状态；如果它只是配置项、静态文案、固定颜色，就不要放进状态。

列表和卡片要靠数据驱动

只要页面里出现重复结构，就应该优先想到数据数组加ForEach。这样新增一项、删除一项、调整顺序都只动数据，不用复制粘贴一段 UI。

这个案例的完整代码里已经把主要内容抽成数组或方法。你可以试着多加一条数据，看页面是否能自然渲染出来。如果能，说明结构是健康的；如果加一条就要改很多 UI，说明组件拆分还不够。

事件回调要短一点

.onClick()、onChange()这类回调里可以直接改状态，但不建议堆太多逻辑。简单切换可以写在回调里，复杂逻辑最好拆成方法。

这样做有两个好处：一是读页面结构时不会被业务逻辑打断；二是后面要加埋点、请求接口、异常处理时，有明确的位置可以改。

样式参数别急着抽常量

这个案例里有不少颜色、间距、圆角、字号。学习阶段直接写在组件链上，反而更容易看出效果。等你确定页面风格稳定后，再把主题色、通用间距、卡片圆角提到统一常量里。

过早抽象会让示例代码变绕。先让页面清楚，再谈工程化，这是我比较推荐的顺序。

总结

这个案例真正值得学的，不只是某个 ArkUI 组件怎么写，而是一个页面如何从数据走到状态，再走到布局和交互。

你可以按这个顺序改造：先替换数据模型，再确认状态更新是否正确，接着调整布局容器，最后打磨样式细节。只要这条主线不乱，页面规模变大也不会失控。

如果后续继续扩展，我会优先把可复用的卡片、列表行、筛选栏或控制区拆成独立组件。这样主页面只保留数据和流程，代码会更接近真实项目里的写法。