ArkTS Stage 工程入门从目录结构到第一个页面HarmonyOS 应用开发刚入门时最容易卡住的不是语法而是“不知道代码从哪里开始跑”。打开 DevEco Studio 新建的 ArkTS Stage 工程后目录里有app.json5、module.json5、EntryAbility.ets、Index.ets、resources等文件。每个文件看起来都重要但它们分别负责什么页面是怎么被加载出来的修改哪个地方才能让应用显示自己的界面这篇文章站在第一次接触 Stage 模型的读者角度把官方快速入门文档里的主线重新梳理一遍先理解工程结构再看 UIAbility 入口最后写一个能运行的首页。1. 为什么 HarmonyOS 推荐 Stage 模型Stage 模型是 HarmonyOS 当前主推的应用模型。和早期 FA 模型相比Stage 模型更强调“模块化”和“生命周期清晰”应用可以由多个模块组成每个模块里声明自己的 AbilityAbility 再负责窗口、页面和系统交互。对普通开发者来说可以先记住三个结论UIAbility是应用界面入口类似“一个可以被系统启动的界面能力”。WindowStage是窗口舞台首页通常通过它加载。ArkUI 页面是具体界面常见文件是pages/Index.ets。2. 新建工程后先看哪几个文件一个典型 ArkTS Stage 工程会包含下面这些关键文件。entry ├── src │ └── main │ ├── ets │ │ ├── entryability │ │ │ └── EntryAbility.ets │ │ └── pages │ │ └── Index.ets │ ├── module.json5 │ └── resources │ ├── base │ │ ├── element │ │ ├── media │ │ └── profile │ └── rawfile └── build-profile.json5这里不要一上来就改很多地方。建议按“配置 - 入口 - 页面”的顺序理解文件作用初学时重点app.json5应用级配置应用名称、版本、图标等module.json5模块级配置声明 Ability、页面路由、权限EntryAbility.etsUIAbility 入口生命周期、窗口创建、首页加载Index.etsArkUI 首页页面布局、状态、点击事件resources资源目录字符串、颜色、图片、profile 配置3.app.json5应用级配置app.json5通常描述整个应用而不是单个页面。开发时常见的配置包括应用包名、版本、图标、标签等。{ app: { bundleName: com.example.stagequickstart, vendor: example, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name } }代码解释bundleName是应用包名正式项目中要保持唯一。versionCode面向系统和市场用数字表示版本递增。versionName面向用户展示比如1.0.0。icon和label使用资源引用不建议直接写死文件路径或中文。4.module.json5模块和 Ability 的声明入口module.json5是初学者必须认真看的文件因为它决定了系统能不能找到你的 UIAbility。{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet, 2in1 ], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:app_icon, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ] } }代码解释mainElement指定模块主入口一般指向EntryAbility。srcEntry指向 UIAbility 源码文件。exported表示该 Ability 是否可以被外部启动。skills中的 home 能力声明决定应用图标入口能否从桌面启动。startWindowIcon和startWindowBackground用于启动页展示。如果桌面点图标后应用没有正常启动除了看代码报错也要检查这里的mainElement、srcEntry和skills。5.EntryAbility.ets应用界面的真正入口EntryAbility.ets是 Stage 工程里最关键的入口文件。它继承自UIAbility系统启动应用时会回调它的生命周期方法。import{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(DOMAIN,StageQuickStart,EntryAbility onCreate);}onWindowStageCreate(windowStage:window.WindowStage):void{hilog.info(DOMAIN,StageQuickStart,WindowStage create);windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(DOMAIN,StageQuickStart,loadContent failed: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,StageQuickStart,loadContent success);});}onForeground():void{hilog.info(DOMAIN,StageQuickStart,EntryAbility foreground);}onBackground():void{hilog.info(DOMAIN,StageQuickStart,EntryAbility background);}}代码解释onCreate表示 Ability 被创建适合做轻量初始化。onWindowStageCreate表示窗口舞台创建这里通常加载首页。windowStage.loadContent(pages/Index)会加载pages/Index.ets。onForeground和onBackground分别对应前台和后台切换。日志使用hilog调试生命周期时比console.log更适合。6.pages/Index.ets第一个 ArkUI 页面首页文件一般放在entry/src/main/ets/pages/Index.ets。下面写一个简单但完整的页面标题、说明、计数器按钮、状态展示都有。EntryComponentstruct Index{Statecount:number0;build(){Column({space:18}){Text(ArkTS Stage 快速入门).fontSize(28).fontWeight(FontWeight.Bold).fontColor(#182431)Text(这个页面由 EntryAbility 通过 WindowStage 加载。).fontSize(16).fontColor(#5A6B7B).textAlign(TextAlign.Center)Text(当前点击次数${this.count}).fontSize(20).fontColor(#0A7F64)Button(点击一次).width(80%).height(48).fontSize(18).onClick((){this.count;})}.width(100%).height(100%).justifyContent(FlexAlign.Center).padding(24).backgroundColor(#F7FAFC)}}代码解释Entry表示这是一个入口组件。Component表示这是 ArkUI 自定义组件。State修饰的变量变化后会触发界面刷新。build()描述页面结构。Column是纵向布局容器适合做入门页面。7. 初学者要理解的页面加载关系这一点非常关键Index.ets本身不会凭空显示出来它需要被窗口加载。windowStage.loadContent(pages/Index,(err){if(err.code){return;}});这里的pages/Index不写.ets后缀。路径和文件结构必须对应entry/src/main/ets/pages/Index.ets如果你把页面文件改名为Home.ets那么加载路径也要同步改成windowStage.loadContent(pages/Home);8. 加一个更接近真实项目的首页布局真实项目不会只有一个按钮。下面这个首页更接近业务应用上方展示标题中间展示功能卡片底部提供操作入口。EntryComponentstruct Index{privatefeatures:string[][Stage 模型,ArkUI 页面,资源引用,页面跳转];build(){Column({space:20}){this.Header()this.FeatureList()this.Footer()}.width(100%).height(100%).padding(20).backgroundColor(#EEF4F8)}BuilderHeader(){Column({space:8}){Text(HarmonyOS Stage 工程).fontSize(30).fontWeight(FontWeight.Bold)Text(先理解入口再写页面最后扩展业务。).fontSize(16).fontColor(#667788)}.width(100%).alignItems(HorizontalAlign.Start)}BuilderFeatureList(){Column({space:12}){ForEach(this.features,(item:string){Row(){Text(item).fontSize(18).fontWeight(FontWeight.Medium)Blank()Text(查看).fontSize(14).fontColor(#0A7F64)}.width(100%).padding(16).borderRadius(16).backgroundColor(Color.White)},(item:string)item)}.width(100%).layoutWeight(1)}BuilderFooter(){Button(开始学习).width(100%).height(52).fontSize(18)}}代码解释Builder可以把复杂页面拆成多个局部构建函数。ForEach用于渲染列表。Blank()可以把左右内容撑开。layoutWeight(1)可以让中间列表占据剩余空间。页面拆分后更容易维护也更接近真实项目写法。9. 日志怎么看生命周期代码写了hilog.info后可以在 DevEco Studio 的 Log 窗口查看。建议给日志设置统一 tag方便过滤。hilog.info(0x0000,StageQuickStart,WindowStage create);调试时重点看三类日志onCreate是否执行。onWindowStageCreate是否执行。loadContent是否成功。如果onCreate有日志但loadContent失败多半是页面路径写错或页面编译报错。10. 常见问题排查10.1 页面白屏先检查EntryAbility.ets中的路径windowStage.loadContent(pages/Index);再检查文件是否真的存在entry/src/main/ets/pages/Index.ets10.2 桌面图标点不开优先检查module.json5mainElement: EntryAbility以及abilities里的name是否一致。10.3 页面状态不刷新检查变量是否使用了StateStatecount:number0;普通字段变化不会自动触发 UI 刷新。10.4 改了配置但运行没变化可以尝试停止当前运行任务。Clean Project。重新 Build。重新安装到设备或模拟器。11. 这篇文章的学习路线如果你是初学者建议按下面顺序练习新建 ArkTS Stage 工程。找到EntryAbility.ets。在onCreate、onWindowStageCreate里加日志。修改Index.ets页面标题。添加一个State计数器。改造页面布局把页面拆成Header、FeatureList、Footer。运行到模拟器或真机。按照这个顺序练一遍你会真正理解“工程配置、Ability 入口、ArkUI 页面”之间的关系。12. 总结ArkTS Stage 工程入门不应该从背 API 开始而应该先建立运行链路应用配置 app.json5 ↓ 模块配置 module.json5 ↓ UIAbility 入口 EntryAbility.ets ↓ WindowStage 加载页面 ↓ ArkUI 页面 Index.ets只要这条链路清楚后面学习页面路由、资源管理、生命周期、Want 跳转、多 Ability 协作都会容易很多。参考资料华为开发者文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-with-ets-stageHarmonyOS AbilityKit 文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/abilitykit-overview