📖 鸿蒙NEXT开发实战系列 | 第25篇 | 工具篇 🎯 适合人群：所有鸿蒙开发者 ⏰ 阅读时间：约10分钟 | 💻 开发环境：DevEco Studio 5.0+

导航链接：

前言

每次开发都要翻官方文档找API？太慢了！

本文整理了鸿蒙开发中最常用的20个API，按功能分类，附可复制代码片段。建议收藏本文，开发时直接 Ctrl+F 搜索使用，效率直接提升50%！

API版本说明：本文所有API基于 HarmonyOS NEXT (API 9+) ，兼容最新DevEco Studio 5.0+版本。

目录

一、文件操作（4个）

1. fs.readFile - 读取文件内容

功能说明：读取指定路径的文件内容，支持文本和二进制文件。

导入语句：

import { fs } from '@kit.CoreFileKit';

代码示例：

// 读取文本文件
async function readFile(path: string): Promise<string> {
  try {
    const content = await fs.readFile(path, { encoding: 'utf-8' });
    return content;
  } catch (error) {
    console.error(`读取文件失败: ${error}`);
    return '';
  }
}

// 使用示例
const filePath = getContext().filesDir + '/test.txt';
const content = await readFile(filePath);
console.log(`文件内容: ${content}`);

注意事项：

  • 需要在 module.json5 中配置文件读写权限

  • 路径必须使用应用沙箱内的绝对路径

2. fs.writeFile - 写入文件内容

功能说明：将内容写入指定路径的文件，文件不存在则自动创建。

导入语句：

import { fs } from '@kit.CoreFileKit';

代码示例：

// 写入文本文件
async function writeFile(path: string, content: string): Promise<boolean> {
  try {
    await fs.writeFile(path, content, { encoding: 'utf-8' });
    return true;
  } catch (error) {
    console.error(`写入文件失败: ${error}`);
    return false;
  }
}

// 使用示例
const filePath = getContext().filesDir + '/output.txt';
const success = await writeFile(filePath, 'Hello HarmonyOS');

注意事项：

  • 文件已存在时会覆盖原内容

  • 可使用 fs.open + fs.write 进行追加写入

3. fs.stat - 获取文件信息

功能说明：获取文件的大小、创建时间、修改时间等元数据。

导入语句：

import { fs } from '@kit.CoreFileKit';

代码示例：

// 获取文件信息
async function getFileInfo(path: string): Promise<fs.Stat | null> {
  try {
    const stat = await fs.stat(path);
    console.log(`文件大小: ${stat.size} bytes`);
    console.log(`修改时间: ${stat.mtime}`);
    return stat;
  } catch (error) {
    console.error(`获取文件信息失败: ${error}`);
    return null;
  }
}

注意事项：

  • 文件不存在时会抛出异常，需做异常处理

  • stat.size 单位为字节

4. fs.listFile - 列出目录文件

功能说明：列出指定目录下的所有文件和子目录。

导入语句：

import { fs } from '@kit.CoreFileKit';

代码示例：

// 列出目录下所有文件
async function listFiles(dirPath: string): Promise<string[]> {
  try {
    const files = await fs.listFile(dirPath);
    console.log(`目录下有 ${files.length} 个文件`);
    return files;
  } catch (error) {
    console.error(`列出文件失败: ${error}`);
    return [];
  }
}

注意事项：

  • 不包含子目录中的文件（递归需自行实现）

  • 返回的文件名不含路径前缀

二、网络请求（3个）

5. http.createHttp() - HTTP网络请求

功能说明：发送HTTP/HTTPS网络请求，支持GET、POST等方法。

导入语句：

import { http } from '@kit.NetworkKit';

代码示例：

// GET请求示例
async function httpGet(url: string): Promise<string> {
  try {
    const httpRequest = http.createHttp();
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.GET,
      header: {
        'Content-Type': 'application/json'
      },
      readTimeout: 10000,
      connectTimeout: 10000
    });

    httpRequest.destroy();
    return response.result.toString();
  } catch (error) {
    console.error(`请求失败: ${error}`);
    return '';
  }
}

// POST请求示例
async function httpPost(url: string, data: object): Promise<string> {
  try {
    const httpRequest = http.createHttp();
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.POST,
      header: {
        'Content-Type': 'application/json'
      },
      extraData: JSON.stringify(data)
    });

    httpRequest.destroy();
    return response.result.toString();
  } catch (error) {
    console.error(`请求失败: ${error}`);
    return '';
  }
}

注意事项：

  • 使用完后必须调用 httpRequest.destroy() 释放资源

  • 需在 module.json5 中配置网络权限 "ohos.permission.INTERNET"

6. WebSocket长连接

功能说明：建立WebSocket长连接，适用于实时通讯场景。

导入语句：

import { webSocket } from '@kit.NetworkKit';

代码示例：

// WebSocket连接示例
let ws: webSocket.WebSocket;

function connectWebSocket(url: string) {
  ws = webSocket.createWebSocket();

  ws.on('open', () => {
    console.log('WebSocket连接成功');
    ws.send('Hello Server');
  });

  ws.on('message', (err, data) => {
    if (!err) {
      console.log(`收到消息: ${data}`);
    }
  });

  ws.on('close', () => {
    console.log('WebSocket连接关闭');
  });

  ws.on('error', (err) => {
    console.error(`WebSocket错误: ${err}`);
  });

  ws.connect(url);
}

// 发送消息
function sendMessage(msg: string) {
  ws.send(msg);
}

// 关闭连接
function closeWebSocket() {
  ws.close();
}

注意事项：

  • WebSocket对象需手动管理生命周期

  • 断线重连需自行实现

7. fetch - 简化版网络请求

功能说明：提供更简洁的网络请求API，类似浏览器的fetch。

导入语句：

import { fetch } from '@kit.NetworkKit';

代码示例：

// GET请求
async function fetchData(url: string): Promise<any> {
  try {
    const response = await fetch(url, {
      method: 'GET'
    });
    const data = await response.json();
    return data;
  } catch (error) {
    console.error(`请求失败: ${error}`);
    return null;
  }
}

// POST请求
async function postData(url: string, body: object): Promise<any> {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    });
    return await response.json();
  } catch (error) {
    console.error(`请求失败: ${error}`);
    return null;
  }
}

注意事项：

  • fetch API 语法更简洁，适合简单场景

  • 复杂场景建议使用 http.createHttp()

三、数据存储（4个）

8. preferences - 轻量级键值存储

功能说明：存储少量键值对数据，适合配置项、用户设置等。

导入语句：

import { preferences } from '@kit.ArkData';

代码示例：

// 获取首选项实例
async function getPreferences(context: Context): Promise<preferences.Preferences> {
  return await preferences.getPreferences(context, 'settings');
}

// 保存数据
async function saveData(context: Context, key: string, value: string) {
  const prefs = await getPreferences(context);
  await prefs.put(key, value);
  await prefs.flush();
}

// 读取数据
async function getData(context: Context, key: string): Promise<string> {
  const prefs = await getPreferences(context);
  return await prefs.get(key, '') as string;
}

// 删除数据
async function deleteData(context: Context, key: string) {
  const prefs = await getPreferences(context);
  await prefs.delete(key);
  await prefs.flush();
}

注意事项：

  • 数据存储在内存中，需调用 flush() 持久化

  • 适合存储少量数据，大量数据建议使用关系型数据库

9. rdb - 关系型数据库

功能说明：轻量级关系型数据库，支持SQL语法，适合结构化数据存储。

导入语句：

import { relationalStore } from '@kit.ArkData';

代码示例：

// 创建数据库
async function createDatabase(context: Context): Promise<relationalStore.RdbStore> {
  const config: relationalStore.StoreConfig = {
    name: 'mydb.db',
    securityLevel: relationalStore.SecurityLevel.S1
  };
  return await relationalStore.getRdbStore(context, config);
}

// 创建表
async function createTable(rdbStore: relationalStore.RdbStore) {
  await rdbStore.executeSql(
    `CREATE TABLE IF NOT EXISTS user (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      age INTEGER
    )`
  );
}

// 插入数据
async function insertUser(rdbStore: relationalStore.RdbStore, name: string, age: number) {
  const bucket: relationalStore.ValuesBucket = { name, age };
  return await rdbStore.insert('user', bucket);
}

// 查询数据
async function queryUsers(rdbStore: relationalStore.RdbStore): Promise<relationalStore.ResultSet> {
  return await rdbStore.querySql('SELECT * FROM user');
}

注意事项：

  • 表结构需提前设计好

  • 大量数据建议使用索引优化查询

10. distributedKVStore - 分布式数据管理

功能说明：支持多设备间数据同步，适用于分布式场景。

导入语句：

import { distributedKVStore } from '@kit.ArkData';

代码示例：

// 创建分布式KVStore
async function createKVStore(context: Context): Promise<distributedKVStore.SingleKVStore> {
  const kvManager = distributedKVStore.createKVManager({
    bundleName: context.bundleName,
    userInfo: {
      userId: '0',
      userType: distributedKVStore.UserType.SAME_USER_ID
    }
  });

  return await kvManager.getKVStore<distributedKVStore.SingleKVStore>('myStore', {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true
  });
}

// 写入数据
async function putData(kvStore: distributedKVStore.SingleKVStore, key: string, value: string) {
  await kvStore.put(key, value);
}

// 读取数据
async function getData(kvStore: distributedKVStore.SingleKVStore, key: string): Promise<string> {
  return await kvStore.get(key) as string;
}

注意事项：

  • 需要设备登录同一华为账号

  • 需配置分布式权限和组网

11. dataShare - 跨应用数据共享

功能说明：实现跨应用的数据共享，遵循DataAbility规范。

导入语句：

import { dataShare } from '@kit.ArkData';

代码示例：

// 创建DataShareHelper
async function createDataShareHelper(context: Context, uri: string) {
  return await dataShare.createDataShareHelper(context, uri);
}

// 查询数据
async function queryData(helper: dataShare.DataShareHelper, uri: string) {
  const predicates = new dataShare.DataSharePredicates();
  const columns = ['id', 'name'];

  const result = await helper.query(uri, predicates, columns);
  return result;
}

// 插入数据
async function insertData(helper: dataShare.DataShareHelper, uri: string, data: object) {
  const valueBucket = { ...data };
  return await helper.insert(uri, valueBucket);
}

注意事项：

  • 需要提供方先注册DataShareExtension

  • 权限配置是关键

四、权限管理（3个）

12. abilityAccessCtrl - 动态权限申请

功能说明：运行时动态申请用户敏感权限。

导入语句：

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { common } from '@kit.AbilityKit';

代码示例：

// 检查权限
async function checkPermission(context: common.UIAbilityContext, permission: string): Promise<boolean> {
  try {
    const result = await abilityAccessCtrl.createAtManager().checkAccessToken(context.tokenID, permission);
    return result === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
  } catch (error) {
    console.error(`检查权限失败: ${error}`);
    return false;
  }
}

// 申请权限
async function requestPermission(context: common.UIAbilityContext, permissions: string[]): Promise<boolean> {
  try {
    const atManager = abilityAccessCtrl.createAtManager();
    const result = await atManager.requestPermissionsFromUser(context, permissions);

    return result.authResults.every(r => r === 0);
  } catch (error) {
    console.error(`申请权限失败: ${error}`);
    return false;
  }
}

// 使用示例
const hasPermission = await checkPermission(context, 'ohos.permission.CAMERA');
if (!hasPermission) {
  const granted = await requestPermission(context, ['ohos.permission.CAMERA']);
  if (granted) {
    console.log('权限已授予');
  }
}

注意事项：

  • 权限需在 module.json5 中先声明

  • 用户拒绝后需引导用户手动开启

13. bundleManager - 应用信息获取

功能说明：获取应用包名、版本号、签名等信息。

导入语句：

import { bundleManager } from '@kit.AbilityKit';

代码示例：

// 获取当前应用信息
async function getAppInfo(context: Context) {
  try {
    const bundleInfo = await bundleManager.getBundleInfoForSelf(
      bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
    );

    console.log(`应用名: ${bundleInfo.name}`);
    console.log(`版本号: ${bundleInfo.versionName}`);
    console.log(`版本Code: ${bundleInfo.versionCode}`);
    return bundleInfo;
  } catch (error) {
    console.error(`获取应用信息失败: ${error}`);
    return null;
  }
}

// 检查应用是否安装
async function isAppInstalled(bundleName: string): Promise<boolean> {
  try {
    await bundleManager.getBundleInfo(bundleName, {
      bundleFlags: 0
    });
    return true;
  } catch (error) {
    return false;
  }
}

注意事项：

  • getBundleInfoForSelf 只能获取自身应用信息

  • 获取其他应用信息需要权限

14. wantAgent - 启动其他应用

功能说明：创建WantAgent，用于启动其他应用或发送通知。

导入语句：

import { wantAgent, WantAgent } from '@kit.AbilityKit';

代码示例：

// 创建启动应用的WantAgent
async function createWantAgent(context: Context) {
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        bundleName: 'com.example.targetapp',
        abilityName: 'EntryAbility'
      }
    ],
    actionType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };

  return await wantAgent.getWantAgent(context, wantAgentInfo);
}

// 触发WantAgent
async function triggerWantAgent(agent: WantAgent) {
  await wantAgent.trigger(agent, null, (err) => {
    if (err) {
      console.error(`触发失败: ${err}`);
    }
  });
}

注意事项：

  • 需要目标应用已安装

  • BundleName和AbilityName必须正确

五、设备信息（3个）

15. deviceInfo - 获取设备信息

功能说明：获取设备型号、品牌、系统版本等基本信息。

导入语句：

import { deviceInfo } from '@kit.BasicServicesKit';

代码示例：

// 获取设备信息
function getDeviceInfo() {
  const info = {
    brand: deviceInfo.brand,         // 设备品牌
    product: deviceInfo.product,     // 产品名称
    model: deviceInfo.model,         // 设备型号
    hardware: deviceInfo.hardware,   // 硬件平台
    deviceType: deviceInfo.deviceType, // 设备类型
    osFullName: deviceInfo.osFullName  // 系统版本
  };

  console.log(`设备型号: ${info.model}`);
  console.log(`系统版本: ${info.osFullName}`);
  return info;
}

注意事项：

  • 部分字段在不同设备上可能为空

  • 不要用于判断是否为手机/平板，使用 display API

16. display - 屏幕信息获取

功能说明：获取屏幕尺寸、分辨率、DPI等显示信息。

导入语句：

import { display } from '@kit.ArkUI';

代码示例：

// 获取默认屏幕信息
function getDisplayInfo() {
  const defaultDisplay = display.getDefaultDisplaySync();

  const info = {
    width: defaultDisplay.width,       // 屏幕宽度(px)
    height: defaultDisplay.height,     // 屏幕高度(px)
    densityPixels: defaultDisplay.densityPixels, // DPI
    densityDPI: defaultDisplay.densityDPI,       // 每英寸像素数
    orientation: defaultDisplay.orientation       // 屏幕方向
  };

  console.log(`屏幕尺寸: ${info.width} x ${info.height}`);
  console.log(`DPI: ${info.densityPixels}`);
  return info;
}

// 获取所有屏幕
async function getAllDisplays() {
  const displays = await display.getAllDisplays();
  return displays;
}

注意事项：

  • 使用 display.getDefaultDisplaySync() 同步获取

  • 折叠屏设备会有多个屏幕

17. batteryInfo - 电池信息获取

功能说明：获取电池电量、充电状态等信息。

导入语句：

import { batteryInfo } from '@kit.BasicServicesKit';

代码示例：

// 获取电池信息
function getBatteryInfo() {
  const info = {
    batterySOC: batteryInfo.batterySOC,           // 电量百分比
    chargingStatus: batteryInfo.chargingStatus,   // 充电状态
    pluggedType: batteryInfo.pluggedType,         // 充电类型
    batteryTemperature: batteryInfo.batteryTemperature // 电池温度
  };

  console.log(`当前电量: ${info.batterySOC}%`);
  console.log(`充电状态: ${info.chargingStatus === 2 ? '充电中' : '未充电'}`);
  return info;
}

// 监听电池变化
batteryInfo.on('batteryStatusChange', (battery) => {
  console.log(`电量变化: ${battery.batterySOC}%`);
});

注意事项：

  • 需要权限 ohos.permission.BATTERY_INFO

  • 模拟器可能无法获取真实数据

六、UI相关（3个）

18. router - 页面路由跳转

功能说明：实现页面间的跳转和参数传递。

导入语句：

import { router } from '@kit.ArkUI';

代码示例：

// 跳转到新页面
function navigateToPage(url: string, params?: object) {
  router.pushUrl({
    url: url,
    params: params
  }).catch((error) => {
    console.error(`跳转失败: ${error}`);
  });
}

// 获取上一页传递的参数
function getPageParams() {
  const params = router.getParams();
  return params;
}

// 返回上一页
function goBack() {
  router.back();
}

// 替换当前页面
function replacePage(url: string) {
  router.replaceUrl({
    url: url
  });
}

// 使用示例
navigateToPage('pages/DetailPage', { id: 123, name: '测试' });

注意事项：

  • 页面路由栈有深度限制

  • 使用 router.clear() 可清空路由栈

19. window - 窗口管理

功能说明：管理应用窗口，设置全屏、状态栏等。

导入语句：

import { window } from '@kit.ArkUI';

代码示例：

// 获取当前窗口
async function getWindowConfig() {
  const windowInstance = window.getLastWindow(getContext());

  // 设置全屏
  await windowInstance.setWindowLayoutFullScreen(true);

  // 隐藏状态栏
  await (await windowInstance.getWindowStage().getMainWindow()).setWindowSystemBarEnable([]);

  // 设置状态栏颜色
  await windowInstance.setWindowSystemBarProperties({
    statusBarContentColor: '#000000'
  });
}

// 设置窗口大小（仅支持PC/2in1设备）
async function setWindowSize(width: number, height: number) {
  const mainWindow = await window.getLastWindow(getContext());
  await mainWindow.resize(width, height);
}

注意事项：

  • 某些API仅支持特定设备类型

  • 全屏模式需配合沉浸式开发

20. promptAction - 弹窗提示

功能说明：显示Toast、对话框、操作菜单等弹窗。

导入语句：

import { promptAction } from '@kit.ArkUI';

代码示例：

// 显示Toast
function showToast(message: string, duration?: number) {
  promptAction.showToast({
    message: message,
    duration: duration || 2000
  });
}

// 显示对话框
async function showDialog(title: string, message: string): Promise<boolean> {
  const result = await promptAction.showDialog({
    title: title,
    message: message,
    buttons: [
      { text: '取消', color: '#666666' },
      { text: '确定', color: '#007AFF' }
    ]
  });

  return result.index === 1; // 点击确定返回true
}

// 显示操作菜单
async function showActionMenu(title: string, menus: string[]): Promise<number> {
  const result = await promptAction.showActionMenu({
    title: title,
    buttons: menus.map(text => ({ text }))
  });

  return result.index;
}

// 使用示例
showToast('操作成功');

const confirmed = await showDialog('提示', '确认删除？');
if (confirmed) {
  // 执行删除操作
}

注意事项：

  • 弹窗不应过于频繁，影响用户体验

  • ActionMenu最多支持6个选项

速查表总结

分类

API

核心用途

文件操作

fs.readFile

读取文件内容

fs.writeFile

写入文件内容

fs.stat

获取文件信息

fs.listFile

列出目录文件

网络请求

http.createHttp()

HTTP网络请求

WebSocket

长连接通讯

fetch

简化版网络请求

数据存储

preferences

键值对存储

rdb

关系型数据库

distributedKVStore

分布式数据

dataShare

跨应用共享

权限管理

abilityAccessCtrl

动态权限申请

bundleManager

应用信息获取

wantAgent

启动其他应用

设备信息

deviceInfo

设备基本信息

display

屏幕显示信息

batteryInfo

电池信息

UI相关

router

页面路由跳转

window

窗口管理

promptAction

弹窗提示

结语

本文整理了鸿蒙开发中最常用的20个API，涵盖了文件操作、网络请求、数据存储、权限管理、设备信息和UI相关等六大类。

使用建议：

  1. 收藏本文：开发时直接 Ctrl+F 搜索API名称

  2. 复制即用：代码示例可直接复制到项目中使用

  3. 注意权限：大部分API需要在 module.json5 中配置权限

  4. 版本兼容：确保API版本与你的鸿蒙版本匹配

如果对你有帮助，欢迎点赞收藏！

系列文章推荐

标签：鸿蒙API HarmonyOS API速查 开发工具 代码片段 鸿蒙开发 API参考 代码大全

版权说明：本文为原创技术博客，转载请注明出处。 作者：鸿蒙开发博客撰写 更新时间：2026年5月8日

# harmonyos # 华为 # 鸿蒙
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS APP＜＜古今职鉴定＞＞开源教程第3篇：ArkTS 语言基础：TypeScript 的鸿蒙进化

avatar HarmonyOS开发者社区

鸿蒙万能卡片开发实战：手把手实现一个天气服务卡片，支持多尺寸+动态刷新+跨设备

本文介绍了鸿蒙NEXT开发实战系列的第27篇，重点讲解如何开发一个天气服务卡片。主要内容包括：1) 卡片配置流程，通过form_config.json定义卡片属性和刷新规则；2) FormExtensionAbility生命周期管理；3) 多尺寸卡片适配（2×2和2×4）；4) 数据模型与服务实现，包括天气数据获取和存储；5) 卡片UI开发，展示天气信息；6) 定时刷新机制，支持自动和手动刷新；7

avatar HarmonyOS开发者社区

HarmonyOS 6学习：ScrollBar与LazyForEach懒加载性能优化实战

本文深入分析了HarmonyOS应用开发中ScrollBar与LazyForEach结合使用时出现的滚动距离骤变问题。核心原因是懒加载导致的高度不确定性，使得ScrollBar无法准确计算位置。解决方案是使用childrenMainSize接口提前声明分组高度，配合智能高度计算和缓存机制。通过精确计算内容高度、缓存优化和预加载策略，显著提升了滚动准确率（从65%到98%）和帧率（45fps到60f

avatar HarmonyOS开发者社区