企业官网建设流程全解析

1. 先搞清楚HarmonyOS里"页面"到底是个什么东西

很多从Android或者前端转过来做HarmonyOS开发的朋友，第一次在DevEco Studio里新建工程，看到那一坨Index.ets和entry/src/main/resources/base/profile/main_pages.json的时候，大概率都会愣一下。页面在哪？布局文件在哪？怎么不像Android那样有个XML，也不像iOS那样有个Storyboard？

我最初也经历过这个困惑期。当时我的第一反应是去翻MainAbility相关的代码，结果更懵了——里面代码量极少，启动逻辑无非就是调了一下windowStage.loadContent('pages/Index')就结束了。页面构建这件事，在这套体系里的组织方式跟过去完全不是一回事。

先给结论：在HarmonyOS的Stage模型下，一个页面本质上就是一个被@Entry装饰的组件。它挂在UIAbility（可以理解成应用的"进程壳"）下面，通过loadContent加载指定路径的页面文件，而这个路径正是注册在main_pages.json里的。

那main_pages.json里的内容长这样：

{ "src": [ "pages/Index", "pages/Detail" ] }

你把哪些页面文件加入这个数组，它们才可能被路由访问到。我不止一次看到新手把页面文件建好了，也写了Navigation跳转逻辑，结果运行起来一点反应没有，原因就是忘了在这里注册。这类问题通常没有任何报错提示，只有一行冷冰冰的router找不到页面的警告，非常容易劝退新人。

理解了这个结构之后，HarmonyOS页面构建的思路就打开了：页面不是画出来的，是"声明"出来的。哪怕你的应用有一百个页面，核心工作也只有三块——写好组件树、管好状态、设计好路由。这三块也是整篇文章接下来要展开的主线。

2. 为什么HarmonyOS坚持让你用声明式语法来搭页面

如果说前面说的是页面的"外在框架"，那这一节聊的是页面构建最核心的语法范式——ArkTS + ArkUI的声明式编程。

HarmonyOS官方推荐的开发语言是ArkTS，它是TypeScript的超集，但加了很多条条框框，目的就是为了更安全地支持UI声明式开发。记得我刚上手的时候写过一行：

let data: any = 'hello';

编译直接报警告。项目配了arkts-identifiers之类的严格检查之后，any基本是禁用的，你得老老实实把类型写死。说实话一开始觉得很烦，但写多了之后我发现这反而是个好事，尤其在页面组件之间传值的时候，类型明确能挡掉一大半低级Bug。

ArkUI声明式开发的核心组成，其实就三样东西：组件、属性、事件。

• 组件就是UI元素，比如Text、Button、Image；
• 属性是修饰UI的配置项，比如宽高、颜色、字体大小；
• 事件就是用户的交互回调，点击、滑动、输入等等。

一个最简单的自定义页面长这样：

@Entry @Component struct Index { @State message: string = 'Hello HarmonyOS'; build() { Column() { Text(this.message) .fontSize(50) .fontWeight(FontWeight.Bold) Button('点击我') .onClick(() => { this.message = '你点击了按钮'; }) } .width('100%') .height('100%') } }

这段代码只要跑起来，你立刻就能感受这套体系的特点：没有布局文件，UI就是代码，代码就是UI。@Entry表示它是页面级入口组件，@Component表示它是个自定义组件，build()方法里描述UI结构。

build()里有几个硬性约束需要特别注意。第一，只能有一个根节点，你写两个根组件直接报编译错误；第二，不能在build()里写if...else之外的其他复杂逻辑，比如循环for是可以的，但不建议在build()里直接声明临时变量做复杂运算。这些限制一开始看觉得束手束脚，但换个角度理解：这就像装修房子，开发商把承重墙的位置定死了，你在里面怎么摆家具随便，但别乱拆墙。官方用这些约束换来了UI渲染的高效和稳定。

这套写法和传统的命令式编程（比如Android的findViewById+ 手动setText）最大的区别在于：你只负责描述"UI应该长什么样、依赖什么数据"，而不需要写"怎么去更新UI"。数据一变，组件自动刷新。这个转变对老手来说一开始有点别扭，但一旦习惯，效率完全不一样。

3. 布局体系选型：用对容器，页面构建等于做完了一半

页面构建最耗时间的地方其实不是写组件，而是布局。HarmonyOS的布局容器五花八门，Column、Row、Stack、Flex、RelativeContainer、GridRow、GridCol……新手最常犯的错，是拿到一个容器就闷头往里堆组件，最后发现自适应效果差，换设备直接乱掉。

我常用的判断逻辑非常简单，分三步：

• 如果整体是上下排列，选Column；
• 如果是左右排列，选Row；
• 如果某个子组件需要悬浮在另一块内容之上，比如角标、关闭按钮、遮罩，选Stack。

以上三个容器覆盖了80%的页面结构需求。剩下那20%是复杂的比例分配和响应式需求，这时候上Flex、GridRow和GridCol。

Flex是弹性布局容器，它的核心价值在于比例分配和换行控制。比如底部一栏要放三个操作按钮，你要左边一个占1份，右边并排两个各占1份，代码这样写：

Flex({ justifyContent: FlexAlign.SpaceBetween }) { Button('操作一') .layoutWeight(1) Button('操作二') .layoutWeight(1) Button('操作三') .layoutWeight(1) } .width('100%') .height(50)

layoutWeight就是ArkUI里的"份数"概念，跟前端Flex里的flex-grow一个意思。你给三个按钮都设成1，它们就等分父容器宽度，不用手算任何像素值。我在做平板适配的时候，这个属性帮了大忙。

再聊一个很容易忽略的点：尺寸单位。ArkUI里的默认单位是vp（virtual pixel，虚拟像素），它跟Android的dp逻辑类似，目的是在不同密度的屏幕上保持一致的视觉尺寸。你写fontSize(16)，实际渲染时系统会自动按屏幕密度换算成物理像素。但是如果你拿到一套设计稿，标注是750px（常见设计稿基准），直接填数值是错的——我记得标准做法是按设计稿除以2来转成vp，具体适配规则可以看官方文档的像素单位说明。这个换算虽然简单，但不注意的话，页面在真机和预览器上看到的呈现效果会差很多。

布局上还有一个重要的点：ArkUI的布局是"测量+约束"的过程。子组件先把自己的尺寸需求告诉父容器，父容器根据自身的布局规则确定子组件的位置。所以你经常看到Row里嵌一个Text，不给宽高也能正常显示，因为Text会按内容自适应。一旦你手动给了固定宽高，反而可能造成文字截断或者拉伸变形。能用自适应就用自适应，固定宽高是最后的手段。

关于布局，我个人的习惯是先用Column/Row把大骨架搭出来，遇到需要悬浮定位的细节再用Stack叠加，最后在整体结构稳定之后统一检查一遍，看看哪些地方用了固定像素，能换成layoutWeight或百分比就坚决换掉。这样一套流程下来，页面在手机和平板上基本不会跑偏。

4. 状态管理不是"锦上添花"，而是页面构建的承重墙

如果只看组件的声明和布局，你写出来的页面就是一张静态图。要让页面真正活起来——用户点一下按钮文字变化、网络请求回来刷新列表、滚动位置带动某个悬浮按钮显隐——靠的都是状态管理。这一节我建议你看得仔细一点，因为状态管理踩坑的人最多。

ArkUI的状态管理核心，是装饰器那一大家族：@State、@Prop、@Link、@Provide、@Consume、@Observed、@ObjectLink。很多新手看到这一堆装饰器头就大了，其实它们的底层逻辑并不复杂，你可以理解成组件之间的数据同步协议。

• @State：组件私有的状态变量。它变化的唯一后果，就是触发依赖它的UI重新渲染。这个最常用，也是所有状态管理的地基。
• @Prop：父组件传给子组件的单向数据。父组件变了，子组件跟着变；子组件内部改了它，不会同步回父组件。
• @Link：子组件和父组件共享一份数据，双向同步。子组件改了，父组件也变，两者保持一致的引用。
• @Provide/@Consume：跨越多层组件共享数据，不需要一层层通过构造函数传参。父组件@Provide，任意层级的子孙组件都能@Consume取到同一个值，类似前端Context。
• @Observed/@ObjectLink：专门用来观察类和数组内部属性变化。@State修饰一个普通对象时，如果只是改对象里的某个子属性，UI常常不刷新，必须配合@Observed和@ObjectLink才能触发深层更新。

我实际开发中遇到最多的坑，就出在@State和对象子属性上。举个例子，你有一个数组@State list: Task[]，往数组里push一条新数据，UI会刷新；但如果是对某个Task对象的某个字段做赋值，比如list[0].title = '新的标题'，这个变化UI感知不到。原理不复杂：@State只能观察第一层属性的变化，对象内部属性不在它的"监视范围"内。

解决方案有两个：第一，不要直接改对象内部字段，而是整体赋值，让list[0]这个引用本身发生变化；第二，把对象类型改成@Observed修饰的类，同时在子组件里用@ObjectLink去接收它。我倾向于在数据模型较复杂时直接用第二种方案，一劳永逸，但要注意取消观察时的内存释放问题。

再来看装饰器的使用场景。一个搜索页面，搜索框和列表是同一个页面里的两个部分，直接用@State就行。如果父页面有一个筛选条件，子组件需要根据筛选条件刷新列表，那就用@Prop单向传入。如果子组件里有个"收藏"按钮，点击后要同时影响父页面的收藏状态和子页面的图标显示，那就上@Link，记住它是双向绑定，不能随意用在不需要反向同步的场景，否则会带来意料之外的联动刷新。

关于状态管理中一个设计原则：谁使用，谁持有。意思是这个状态值只影响哪个组件，就放在离它最近的层级。别动不动就把所有状态都提全局。全局状态一多，排查问题和性能优化都会变得非常痛苦。

还有个小技巧：如果你想在页面里实现输入框的双向绑定，ArkUI提供了一个语法糖$$。我封装自定义输入组件时，经常用@Link配合$$来实现内外数据同步，代码简洁不少，但这个语法只支持特定场景，用之前最好翻一下官方说明。

5. 页面路由：Navigation和Router，选哪个、怎么用

页面构建的最后一块拼图是路由——也就是说，用户怎么从这个页面跳到那个页面，页面栈怎么维护，返回的时候数据怎么带回来。

HarmonyOS提供两套路由方案：Router和Navigation。前者较老，实现简单但能力有限；后者是官方主推的架构，支持更复杂的页面栈管理、跨设备部署能力也更好。

直接给结论：新项目就用Navigation，除非你只是维护一个一两个页面的超级轻量应用，Router足够，否则不要选老方案。为什么？我举一个特别常见的场景：页面A跳到页面B，页面B跳到页面C，用户在页面C直接返回页面A。用Router你得自己管理栈来popUntil，用Navigation的话，你可以用Navigation的mode为Stack时提供的页面栈管理API，清晰很多。

Navigation的基础用法是这样的：

@Entry @Component struct Index { navStack: NavPathStack = new NavPathStack(); build() { Navigation(this.navStack) { Button('跳转到详情页') .onClick(() => { this.navStack.pushPath({ name: 'pages/Detail' }); }) } } }

然后在pages/Detail里，你需要用NavDestination包裹内容，指定这个页面是Navigation路由的目的地：

@Entry @Component struct Detail { build() { NavDestination() { Text('这是详情页') } .title('详情') } }

初始化和跳转之间，需要保持一致的是同一个NavPathStack实例。这个实例负责整条导航链路的页面栈数据，类似一个"导航员"。

页面之间传参也是一个高频需求。Navigation的pushPath支持带参数：

this.navStack.pushPath({ name: 'pages/Detail', param: { id: 123, title: '项目详情' } });

接收端在NavDestination的onReady回调里，通过this.navPathStack.getParamByName('pages/Detail')或者其他方式取参数。这里有个容易被忽略的细节：参数的取值时机尽量放在onReady里，不要放在aboutToAppear里，因为aboutToAppear触发时页面参数可能还没有完全挂载。

返回传参是另一个高频需求场景。页面B要返回页面A，同时告诉A"我这边选了一个值"。一种常见做法是借助NavPathStack的返回监听机制，在页面A里对目标页面的返回事件做处理，或者更简单的方法是用@Provide/@Consume做跨页面共享状态。我个人偏向后者，共享一个"选择结果"状态，页面B修改它，页面A自动感知。这样回到A页面后UI直接刷新，代码线性好读，不需要额外维护回调接口。

最后说生命周期。页面级生命周期和组件级生命周期要分清：页面级的onPageShow、onPageHide是页面显示/隐藏时触发，适合做埋点、数据刷新；组件级的aboutToAppear、aboutToDisappear是组件创建/销毁时触发。举个例子，你在页面A点按钮跳转到页面B，页面A的onPageHide会执行；从B返回A，onPageShow执行。但如果你在页面A内部if条件切换两个组件，被切走的组件走的是aboutToDisappear，跟页面生命周期无关。区分这个，能帮你避免在错误的地方写业务逻辑。

6. 实战：从零构建一个搜索列表页，顺便聊聊性能坑

光说理论容易飘，最后用一个完整的例子把前面的内容串起来。这个例子是HarmonyOS应用里最常见的页面形态：顶部搜索框 + 中间列表 + 点击跳详情。

先看整体结构。页面最外层是Column，从上到下依次是搜索行、列表区域。搜索行是一个Row，里面放一个TextInput和一个"搜索"按钮。列表用List组件，每条数据用一个自定义组件TaskItem渲染。

核心代码骨架如下：

@Entry @Component struct SearchListPage { @State keyword: string = ''; @State taskList: TaskModel[] = []; private scroller: Scroller = new Scroller(); aboutToAppear() { this.taskList = fetchTaskList(); } build() { Column() { Row({ space: 8 }) { TextInput({ placeholder: '输入关键词', text: this.keyword }) .layoutWeight(1) .onChange((value: string) => { this.keyword = value; }) Button('搜索') .onClick(() => { this.taskList = filterTaskList(this.taskList, this.keyword); }) } .width('100%') .padding(12) List({ space: 12, scroller: this.scroller }) { ForEach(this.taskList, (item: TaskModel) => { ListItem() { TaskItem({ task: item }) .onClick(() => { this.navStack.pushPath({ name: 'pages/TaskDetail', param: { id: item.id } }); }) } }, (item: TaskModel) => item.id) } .layoutWeight(1) .width('100%') .scrollBar(BarState.Off) } .width('100%') .height('100%') } }

这段代码信息量很足，仔细拆解一下里面的关键细节。

首先是ForEach的第三个参数——键值生成函数。我写的(item: TaskModel) => item.id就是告诉UI框架："每个列表项的唯一标识是它的id"。这个键值直接影响列表刷新的精细度。如果你用数组下标做键，那么当列表中间插入一条数据时，后面所有项都会被认定为"不同的项"，从而触发重建，性能非常差。用稳定的业务id做键，框架就能精准识别哪些项该复用、哪些该删除，这是列表性能的第一道关卡。

其次是List和Scroller的组合。列表页通常要支持滚动，Scroller实例绑定在List上之后，你可以编程式控制滚动位置，比如点击某个按钮滚到顶部：

this.scroller.scrollToIndex(0);

这个开发场景很常见，比如"回到顶部"悬浮按钮。

再来看TaskItem自定义组件。它的接收参数是TaskModel类型，为了让行的状态变化能精确触发UI刷新，TaskModel应该用@Observed修饰，TaskItem内部用@ObjectLink接收：

@Observed class TaskModel { id: number = 0; title: string = ''; finished: boolean = false; } @Component struct TaskItem { @ObjectLink task: TaskModel; build() { Row() { Checkbox() .select(this.task.finished) .onChange((value: boolean) => { this.task.finished = value; }) Text(this.task.title) .fontSize(16) .margin({ left: 8 }) } .width('100%') .padding(12) .backgroundColor(Color.White) .borderRadius(8) } }

@ObjectLink确保勾选任务时，只有那一个TaskItem内部的UI刷新，其他行不受影响。我在项目里见过把整个taskList通过@Prop传递的写法，结果每次勾选都把整个列表重新渲染一遍，不做任何性能优化的话，列表超过30条就开始掉帧。而用@ObjectLink的方案，实测在几百条的列表上滚动和勾选都保持流畅。

最后说几个实实在在踩过的坑。

第一个坑，List嵌套Scroll的巨大手势冲突。我早期做页面时，外层用了Scroll，里面塞一个List，结果两个可滚动组件互相抢手势，列表经常滑不动。排查半天才回过神来：这俩组件本身都有自己的滚动体系，根本不该嵌套。解决思路是只保留一个滚动容器——推荐用List承担主滚动，内部不要再嵌套Scroll；如果列表里某一项内容特别长，可以单独设置ListItem内部才用Scroll，并且通过.nestedScroll配置滚动嵌套策略。总之没事别嵌套。

第二个坑，键盘弹起遮挡输入框。页面底部如果有输入框，默认情况软键盘弹起会把输入框顶上去一部分，不处理的话输入框很容易被键盘盖住。我当时的处理方案是给那个输入框所在的容器设置.expandSafeArea配合键盘避让的属性和模式，具体参数要按你的页面布局调，建议真机上多试几次，因为模拟器的键盘行为跟真机不完全一致。这是HarmonyOS输入体验里最容易被忽视的细节之一。

第三个坑，页面白屏排查思路。页面构建好之后跑起来一片空白，先别急着怀疑人生——按这个顺序查：main_pages.json注册了没？@Entry加了没？build()里是不是只渲染了一个条件为false的if？再往后，网络回调有没有触发@State更新？这几个环节几乎覆盖了90%的白屏原因。最诡异的情况是只走一半就白屏，这种多半是ForEach生成了空数据，或者某个组件抛了未捕获异常，打开DevEco Studio的Log窗口直接搜Error，通常能定位到具体行号。

第四个坑，图片懒加载。List虽然本身支持按需加载，但Image加载大图时，如果用户快速滑动，会造成图片解码任务堆积，表现为滑动卡顿甚至OOM。我的习惯是给列表里的Image加上.objectFit(ImageFit.Cover)，并且配合缩略图地址加载，真正进入详情页再加载原图。这是后端配合就能解决的问题，开发时顺手就做了，别等线上被用户投诉卡顿再回来补。

把上面这些做完，一个搜索列表页的构建工作就到这儿了。这个页面麻雀虽小，五脏俱全——布局、状态管理、路由、生命周期、性能优化全部覆盖，基本可以当成一个标准模板来套用。

最后分享一点我个人经验。HarmonyOS页面构建的学习曲线确实有点陡——不是说它多难，而是它跟传统移动端开发的设计思路完全不一样。你在Android里处理UI的经验，在这里只有一半能用，剩下的一半是你的心态问题：不要试图用旧习惯硬套新框架。从我的实践看，最快的上手方式是先把一个小页面从头到尾写五遍，每一遍重点看状态管理和路由的代码，这样形成的肌肉记忆比任何教程都管用。等你对@State、@Link、Navigation这些概念有直觉反应的时候，HarmonyOS的页面构建就已经迈过最难的坎了。