HarmonyOS应用开发实战（基础篇）Day10 -《鸿蒙网络请求实战》
鸿蒙网络请求实战
安装三方库 axios
在鸿蒙应用开发中，网络请求是连接前端与后端服务的核心能力。虽然系统提供了 @ohos.net.http 原生模块，但其 API 较为底层。为了提升开发效率与代码可维护性，社区广泛采用 @ohos/axios —— 这是专为 OpenHarmony / HarmonyOS 适配的 Axios 版本，兼容熟悉的 Promise 与 async/await 语法，并支持 TypeScript 类型推断。
📦 三方库信息：名称：@ohos/axios版本：V2.2.7（截至 2026 年）仓库地址：@ohos/axios(V2.2.7)安装步骤
- 访问 OHPM（OpenHarmony Package Manager）中心仓，搜索
@ohos/axios； - 点击“安装”按钮，系统将自动生成安装命令；
- 在 DevEco Studio 的 Terminal 中执行该命令。
ohpm install @ohos/axios ✅ 验证安装：
安装成功后，oh-package.json5文件中会新增依赖项，且node_modules/@ohos/axios目录存在。
配置网络权限
鸿蒙应用默认禁止网络访问，必须显式声明权限。在 module.json5 文件的 requestPermissions 字段中添加：
{"module":{"requestPermissions":[{"name":"ohos.permission.INTERNET"}]}}⚠️ 常见问题：
若未配置此权限，axios 请求将直接失败，且错误信息可能不明确（如Network Error）。
网络请求测试
我们使用经典的 JSONPlaceholder 模拟 API 服务，其 /users 接口返回 10 条用户数据，结构清晰，非常适合教学演示。
- 测试接口：
https://jsonplaceholder.typicode.com/users - 返回格式：JSON 数组，每项包含
id,name,email,address,phone,website,company等字段。
官方文档提供了详细的使用说明，包括泛型参数、拦截器、错误处理等高级用法。
创建用户类（TypeScript 类型建模）
为确保类型安全与代码可读性，我们基于接口返回结构，定义完整的 TypeScript 类体系。这不仅能避免运行时错误，还能在 IDE 中获得智能提示。
/** * 用户核心类型 */exportclassUser{ id:number; name:string; username:string; email:string; address: Address; phone:string; website:string; company: Company;constructor(id:number, name:string, username:string, email:string, address: Address, phone:string, website:string, company: Company){this.id = id;this.name = name;this.username = username;this.email = email;this.address = address;this.phone = phone;this.website = website;this.company = company;}}/** * 地理坐标类型 */classGeo{ lat:string; lng:string;constructor(lat:string, lng:string){this.lat = lat;this.lng = lng;}}/** * 地址类型 */classAddress{ street:string; suite:string; city:string; zipcode:string; geo: Geo;constructor(street:string, suite:string, city:string, zipcode:string, geo: Geo){this.street = street;this.suite = suite;this.city = city;this.zipcode = zipcode;this.geo = geo;}}/** * 公司信息类型 */classCompany{ name:string; catchPhrase:string; bs:string;constructor(name:string, catchPhrase:string, bs:string){this.name = name;this.catchPhrase = catchPhrase;this.bs = bs;}}💡 工程建议：
此类文件应存放于src/main/ets/common/目录下，命名为UserModel.ts或UserDemo.ts，便于跨组件复用。
测试代码实现
完成准备工作后，在页面组件中集成 axios 请求逻辑。
import axios,{ AxiosResponse }from'@ohos/axios';import{ User }from'../common/UserDemo'@Entry@Component struct Index { url:string='https://jsonplaceholder.typicode.com/users' users: User[]=[]// 支持 async/await 用法asyncgetUser(){try{const response: AxiosResponse =await axios.get<string, AxiosResponse<User>,null>(this.url);console.log('VON',JSON.stringify(response));}catch(error){console.error('VON',JSON.stringify(error));}}build(){Column(){Button('axios测试').onClick(()=>{this.getUser()})}}}🔍 关键点解析：axios.get<T, R, D>()泛型参数依次为：响应数据类型、完整响应类型、请求体类型；当前写法中，response.data应为User[]，但代码未赋值给users，因此 UI 不会更新；后续我们将完善此逻辑，实现数据驱动视图。
创建用户列表（完整交互版）
在基础请求之上，我们构建一个可交互的用户列表，支持：
- 点击按钮加载数据；
- 列表展示姓名与邮箱；
- 右滑删除本地记录。
最终效果如下动图所示：
页面部分代码解析
一、代码整体功能总结
这段代码实现了一个完整的鸿蒙应用页面，具备以下能力：
- 网络请求：点击「获取数据」按钮，通过
@ohos/axios从jsonplaceholder.typicode.com获取用户列表； - 响应式渲染：将返回的
User[]数据绑定到@State变量，自动驱动List组件更新； - 交互操作：列表项支持右滑显示删除按钮，点击后从本地数组移除对应用户，UI 实时刷新；
- 类型安全：全程使用 TypeScript 类约束数据结构，避免属性访问错误。
二、逐部分详细解析
1. 依赖导入部分
import axios,{ AxiosResponse }from'@ohos/axios';import{ User }from'../common/UserDemo'@ohos/axios：非 Web 标准 axios，而是针对鸿蒙网络栈（如@ohos.net.http）封装的兼容层；AxiosResponse：提供data,status,headers等标准字段的类型定义；User：确保response.data被正确识别为User[]类型，IDE 可智能提示item.name、item.email等属性。
📌 路径说明：../common/UserDemo表示从当前页面目录向上一级，再进入common文件夹。
2. 组件核心结构
@Entry@Component struct Index {// ...}@Entry：标识该组件为应用主页面入口（通常对应main_pages.json中的首页）；@Component：声明此struct为 UI 组件，可被其他组件引用或作为页面根节点；struct Index：ArkTS 中定义组件的标准方式，所有状态与方法均在此结构体内。
3. 组件属性定义
url:string='https://jsonplaceholder.typicode.com/users'@State users: User[]=[]url：常量字符串，存储 API 地址；@State users：@State是 ArkTS 的响应式状态装饰器；- 当
users数组被修改（如push,splice），所有依赖它的 UI 元素（如ForEach）会自动重新渲染； - 初始为空数组，确保页面首次加载时列表为空，避免 undefined 错误。
4. 获取数据的核心方法
asyncgetUser(){try{const response: AxiosResponse =await axios.get<string, AxiosResponse<User>,null>(this.url);this.users = response.data;// 关键：赋值触发 UI 更新console.log('VON',JSON.stringify(this.users));}catch(error){console.error('VON',JSON.stringify(error));}}async/await：简化异步流程，避免.then().catch()嵌套；- 泛型校正：实际应写作
axios.get<User[], AxiosResponse<User[]>>，因为返回的是用户数组而非单个User； - 赋值操作：
this.users = response.data是 UI 更新的关键——没有这一步，列表将始终为空； - 错误处理：捕获网络异常（如 DNS 失败、超时、HTTP 500），防止应用崩溃。
✅ 优化建议：可添加 loading 状态，防止重复点击。
5. 自定义构建器（删除按钮）
@BuilderdelBuilder(index:number){Row(){Button('🚮').onClick(()=>{this.users.splice(index,1);// 修改 @State 数组})}}@Builder：用于封装可复用的 UI 片段，支持传参；index：标识要删除的用户在数组中的位置；splice(index, 1)：原地删除数组元素，由于users是@State，此操作会触发List重绘；- 图标选择：使用 Unicode 表情
🚮（垃圾桶）提升视觉识别度。
6. 页面 UI 构建（build 方法）
build(){Column(){Button('获取数据').onClick(()=>{this.getUser()})List(){ForEach(this.users,(item: User, index:number)=>{ListItem(){Column(){Text('姓名：'+ item.name)Text('邮箱：'+ item.email)}.width('100%').height(40).justifyContent(FlexAlign.Start).alignItems(HorizontalAlign.Start).margin(10)}.swipeAction({ end:this.delBuilder(index)})})}.width('100%').height('100%')}.width('100%').height('100%')}Column：垂直布局容器，容纳按钮与列表；List+ForEach：List是高性能滚动列表组件，仅渲染可视区域项；ForEach(data, itemGenerator, keyGenerator?)遍历users，为每个用户生成ListItem；
ListItem：列表单项，内部用Column展示两行文本；.swipeAction({ end: ... })：end表示从右侧滑入时显示的操作区；- 绑定
delBuilder(index)，实现右滑删除功能； - 鸿蒙系统自动处理手势识别与动画。
三、代码运行流程
- 初始化：
users = []，List无内容； - 点击按钮：调用
getUser()，发起 GET 请求； - 请求成功：
response.data（User[]）赋值给users，触发ForEach重建，列表显示 10 条用户； - 右滑操作：用户向左滑动某一项，右侧出现垃圾桶按钮；
- 点击删除：
splice(index, 1)修改数组，List自动移除该项； - 请求失败：控制台输出错误，UI 保持不变。
总结与延伸建议
核心技术栈
| 技术 | 作用 |
|---|---|
@ohos/axios | 简化 HTTP 请求 |
@State | 实现数据驱动 UI |
List + ForEach | 高性能列表渲染 |
swipeAction | 原生手势交互 |
| TypeScript Class | 类型安全与结构化 |
工程化建议
- 错误边界处理：添加 Toast 提示“网络请求失败”；
- 加载状态：请求期间禁用按钮并显示“加载中…”；
- 分页支持：若数据量大，应分页加载；
- 真实 API 替换：
jsonplaceholder仅为模拟，上线需对接真实后端； - 持久化缓存：可结合
@ohos.data.preferences缓存用户列表，提升体验。
🔒 安全提醒：
生产环境中，切勿在前端硬编码敏感接口地址，应通过配置中心或环境变量管理。
通过本案例，开发者不仅掌握了 axios 在鸿蒙中的使用，更深入理解了状态管理、列表渲染、手势交互三大核心能力，为构建复杂应用打下坚实基础。
