鸿蒙ArkTS实战：从Stage工程骨架启动待办面板

2501_93573368

86人浏览 · 2026-07-11 18:50:04

2501_93573368 · 2026-07-11 18:50:04 发布

在这里插入图片描述

一、先把“能写页面”变成“能导入的工程”

待办面板的第一篇文章讨论了状态和列表，但页面代码不能脱离工程独立存在。一个 ArkTS 页面要出现在设备上，至少还需要应用级配置、entry 模块、页面清单和入口 Ability 把它们串起来。把这些文件一次性归位，后续做搜索、持久化、组件拆分时就不会反复调整工程基础。

本系列采用一个保持克制的目标：先创建一个单入口、单页面的 Stage 工程。它不是为了展示复杂目录，而是明确四个问题：应用叫什么、模块从哪里启动、页面路由指向哪里、页面所需的文本和图标资源放在哪里。

当前项目的关键目录如下：

harmony-todo-desk/
├── AppScope/
│   ├── app.json5
│   └── resources/base/element/string.json
├── entry/
│   ├── build-profile.json5
│   ├── src/main/module.json5
│   ├── src/main/ets/entryability/EntryAbility.ets
│   ├── src/main/ets/pages/Index.ets
│   └── src/main/resources/base/
├── build-profile.json5
├── hvigorfile.ts
└── oh-package.json5

AppScope 放全应用共享的信息；entry 是可以被安装和启动的入口模块；Index.ets 则只是页面本身。这样区分后，修改应用名不必翻页面代码，修改页面布局也不需要碰启动逻辑。

二、应用配置只表达应用身份，不承载页面逻辑

AppScope/app.json5 的职责是声明应用包名、版本、图标和应用名称。以本项目为例：

{
  "app": {
    "bundleName": "com.huihui.harmonytododesk",
    "vendor": "huihui",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

这里的 label 没有直接写“鸿蒙待办面板”，而是引用 $string:app_name。对应文字放进资源文件，后续做多语言、统一改名或在不同模块中复用时，修改点会更集中。图标同样用资源名引用，避免把文件路径散落在代码中。

初期最容易忽略的是 SDK 版本。根目录和 entry 模块都有构建配置，项目中预填的 6.0.0(20) 只是一个静态起点。真实导入 DevEco Studio 后，必须以本机实际安装的 SDK为准调整兼容版本与编译版本；没有对应 SDK 时，构建失败是正确结果，不能靠修改文章文字掩盖问题。

三、入口 Ability 只做启动，不把业务塞进去

EntryAbility.ets 的核心任务是把窗口内容加载到页面路由：

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        return;
      }
    });
  }
}

loadContent('pages/Index') 与 main_pages.json 中的 pages/Index 对应。它们是两个不同层面的声明：前者决定启动后加载哪一个页面，后者维护模块允许访问的页面列表。页面路径少一个字符就会导致启动阶段找不到内容，因此项目创建后应该先核对这两处，再开始研究页面组件。

不建议把待办数组、筛选算法或网络初始化都写进 Ability。Ability 应保持生命周期和窗口职责；页面层负责交互状态；后续的仓储层再负责数据保存。责任越清楚，后面拆分文章和代码模块就越自然。

四、主页文件先保持可验证的最小闭环

首页 Index.ets 目前实现了一个最小功能闭环：左侧筛选项、右侧搜索框、任务输入框和任务列表。每一次新增、筛选或勾选都会通过页面状态重新计算需要显示的任务。这个范围足够作为工程启动验证，也为后续文章留下了明确演进方向：

先确认 Ability 能加载 Index；
再确认页面能绘制初始三条任务；
然后确认新增和勾选会改变界面；
最后再逐步加入持久化、编辑、分组和测试。

这样安排的重要性在于：出现问题时可以迅速定位层级。如果应用根本无法启动，先检查配置和路由；如果能启动但列表为空，检查页面状态和渲染；如果勾选无效，再检查事件回调。不要一开始就把所有功能一起接入，否则错误信号会混在一起。

五、导入前可以做哪些静态检查

即使还没有可用模拟器，也能先进行不冒充运行结果的检查：

AppScope/app.json5 的应用名、图标资源名和实际资源文件一致；
module.json5 的 mainElement、srcEntry 与 EntryAbility.ets 一致；
main_pages.json 包含 pages/Index；
EntryAbility.ets 的加载路径仍是 pages/Index；
Index.ets 中使用的字符串、颜色和图标没有引用不存在的资源；
工程目录使用英文、数字、连字符或下划线，避免构建工具因项目路径字符不兼容而拒绝执行。

这些检查不能替代编译，但能把很多低级错误提前消掉。当前项目曾在包含中文目录名的父路径下被构建工具拒绝，这也说明“目录能在 Finder 中打开”不等于“构建工具接受该路径”。因此，项目已保留在英文路径 /Users/huihui/Documents/harmony-todo-desk，内容工作区内只保留一个指向它的入口链接。