从零创建一个鸿蒙原生应用：实战教程

适用版本HarmonyOS 5NEXT ArkTS Stage 模型开发工具DevEco Studio最终产出一个带搜索功能的待办事项TodoApp一、开发环境搭建1.1 下载 DevEco Studio访问 华为开发者联盟 下载 DevEco Studio基于 IntelliJ IDEA 定制。注意HarmonyOS 5 需要 DevEco Studio 5.0旧版本无法创建纯血鸿蒙项目。1.2 配置 SDK首次启动 DevEco Studio 后进入 Settings → SDK Manager至少安装SDK 组件 用途API 12HarmonyOS 5 NEXT 目标 SDK纯血鸿蒙ArkTS 声明式 UI 开发框架Toolchains 编译工具链Local Emulator可选 本地模拟器方便调试1.3 注册华为开发者账号在 AppGallery Connect 注册账号并实名认证——后续真机调试、上架均依赖此账号。二、创建第一个项目2.1 新建项目打开 DevEco Studio点击 Create Project选择模板textApplication → Empty Ability配置项 填写值Project Name TodoAppBundle Name com.example.todoappSave Location 自定义Compatible SDK 5.0.0 (API 12)Device Type PhoneLanguage ArkTSModel Stage点击 FinishIDE 会自动完成项目初始化。2.2 项目结构解读创建完成后项目目录如下textTodoApp/├── AppScope/ # 应用全局配置│ └── app.json5 # 应用名称、版本、图标等├── entry/ # 主模块entry类型的HAP包│ ├── src/│ │ ├── main/│ │ │ ├── ets/ # ArkTS 源码目录│ │ │ │ ├── entryability/ # Ability应用入口│ │ │ │ │ └── EntryAbility.ets│ │ │ │ └── pages/ # 页面文件│ │ │ │ └── Index.ets│ │ │ ├── resources/ # 资源文件图片、字符串、颜色等│ │ │ └── module.json5 # 模块配置Ability注册、权限申请│ │ └── ohosTest/ # 测试代码│ ├── build-profile.json5 # 构建配置│ └── oh-package.json5 # 依赖管理类似 npm└── oh_modules/ # 依赖包本地缓存核心概念速览概念 类比 说明Ability Android 的 Activity / Service 应用的功能单元。EntryAbility 就是启动页Stage 模型 模块化架构 每个 Ability 独立运行生命周期由系统管理Page 一个界面 基于 Entry Component 装饰器定义module.json5AndroidManifest.xml注册 Ability、配置权限、声明设备类型三、ArkTS 语言速览ArkTS 是鸿蒙原生应用的开发语言基于 TypeScript 扩展了声明式 UI 和状态管理。你只需掌握三个核心语法。3.1 装饰器DecoratorstypescriptEntry // 标记这是一个页面入口Component // 标记这是一个自定义组件struct MyPage {State message: string ‘Hello’ // State 标记响应式状态Prop label: string // Prop 父传子Link count: number // Link 双向绑定build() { // 必须实现的 UI 描述函数// …}}3.2 声明式 UI不是写 XML 布局也不是命令式 new TextView()——而是 用函数描述 UItypescriptbuild() {Column() { // 纵向容器类似 FlexDirection: columnText(‘Hello’) // 文本组件Button(‘点击我’) // 按钮组件.onClick(() {}) // 链式调用事件Image($r(‘app.media.icon’)) // 图片组件}.width(‘100%’).height(‘100%’).padding(16)}3.3 状态驱动视图状态变了UI 自动更新——你只管改数据不用操作 DOMtypescriptState count: number 0build() {Column() {Text(计数: ${this.count})Button(‘1’).onClick(() {this.count // 改状态Text 自动刷新})}}四、实战构建 Todo 应用下面开始编写一个完整的 待办事项应用包含添加、列表展示、搜索、标记完成。4.1 定义数据模型新建文件 entry/src/main/ets/models/TodoItem.etstypescriptexport class TodoItem {id: numbertitle: stringisDone: booleanconstructor(title: string) {this.id Date.now() // 时间戳作ID简单够用this.title titlethis.isDone false}}4.2 编写主页面修改 entry/src/main/ets/pages/Index.ets 为完整内容typescriptimport { TodoItem } from ‘…/models/TodoItem’EntryComponentstruct Index {// — 状态 —State todoList: TodoItem[] [new TodoItem(‘学习 ArkTS 语法’),new TodoItem(‘搭建 DevEco Studio’),new TodoItem(‘写第一个鸿蒙应用’)]State inputValue: string ‘’State searchKeyword: string ‘’// — 计算属性按关键词过滤 —get filteredList(): TodoItem[] {if (this.searchKeyword.trim() ‘’) {return this.todoList}return this.todoList.filter(item item.title.toLowerCase().includes(this.searchKeyword.toLowerCase()))}// — UI —build() {Column() {// ── 标题 ──Text(‘我的待办’).fontSize(28).fontWeight(FontWeight.Bold).width(‘100%’).padding({ top: 24, bottom: 16, left: 16 })// ── 搜索栏 ── Search({ placeholder: 搜索待办..., value: this.searchKeyword }) .width(90%) .height(40) .onChange((value: string) { this.searchKeyword value }) // ── 输入区域 ── Row() { TextInput({ placeholder: 输入新的待办事项, text: this.inputValue }) .layoutWeight(1) .height(48) .onChange((value: string) { this.inputValue value }) Button(添加) .height(48) .margin({ left: 8 }) .onClick(() { this.addTodo() }) } .width(90%) .padding({ top: 12, bottom: 12 }) // ── 列表 ── List() { ForEach(this.filteredList, (item: TodoItem) { ListItem() { Row() { // 复选框 Checkbox() .checked(item.isDone) .onChange((val: boolean) { item.isDone val }) // 标题已完成加删除线 Text(item.title) .fontSize(16) .decoration({ type: item.isDone ? TextDecorationType.LineThrough : TextDecorationType.None }) .fontColor(item.isDone ? #999999 : #000000) .margin({ left: 8 }) // 删除按钮 Button() { Text(✕).fontSize(14).fontColor(#ff4444) } .width(32) .height(32) .backgroundColor(transparent) .position({ right: 0 }) .onClick(() { this.deleteTodo(item.id) }) } .width(100%) .padding({ left: 16, right: 16, top: 8, bottom: 8 }) } .width(100%) }, (item: TodoItem) item.id.toString()) } .width(100%) .layoutWeight(1) // 撑满剩余空间 .divider({ strokeWidth: 1, color: #eeeeee }) } .width(100%) .height(100%) .backgroundColor(#f5f5f5)}// — 方法 —addTodo() {const text this.inputValue.trim()if (text ‘’) {return // 空输入不处理}this.todoList.push(new TodoItem(text))this.inputValue ‘’ // 清空输入框}deleteTodo(id: number) {const index this.todoList.findIndex(item item.id id)if (index ! -1) {this.todoList.splice(index, 1)}}}4.3 代码要点解释代码 作用State 标记响应式变量值变化后自动重绘 UIForEach 遍历数组渲染列表第三个参数指定唯一 key.onChange() 输入框内容变化时回调.layoutWeight(1) 按权重分配剩余空间类似 flex:1TextDecorationType.LineThrough 完成事项加删除线filteredList 计算属性 每次 searchKeyword 或 todoList 变化时自动重算4.4 修改模块配置编辑 entry/src/main/module.json5确保配置正确json5{module: {name: ‘entry’,type: ‘entry’,srcEntrance: ‘./ets/entryability/EntryAbility.ets’,abilities: [{name: ‘EntryAbility’,srcEntrance: ‘./ets/entryability/EntryAbility.ets’,description: ‘string:abilitydesc′,icon:′string:ability_desc, icon: string:abilityd​esc′,icon:′media:icon’,label: ‘string:abilityname′,startWindowIcon:′string:ability_name, startWindowIcon: string:abilityn​ame′,startWindowIcon:′media:icon’,startWindowBackground: ‘$color:start_window_background’,exported: true}]}}五、运行与调试5.1 使用模拟器DevEco Studio 工具栏点击 Device Manager → Local Emulator选择一个手机镜像API 12启动模拟器后点击 Run ▶ 按钮。5.2 使用真机手机开启 开发者模式设置 → 关于手机 → 连续点击版本号 7 次开启 USB 调试连接电脑在弹出的授权对话框点击 允许确保手机登录的华为账号与 DevEco Studio 中配置的开发者账号一致点击 Run ▶选择真机设备。常见问题如果提示 “Signing error”去 Build → Generate Key and CSR 生成签名证书或使用自动签名。六、功能扩展添加上一篇文章的知识既然我们刚刚聊过 HarmonyOS 5 的 AI 特性不妨在 Todo 应用里加入一个小艺智能推荐按钮——演示如何调用系统 AI 能力。typescript// 在 Index.ets 的输入区域下方添加Button(‘✧ 智能建议’).height(40).width(‘90%’).fontSize(14).backgroundColor(‘#007dff’).fontColor(‘#ffffff’).onClick(() {// 调用系统 AI 建议能力示意代码this.inputValue 给妈妈打电话 - ’ new Date().toLocaleDateString()})实际开发中可通过 kit.AI 的意图识别 API 实现真正的智能推荐。七、总结通过这篇教程你亲手完成了阶段 成果✅ 环境搭建 DevEco Studio SDK 开发者账号✅ 项目创建 Stage 模型 ArkTS 模板✅ 语法入门 装饰器 声明式 UI 状态管理✅ 完整应用 添加/删除/搜索/标记完成的 Todo App✅ 运行调试 模拟器或真机验证下一步可以试试用 StorageLink 实现数据持久化本地存储接入 HarmonyOS 云开发 实现多端同步用 ohos.multimedia.media 给事项加上语音提醒打包成 HAP上传到 AppGallery 测试分发。一句话总结鸿蒙开发体验ArkTS 的声明式 UI 比 XML 布局更直观比手写 DOM 更高效 —— 如果你有过 React 或 SwiftUI 经验几乎可以无缝上手。纯血鸿蒙的世界里没有历史包袱每一个应用都是从头设计的。