做鸿蒙开发这段时间我最大的感触是ArkTS 这套声明式 UI 的乐趣和坑都藏在完整项目里。这次我挑了一个特别经典的练手题材——仿网易新闻客户端没有做复杂的账号体系也没有堆服务端就把“新闻列表页 新闻详情页”这两件事从零走通。结果发现光是这两个页面就把鸿蒙开发里的 List 懒加载、网络请求、JSON 解析、页面路由、Tabs 底部导航、RelativeContainer 和 Flex 布局全部串了一遍。如果你是刚接触鸿蒙、想通过一个完整项目把基础打扎实的开发者这篇文章很适合当作第一块练手砖。这个项目能帮你解决什么问题简单说三个第一搞明白 ArkTS 页面到底怎么组织windowStage.loadContent()和入口 Page 的关系第二搞清楚新闻类 App 最常见的“列表进详情”跳转逻辑包括参数传递和页面生命周期第三实战掌握 List 组件的性能优化思路。当然我也会把我在真机调试时踩过的坑一并写出来基本都是官方文档不会细讲、但开发时绕不过去的细节。1. 项目整体设计与技术选型1.1 为什么选“新闻列表 详情页”这个组合很多新手学鸿蒙习惯跟着官方示例做“按钮点击 文本变化”看完感觉会了一开真实项目还是无从下手。新闻客户端恰恰是介于“Demo”和“商业项目”之间的最佳样本数据是动态的、列表是长列表、图片要异步加载、页面要跳转传参。这些几乎就是日常业务开发的全部核心场景。我刻意没有引入数据库和登录模块是因为这两个东西会稀释对 UI 层和页面交互的关注。做这个项目时我的主线非常明确用真实的请求去拉新闻数据用 List 渲染列表点击进入 WebView 加载详情页。至于服务端我用的是网易公开的资讯接口开发调试用生产环境请换成自己后端数据格式是标准的 JSON。1.2 技术栈选型与 API 版本策略开发工具方面我选的是 DevEco Studio 最新稳定版HarmonyOS SDK API 12 起步部分 API 在 API 9 也能跑但有些组件特性建议直接用新版。语言不用 Java用 ArkTS——这就是鸿蒙原生声明式 UI 的标准姿势。这里先解释两个最容易让新手懵的概念声明式 UI和命令式 UI的区别。传统 Android 开发是“我先 new 一个控件再设置它的属性最后 add 到布局里”每一步都是命令ArkTS 则是“我描述页面长什么样数据变了界面自动更新”。比如我定义一个State newsList只要往这个数组里 push 新数据列表会自动刷新不需要手动去调用list.addChild()。这种开发习惯的转变是鸿蒙入门的第一道坎。布局方面我在列表卡片上用了RelativeContainer相对布局和Flex弹性布局组合。RelativeContainer 适合处理卡片内部“标题左侧、摘要下方、时间左下、来源右侧”这种相对位置关系Flex 则擅长处理一行内多个元素的水平排布。很多初学者喜欢一层层嵌套 Row 和 Column但嵌套层级一旦超过四层性能会明显下降布局代码也极其难维护。用 RelativeContainer 可以大幅减少嵌套深度。1.3 页面结构和路由方案设计整个项目只有两个核心页面新闻列表页入口页和新闻详情页。因为要做底部导航我把列表页包进了 Tabs 容器让“首页”“热点”“视频”“我的”四个标签先搭起 App 的基本框架再把新闻列表填进“首页”这个 Tab。页面跳转我用的是官方主推的Navigation NavPathStack方案而不是老项目常见的router.pushUrl()。原因很简单Navigation 是 HarmonyOS 最新的导航容器支持路由堆栈管理还能和系统返回手势、转场动画天然配合。代码上我只需要在入口页面创建一个NavPathStack通过navStack.pushPathByName(NewsDetail, params)跳转详情页用NavDestination接收参数。这套模式后续做复杂的多级页面会非常从容。提示如果你当前项目用的还是ohos.router也没有问题短期不会被废弃。但新项目我建议直接上手 Navigation避免项目后期迁移成本。2. 工程搭建与开发环境准备2.1 DevEco Studio 工程创建与目录结构打开 DevEco Studio选择 “Create Project”模板我选的是“Empty Ability”。工程名我起的是NewsClient包名用com.example.newsclientCompatible SDK 选 5.0.0(API 12) 以上。创建完成后工程里会生成一个默认的entry模块核心目录结构长这样entry/src/main/ets/entryability/EntryAbility.ets应用入口负责onWindowStageCreate生命周期。entry/src/main/ets/pages/Index.ets默认入口页面。entry/src/main/resources/base/profile/main_pages.json页面路由表。entry/src/main/ets/model/NewsModel.ets我新建的数据模型目录。entry/src/main/ets/service/NewsService.ets我新建的网络请求封装。关于windowStage.loadContent()可能很多人第一次看到时有点懵。它其实就是“把某一个页面加载进窗口”的入口函数系统在onWindowStageCreate回调里把 windowStage 交给你你要告诉它第一个页面是谁。我项目里的核心写法是这样export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent(pages/Index, (err) { if (err.code) { console.error(加载首页失败: ${JSON.stringify(err)}); return; } }); } }如果项目需要用多个模块、多个入口可以配置module.json5里的abilities数组但本项目一个入口就够了。2.2 模拟器配置与真机连线调试模拟器我建议直接用 DevEco Studio 自带的 Local EmulatorAPI 12 镜像。创建模拟器的时候记得把分辨率调成 Phone 常规尺寸。真机调试的好处是能验证网络权限、弱网状态和真实 UI 渲染效果但需要先在手机设置 → 关于手机里反复点击版本号打开“开发者模式”然后把手机插上电脑允许 USB 调试。这里有个常见坑模拟器可能访问外网受限而新闻接口又是 HTTP 明文请求。HarmonyOS 默认禁止 HTTP 明文流量安全策略如果你直接请求http://开头的接口会报一个java.io.IOException: Cleartext HTTP traffic not permitted类似的错误。解决办法有两个开发阶段在module.json5里加networkSecurityConfig或者直接申请ohos.permission.INTERNET权限并配置明文流量开关。我的module.json5里权限配置如下{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ], deviceTypes: [phone] } }如果你要允许明文 HTTP可以在src/main/resources/base/profile/network_config.json里配置cleartextTrafficPermitted: true并在module.json5中引用它。调试阶段建议开启上线前必须切到 HTTPS 并关掉明文。3. 新闻列表页核心实现3.1 数据模型与 JSON 解析新闻列表的数据结构并不复杂但我坚持单独建一个模型类而不是直接用Recordstring, Object到处传递。原因很简单模型类能静态约束字段类型编译器能帮你抓出拼写错误后续维护也轻松。我定义了一个NewsItem类export class NewsItem { id: string ; title: string ; summary: string ; source: string ; imageUrl: string ; publishTime: string ; newsUrl: string ; constructor(obj?: Recordstring, Object) { if (obj) { this.id String(obj[id] ?? ); this.title String(obj[title] ?? ); this.summary String(obj[summary] ?? ); this.source String(obj[source] ?? ); this.imageUrl String(obj[imageUrl] ?? ); this.publishTime String(obj[publishTime] ?? ); this.newsUrl String(obj[newsUrl] ?? ); } } }很多新手喜欢在 JSON 解析时直接JSON.parse(response.result) as NewsItem但 ArkTS 对as转换的检查比较严格而且服务端返回的字段可能有多余或者缺失。我习惯写一个构造函数对每个字段做String()包裹转换这样即使某个字段为空也不会在 UI 层出现undefined崩溃。3.2 网络请求封装与列表刷新策略鸿蒙原生提供的网络能力在ohos.net.http模块我用它封了一个简单的NewsServiceimport http from ohos.net.http; export class NewsService { static async fetchNews(): PromiseNewsItem[] { const httpRequest http.createHttp(); const response await httpRequest.request( https://api.example.com/news, { method: http.RequestMethod.GET, connectTimeout: 10000, readTimeout: 10000, header: { Content-Type: application/json } } ); if (response.responseCode 200) { const result JSON.parse(response.result as string) as Recordstring, Object; const list result[data] as Recordstring, Object[]; return list.map((item) new NewsItem(item)); } throw new Error(请求失败状态码: ${response.responseCode}); } }这里要注意http.createHttp()创建的请求对象要记得在不用时destroy()否则会一直占着连接资源。我是在页面aboutToDisappear生命周期里统一销毁的。列表刷新策略我做了两层初次加载时用State维护一个loading状态展示加载中占位下拉刷新时重新请求数据并替换整个列表上拉加载更多则做分页拼接。由于是仿新闻客户端不需要像资讯流那样复杂的预加载普通的分页即可满足体验。3.3 List 组件布局与 RelativeContainer 实战列表页的核心是ListListItem。List组件是鸿蒙里专门负责滚动列表的容器它自带懒加载机制不会一次性创建所有列表项这也是我选它而不是用ColumnScroll的关键原因。假如你用Scroll包裹Column一次性渲染几百条数据帧率会肉眼可见地往下掉。列表项卡片我用RelativeContainer来布局这是鸿蒙 API 12 比较推荐的写法。它允许子组件之间通过相对约束定位比如“图片右侧对齐、标题相对图片左边缘偏移16vp、摘要相对标题下方偏移8vp”。RelativeContainer() { Image(this.item.imageUrl) .width(110) .height(80) .borderRadius(8) .objectFit(ImageFit.Cover) .id(newsImage) .alignRules({ center: { anchor: __container__, align: VerticalAlign.Center }, right: { anchor: __container__, align: HorizontalAlign.End } }) .margin({ right: 12 }) Text(this.item.title) .fontSize(17) .fontWeight(FontWeight.Medium) .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) .id(newsTitle) .alignRules({ left: { anchor: __container__, align: HorizontalAlign.Start }, top: { anchor: __container__, align: VerticalAlign.Top }, right: { anchor: newsImage, align: HorizontalAlign.Left } }) } .width(100%) .height(98) .padding(12) .backgroundColor(Color.White) .borderRadius(12)alignRules里的锚点需要注意__container__表示父容器newsImage表示另一个子组件的 id。相对约束的好处是不管屏幕宽度怎么变图片始终右侧垂直居中标题始终在图片左侧并自动撑满剩余空间。不需要额外计算margin值界面在平板折叠屏上也能自适应。类似地摘要、来源、时间都可以通过相对锚点挂到相应组件上。3.4 底部导航栏与 Tabs 容器整合新闻列表页在“首页”这个 Tab 下。鸿蒙的底部导航最常用的是TabsTabContent组件。我搭了一个非常标准的四栏结构Tabs({ barPosition: BarPosition.End }) { TabContent() { HomePage() } .tabBar(this.tabBarBuilder(首页, 0)) TabContent() { HotPage() } .tabBar(this.tabBarBuilder(热点, 1)) TabContent() { VideoPage() } .tabBar(this.tabBarBuilder(视频, 2)) TabContent() { MinePage() } .tabBar(this.tabBarBuilder(我的, 3)) } .scrollable(false) .onChange((index: number) { this.currentIndex index; })tabBar的构建器我单独用Builder封装这样能保留 TabBar 的点击反馈和选中状态。要特别提醒的是TabContent的父级必须是Tabs不能自己嵌套在别的容器里否则某些版本会遇到布局不刷新的怪问题。4. 新闻详情页与页面导航4.1 Navigation 路由与参数传递从列表页点击某条新闻跳转到详情页。我用的是Navigation组件方案。首先在入口Index.ets里创建一个NavPathStack代码大致是Provide(navStack) navStack: NavPathStack new NavPathStack(); build() { Navigation(this.navStack) { Tabs({ barPosition: BarPosition.End }) { // 首页、热点、视频、我的 } } }在列表项的onClick事件里this.navStack.pushPathByName(NewsDetailPage, { newsId: this.item.id, title: this.item.title, url: this.item.newsUrl });然后需要在main_pages.json里注册详情页路径{ src: [ pages/Index, pages/NewsDetailPage ] }详情页里用NavDestination接收参数Builder pageMap(name: string, param: Object) { if (name NewsDetailPage) { NewsDetailPage({ newsParam: param as NewsDetailParam }) } }NavDestination内部可以拿到 router 参数但注意它不能直接访问this.navStack需要通过Consume(navStack)注入。我踩过几次坑后发现参数用Recordstring, Object传递比强类型对象更稳因为路由是动态的参数类型只有到达目标页面时才真正确定。4.2 WebView 加载详情内容新闻详情页我没有自己解析正文而是用Web组件直接加载新闻原文 URL。这是新闻类 App 最成熟的方案省掉大量富文本解析工作体验也稳定。Web({ src: this.newsParam.url, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .onPageBegin((event) { this.isLoading true; }) .onPageEnd((event) { this.isLoading false; })这里有两个细节值得注意。第一ohos.web.webview的Web组件默认不允许加载 HTTPS 以外的内容开发阶段如果接口是 HTTP需要设置mixedMode或相关配置否则页面一片白。第二详情页顶部我自定义了一个返回按钮用this.controller.backward()控制 WebView 回退但如果是直接从列表跳进来的第一层页面用户按系统返回键应该直接退出详情页而不是退到空白历史记录。所以我需要监听路由栈深度在深度为 1 时让navStack.pop()。另外分享一个小细节新闻详情页顶部我放了标题和来源正文字体用的是系统字体HarmonyOS Sans行距设成 1.6 倍阅读体验会明显舒服很多。别小看这个细节很多仿新闻的 Demo 做出来一眼假就是排版太挤。4.3 详情页踩坑Web 组件全屏与 SafeArea我在真机上发现两个高频问题。第一个是 WebView 里的视频全屏播放需要额外配置onFullScreenEnter和onFullScreenExit回调处理沉浸式切换否则播放视频时会闪黑屏。第二个是刘海屏和安全区问题。详情页顶部如果有自绘标题栏必须注意expandSafeArea的使用范围不能无脑设置全屏沉浸否则标题栏会顶到挖孔区。我最终方案是标题栏区域手动加上statusBarHeight的 padding用window.getWindowAvoidArea拿真实数据。5. 常见问题与性能优化实录5.1 List 渲染性能为什么实测滑动卡顿我一开始用ForEach渲染列表项数据只有 30 条时很流畅但拉到 200 条后明显掉帧。后来定位到两个原因。第一ForEach的 key 生成不对。如果item.id为空框架会把 index 作为 key一旦数据中间插一条整个列表 diff 就失效了导致大量组件重建。修复方式很简单给每条数据生成唯一 key我用的item.id如果接口没有 id 就自己拼一个ForEach(this.newsList, (item: NewsItem) { ListItem() { NewsCard({ item: item }) } }, (item: NewsItem) item.id)第二不要在列表项里做耗时操作。我一开始在卡片里直接调Image(item.imageUrl)加载图片图片还挺大。后来换成Image组件的objectFit(ImageFit.Cover)并限制图片尺寸。如果图片还是偏大可以考虑用Image的syncLoad属性区别处理或者使用pixelMap做二次采样不过这会增加复杂度本项目没有深入。5.2 下拉刷新与上拉加载的推荐姿势鸿蒙自带PullToRefresh组件吗常见方案是配合Refresh容器使用。我项目里用的是Refresh包住ListonRefreshing回调里重新请求第一页数据。上拉加载我监听List的onReachEnd事件在触底时请求下一页。真实项目里这里要加一个“是否正在加载更多”的开关防止重复请求。Refresh({ refreshing: this.isRefreshing }) { List({ space: 12 }) { ForEach(this.newsList, ...) } .onReachEnd(() { if (!this.isLoadingMore) { this.isLoadingMore true; this.currentPage; this.loadMore(); } }) } .onRefreshing(() { this.currentPage 1; this.loadNews(true); })5.3 真机调试与签名配置避坑用 DevEco Studio 跑真机时新手最容易卡在“自动签名”上。如果没有登录华为账号或者项目 bundle name 和账号不一致编译完成后安装到手机时可能会报signature verification failed。解决办法是打开File → Project Structure → Signing Configs勾选 Automatically generate signature并登录自己的开发者账号。注意调试证书和发布证书是分开的别弄混。另外真机上跑 HTTP 明文接口还有一个隐蔽问题部分 API 版本对明文流量限制得更严格你配置了networkSecurityConfig仍然请求失败。我在 API 12 的机器上遇到过最后是在module.json5的deviceTypes之外额外给targetSdkVersion做了降级调试才定位到是系统安全策略的差异。建议优先使用 HTTPS 接口省去一堆麻烦。5.4 状态管理从 State 到 Provide 的演进项目里我用到了State、Prop、Provide和Consume四种装饰器。列表页内部的数据用State就够不需要全局共享。页面间共享数据用Provide和Consume比如我的navStack。父子组件间如果只做单向数据流用Prop。这里要记住一个原则能用局部状态就别上全局状态越多界面刷新次数越不可控性能越差。我在详情页收到参数后把title单独赋给State用于顶部标题栏展示而不是直接修改Prop。因为Prop不允许在子组件内部随意赋值不然会报警告或直接不生效。6. 后续可以怎么扩展这个项目虽然只写了两个页面但扩展空间很大。如果你想把新闻客户端做得更完整可以考虑加一个本地数据库缓存用ohos.data.relationalStore把新闻列表存下来实现离线阅读也可以把首页的 List 替换成Grid做一个瀑布流的双列资讯流或者加一个搜索页接入TextInput组件做关键词联想。我个人下一个想做的方向是接入鸿蒙的元服务卡片能力把“今日新闻”做成桌面小组件——这是鸿蒙区别于 Android 和 iOS 的一个真实差异点也是很值得投入的方向。从仿网易新闻这个项目里我最想对你说的其实是一句话别急着背 API先动手做一个完整页面。鸿蒙的 API 多到记不完但如果你亲手写过一遍网络请求、列表渲染、页面跳转下一次做任何 App 时核心骨架基本都能迁移过去。踩坑不可怕可怕的是坑都踩完了却没有记录下解决方案。希望这篇实战记录能帮你省掉一些我当初浪费的调试时间。
做鸿蒙开发这段时间我最大的感触是ArkTS 这套声明式 UI 的乐趣和坑都藏在完整项目里。这次我挑了一个特别经典的练手题材——仿网易新闻客户端没有做复杂的账号体系也没有堆服务端就把“新闻列表页 新闻详情页”这两件事从零走通。结果发现光是这两个页面就把鸿蒙开发里的 List 懒加载、网络请求、JSON 解析、页面路由、Tabs 底部导航、RelativeContainer 和 Flex 布局全部串了一遍。如果你是刚接触鸿蒙、想通过一个完整项目把基础打扎实的开发者这篇文章很适合当作第一块练手砖。这个项目能帮你解决什么问题简单说三个第一搞明白 ArkTS 页面到底怎么组织windowStage.loadContent()和入口 Page 的关系第二搞清楚新闻类 App 最常见的“列表进详情”跳转逻辑包括参数传递和页面生命周期第三实战掌握 List 组件的性能优化思路。当然我也会把我在真机调试时踩过的坑一并写出来基本都是官方文档不会细讲、但开发时绕不过去的细节。1. 项目整体设计与技术选型1.1 为什么选“新闻列表 详情页”这个组合很多新手学鸿蒙习惯跟着官方示例做“按钮点击 文本变化”看完感觉会了一开真实项目还是无从下手。新闻客户端恰恰是介于“Demo”和“商业项目”之间的最佳样本数据是动态的、列表是长列表、图片要异步加载、页面要跳转传参。这些几乎就是日常业务开发的全部核心场景。我刻意没有引入数据库和登录模块是因为这两个东西会稀释对 UI 层和页面交互的关注。做这个项目时我的主线非常明确用真实的请求去拉新闻数据用 List 渲染列表点击进入 WebView 加载详情页。至于服务端我用的是网易公开的资讯接口开发调试用生产环境请换成自己后端数据格式是标准的 JSON。1.2 技术栈选型与 API 版本策略开发工具方面我选的是 DevEco Studio 最新稳定版HarmonyOS SDK API 12 起步部分 API 在 API 9 也能跑但有些组件特性建议直接用新版。语言不用 Java用 ArkTS——这就是鸿蒙原生声明式 UI 的标准姿势。这里先解释两个最容易让新手懵的概念声明式 UI和命令式 UI的区别。传统 Android 开发是“我先 new 一个控件再设置它的属性最后 add 到布局里”每一步都是命令ArkTS 则是“我描述页面长什么样数据变了界面自动更新”。比如我定义一个State newsList只要往这个数组里 push 新数据列表会自动刷新不需要手动去调用list.addChild()。这种开发习惯的转变是鸿蒙入门的第一道坎。布局方面我在列表卡片上用了RelativeContainer相对布局和Flex弹性布局组合。RelativeContainer 适合处理卡片内部“标题左侧、摘要下方、时间左下、来源右侧”这种相对位置关系Flex 则擅长处理一行内多个元素的水平排布。很多初学者喜欢一层层嵌套 Row 和 Column但嵌套层级一旦超过四层性能会明显下降布局代码也极其难维护。用 RelativeContainer 可以大幅减少嵌套深度。1.3 页面结构和路由方案设计整个项目只有两个核心页面新闻列表页入口页和新闻详情页。因为要做底部导航我把列表页包进了 Tabs 容器让“首页”“热点”“视频”“我的”四个标签先搭起 App 的基本框架再把新闻列表填进“首页”这个 Tab。页面跳转我用的是官方主推的Navigation NavPathStack方案而不是老项目常见的router.pushUrl()。原因很简单Navigation 是 HarmonyOS 最新的导航容器支持路由堆栈管理还能和系统返回手势、转场动画天然配合。代码上我只需要在入口页面创建一个NavPathStack通过navStack.pushPathByName(NewsDetail, params)跳转详情页用NavDestination接收参数。这套模式后续做复杂的多级页面会非常从容。提示如果你当前项目用的还是ohos.router也没有问题短期不会被废弃。但新项目我建议直接上手 Navigation避免项目后期迁移成本。2. 工程搭建与开发环境准备2.1 DevEco Studio 工程创建与目录结构打开 DevEco Studio选择 “Create Project”模板我选的是“Empty Ability”。工程名我起的是NewsClient包名用com.example.newsclientCompatible SDK 选 5.0.0(API 12) 以上。创建完成后工程里会生成一个默认的entry模块核心目录结构长这样entry/src/main/ets/entryability/EntryAbility.ets应用入口负责onWindowStageCreate生命周期。entry/src/main/ets/pages/Index.ets默认入口页面。entry/src/main/resources/base/profile/main_pages.json页面路由表。entry/src/main/ets/model/NewsModel.ets我新建的数据模型目录。entry/src/main/ets/service/NewsService.ets我新建的网络请求封装。关于windowStage.loadContent()可能很多人第一次看到时有点懵。它其实就是“把某一个页面加载进窗口”的入口函数系统在onWindowStageCreate回调里把 windowStage 交给你你要告诉它第一个页面是谁。我项目里的核心写法是这样export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent(pages/Index, (err) { if (err.code) { console.error(加载首页失败: ${JSON.stringify(err)}); return; } }); } }如果项目需要用多个模块、多个入口可以配置module.json5里的abilities数组但本项目一个入口就够了。2.2 模拟器配置与真机连线调试模拟器我建议直接用 DevEco Studio 自带的 Local EmulatorAPI 12 镜像。创建模拟器的时候记得把分辨率调成 Phone 常规尺寸。真机调试的好处是能验证网络权限、弱网状态和真实 UI 渲染效果但需要先在手机设置 → 关于手机里反复点击版本号打开“开发者模式”然后把手机插上电脑允许 USB 调试。这里有个常见坑模拟器可能访问外网受限而新闻接口又是 HTTP 明文请求。HarmonyOS 默认禁止 HTTP 明文流量安全策略如果你直接请求http://开头的接口会报一个java.io.IOException: Cleartext HTTP traffic not permitted类似的错误。解决办法有两个开发阶段在module.json5里加networkSecurityConfig或者直接申请ohos.permission.INTERNET权限并配置明文流量开关。我的module.json5里权限配置如下{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ], deviceTypes: [phone] } }如果你要允许明文 HTTP可以在src/main/resources/base/profile/network_config.json里配置cleartextTrafficPermitted: true并在module.json5中引用它。调试阶段建议开启上线前必须切到 HTTPS 并关掉明文。3. 新闻列表页核心实现3.1 数据模型与 JSON 解析新闻列表的数据结构并不复杂但我坚持单独建一个模型类而不是直接用Recordstring, Object到处传递。原因很简单模型类能静态约束字段类型编译器能帮你抓出拼写错误后续维护也轻松。我定义了一个NewsItem类export class NewsItem { id: string ; title: string ; summary: string ; source: string ; imageUrl: string ; publishTime: string ; newsUrl: string ; constructor(obj?: Recordstring, Object) { if (obj) { this.id String(obj[id] ?? ); this.title String(obj[title] ?? ); this.summary String(obj[summary] ?? ); this.source String(obj[source] ?? ); this.imageUrl String(obj[imageUrl] ?? ); this.publishTime String(obj[publishTime] ?? ); this.newsUrl String(obj[newsUrl] ?? ); } } }很多新手喜欢在 JSON 解析时直接JSON.parse(response.result) as NewsItem但 ArkTS 对as转换的检查比较严格而且服务端返回的字段可能有多余或者缺失。我习惯写一个构造函数对每个字段做String()包裹转换这样即使某个字段为空也不会在 UI 层出现undefined崩溃。3.2 网络请求封装与列表刷新策略鸿蒙原生提供的网络能力在ohos.net.http模块我用它封了一个简单的NewsServiceimport http from ohos.net.http; export class NewsService { static async fetchNews(): PromiseNewsItem[] { const httpRequest http.createHttp(); const response await httpRequest.request( https://api.example.com/news, { method: http.RequestMethod.GET, connectTimeout: 10000, readTimeout: 10000, header: { Content-Type: application/json } } ); if (response.responseCode 200) { const result JSON.parse(response.result as string) as Recordstring, Object; const list result[data] as Recordstring, Object[]; return list.map((item) new NewsItem(item)); } throw new Error(请求失败状态码: ${response.responseCode}); } }这里要注意http.createHttp()创建的请求对象要记得在不用时destroy()否则会一直占着连接资源。我是在页面aboutToDisappear生命周期里统一销毁的。列表刷新策略我做了两层初次加载时用State维护一个loading状态展示加载中占位下拉刷新时重新请求数据并替换整个列表上拉加载更多则做分页拼接。由于是仿新闻客户端不需要像资讯流那样复杂的预加载普通的分页即可满足体验。3.3 List 组件布局与 RelativeContainer 实战列表页的核心是ListListItem。List组件是鸿蒙里专门负责滚动列表的容器它自带懒加载机制不会一次性创建所有列表项这也是我选它而不是用ColumnScroll的关键原因。假如你用Scroll包裹Column一次性渲染几百条数据帧率会肉眼可见地往下掉。列表项卡片我用RelativeContainer来布局这是鸿蒙 API 12 比较推荐的写法。它允许子组件之间通过相对约束定位比如“图片右侧对齐、标题相对图片左边缘偏移16vp、摘要相对标题下方偏移8vp”。RelativeContainer() { Image(this.item.imageUrl) .width(110) .height(80) .borderRadius(8) .objectFit(ImageFit.Cover) .id(newsImage) .alignRules({ center: { anchor: __container__, align: VerticalAlign.Center }, right: { anchor: __container__, align: HorizontalAlign.End } }) .margin({ right: 12 }) Text(this.item.title) .fontSize(17) .fontWeight(FontWeight.Medium) .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) .id(newsTitle) .alignRules({ left: { anchor: __container__, align: HorizontalAlign.Start }, top: { anchor: __container__, align: VerticalAlign.Top }, right: { anchor: newsImage, align: HorizontalAlign.Left } }) } .width(100%) .height(98) .padding(12) .backgroundColor(Color.White) .borderRadius(12)alignRules里的锚点需要注意__container__表示父容器newsImage表示另一个子组件的 id。相对约束的好处是不管屏幕宽度怎么变图片始终右侧垂直居中标题始终在图片左侧并自动撑满剩余空间。不需要额外计算margin值界面在平板折叠屏上也能自适应。类似地摘要、来源、时间都可以通过相对锚点挂到相应组件上。3.4 底部导航栏与 Tabs 容器整合新闻列表页在“首页”这个 Tab 下。鸿蒙的底部导航最常用的是TabsTabContent组件。我搭了一个非常标准的四栏结构Tabs({ barPosition: BarPosition.End }) { TabContent() { HomePage() } .tabBar(this.tabBarBuilder(首页, 0)) TabContent() { HotPage() } .tabBar(this.tabBarBuilder(热点, 1)) TabContent() { VideoPage() } .tabBar(this.tabBarBuilder(视频, 2)) TabContent() { MinePage() } .tabBar(this.tabBarBuilder(我的, 3)) } .scrollable(false) .onChange((index: number) { this.currentIndex index; })tabBar的构建器我单独用Builder封装这样能保留 TabBar 的点击反馈和选中状态。要特别提醒的是TabContent的父级必须是Tabs不能自己嵌套在别的容器里否则某些版本会遇到布局不刷新的怪问题。4. 新闻详情页与页面导航4.1 Navigation 路由与参数传递从列表页点击某条新闻跳转到详情页。我用的是Navigation组件方案。首先在入口Index.ets里创建一个NavPathStack代码大致是Provide(navStack) navStack: NavPathStack new NavPathStack(); build() { Navigation(this.navStack) { Tabs({ barPosition: BarPosition.End }) { // 首页、热点、视频、我的 } } }在列表项的onClick事件里this.navStack.pushPathByName(NewsDetailPage, { newsId: this.item.id, title: this.item.title, url: this.item.newsUrl });然后需要在main_pages.json里注册详情页路径{ src: [ pages/Index, pages/NewsDetailPage ] }详情页里用NavDestination接收参数Builder pageMap(name: string, param: Object) { if (name NewsDetailPage) { NewsDetailPage({ newsParam: param as NewsDetailParam }) } }NavDestination内部可以拿到 router 参数但注意它不能直接访问this.navStack需要通过Consume(navStack)注入。我踩过几次坑后发现参数用Recordstring, Object传递比强类型对象更稳因为路由是动态的参数类型只有到达目标页面时才真正确定。4.2 WebView 加载详情内容新闻详情页我没有自己解析正文而是用Web组件直接加载新闻原文 URL。这是新闻类 App 最成熟的方案省掉大量富文本解析工作体验也稳定。Web({ src: this.newsParam.url, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .onPageBegin((event) { this.isLoading true; }) .onPageEnd((event) { this.isLoading false; })这里有两个细节值得注意。第一ohos.web.webview的Web组件默认不允许加载 HTTPS 以外的内容开发阶段如果接口是 HTTP需要设置mixedMode或相关配置否则页面一片白。第二详情页顶部我自定义了一个返回按钮用this.controller.backward()控制 WebView 回退但如果是直接从列表跳进来的第一层页面用户按系统返回键应该直接退出详情页而不是退到空白历史记录。所以我需要监听路由栈深度在深度为 1 时让navStack.pop()。另外分享一个小细节新闻详情页顶部我放了标题和来源正文字体用的是系统字体HarmonyOS Sans行距设成 1.6 倍阅读体验会明显舒服很多。别小看这个细节很多仿新闻的 Demo 做出来一眼假就是排版太挤。4.3 详情页踩坑Web 组件全屏与 SafeArea我在真机上发现两个高频问题。第一个是 WebView 里的视频全屏播放需要额外配置onFullScreenEnter和onFullScreenExit回调处理沉浸式切换否则播放视频时会闪黑屏。第二个是刘海屏和安全区问题。详情页顶部如果有自绘标题栏必须注意expandSafeArea的使用范围不能无脑设置全屏沉浸否则标题栏会顶到挖孔区。我最终方案是标题栏区域手动加上statusBarHeight的 padding用window.getWindowAvoidArea拿真实数据。5. 常见问题与性能优化实录5.1 List 渲染性能为什么实测滑动卡顿我一开始用ForEach渲染列表项数据只有 30 条时很流畅但拉到 200 条后明显掉帧。后来定位到两个原因。第一ForEach的 key 生成不对。如果item.id为空框架会把 index 作为 key一旦数据中间插一条整个列表 diff 就失效了导致大量组件重建。修复方式很简单给每条数据生成唯一 key我用的item.id如果接口没有 id 就自己拼一个ForEach(this.newsList, (item: NewsItem) { ListItem() { NewsCard({ item: item }) } }, (item: NewsItem) item.id)第二不要在列表项里做耗时操作。我一开始在卡片里直接调Image(item.imageUrl)加载图片图片还挺大。后来换成Image组件的objectFit(ImageFit.Cover)并限制图片尺寸。如果图片还是偏大可以考虑用Image的syncLoad属性区别处理或者使用pixelMap做二次采样不过这会增加复杂度本项目没有深入。5.2 下拉刷新与上拉加载的推荐姿势鸿蒙自带PullToRefresh组件吗常见方案是配合Refresh容器使用。我项目里用的是Refresh包住ListonRefreshing回调里重新请求第一页数据。上拉加载我监听List的onReachEnd事件在触底时请求下一页。真实项目里这里要加一个“是否正在加载更多”的开关防止重复请求。Refresh({ refreshing: this.isRefreshing }) { List({ space: 12 }) { ForEach(this.newsList, ...) } .onReachEnd(() { if (!this.isLoadingMore) { this.isLoadingMore true; this.currentPage; this.loadMore(); } }) } .onRefreshing(() { this.currentPage 1; this.loadNews(true); })5.3 真机调试与签名配置避坑用 DevEco Studio 跑真机时新手最容易卡在“自动签名”上。如果没有登录华为账号或者项目 bundle name 和账号不一致编译完成后安装到手机时可能会报signature verification failed。解决办法是打开File → Project Structure → Signing Configs勾选 Automatically generate signature并登录自己的开发者账号。注意调试证书和发布证书是分开的别弄混。另外真机上跑 HTTP 明文接口还有一个隐蔽问题部分 API 版本对明文流量限制得更严格你配置了networkSecurityConfig仍然请求失败。我在 API 12 的机器上遇到过最后是在module.json5的deviceTypes之外额外给targetSdkVersion做了降级调试才定位到是系统安全策略的差异。建议优先使用 HTTPS 接口省去一堆麻烦。5.4 状态管理从 State 到 Provide 的演进项目里我用到了State、Prop、Provide和Consume四种装饰器。列表页内部的数据用State就够不需要全局共享。页面间共享数据用Provide和Consume比如我的navStack。父子组件间如果只做单向数据流用Prop。这里要记住一个原则能用局部状态就别上全局状态越多界面刷新次数越不可控性能越差。我在详情页收到参数后把title单独赋给State用于顶部标题栏展示而不是直接修改Prop。因为Prop不允许在子组件内部随意赋值不然会报警告或直接不生效。6. 后续可以怎么扩展这个项目虽然只写了两个页面但扩展空间很大。如果你想把新闻客户端做得更完整可以考虑加一个本地数据库缓存用ohos.data.relationalStore把新闻列表存下来实现离线阅读也可以把首页的 List 替换成Grid做一个瀑布流的双列资讯流或者加一个搜索页接入TextInput组件做关键词联想。我个人下一个想做的方向是接入鸿蒙的元服务卡片能力把“今日新闻”做成桌面小组件——这是鸿蒙区别于 Android 和 iOS 的一个真实差异点也是很值得投入的方向。从仿网易新闻这个项目里我最想对你说的其实是一句话别急着背 API先动手做一个完整页面。鸿蒙的 API 多到记不完但如果你亲手写过一遍网络请求、列表渲染、页面跳转下一次做任何 App 时核心骨架基本都能迁移过去。踩坑不可怕可怕的是坑都踩完了却没有记录下解决方案。希望这篇实战记录能帮你省掉一些我当初浪费的调试时间。
