HarmonyOS 网络请求实战:基于 Axios 的交互实现
本文介绍在 HarmonyOS 应用中集成 @ohos/axios 进行网络请求的方法。内容包括安装依赖、配置网络权限、定义 TypeScript 用户模型、发起 GET 请求获取数据,以及使用 List 和 SwipeAction 实现可删除的用户列表交互。重点展示了 ArkTS 状态管理 (@State) 与 UI 渲染的联动机制。

本文介绍在 HarmonyOS 应用中集成 @ohos/axios 进行网络请求的方法。内容包括安装依赖、配置网络权限、定义 TypeScript 用户模型、发起 GET 请求获取数据,以及使用 List 和 SwipeAction 实现可删除的用户列表交互。重点展示了 ArkTS 状态管理 (@State) 与 UI 渲染的联动机制。

在鸿蒙应用开发中,网络请求是连接前端与后端服务的核心能力。虽然系统提供了 @ohos.net.http 原生模块,但其 API 较为底层。为了提升开发效率与代码可维护性,社区广泛采用 @ohos/axios —— 这是专为 OpenHarmony / HarmonyOS 适配的 Axios 版本,兼容熟悉的 Promise 与 async/await 语法,并支持 TypeScript 类型推断。
📦 三方库信息:名称:
@ohos/axios版本:V2.2.7(截至 2026 年)仓库地址:@ohos/axios(V2.2.7)
@ohos/axios;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/usersid, name, email, address, phone, website, company 等字段。官方文档提供了详细的使用说明,包括泛型参数、拦截器、错误处理等高级用法。
为确保类型安全与代码可读性,我们基于接口返回结构,定义完整的 TypeScript 类体系。这不仅能避免运行时错误,还能在 IDE 中获得智能提示。
/** * 用户核心类型 */
export class User {
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;
}
}
/** * 地理坐标类型 */
class {
: ;
: ;
() {
. = lat;
. = lng;
}
}
{
: ;
: ;
: ;
: ;
: ;
() {
. = street;
. = suite;
. = city;
. = zipcode;
. = geo;
}
}
{
: ;
: ;
: ;
() {
. = name;
. = catchPhrase;
. = 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 用法
async getUser() {
try {
const response: AxiosResponse = await axios.get<string, AxiosResponse<User>, null>(this.url);
console.log(JSON.stringify(response));
} catch (error) {
console.error(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 组件更新;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文件夹。
@Entry
@Component
struct Index {
// ...
}
@Entry:标识该组件为应用主页面入口(通常对应 main_pages.json 中的首页);@Component:声明此 struct 为 UI 组件,可被其他组件引用或作为页面根节点;struct Index:ArkTS 中定义组件的标准方式,所有状态与方法均在此结构体内。url: string = 'https://jsonplaceholder.typicode.com/users';
@State users: User[] = [];
url:常量字符串,存储 API 地址;@State users:
@State 是 ArkTS 的响应式状态装饰器;users 数组被修改(如 push, splice),所有依赖它的 UI 元素(如 ForEach)会自动重新渲染;async getUser() {
try {
const response: AxiosResponse = await axios.get<string, AxiosResponse<User>, null>(this.url);
this.users = response.data; // 关键:赋值触发 UI 更新
console.log(JSON.stringify(this.users));
} catch (error) {
console.error(JSON.stringify(error));
}
}
async/await:简化异步流程,避免 .then().catch() 嵌套;axios.get<User[], AxiosResponse<User[]>>,因为返回的是用户数组而非单个 User;this.users = response.data 是 UI 更新的关键——没有这一步,列表将始终为空;✅ 优化建议:可添加 loading 状态,防止重复点击。
@Builder delBuilder(index: number) {
Row() {
Button('🚮').onClick(() => {
this.users.splice(index, 1); // 修改 @State 数组
});
}
}
@Builder:用于封装可复用的 UI 片段,支持传参;index:标识要删除的用户在数组中的位置;splice(index, 1):原地删除数组元素,由于 users 是 @State,此操作会触发 List 重绘;🚮(垃圾桶)提升视觉识别度。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 自动移除该项;| 技术 | 作用 |
|---|---|
@ohos/axios | 简化 HTTP 请求 |
@State | 实现数据驱动 UI |
List + ForEach | 高性能列表渲染 |
swipeAction | 原生手势交互 |
| TypeScript Class | 类型安全与结构化 |
jsonplaceholder 仅为模拟,上线需对接真实后端;@ohos.data.preferences 缓存用户列表,提升体验。🔒 安全提醒:生产环境中,切勿在前端硬编码敏感接口地址,应通过配置中心或环境变量管理。
通过本案例,开发者不仅掌握了 axios 在鸿蒙中的使用,更深入理解了状态管理、列表渲染、手势交互三大核心能力,为构建复杂应用打下坚实基础。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online
通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online