开头
这一篇只讲一个主角：Image。
展示资源目录中的图片，做头像、图标、封面和说明插图。 对新手来说，学习控件最有效的方法不是把官方属性一次背完，而是先把一个完整页面跑起来，然后围绕这个页面改尺寸、改状态、改事件。下面的代码就是配套截图 App 中已经编译通过的完整页面。
本篇目标
- 看懂 Image 的基础用法。
- 能复制完整页面到 ArkTS 工程中运行。
- 知道关键属性和事件分别控制什么。
- 能基于同一个组件改出几个小样例。
对应 App 页面
配套 App 中，本篇对应页面文件是：
entry/src/main/ets/pages/ImageResourcePage.ets运行 App 后，从首页点击 Image 入口即可进入本页截图。
完整页面代码
import{router}from'@kit.ArkUI';@Entry@Componentstruct ImageResourcePage{build(){Column({space:18}){Row(){Button('<').width(44).height(36).onClick(()=>{router.back();})Text('Image').fontSize(22).fontWeight(FontWeight.Bold).layoutWeight(1).textAlign(TextAlign.Center)Blank().width(44)}.width('100%')Column({space:16}){Image($r('app.media.start_icon')).width(120).height(120).borderRadius(24)Text('资源图片展示').fontSize(30).fontWeight(FontWeight.Bold).fontColor('#126A5E')Text('Image 可以加载 resources 中的图片，用来做头像、图标和插图。').fontSize(15).fontColor('#667085').textAlign(TextAlign.Center)}.width('100%').padding(28).borderRadius(8).backgroundColor('#FFFFFF')}.width('100%').height('100%').padding(20).backgroundColor('#F7F2E8')}}核心属性和事件讲解
| 属性/写法 | 作用 | 本篇用法 |
|---|---|---|
Image($r('app.media.start_icon')) | 从资源目录加载图片 | 读取resources/base/media/start_icon.svg |
.width(120)/.height(120) | 固定显示尺寸 | 让截图中的图片大小稳定 |
.borderRadius(24) | 设置圆角 | 做成更像 App 图标的视觉效果 |
.padding() | 控制图片周围留白 | 让图片不贴边，截图更干净 |
代码结构拆开看
1. 顶部返回栏
每个截图页都保留一个简单顶部栏：左边是返回按钮，中间是当前组件名称，右边用 Blank() 占位。这样做的好处是所有截图页面结构一致，后期整理文章配图时不会乱。
Row(){Button('<')Text('Image')Blank()}2. 主体卡片
主体区域才是本篇组件的练习区。截图 Demo 里统一使用浅色背景和白色卡片，是为了让控件更清楚地被看到。真实项目里你可以把这些颜色替换成自己的设计规范。
3. 状态和事件
如果页面里有 @State，它就是驱动界面变化的数据。事件里修改状态，界面就会跟着刷新。这个规则在 Search、TextArea、Progress、Rating、Radio、Select、LoadingProgress 这些页面里都能看到。
再做几个小样例
样例 1：头像圆图
Image($r('app.media.start_icon')).width(80).height(80).borderRadius(40)样例 2：封面图
Image($r('app.media.start_icon')).width('100%').height(180).objectFit(ImageFit.Contain)样例 3：图文卡片
Row({space:12}){Image($r('app.media.start_icon')).width(56).height(56)Text('ArkTS 控件示例').fontSize(18)}新手常见问题
- 只复制了组件，没有复制 @State。如果组件依赖状态，页面会报错或无法交互。
- 只改了显示文本，没有改事件里的状态变量，导致看起来“点了没反应”。
- 截图页没有固定宽高或留白，模拟器尺寸一变，画面就挤在一起。
本篇小结
Image 的学习重点是先把“能运行的完整页面”看懂，再去拆属性和事件。你可以直接使用本篇完整代码截图，也可以从“再做几个小样例”里挑一个继续改。
附录：项目设置与构建问题记录
一、项目设置
本篇配套一个独立 ArkTS 示例 App，用于运行页面和截图：
建议用 DevEco Studio 打开项目后运行entry模块。项目定位是截图练习 Demo，不依赖后端服务，也不需要额外权限。
建议新建或检查工程时保持以下设置：
- Project type：Application。
- Template：Empty Ability。
- Language：ArkTS。
- Model：Stage。
- Device：Phone，可按需要兼容 Tablet、2in1。
- Runtime OS：HarmonyOS。
二、SDK 版本
本文主题面向 HarmonyOS ArkTS API 24+。本次示例工程根目录build-profile.json5使用如下配置：
{ "compatibleSdkVersion": "6.1.1(24)", "targetSdkVersion": "6.1.1(24)", "runtimeOS": "HarmonyOS" }如果本机 DevEco Studio SDK Manager 中安装的版本不同，请按本机实际 API 24+ SDK 调整compatibleSdkVersion和targetSdkVersion。
三、项目目录说明
核心目录如下：
HarmonyOS_ArkTS_API24_ControlsScreenshotApp/ ├── AppScope/ │ ├── app.json5 │ └── resources/ ├── entry/ │ ├── src/main/ets/entryability/EntryAbility.ets │ ├── src/main/ets/pages/ │ ├── src/main/resources/base/profile/main_pages.json │ ├── build-profile.json5 │ └── oh-package.json5 ├── build-profile.json5 ├── hvigorfile.ts └── oh-package.json5页面文件都在：
entry/src/main/ets/pages/路由注册文件在：
entry/src/main/resources/base/profile/main_pages.json五、创建项目过程
- 打开 DevEco Studio。
- 点击 Create Project。
- 选择 Application。
- 模板选择 Empty Ability。
- 开发语言选择 ArkTS。
- 模型选择 Stage。
- 设置项目名称，例如
ArkTSControlsDemo。 - 选择保存路径，建议路径只包含英文、数字、下划线或连字符。
- 选择 API 24+ 对应 SDK。
- 点击 Finish，等待工程创建完成。
- 打开
entry/src/main/ets/pages/Index.ets。 - 运行默认工程，确认模拟器或真机能打开。
- 再逐个添加本文中的页面代码并截图。
六、本次编译安装遇到的问题与解决办法
1. 中文路径导致 Hvigor 拒绝构建
问题现象：
Invalid project path. Current path does not match: D:\私人资料\CSDN\HarmonyOS_ArkTS_API24_ControlsScreenshotApp原因：Hvigor 对工程路径有限制，路径只能包含英文字母、数字、连字符、下划线、英文句点、英文括号、空格或@。
处理办法：把项目复制到 ASCII 路径后构建：
D:\\HarmonyOS_ArkTS_API24_ControlsScreenshotApp2.DEVECO_SDK_HOME环境变量无效
问题现象：
Invalid value of 'DEVECO_SDK_HOME' in the system environment path.处理办法：在当前命令会话中临时指定 DevEco SDK 根目录：
$env:DEVECO_SDK_HOME='D:\Program Files\Huawei\DevEco Studio Beta\sdk'3.hvigor-config.json5缺少dependencies
问题现象：
Schema validate failed ... missingProperty: 'dependencies'处理办法：补齐hvigor/hvigor-config.json5：
{ "modelVersion": "5.0.0", "dependencies": { } }4. 打包阶段找不到 Java
问题现象：
spawn java ENOENT处理办法：使用 DevEco Studio 自带 JBR，并停止旧的 Hvigor daemon 后重新构建：
$env:JAVA_HOME='D:\Program Files\Huawei\DevEco Studio Beta\jbr'$env:Path="D:\Program Files\Huawei\DevEco Studio Beta\jbr\bin;$env:Path"hvigorw--stop-daemon5. 构建成功但有弃用警告
构建时出现过router.pushUrl、router.back、AlertDialog.show的弃用警告，但不影响本次截图 Demo 编译和安装。正式项目建议后续按当前 API 推荐方式替换。
七、本次安装启动记录
构建命令：
hvigorw--mode module-p module=entry@default-p product=default assembleHap安装命令：
hdc install entry-default-unsigned.hap启动命令：
hdc shell aastart-a EntryAbility-b com.csdn.arkts.controls.screenshot验证结果：
- HAP 构建成功。
- 模拟器目标：
127.0.0.1:5555。 - 安装结果：
install bundle successfully。 - 启动结果：
start ability successfully。
