OpenHarmony(KaihongOS API11)北向应用开发笔记
·
一、前期开发环境配置与检查
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调试环境配置
- 将SDK的
toolchains目录添加到系统Path环境变量。 - 新增环境变量:
HDC_SERVER_PORT,填写未被占用端口,例7035。 - 配置完成:关闭全部终端 + 重启DevEco Studio。
- 设备接线顺序:先插USB调试数据线,再接电源线,严禁带电插拔接口。
- 设备识别命令
hdc list targets
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 输出设备序列号 | 设备正常 | 继续开发 |
返回[Empty] | 实验箱未识别 | 断电,重新插紧调试USB接口 |
提示hdc不是可识别命令 | Path环境变量未配置/未重启终端 | 修改环境变量,重启终端和IDE |
[Fail]Failed to communicate with daemon | 端口被别的程序占用 | 修改HDC_SERVER_PORT为其他空闲端口 |
卸载旧应用命令:
hdc uninstall com.example.component
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底层都是Flex | direction排列方向;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自定义组件生命周期
真实生效回调函数(只有这两个)
aboutToAppear():组件即将渲染显示到屏幕上,组件创建完成触发。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没有安装API11 | SDK Manager安装API11 |
| Flex设置wrap:FlexWrap.Wrap但是不换行 | 子组件整体总宽度小于容器可用宽度 | 属于正常机制,不会换行,现象如实记录 |
| prompt导入报错、toast弹不出来 | @ohos.prompt已经废弃 | 全部替换为@ohos.promptAction |
| bindPopup点击外部关闭后,再次点击打不开气泡 | 没有写onStateChange回调,@State变量没有复位 | 需要连续点击两次图标恢复,完善回调修复该逻辑 |
| Toast设置duration时间和实际显示时间不一样 | 系统钳制时间1500‑10000ms | 数值超出区间系统强制修正,记录实际现象 |
| Log过滤关键字看不到任何日志 | 过滤词写错,应用没有重启 | 杀掉应用重新运行,核对过滤tag关键字 |
| 安装失败,包名冲突 | 设备上已经安装同名包 | hdc uninstall 包名卸载旧应用再运行 |
八、整体开发易错点总结
- 页面路由三处配置强关联:
module.json5、main_pages.json、EntryAbility loadContent,任意写错页面1003报错空白。 - 导入外部工程一定要重新自动生成签名,不要直接使用别人证书。
- API11不要再使用废弃
prompt模块,统一使用promptAction。 - Flex换行不是写wrap就一定换行;子组件总宽度大于容器宽度,换行才会生效。
- 自定义组件生命周期只有
aboutToAppear、aboutToDisappear两个,其余名称是错误API,不会执行。 - 路由路径严格区分大小写,区分小写L和大写I,很容易踩坑。
- 很多布局对齐属性,需要容器设置宽高才会出现视觉效果;组件大小由内容撑开的时候对齐不生效。
- bindPopup点击外部关闭不会自动重置状态变量。
- hdc工具配置完成必须重启终端和IDE,环境变量才生效。
- 工程路径绝对不要中文、空格,会引发各种诡异编译异常。
更多推荐


所有评论(0)