鸿蒙 Electron 核心 API 速查：从应用生命周期到基础能力调用

鸿蒙 Electron 核心 API 基于原生 Electron API 扩展而来，既保留了开发者熟悉的桌面应用开发接口，又新增了适配鸿蒙全场景的专属能力。对于开发者而言，熟练掌握核心 API 是实现“应用启停管控、窗口灵活操作、基础能力调用”的关键，也是规避“版本兼容问题、能力调用失败”等坑点的基础。本文聚焦开发中最常用的四大类 API（应用生命周期、窗口操作、日志打印、路径处理），以“语法格式+参数解析+实战示例+注意事项”的结构呈现，并附上鸿蒙版本兼容性说明，打造即查即用的实用指南。

一、基础认知：鸿蒙 Electron API 的层级与调用规则

在使用 API 前，需明确其层级划分和调用限制，避免因“调用场景错误”导致功能失效。鸿蒙 Electron 的 API 主要分为三个层级，且存在严格的进程调用限制：

API 层级	核心模块	可调用进程	核心能力
基础层（原生继承）	app、BrowserWindow、path 等	app、BrowserWindow 仅主进程；path 全进程	应用生命周期、窗口操作、基础工具
鸿蒙扩展层	harmony 模块	仅主进程	分布式协同、原子化服务、鸿蒙权限
通信层	ipcMain、ipcRenderer、contextBridge	ipcMain 主进程；ipcRenderer 渲染进程	主/渲染进程数据交互

核心调用规则：鸿蒙扩展层 API（harmony 模块）和应用/窗口核心 API（app、BrowserWindow）仅能在主进程调用。渲染进程若需使用这些能力，必须通过 ipcRenderer 与主进程通信，由主进程代为调用。

API 引入方式：主进程和渲染进程的引入方式一致，通过 import 语句导入对应模块，鸿蒙扩展模块需导入专属的 @hmos/electron 包：

// 主进程引入核心模块
import { app, BrowserWindow, ipcMain, path } from '@hmos/electron';
import { harmony } from '@hmos/electron'; // 鸿蒙扩展模块

// 渲染进程引入通信模块（仅能使用ipcRenderer）
import { ipcRenderer } from '@hmos/electron';

二、应用生命周期 API：掌控应用的“生老病死”

应用生命周期 API 主要通过 app 模块实现，负责管控应用的启动、就绪、激活、退出等关键环节，是实现应用基础流程的核心。每个生命周期事件对应固定的触发时机，开发者可在对应事件中执行初始化、资源释放等操作。

2.1 核心 API 速查表

API 语法	触发时机	核心用途	调用场景
app.whenReady()	应用完成初始化并准备就绪	获取应用就绪状态的 Promise 对象	初始化主窗口、加载鸿蒙能力
app.on('ready', callback)	同 whenReady()，回调形式	监听应用就绪事件	兼容旧版代码，初始化操作
app.on('activate', callback)	应用从后台激活（如点击图标）	恢复窗口或重新创建窗口	macOS 下窗口关闭后重新激活应用
app.on('window-all-closed', callback)	所有应用窗口都关闭后	决定是否退出应用	控制不同系统的退出逻辑
app.quit()	主动调用时	关闭所有窗口并退出应用	点击“退出”菜单时触发
app.exit(code)	主动调用时	强制退出应用，code 为退出码	发生严重错误时强制退出
app.getVersion()	主动调用时	获取应用版本号（package.json 中定义）	关于页面展示版本信息
app.getName()	主动调用时	获取应用名称（package.json 中定义）	窗口标题、关于页面展示

2.2 实战：完整生命周期流程实现

以下代码实现了应用从启动到退出的完整生命周期管控，包含鸿蒙分布式能力初始化、跨系统退出逻辑适配等关键操作，可直接作为主进程入口文件的基础模板：

import { app, BrowserWindow } from '@hmos/electron';
import { initHarmonyDistributed } from './harmonyApi'; // 鸿蒙能力初始化函数
import path from 'path';

let mainWindow: BrowserWindow | null = null;

// 应用就绪时初始化窗口和鸿蒙能力
app.whenReady().then(async () => {
  try {
    // 初始化鸿蒙分布式能力（主进程专用）
    await initHarmonyDistributed();
    console.log('鸿蒙分布式能力初始化完成');

    // 创建主窗口
    mainWindow = new BrowserWindow({
      width: 1200,
      height: 800,
      webPreferences: {
        preload: path.join(__dirname, '../common/preload.js'),
        contextIsolation: true,
        nodeIntegration: false
      }
    });

    // 加载渲染进程
    if (process.env.NODE_ENV === 'development') {
      mainWindow.loadURL('http://localhost:3000');
      mainWindow.webContents.openDevTools(); // 开发模式下开启调试工具
    } else {
      mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
    }

    // 窗口关闭时释放实例
    mainWindow.on('closed', () => {
      mainWindow = null;
    });
  } catch (error) {
    console.error('应用初始化失败:', error);
    app.quit(); // 初始化失败时退出应用
  }
});

// macOS激活事件处理
app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    mainWindow = new BrowserWindow({
      width: 1200,
      height: 800,
      webPreferences: {
        preload: path.join(__dirname, '../common/preload.js'),
        contextIsolation: true
      }
    });
    process.env.NODE_ENV === 'development'
      ? mainWindow.loadURL('http://localhost:3000')
      : mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
  }
});

// 窗口关闭事件处理
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit(); // 非macOS平台直接退出
  }
});

// 应用退出前清理资源
app.on('will-quit', () => {
  console.log('应用即将退出，正在释放资源');
  // 执行资源释放操作
});

2.3 关键注意事项

• 就绪事件唯一性：app.whenReady() 和 app.on('ready', ...) 作用一致，建议使用 whenReady()（Promise 风格，支持 async/await），避免重复监听；

• 系统差异适配：macOS 下应用关闭所有窗口后不会自动退出，需在 activate 事件中重新创建窗口，Windows 和 Linux 则可直接退出；

• 资源释放时机：耗时的资源释放操作（如关闭网络连接）应在 will-quit 事件中执行，避免阻塞窗口关闭流程。

三、窗口操作 API：打造灵活的交互界面

窗口操作 API 通过 BrowserWindow 类实现，负责窗口的创建、尺寸控制、位置调整、显示隐藏等操作，是构建桌面应用交互界面的核心。每个 BrowserWindow 实例对应一个应用窗口，支持多窗口管理。

3.1 核心 API 速查表

API 语法	功能描述	参数说明	实战场景
new BrowserWindow(options)	创建窗口实例	options：窗口配置对象（宽高、样式等）	应用初始化时创建主窗口
win.loadURL(url)	加载 URL 地址（开发环境）	url：开发服务地址（如 http://localhost:3000）	开发环境加载前端开发服务
win.loadFile(path)	加载本地 HTML 文件（生产环境）	path：HTML 文件路径	生产环境加载打包后的静态界面
win.show()	显示窗口	无	从后台唤醒窗口
win.hide()	隐藏窗口	无	最小化到托盘时隐藏窗口
win.minimize()	窗口最小化	无	点击“最小化”按钮
win.maximize()	窗口最大化	无	点击“最大化”按钮
win.unmaximize()	取消最大化	无	最大化后恢复原尺寸
win.setSize(width, height)	设置窗口尺寸	width/height：宽高数值	响应式调整窗口大小
win.getSize()	获取窗口尺寸	无	保存窗口上次关闭时的尺寸
win.setPosition(x, y)	设置窗口位置	x/y：屏幕坐标	多窗口时调整窗口布局
win.close()	关闭窗口	无	点击“关闭”按钮
win.webContents.openDevTools()	打开调试工具	options：调试工具配置（如位置）	开发环境调试前端界面

3.2 实战：窗口精细化控制案例

以下案例实现窗口的高级控制逻辑，包括“记住上次关闭尺寸和位置”“自定义窗口按钮功能”“多窗口管理”等实用功能，覆盖开发中常见的窗口操作场景：

import { app, BrowserWindow, ipcMain } from '@hmos/electron';
import path from 'path';
import fs from 'fs';

// 窗口状态配置文件路径
const windowStatePath = path.join(app.getPath('userData'), 'window-state.json');

// 加载窗口状态
function loadWindowState() {
    try {
        if (fs.existsSync(windowStatePath)) {
            return JSON.parse(fs.readFileSync(windowStatePath, 'utf8'));
        }
    } catch (error) {
        console.error('读取窗口状态失败：', error);
    }
    
    // 默认窗口状态
    return { 
        width: 1200, 
        height: 800, 
        x: undefined, 
        y: undefined 
    };
}

// 保存窗口状态
function saveWindowState(win: BrowserWindow) {
    fs.writeFileSync(windowStatePath, JSON.stringify(win.getBounds()), 'utf8');
}

let mainWindow: BrowserWindow | null = null;
let secondaryWindow: BrowserWindow | null = null;

app.whenReady().then(() => {
    const windowState = loadWindowState();

    // 创建主窗口
    mainWindow = new BrowserWindow({
        width: windowState.width,
        height: windowState.height,
        x: windowState.x,
        y: windowState.y,
        frame: false,
        webPreferences: {
            preload: path.join(__dirname, '../common/preload.js'),
            contextIsolation: true
        }
    });

    // 加载主窗口内容
    mainWindow.loadURL(
        process.env.NODE_ENV === 'development' 
            ? 'http://localhost:3000' 
            : `file://${path.join(__dirname, '../renderer/index.html')}`
    );

    // 保存窗口状态
    mainWindow.on('close', () => saveWindowState(mainWindow!));

    // 处理窗口操作请求
    ipcMain.handle('window-operation', (_, action: string) => {
        if (!mainWindow) return false;

        switch (action) {
            case 'minimize':
                mainWindow.minimize();
                return true;
            case 'maximize':
                mainWindow.isMaximized() ? mainWindow.unmaximize() : mainWindow.maximize();
                return true;
            case 'close':
                mainWindow.close();
                return true;
            case 'open-secondary':
                // 创建次级窗口
                secondaryWindow = new BrowserWindow({
                    width: 800,
                    height: 600,
                    parent: mainWindow,
                    modal: true,
                    webPreferences: {
                        preload: path.join(__dirname, '../common/preload.js'),
                        contextIsolation: true
                    }
                });

                secondaryWindow.loadURL(
                    process.env.NODE_ENV === 'development'
                        ? 'http://localhost:3000/#/settings'
                        : `file://${path.join(__dirname, '../renderer/index.html#/settings')}`
                );

                // 清理次级窗口引用
                secondaryWindow.on('closed', () => {
                    secondaryWindow = null;
                });
                return true;
            default:
                return false;
        }
    });
});

3.3 关键注意事项

• 自定义标题栏配置：若需实现自定义标题栏，需设置 frame: false 隐藏系统边框，同时通过 ipcMain 监听渲染进程的按钮事件实现窗口操作；

• 多窗口管理：通过 parent 参数设置父窗口，modal: true 可创建模态窗口，避免多窗口操作混乱；

• 窗口状态持久化：利用 app.getPath('userData') 获取系统默认的用户数据目录，用于保存窗口状态，提升用户体验；

• 性能优化：非必要时避免创建过多窗口，关闭窗口后需及时释放实例（设置为 null），避免内存泄漏。

四、基础工具能力 API：日志、路径与系统信息

基础工具能力 API 涵盖日志打印、路径处理、系统信息获取等常用功能，是提升开发效率和应用稳定性的关键。这类 API 大部分支持全进程调用，部分系统信息相关 API 仅主进程可调用。

4.1 日志打印 API：调试与问题定位的核心

鸿蒙 Electron 支持原生 console 日志和鸿蒙扩展日志两种方式，前者适用于开发调试，后者适用于生产环境的日志持久化。

4.1.1 核心 API 速查表

API 语法	功能描述	可调用进程	使用场景
console.log/info/warn/error(msg)	打印不同级别日志	全进程	开发调试、简单日志输出
harmony.log.writeLog(options)	鸿蒙系统日志，支持持久化	仅主进程	生产环境日志记录
harmony.log.getLogPath()	获取日志存储路径	仅主进程	日志导出、问题排查

4.1.2 实战：生产环境日志方案

开发环境使用 console 日志即可，生产环境需使用鸿蒙扩展日志 API 实现日志持久化，便于问题排查：

import { harmony, app } from '@hmos/electron';

// 初始化生产环境日志配置
export function initProductionLog() {
  if (process.env.NODE_ENV !== 'production') return;

  try {
    // 配置日志参数
    harmony.log.configure({
      level: 'info', // 日志级别：debug < info < warn < error
      maxSize: 1024 * 1024 * 10, // 单日志文件最大10MB
      maxDays: 7, // 日志保留7天
      moduleName: app.getName() // 日志模块名称
    });

    // 重写console.log方法
    const originalLog = console.log;
    console.log = (...args) => {
      originalLog(...args);
      harmony.log.writeLog({
        level: 'info',
        content: args.join(' '),
        moduleName: app.getName()
      });
    };

    // 重写console.error方法
    const originalError = console.error;
    console.error = (...args) => {
      originalError(...args);
      harmony.log.writeLog({
        level: 'error',
        content: `${args.join(' ')}\n${new Error().stack}`, // 附加调用栈
        moduleName: app.getName()
      });
    };

    console.log('生产环境日志初始化成功');
  } catch (error) {
    console.error('日志初始化失败：', error);
  }
}

// 获取日志路径
export function getLogPath() {
  return harmony.log.getLogPath();
}

// 使用示例
initProductionLog();
console.log('应用启动成功，版本：', app.getVersion());
console.error('测试错误日志输出');

4.2 路径处理 API：规避跨系统路径问题

路径处理是应用开发的基础，鸿蒙 Electron 继承了 Node.js 的 path 模块，并通过 app.getPath(name) 提供系统路径快捷获取方式，避免硬编码路径导致的跨系统兼容问题。

4.2.1 核心 API 速查表

API 语法	功能描述	可调用进程	示例输出（Windows）
path.join(...paths)	拼接路径，自动处理分隔符	全进程	path.join('a', 'b') → "a\\b"
path.resolve(...paths)	解析为绝对路径	全进程	path.resolve('a') → "C:\\项目目录\\a"
path.basename(path)	获取路径中的文件名	全进程	path.basename("a/b/c.txt") → "c.txt"
app.getPath(name)	获取系统预设路径	仅主进程	app.getPath('userData') → "C:\\用户\\AppData\\Roaming\\应用名"

4.2.2 常用系统路径说明（app.getPath 参数）

• 'userData'：应用用户数据目录（最常用），用于存储配置文件、日志、缓存等，不同应用独立；

• 'appData'：系统应用数据目录，多个应用共享；

• 'desktop'：桌面目录，用于导出文件到桌面；

• 'documents'：文档目录，用于保存用户创建的文档；

• 'temp'：临时文件目录，重启系统后可能被清理。

4.2.3 实战：安全的文件存储方案

以下示例实现配置文件的安全读写，使用 app.getPath('userData') 作为存储目录，避免硬编码路径：

import { app } from '@hmos/electron';
import path from 'path';
import fs from 'fs/promises';

// 配置文件路径：用户数据目录下的config.json
const configPath = path.join(app.getPath('userData'), 'config.json');

/**
 * 读取配置文件
 * @returns 解析后的配置对象或默认配置
 */
export async function readConfig() {
  try {
    await fs.access(configPath);
    const content = await fs.readFile(configPath, 'utf8');
    return JSON.parse(content);
  } catch {
    // 文件不存在时返回默认配置
    return { 
      theme: 'light',
      fontSize: 14,
      autoSync: true
    };
  }
}

/**
 * 写入配置文件
 * @param config 要写入的配置对象
 * @returns 是否写入成功
 */
export async function writeConfig(config: Record<string, any>) {
  try {
    // 确保目录存在（首次运行时创建）
    await fs.mkdir(path.dirname(configPath), { recursive: true });
    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
    return true;
  } catch (error) {
    console.error('写入配置失败：', error);
    return false;
  }
}

/**
 * 配置操作示例（主进程）
 */
async function testConfig() {
  const config = await readConfig();
  console.log('当前配置：', config);

  config.theme = 'dark';
  const result = await writeConfig(config);
  console.log('配置写入结果：', result);
}

五、API 兼容性说明：规避版本适配坑点

鸿蒙 Electron API 的兼容性主要取决于两个维度：一是鸿蒙 Electron 脚手架版本，二是运行设备的鸿蒙系统版本（API Version）。不同版本对 API 的支持情况不同，误用未兼容的 API 会导致应用崩溃或功能失效。

5.1 核心 API 兼容性矩阵

API 类别	核心 API	支持的鸿蒙 Electron 版本	支持的鸿蒙系统 API Version	备注
应用生命周期	app.whenReady()	≥1.0.0	≥10	全版本支持
	app.getVersion()	≥1.0.0	≥10	全版本支持
	app.exit(code)	≥1.0.0	≥10	全版本支持
窗口操作	new BrowserWindow()	≥1.0.0	≥10	frame: false 需 ≥1.1.0
	win.setPosition()	≥1.0.0	≥10	全版本支持
	win.webContents.openDevTools()	≥1.0.0	≥10	开发环境专用
日志打印	console 系列	≥1.0.0	≥10	全版本支持
	harmony.log.writeLog()	≥1.2.0	≥12	1.2.0 新增鸿蒙扩展日志
路径处理	path 模块	≥1.0.0	≥10	全版本支持
	app.getPath()	≥1.0.0	≥10	全版本支持

5.2 兼容性检测实战

开发中需主动检测运行环境的版本，避免调用未兼容的 API。可通过以下方式实现版本检测：

import { app, harmony } from '@hmos/electron';

/**
 * 检查当前 Electron 版本是否满足要求
 * @param requiredVersion 所需最低版本号
 * @returns 是否满足版本要求
 */
function checkElectronVersion(requiredVersion: string): boolean {
  const currentVersion = app.getVersion();
  // 版本号比较（简化实现，实际建议使用 semver 库）
  const currentParts = currentVersion.split('.').map(Number);
  const requiredParts = requiredVersion.split('.').map(Number);
  
  for (let i = 0; i < requiredParts.length; i++) {
    if (currentParts[i] < requiredParts[i]) return false;
    if (currentParts[i] > requiredParts[i]) return true;
  }
  return true;
}

/**
 * 检查鸿蒙系统 API 版本是否满足要求
 * @param requiredVersion 所需最低 API 版本
 * @returns 是否满足 API 版本要求
 */
function checkHarmonyApiVersion(requiredVersion: number): boolean {
  const systemInfo = harmony.system.getSystemInfo();
  return systemInfo.apiVersion >= requiredVersion;
}

/**
 * 安全写入日志（自动检测环境版本）
 * @param content 日志内容
 */
export function safeWriteLog(content: string): void {
  // 要求 Electron ≥1.2.0 且鸿蒙 API ≥12
  if (checkElectronVersion('1.2.0') && checkHarmonyApiVersion(12)) {
    harmony.log.writeLog({
      level: 'info',
      content,
      moduleName: app.getName()
    });
  } else {
    // 版本不满足时降级处理
    console.log('日志（降级）：', content);
  }
}

5.3 版本适配建议

• 最低版本选型：若需适配旧版鸿蒙系统（API Version 10/11），建议使用鸿蒙 Electron 1.1.0 版本；若需使用鸿蒙扩展日志等新能力，需升级到 1.2.0 及以上版本，并要求系统 API Version ≥12；

• 降级策略：对关键功能实现降级策略，如日志打印在旧版本中使用 console，新版本中使用鸿蒙扩展日志；

• 文档参考：开发前查阅官方 API 文档，确认目标版本的 API 支持情况，官方文档会实时更新兼容性信息。

六、总结：API 使用的核心原则

鸿蒙 Electron 核心 API 的使用需遵循“进程隔离、场景匹配、版本兼容”三大核心原则：

1. 进程隔离原则：严格区分主进程和渲染进程的 API 调用权限，鸿蒙扩展 API 和应用/窗口核心 API 仅在主进程调用，渲染进程通过通信机制间接使用；

2. 场景匹配原则：根据开发场景选择合适的 API，如开发环境用 console 日志和调试工具，生产环境用鸿蒙扩展日志和窗口状态持久化；

3. 版本兼容原则：主动检测运行环境的版本，为关键功能实现降级策略，避免因版本不兼容导致应用崩溃。

掌握本文梳理的核心 API 及使用技巧，即可覆盖 90% 以上的开发场景。实际开发中，建议结合官方 API 文档实时查阅，及时了解新增 API 和版本更新带来的能力提升。