鸿蒙开发常用API速查表：20个高频使用API整理，开发时Ctrl+F直接用

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

导航链接：

• 系列文章导航

• 官方API参考文档

前言

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

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

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

目录

• 一、文件操作（4个）

• 二、网络请求（3个）

• 三、数据存储（4个）

• 四、权限管理（3个）

• 五、设备信息（3个）

• 六、UI相关（3个）

一、文件操作（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; } }

注意事项：

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

• 复杂场景建议使用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; }

注意事项：

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

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

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个选项

速查表总结

结语

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

使用建议：

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

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

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

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

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

系列文章推荐

• 第1篇：鸿蒙NEXT开发环境搭建

• 第5篇：ArkUI组件开发实战

• 第10篇：Stage模型详解

• 第15篇：网络请求封装

• 第20篇：性能优化实战

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

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