一、前期开发环境配置与检查

1. 环境软件硬件清单

  • 开发工具:DevEco Studio 4.1 Release,低版本无法打开API11工程(具体看你的硬件真机是可以用哪个版本)
  • SDK:KaihongOS_Public_SDK 4.1.2.17,API Version 11(不对就自己去下载对应的版本注意build-profile.json5的2个sdkversion)
  • 调试工具:hdc,位于SDKtoolchains文件夹

2. hdc调试环境配置

  1. 将SDK的toolchains目录添加到系统Path环境变量。
  2. 新增环境变量:HDC_SERVER_PORT,填写未被占用端口,例7035。
  3. 配置完成:关闭全部终端 + 重启DevEco Studio。
  4. 设备接线顺序:先插USB调试数据线,再接电源线,严禁带电插拔接口。
  5. 设备识别命令
hdc list targets
现象原因解决方案
输出设备序列号设备正常继续开发
返回[Empty]实验箱未识别断电,重新插紧调试USB接口
提示hdc不是可识别命令Path环境变量未配置/未重启终端修改环境变量,重启终端和IDE
[Fail]Failed to communicate with daemon端口被别的程序占用修改HDC_SERVER_PORT为其他空闲端口

卸载旧应用命令:

hdc uninstall com.example.component

3. 工程导入注意事项

  1. 工程存放路径不能包含中文、空格。
  2. 打开工程时,选择内层工程文件夹,不要选择上一级目录,否则工程识别失败。
  3. build‑profile.json5关键编译配置
compileSdkVersion:11,
compatibleSdkVersion:11,
runtimeOS:"OpenHarmony"

这三个参数控制SDK编译版本,实训工程不需要修改。

4. 签名配置

外部导入工程自带的证书路径是其他电脑用户目录,本机直接运行必然报错! 操作路径:File → Project Structure → SigningConfigs 勾选 Automatically generate signature(自动生成签名) IDE自动在本机.ohos目录生成证书、profile、密钥库文件,禁止手动复制别人证书文件。

5. 依赖同步

  • 开发依赖:@ohos/hypium、@ohos/hamock
  • 现象:oh_modules/@ohos为空
  • 处理:保持网络连通,点击Sync同步,出现Sync Successfully代表同步完成。
  • 报错SDK版本不匹配:SDK Manager安装API11。

二、项目必须关注的核心配置文件

这三个文件强关联,任意一处写错,页面加载失败(错误码1003,屏幕空白)

1. AppScope/app.json5

  • 关注字段:bundleName应用包名
  • 作用:整个应用的唯一包标识,hdc卸载、安装命令需要使用包名。

2. entry/src/main/module.json5

"pages":"$profile:main_pages"
  • 关注字段:pages
  • 作用:指定路由配置文件指向main_pages.json,告诉系统去哪里读取页面路由清单。

3. entry/src/main/resources/base/profile/main_pages.json

"src":[
  "pages/xxx/Page1",
  "pages/xxx/Page2"
]
  • 关注字段:src[]路由数组
  • 作用:所有页面必须在这里注册路由,没有注册的页面无法被加载。

    易错:路由路径严格区分大小写字母;TextInput第四个字符是小写L,写成大写I页面找不到。

4. entry/src/main/ets/entryability/EntryAbility.ets

windowStage.loadContent("页面路径",(err)=>{
})
  • 关注:onWindowStageCreate生命周期回调中的loadContent()第一个参数。
  • 作用:设置APP启动后默认打开的首页。
  • 成功日志:Succeeded in loading the content.
  • 失败日志:Failed to load the content. Cause:{"code":1003}

三者联动逻辑 module.json5 指向 main_pages.json;main_pages.json登记全部页面;EntryAbility的loadContent选择其中一条路由作为启动首页。

5. oh‑package.json5

  • 关注:devDependencies开发期依赖。
  • 作用:声明项目需要的开发库,同步依赖读取该文件。

三、ArkUI 常用内置组件与注意要点

1. Text 文本组件

Text("测试文字")
.fontSize(20)
.fontColor(Color.Red)
.textAlign(TextAlign.Center)
.textOverflow({overflow:TextOverflow.Ellipsis})
.maxLines(1)
.lineHeight(40)
  • textAlign生效前提:Text组件本身具备宽度;如果宽度由文字撑开,对齐属性看不到效果。
  • textOverflow.Clip直接截断文字;Ellipsis显示省略号。

2. Button 按钮组件

Button("OK",{type:ButtonType.Normal,stateEffect:true})
  • ButtonType.Normal普通圆角按钮;Capsule胶囊按钮;Circle圆形按钮。
  • stateEffect:true开启点击按压反馈;false关闭按压效果。
  • opacity()设置透明度。

3. Image 图片组件

Image($r('app.media.icon'))
.width(110).height(110)
.overlay("png",{align:Alignment.Bottom})
.objectFit(ImageFit.Cover)
  • $r('app.media.xxx')读取resources/media下面的图片资源,支持png/gif/svg/jpg。
  • .overlay():图片上方叠加文字。
  • objectFit.ImageFit.Cover图片铺满容器,会裁剪图片。

4. TextInput输入框组件

TextInput({placeholder:"请输入",controller:this.controller})
.type(InputType.Password)
.showPasswordIcon(true)
.style(TextInputStyle.Inline)
.maxLength(9)
  • InputType.Password密码框;showPasswordIcon(true)显示密码显隐切换图标。
  • TextInputStyle.Inline内联输入框样式。
  • TextInputController控制器,控制光标位置;多个输入框共用同一个控制器,光标会互相干扰。
  • @Extend(TextInput)可以扩展封装输入框通用样式,简化重复代码。

四、五大布局组件

重点:容器如果不设置宽高,大小由内部子组件内容撑开,很多对齐属性不会出现视觉效果。

布局组件功能核心属性
Column垂直方向排列子组件space子元素间距;justifyContent主轴(垂直)对齐;alignItems交叉轴(水平)对齐
Row水平方向排列子组件space间距;justifyContent主轴(水平)对齐;alignItems交叉轴(垂直)对齐
Stack层叠布局,子组件重叠堆叠子组件按照书写顺序一层层覆盖;alignSelf()单独设置子组件对齐方式
Flex弹性布局,Row/Column底层都是Flexdirection排列方向;justifyContent主轴排布;alignItems交叉轴;wrap:FlexWrap.Wrap开启换行。
子组件总宽度小于容器宽度,wrap换行不会触发
RelativeContainer相对布局,控件依靠ID互相锚定位置子组件设置.id("标记");.alignRules({})设置相对哪个控件摆放

五、事件、弹窗与提示

1. 点击事件 onClick

Button("按钮")
.onClick(()=>{
  //点击执行逻辑
})
  • 配合@State状态变量,修改变量自动刷新UI界面。

2. Toast、Dialog、ActionMenu(模块废弃)

❗@ohos.prompt模块API9起停止维护,API11必须替换为@ohos.promptAction

import promptAction from '@ohos.promptAction'

//吐司提示
promptAction.showToast({
  message:"提示文字",
  bottom:300, //距离屏幕底部位置
  duration:8000 //显示时长,系统强制钳制区间1500‑10000ms
})

//系统对话框,返回点击按钮index,从0开始计数
promptAction.showDialog({title:"标题",message:"内容",buttons:[...]})

//底部操作菜单
promptAction.showActionMenu({title:"菜单标题",buttons:[...]})

duration设置小于1500或者大于10000毫秒,系统会强制修正,和代码设置时长不一致。

3. bindPopup气泡弹窗

.bindPopup(this.isShowPopup,{message:"提示"})
  • 现象:点击弹窗外部空白关闭气泡,不会自动修改@State变量,再次点击图标气泡不弹出。
  • 原因:缺少onStateChange状态回调,状态变量没有复位。

六、装饰器、自定义组件、组件生命周期

常用装饰器

装饰器作用
@Component标记自定义UI组件
@Entry标记页面入口组件,可以被路由加载
@State组件内部状态;变量修改,UI自动刷新
@Prop接收父组件传递的数据;单向数据流
@Builder自定义构建函数,复用UI模板,可以传入参数
@Extend(组件名)扩展系统组件,批量复用样式属性

ArkUI自定义组件生命周期

真实生效回调函数(只有这两个)

  1. aboutToAppear():组件即将渲染显示到屏幕上,组件创建完成触发。
  2. aboutToDisappear():组件即将从页面销毁消失。

❌不存在的生命周期,写代码不会执行,无日志输出 onCreate()、onWillDisappear()、onDisappear()、onDestroy()

实训现象:页面仅打印Component is about to appear on the screen.,其余四个方法日志完全不输出。

七、常见报错、问题与解决方案汇总

问题现象根因处理方案
应用打开屏幕空白,日志Failed to load the content code:1003三处路由配置不匹配;loadContent路径和main_pages.json注册路径不一致核对module.json5、main_pages.json、loadContent三者路径;文件名大小写、目录名称检查
新增页面,运行找不到页面main_pages.json没有注册src路由数组;路由字母写错(小写L写成大写I)在src数组添加完整页面路由,逐字符比对文件路径
运行报证书、profile签名错误导入工程自带证书是别的电脑路径勾选自动生成签名 Automatically generate signature,禁止复制外部证书
hdc list targets返回[Empty]USB没有插到调试口,接触不良断电重新插调试USB线
工程同步Sync失败,ohpm依赖报错网络问题,oh_modules依赖未生成联网重新Sync;离线使用本地ohpm仓库
提示SDK版本不匹配SDK没有安装API11SDK Manager安装API11
Flex设置wrap:FlexWrap.Wrap但是不换行子组件整体总宽度小于容器可用宽度属于正常机制,不会换行,现象如实记录
prompt导入报错、toast弹不出来@ohos.prompt已经废弃全部替换为@ohos.promptAction
bindPopup点击外部关闭后,再次点击打不开气泡没有写onStateChange回调,@State变量没有复位需要连续点击两次图标恢复,完善回调修复该逻辑
Toast设置duration时间和实际显示时间不一样系统钳制时间1500‑10000ms数值超出区间系统强制修正,记录实际现象
Log过滤关键字看不到任何日志过滤词写错,应用没有重启杀掉应用重新运行,核对过滤tag关键字
安装失败,包名冲突设备上已经安装同名包hdc uninstall 包名卸载旧应用再运行

八、整体开发易错点总结

  1. 页面路由三处配置强关联:module.json5、main_pages.json、EntryAbility loadContent,任意写错页面1003报错空白。
  2. 导入外部工程一定要重新自动生成签名,不要直接使用别人证书。
  3. API11不要再使用废弃prompt模块,统一使用promptAction。
  4. Flex换行不是写wrap就一定换行;子组件总宽度大于容器宽度,换行才会生效。
  5. 自定义组件生命周期只有aboutToAppear、aboutToDisappear两个,其余名称是错误API,不会执行。
  6. 路由路径严格区分大小写,区分小写L和大写I,很容易踩坑。
  7. 很多布局对齐属性,需要容器设置宽高才会出现视觉效果;组件大小由内容撑开的时候对齐不生效。
  8. bindPopup点击外部关闭不会自动重置状态变量。
  9. hdc工具配置完成必须重启终端和IDE,环境变量才生效。
  10. 工程路径绝对不要中文、空格,会引发各种诡异编译异常。

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐