HarmonyOS 动态任务列表应用开发实战API Version 24 | ArkUI 声明式 UI | ArkTS一、前言随着 HarmonyOS Next 的推进越来越多的开发者关注纯血鸿蒙应用开发。ArkTS 融合了 TypeScript 的类型安全与声明式 UI 的开发效率为移动端开发带来全新体验。本文以一个完整的“动态任务列表”应用为案例从项目结构、页面布局、状态管理到交互逻辑带您掌握 HarmonyOS 应用开发的核心技术。二、应用功能概览本应用是一个功能完整的待办事项管理工具包含以下特性新建任务— 输入标题、可选副标题选择优先级高/中/低任务列表展示— 标题、副标题、优先级彩色标签完成状态切换— 点击任务项切换已完成显示删除线和绿色对勾左滑删除— 向左滑动露出红色删除按钮清除已完成— 一键清除所有已完成任务重置示例— 恢复三个预设示例任务实时统计— 顶部显示任务总数三、项目结构使用 DevEco Studio 创建 Empty Ability 模板项目API 24目录结构如下app6124/ ├── AppScope/app.json5 # 应用级配置 ├── entry/src/main/ │ ├── ets/ │ │ ├── entryability/ # Ability 生命周期 │ │ └── pages/Index.ets # 主页面 │ ├── module.json5 # 模块配置 │ └── resources/base/media/ # 图标资源SVG ├── build-profile.json5 # 项目级构建 └── hvigor/ # Hvigor 构建配置四、核心技术实现4.1 数据模型层通过枚举和自定义类定义任务的数据结构enumPriority{HIGHHIGH,MEDIUMMEDIUM,LOWLOW}classTaskItem{title:string;subtitle:string;priority:Priority;completed:boolean;constructor(title:string,subtitle:string,priority:Priority,completed:boolean){this.titletitle;this.subtitlesubtitle;this.prioritypriority;this.completedcompleted;}}使用enumclass的组合配合State装饰器实现响应式追踪。当任务对象的属性变化时ArkUI 会自动侦测并刷新 UI。4.2 主页面结构页面使用Entry和Component装饰器标记这是 ArkTS 声明式 UI 的核心模式EntryComponentstruct Index{Statetasks:TaskItem[][];StatenewTaskTitle:string;StatenewTaskSubtitle:string;StatenewTaskPriority:PriorityPriority.HIGH;StatepriorityPickerShow:booleanfalse;aboutToAppear():void{this.resetSampleTasks();}// ... 方法}装饰器作用Entry标记为页面入口可作为路由目标Component声明该结构体是 UI 组件State标记为响应式状态修改后自动触发 UI 刷新4.3 顶层布局采用Column纵向布局背景色为浅灰色#F2F2F7模拟分组列表效果build(){Column(){// 1. 标题栏// 2. 新建任务输入区// 3. 操作按钮// 4. 任务列表// 5. 底部提示}.width(100%).height(100%).backgroundColor(#F2F2F7)}4.4 标题栏使用Row水平布局左侧应用名称右侧任务总数中间用Blank()撑满Row(){Text(动态任务列表).fontSize(22).fontWeight(FontWeight.Bold).fontColor(#1C1C1E)Blank()Text(共${this.tasks.length}项).fontSize(14).fontColor(#8E8E93)}.width(100%).padding({left:16,right:16,top:12,bottom:8})Blank组件类似于 Flexbox 的flex-grow: 1自动占据剩余空间实现两端对齐。4.5 新建任务输入区输入区包含三部分标题输入框、副标题输入框、优先级选择器 添加按钮行。TextInput组件通过State双向绑定数据TextInput({placeholder:输入新任务...,text:this.newTaskTitle}).placeholderColor(#C7C7CC).fontSize(16).height(44).padding({left:12}).onChange((value:string){this.newTaskTitlevalue;})优先级选择器设计为弹出式下拉菜单使用Radio单选组件if(this.priorityPickerShow){Column(){ForEach([Priority.HIGH,Priority.MEDIUM,Priority.LOW],(p:Priority){Row(){Radio({value:this.getPriorityText(p),group:priority}).checked(this.newTaskPriorityp).onChange((){this.setPriority(p);})Text(this.getPriorityText(p)).fontSize(15)}.onClick((){this.setPriority(p);})})}// ...样式}这里使用条件渲染if直接写在 UI 描述中控制下拉菜单显示隐藏比visible属性更直观高效。4.6 添加任务逻辑addTask():void{consttitlethis.newTaskTitle.trim();if(!title)return;this.tasks.push(newTaskItem(title,this.newTaskSubtitle.trim(),this.newTaskPriority,false));this.newTaskTitle;this.newTaskSubtitle;this.newTaskPriorityPriority.HIGH;}由于tasks被State装饰push操作自动触发列表重新渲染。ArkTS 对数组的响应式追踪支持push、splice、filter等常见操作。4.7 操作按钮区两个按钮并排分别使用红色和绿色背景内部包含图标 文字Button(){Row(){Image($r(app.media.ic_checkmark)).width(16).height(16).fillColor(#FFFFFF)Text(清除已完成).fontSize(14).fontColor(#FFFFFF).margin({left:4})}}.height(36).backgroundColor(#FF3B30).borderRadius(18).padding({left:14,right:14}).onClick((){this.clearCompleted();})使用带子组件的 Button——Button()不传 label内部用RowImageText自定义内容。这与Button(文字)的单标签模式是两种不同用法。4.8 任务列表使用ListListItemForEach组合List({space:0}){ForEach(this.tasks,(task:TaskItem,index:number){ListItem(){// 任务卡片 UI}.onClick((){this.toggleTaskCompletion(index);}).swipeAction({end:():voidthis.deleteSwipeAction(index)})})}.width(100%).layoutWeight(1).divider({strokeWidth:0.5px,color:#E5E5EA,startMargin:52,endMargin:0})ForEach— 遍历数组增量更新 DOMswipeAction— 左滑操作使用Builder构建面板divider— 列表分隔线支持缩进控制.layoutWeight(1)— 占满剩余空间4.9 左滑删除swipeAction的end属性接收构建函数。ArkTS 不支持Function.bind使用lambda 闭包传参BuilderdeleteSwipeAction(index:number){Button(){Image($r(app.media.ic_delete)).width(24).height(24).fillColor(#FFFFFF)}.width(68).height(100%).backgroundColor(#FF3B30).borderRadius(0).onClick((){this.deleteTask(index);})}Builder装饰器可以将一段 UI 描述封装为可复用构建函数内可直接编写声明式 UI 代码。4.10 条件样式渲染根据完成状态动态切换样式Image(task.completed?$r(app.media.ic_checkmark_circle):$r(app.media.ic_circle)).fillColor(task.completed?#34C759:#C7C7CC)Text(task.title).fontColor(task.completed?#8E8E93:#1C1C1E).decoration({type:task.completed?TextDecorationType.LineThrough:TextDecorationType.None})使用三元运算符动态控制样式属性无需分支代码非常简洁。4.11 核心方法toggleTaskCompletion(index:number):void{if(index0indexthis.tasks.length){this.tasks[index].completed!this.tasks[index].completed;}}deleteTask(index:number):void{if(index0indexthis.tasks.length){this.tasks.splice(index,1);}}clearCompleted():void{this.tasksthis.tasks.filter(task!task.completed);}resetSampleTasks():void{this.tasks[newTaskItem(学习 State 装饰器,掌握声明式响应式数据绑定,Priority.HIGH,true),newTaskItem(探索 Grid 布局,了解网格布局的参数配置,Priority.LOW,false),newTaskItem(完成第一篇笔记,将学到的知识整理成文档,Priority.MEDIUM,false),];}修改State数组后UI 自动响应式更新。五、资源文件管理在resources/base/media/下存放 6 个 SVG 图标文件用途ic_arrow_down.svg优先级下拉箭头ic_checkmark.svg对勾图标ic_checkmark_circle.svg实心圆圈对勾已完成ic_circle.svg空心圆圈未完成ic_refresh.svg刷新图标ic_delete.svg删除图标SVG 图标的优势是可通过.fillColor()动态修改颜色无需为每种颜色准备独立图片。六、构建与部署6.1 构建终端执行hvigorw assembleHap流程PreBuild → CreateModuleInfo → MergeProfile → ProcessResource →CompileArkTS→ PackageHap → SignHap → 完成。6.2 常见问题问题 1Button 标签冲突Error: The Button component with a label parameter can not have any child.要么用Button(文字)不带花括号要么用Button() { Text(文字) }二者选一。问题 2Function.bind 不支持Error: Function.bind is not supported (arkts-no-func-bind)ArkTS 禁用了bind改用 lambda() this.myMethod(arg)。问题 3属性命名冲突Warning: ... cannot have name as activeCount.某些名称与系统属性冲突换名即可如incompleteCount。问题 4运行时闪退检查module.json5中pages是否指向正确的$profile:main_pages以及main_pages.json的页面路径是否匹配。七、ArkTS 开发最佳实践7.1 声明式 UI 思维ArkTS 采用声明式范式与传统命令式 UI 本质不同传统命令式ArkTS 声明式手动 findViewById直接编写 UI 描述手动 setText/setColorUI 自动随状态变化复杂的 Diff 刷新细粒度响应式追踪写作 UI 时思考当前状态下 UI 应该什么样而非怎么修改控件。7.2 响应式状态体系装饰器场景State组件内自有状态Prop父→子单向传递Link父子双向同步Provide/Consume跨层级通信Observed/ObjectLink深层对象观测7.3 组件化拆分建议应用功能增长时拆分为子组件Index → TaskHeader TaskInput含 PriorityPicker → TaskActions TaskList含 TaskCard TaskFooter子组件通过Prop/Link通信保持代码清晰可维护。7.4 生命周期钩子时机aboutToAppear组件创建前初始化数据onPageShow页面显示onPageHide页面隐藏aboutToDisappear组件销毁前清理资源八、扩展方向当前应用功能完整还可扩展数据持久化— 使用ohos.data.preferences或ohos.data.relationalStore保存任务任务编辑— 长按弹出对话框修改标题/副标题/优先级搜索筛选— 按关键词搜索、按优先级筛选拖拽排序— 使用ListItem的dragEnabled属性时间提醒— 结合ohos.backgroundTaskManager发送本地通知深色模式— 监听configurationChange切换主题九、总结本文从零构建了一个完整的 HarmonyOS 动态任务列表应用涵盖了ArkTS 基础— 枚举、类、装饰器、泛型ArkUI 核心组件— Column、Row、Text、TextInput、Button、List、Image、Radio、Stack声明式 UI 语法— 条件渲染、循环渲染、Builder响应式状态— State 与数组响应式追踪事件处理— onClick、onChange、swipeAction资源管理— SVG 图标引用与动态着色构建部署— Hvigor 流程与问题排查通过这个项目您已掌握 HarmonyOS 应用开发的核心流程。声明式 UI 需要一些时间适应但上手后会发现代码更简洁、维护成本更低。项目完整代码位于entry/src/main/ets/pages/Index.etsSVG 图标位于resources/base/media/。使用 DevEco Studio 打开即可运行体验。本文发布于 HarmonyOS Next API 24所有代码均已通过hvigorw assembleHap构建验证零错误零警告。
【共创季稿事节】HarmonyOS动态任务列表开发实战
HarmonyOS 动态任务列表应用开发实战API Version 24 | ArkUI 声明式 UI | ArkTS一、前言随着 HarmonyOS Next 的推进越来越多的开发者关注纯血鸿蒙应用开发。ArkTS 融合了 TypeScript 的类型安全与声明式 UI 的开发效率为移动端开发带来全新体验。本文以一个完整的“动态任务列表”应用为案例从项目结构、页面布局、状态管理到交互逻辑带您掌握 HarmonyOS 应用开发的核心技术。二、应用功能概览本应用是一个功能完整的待办事项管理工具包含以下特性新建任务— 输入标题、可选副标题选择优先级高/中/低任务列表展示— 标题、副标题、优先级彩色标签完成状态切换— 点击任务项切换已完成显示删除线和绿色对勾左滑删除— 向左滑动露出红色删除按钮清除已完成— 一键清除所有已完成任务重置示例— 恢复三个预设示例任务实时统计— 顶部显示任务总数三、项目结构使用 DevEco Studio 创建 Empty Ability 模板项目API 24目录结构如下app6124/ ├── AppScope/app.json5 # 应用级配置 ├── entry/src/main/ │ ├── ets/ │ │ ├── entryability/ # Ability 生命周期 │ │ └── pages/Index.ets # 主页面 │ ├── module.json5 # 模块配置 │ └── resources/base/media/ # 图标资源SVG ├── build-profile.json5 # 项目级构建 └── hvigor/ # Hvigor 构建配置四、核心技术实现4.1 数据模型层通过枚举和自定义类定义任务的数据结构enumPriority{HIGHHIGH,MEDIUMMEDIUM,LOWLOW}classTaskItem{title:string;subtitle:string;priority:Priority;completed:boolean;constructor(title:string,subtitle:string,priority:Priority,completed:boolean){this.titletitle;this.subtitlesubtitle;this.prioritypriority;this.completedcompleted;}}使用enumclass的组合配合State装饰器实现响应式追踪。当任务对象的属性变化时ArkUI 会自动侦测并刷新 UI。4.2 主页面结构页面使用Entry和Component装饰器标记这是 ArkTS 声明式 UI 的核心模式EntryComponentstruct Index{Statetasks:TaskItem[][];StatenewTaskTitle:string;StatenewTaskSubtitle:string;StatenewTaskPriority:PriorityPriority.HIGH;StatepriorityPickerShow:booleanfalse;aboutToAppear():void{this.resetSampleTasks();}// ... 方法}装饰器作用Entry标记为页面入口可作为路由目标Component声明该结构体是 UI 组件State标记为响应式状态修改后自动触发 UI 刷新4.3 顶层布局采用Column纵向布局背景色为浅灰色#F2F2F7模拟分组列表效果build(){Column(){// 1. 标题栏// 2. 新建任务输入区// 3. 操作按钮// 4. 任务列表// 5. 底部提示}.width(100%).height(100%).backgroundColor(#F2F2F7)}4.4 标题栏使用Row水平布局左侧应用名称右侧任务总数中间用Blank()撑满Row(){Text(动态任务列表).fontSize(22).fontWeight(FontWeight.Bold).fontColor(#1C1C1E)Blank()Text(共${this.tasks.length}项).fontSize(14).fontColor(#8E8E93)}.width(100%).padding({left:16,right:16,top:12,bottom:8})Blank组件类似于 Flexbox 的flex-grow: 1自动占据剩余空间实现两端对齐。4.5 新建任务输入区输入区包含三部分标题输入框、副标题输入框、优先级选择器 添加按钮行。TextInput组件通过State双向绑定数据TextInput({placeholder:输入新任务...,text:this.newTaskTitle}).placeholderColor(#C7C7CC).fontSize(16).height(44).padding({left:12}).onChange((value:string){this.newTaskTitlevalue;})优先级选择器设计为弹出式下拉菜单使用Radio单选组件if(this.priorityPickerShow){Column(){ForEach([Priority.HIGH,Priority.MEDIUM,Priority.LOW],(p:Priority){Row(){Radio({value:this.getPriorityText(p),group:priority}).checked(this.newTaskPriorityp).onChange((){this.setPriority(p);})Text(this.getPriorityText(p)).fontSize(15)}.onClick((){this.setPriority(p);})})}// ...样式}这里使用条件渲染if直接写在 UI 描述中控制下拉菜单显示隐藏比visible属性更直观高效。4.6 添加任务逻辑addTask():void{consttitlethis.newTaskTitle.trim();if(!title)return;this.tasks.push(newTaskItem(title,this.newTaskSubtitle.trim(),this.newTaskPriority,false));this.newTaskTitle;this.newTaskSubtitle;this.newTaskPriorityPriority.HIGH;}由于tasks被State装饰push操作自动触发列表重新渲染。ArkTS 对数组的响应式追踪支持push、splice、filter等常见操作。4.7 操作按钮区两个按钮并排分别使用红色和绿色背景内部包含图标 文字Button(){Row(){Image($r(app.media.ic_checkmark)).width(16).height(16).fillColor(#FFFFFF)Text(清除已完成).fontSize(14).fontColor(#FFFFFF).margin({left:4})}}.height(36).backgroundColor(#FF3B30).borderRadius(18).padding({left:14,right:14}).onClick((){this.clearCompleted();})使用带子组件的 Button——Button()不传 label内部用RowImageText自定义内容。这与Button(文字)的单标签模式是两种不同用法。4.8 任务列表使用ListListItemForEach组合List({space:0}){ForEach(this.tasks,(task:TaskItem,index:number){ListItem(){// 任务卡片 UI}.onClick((){this.toggleTaskCompletion(index);}).swipeAction({end:():voidthis.deleteSwipeAction(index)})})}.width(100%).layoutWeight(1).divider({strokeWidth:0.5px,color:#E5E5EA,startMargin:52,endMargin:0})ForEach— 遍历数组增量更新 DOMswipeAction— 左滑操作使用Builder构建面板divider— 列表分隔线支持缩进控制.layoutWeight(1)— 占满剩余空间4.9 左滑删除swipeAction的end属性接收构建函数。ArkTS 不支持Function.bind使用lambda 闭包传参BuilderdeleteSwipeAction(index:number){Button(){Image($r(app.media.ic_delete)).width(24).height(24).fillColor(#FFFFFF)}.width(68).height(100%).backgroundColor(#FF3B30).borderRadius(0).onClick((){this.deleteTask(index);})}Builder装饰器可以将一段 UI 描述封装为可复用构建函数内可直接编写声明式 UI 代码。4.10 条件样式渲染根据完成状态动态切换样式Image(task.completed?$r(app.media.ic_checkmark_circle):$r(app.media.ic_circle)).fillColor(task.completed?#34C759:#C7C7CC)Text(task.title).fontColor(task.completed?#8E8E93:#1C1C1E).decoration({type:task.completed?TextDecorationType.LineThrough:TextDecorationType.None})使用三元运算符动态控制样式属性无需分支代码非常简洁。4.11 核心方法toggleTaskCompletion(index:number):void{if(index0indexthis.tasks.length){this.tasks[index].completed!this.tasks[index].completed;}}deleteTask(index:number):void{if(index0indexthis.tasks.length){this.tasks.splice(index,1);}}clearCompleted():void{this.tasksthis.tasks.filter(task!task.completed);}resetSampleTasks():void{this.tasks[newTaskItem(学习 State 装饰器,掌握声明式响应式数据绑定,Priority.HIGH,true),newTaskItem(探索 Grid 布局,了解网格布局的参数配置,Priority.LOW,false),newTaskItem(完成第一篇笔记,将学到的知识整理成文档,Priority.MEDIUM,false),];}修改State数组后UI 自动响应式更新。五、资源文件管理在resources/base/media/下存放 6 个 SVG 图标文件用途ic_arrow_down.svg优先级下拉箭头ic_checkmark.svg对勾图标ic_checkmark_circle.svg实心圆圈对勾已完成ic_circle.svg空心圆圈未完成ic_refresh.svg刷新图标ic_delete.svg删除图标SVG 图标的优势是可通过.fillColor()动态修改颜色无需为每种颜色准备独立图片。六、构建与部署6.1 构建终端执行hvigorw assembleHap流程PreBuild → CreateModuleInfo → MergeProfile → ProcessResource →CompileArkTS→ PackageHap → SignHap → 完成。6.2 常见问题问题 1Button 标签冲突Error: The Button component with a label parameter can not have any child.要么用Button(文字)不带花括号要么用Button() { Text(文字) }二者选一。问题 2Function.bind 不支持Error: Function.bind is not supported (arkts-no-func-bind)ArkTS 禁用了bind改用 lambda() this.myMethod(arg)。问题 3属性命名冲突Warning: ... cannot have name as activeCount.某些名称与系统属性冲突换名即可如incompleteCount。问题 4运行时闪退检查module.json5中pages是否指向正确的$profile:main_pages以及main_pages.json的页面路径是否匹配。七、ArkTS 开发最佳实践7.1 声明式 UI 思维ArkTS 采用声明式范式与传统命令式 UI 本质不同传统命令式ArkTS 声明式手动 findViewById直接编写 UI 描述手动 setText/setColorUI 自动随状态变化复杂的 Diff 刷新细粒度响应式追踪写作 UI 时思考当前状态下 UI 应该什么样而非怎么修改控件。7.2 响应式状态体系装饰器场景State组件内自有状态Prop父→子单向传递Link父子双向同步Provide/Consume跨层级通信Observed/ObjectLink深层对象观测7.3 组件化拆分建议应用功能增长时拆分为子组件Index → TaskHeader TaskInput含 PriorityPicker → TaskActions TaskList含 TaskCard TaskFooter子组件通过Prop/Link通信保持代码清晰可维护。7.4 生命周期钩子时机aboutToAppear组件创建前初始化数据onPageShow页面显示onPageHide页面隐藏aboutToDisappear组件销毁前清理资源八、扩展方向当前应用功能完整还可扩展数据持久化— 使用ohos.data.preferences或ohos.data.relationalStore保存任务任务编辑— 长按弹出对话框修改标题/副标题/优先级搜索筛选— 按关键词搜索、按优先级筛选拖拽排序— 使用ListItem的dragEnabled属性时间提醒— 结合ohos.backgroundTaskManager发送本地通知深色模式— 监听configurationChange切换主题九、总结本文从零构建了一个完整的 HarmonyOS 动态任务列表应用涵盖了ArkTS 基础— 枚举、类、装饰器、泛型ArkUI 核心组件— Column、Row、Text、TextInput、Button、List、Image、Radio、Stack声明式 UI 语法— 条件渲染、循环渲染、Builder响应式状态— State 与数组响应式追踪事件处理— onClick、onChange、swipeAction资源管理— SVG 图标引用与动态着色构建部署— Hvigor 流程与问题排查通过这个项目您已掌握 HarmonyOS 应用开发的核心流程。声明式 UI 需要一些时间适应但上手后会发现代码更简洁、维护成本更低。项目完整代码位于entry/src/main/ets/pages/Index.etsSVG 图标位于resources/base/media/。使用 DevEco Studio 打开即可运行体验。本文发布于 HarmonyOS Next API 24所有代码均已通过hvigorw assembleHap构建验证零错误零警告。
