HarmonyOS 网络请求实战：Axios 集成与用户列表交互

鸿蒙网络请求实战

在这里插入图片描述

安装三方库 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 中获得智能提示。

/**
 * 用户核心类型
 */
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 Geo {
  lat: string;
  lng: string;
  constructor(lat: string, lng: string) {
    this.lat = lat;
    this.lng = lng;
  }
}

/**
 * 地址类型
 */
class Address {
  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;
  }
}

/**
 * 公司信息类型
 */
class Company {
  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 用法
  async getUser() {
    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. 获取数据的核心方法

async getUser() {
  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. 自定义构建器（删除按钮）

@Builder delBuilder(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 在鸿蒙中的使用，更深入理解了状态管理、列表渲染、手势交互三大核心能力，为构建复杂应用打下坚实基础。

鸿蒙网络请求实战

在这里插入图片描述

安装三方库 axios

📦 三方库信息：名称：@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 中获得智能提示。

/**
 * 用户核心类型
 */
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 Geo {
  lat: string;
  lng: string;
  constructor(lat: string, lng: string) {
    this.lat = lat;
    this.lng = lng;
  }
}

/**
 * 地址类型
 */
class Address {
  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;
  }
}

/**
 * 公司信息类型
 */
class Company {
  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 用法
  async getUser() {
    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. 获取数据的核心方法

async getUser() {
  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. 自定义构建器（删除按钮）

@Builder delBuilder(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 在鸿蒙中的使用，更深入理解了状态管理、列表渲染、手势交互三大核心能力，为构建复杂应用打下坚实基础。

HarmonyOS 网络请求实战：Axios 集成与用户列表交互

鸿蒙网络请求实战

安装三方库 axios

安装步骤

配置网络权限

网络请求测试

创建用户类（TypeScript 类型建模）

测试代码实现

创建用户列表（完整交互版）

页面部分代码解析

一、代码整体功能总结

二、逐部分详细解析

1. 依赖导入部分

2. 组件核心结构

3. 组件属性定义

4. 获取数据的核心方法

5. 自定义构建器（删除按钮）

6. 页面 UI 构建（build 方法）

三、代码运行流程

总结与延伸建议

核心技术栈

工程化建议

HarmonyOS 网络请求实战：Axios 集成与用户列表交互

鸿蒙网络请求实战

安装三方库 axios

安装步骤

配置网络权限

网络请求测试

创建用户类（TypeScript 类型建模）

测试代码实现

创建用户列表（完整交互版）

页面部分代码解析

一、代码整体功能总结

二、逐部分详细解析

1. 依赖导入部分

2. 组件核心结构

3. 组件属性定义

4. 获取数据的核心方法

5. 自定义构建器（删除按钮）

6. 页面 UI 构建（build 方法）

三、代码运行流程

总结与延伸建议

核心技术栈

工程化建议

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具