HarmonyOS ArkTS 的新手练手样例：Image 资源图片展示卡片

开头这一篇只讲一个主角Image。展示资源目录中的图片做头像、图标、封面和说明插图。 对新手来说学习控件最有效的方法不是把官方属性一次背完而是先把一个完整页面跑起来然后围绕这个页面改尺寸、改状态、改事件。下面的代码就是配套截图 App 中已经编译通过的完整页面。本篇目标看懂 Image 的基础用法。能复制完整页面到 ArkTS 工程中运行。知道关键属性和事件分别控制什么。能基于同一个组件改出几个小样例。对应 App 页面配套 App 中本篇对应页面文件是entry/src/main/ets/pages/ImageResourcePage.ets运行 App 后从首页点击 Image 入口即可进入本页截图。完整页面代码import{router}fromkit.ArkUI;EntryComponentstruct 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 typeApplication。TemplateEmpty Ability。LanguageArkTS。ModelStage。DevicePhone可按需要兼容 Tablet、2in1。Runtime OSHarmonyOS。二、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_HOMED:\Program Files\Huawei\DevEco Studio Beta\sdk3.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_HOMED:\Program Files\Huawei\DevEco Studio Beta\jbr$env:PathD:\Program Files\Huawei\DevEco Studio Beta\jbr\bin;$env:Pathhvigorw--stop-daemon5. 构建成功但有弃用警告构建时出现过router.pushUrl、router.back、AlertDialog.show的弃用警告但不影响本次截图 Demo 编译和安装。正式项目建议后续按当前 API 推荐方式替换。七、本次安装启动记录构建命令hvigorw--mode module-p moduleentrydefault-p productdefault 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。