鸿蒙PC平台 Gnote 笔记应用适配实战：从 Linux 到鸿蒙PC 的 Electron 迁移

Gnote是一款Linux桌面轻量级笔记应用，现通过Electron+鸿蒙架构实现跨平台迁移。项目采用Electron核心功能（HTML/CSS/JS）与鸿蒙壳工程（ArkTS WebView）结合的方案，保留富文本编辑、标签管理、搜索等核心功能。技术架构上，利用Electron的跨平台特性和鸿蒙WebView桥接，既保证代码复用性又解决Native兼容问题。关键实现包括：动态窗口布局（占据80%

星辰徐哥

275人浏览 · 2026-06-08 13:57:44

星辰徐哥 · 2026-06-08 13:57:44 发布

项目简介

Gnote 是 Linux 桌面环境的一款轻量级笔记应用，支持富文本编辑、标签分类、搜索等功能。本项目将其从 Linux GTK 应用迁移到鸿蒙平台，采用 Electron 核心功能 + 鸿蒙壳工程 的架构模式。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址：https://atomgit.com/weixin_62765017/ohos_gnote_electron

核心功能

📝 富文本编辑（粗体/斜体/下划线/删除线）
🎨 字体颜色和背景高亮
📑 多级标题（H1-H4）
📋 有序/无序列表
💬 引用块和分割线
↔️ 文本对齐（左/中/右）
🏷️ 标签管理
🔍 笔记搜索
💾 自动保存（2秒防抖）
⌨️ 完整快捷键支持

一、技术架构

1.1 原始架构（Linux GTK）

Gnote (C/GTK)
├── 文本编辑：GtkTextView
├── UI 渲染：GTK+ 3.0
├── 数据存储：SQLite
└── 配置管理：GSettings

1.2 目标架构（鸿蒙 Electron）

鸿蒙壳工程 (ArkTS)
└── web_engine 模块 (XComponent WebView)
    └── Electron 应用 (HTML/CSS/JavaScript)
        ├── main.js - Electron 主进程
        ├── renderer.js - 渲染进程（核心逻辑）
        ├── index.html - UI 界面
        └── styles/gnote.css - 样式文件

1.3 架构优势

跨平台：Electron 代码可在 Windows/macOS/Linux 复用
快速开发：Web 技术栈，开发效率高
易于维护：UI 和业务逻辑分离
鸿蒙兼容：通过 WebView 桥接，避开 Native 兼容问题

二、环境准备

2.1 开发环境要求

操作系统：Windows 10
开发工具：DevEco Studio（鸿蒙官方 IDE）
HarmonyOS SDK：API 15
Node.js：v24+（Electron 依赖）

2.2 项目结构

ohos_hap/
├── electron-apps/
│   └── gnote/                  # Electron 笔记应用源码
│       ├── main.js             # 主进程（窗口管理、IPC）
│       ├── renderer.js         # 渲染进程（UI 交互逻辑）
│       ├── index.html          # 界面结构
│       ├── package.json        # 项目配置
│       └── styles/
│           └── gnote.css       # 样式文件
├── web_engine/                 # 鸿蒙 web_engine 模块
│   └── src/main/resources/
│       └── resfile/resources/app/  # 部署目录
│           ├── main.js
│           ├── renderer.js
│           ├── index.html
│           └── styles/gnote.css
└── build-profile.json5         # 鸿蒙构建配置

三、核心适配流程

3.1 第一步：创建 Electron 主进程

文件：electron-apps/gnote/main.js

// Gnote Notes App - Electron 主进程
const { app, BrowserWindow, ipcMain, dialog, screen } = require('electron');
const path = require('path');
const fs = require('fs');

let mainWindow = null;
let notesDir = null;

// 初始化笔记目录
function initNotesDir() {
  try {
    notesDir = path.join(app.getPath('userData'), 'notes');
    
    // 确保笔记目录存在
    if (!fs.existsSync(notesDir)) {
      fs.mkdirSync(notesDir, { recursive: true });
      console.log('Gnote: Notes directory created:', notesDir);
    } else {
      console.log('Gnote: Notes directory exists:', notesDir);
    }
    
    return true;
  } catch (error) {
    console.error('Gnote: Failed to init notes directory:', error);
    return false;
  }
}

function createWindow() {
  console.log('Gnote: Creating window...');
  
  // 获取屏幕尺寸
  const primaryDisplay = screen.getPrimaryDisplay();
  const { width: screenWidth, height: screenHeight } = primaryDisplay.workAreaSize;
  
  // 窗口配置：占据80%屏幕宽度，85%屏幕高度
  const windowWidth = Math.floor(screenWidth * 0.8);
  const windowHeight = Math.floor(screenHeight * 0.85);
  
  mainWindow = new BrowserWindow({
    width: windowWidth,
    height: windowHeight,
    x: Math.floor((screenWidth - windowWidth) / 2),  // 水平居中
    y: Math.floor((screenHeight - windowHeight) / 2), // 垂直居中
    frame: true,
    transparent: false,
    hasShadow: true,
    resizable: true,
    focusable: true,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
      backgroundThrottling: false
    }
  });

  console.log('Gnote: Loading index.html from:', path.join(__dirname, 'index.html'));
  mainWindow.loadFile(path.join(__dirname, 'index.html'));
  
  console.log('Gnote: Window created with size:', windowWidth, 'x', windowHeight);

  mainWindow.on('closed', () => {
    console.log('Gnote: Window closed');
    mainWindow = null;
  });
  
  mainWindow.webContents.on('did-finish-load', () => {
    console.log('Gnote: Page loaded successfully');
  });
  
  mainWindow.webContents.on('did-fail-load', (event, errorCode, errorDescription) => {
    console.error('Gnote: Page failed to load:', errorCode, errorDescription);
  });

  setupIpcHandlers();
}

app.whenReady().then(() => {
  // 初始化笔记目录
  if (!initNotesDir()) {
    console.error('Gnote: Failed to initialize notes directory');
    app.quit();
    return;
  }
  
  createWindow();
  console.log('Gnote Notes App 已启动');
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

关键要点：

使用 screen.getPrimaryDisplay() 获取屏幕尺寸，动态计算窗口大小
窗口占据 80% 屏幕宽度和 85% 屏幕高度，并自动居中
使用 initNotesDir() 函数预先初始化笔记目录，带错误处理
设置 backgroundThrottling: false 保证后台自动保存性能
添加详细的 console.log 用于调试和日志追踪

3.2 第二步：实现笔记数据存储

文件：electron-apps/gnote/main.js

function setupIpcHandlers() {
  console.log('Gnote: Setting up IPC handlers');
  
  // 获取所有笔记列表
  ipcMain.handle('get-notes-list', async () => {
    try {
      if (!fs.existsSync(notesDir)) {
        return [];
      }
      
      const files = fs.readdirSync(notesDir);
      const notes = [];
      
      for (const file of files) {
        if (file.endsWith('.json')) {
          const filePath = path.join(notesDir, file);
          const content = fs.readFileSync(filePath, 'utf8');
          const note = JSON.parse(content);
          notes.push({
            id: note.id,
            title: note.title,
            content: note.content || '',  // 添加内容字段用于预览
            updatedAt: note.updatedAt,
            tags: note.tags || []
          });
        }
      }
      
      // 按更新时间倒序排序
      notes.sort((a, b) => new Date(b.updatedAt) - new Date(a.updatedAt));
      return notes;
    } catch (error) {
      console.error('Gnote: Failed to get notes list:', error);
      return [];
    }
  });

  // 保存笔记
  ipcMain.handle('save-note', async (event, note) => {
    try {
      const noteData = {
        id: note.id || Date.now().toString(),
        title: note.title || '无标题笔记',
        content: note.content || '',
        tags: note.tags || [],
        createdAt: note.createdAt || new Date().toISOString(),
        updatedAt: new Date().toISOString()
      };
      
      const filePath = path.join(notesDir, `${noteData.id}.json`);
      fs.writeFileSync(filePath, JSON.stringify(noteData, null, 2), 'utf8');
      
      console.log('Gnote: Note saved:', noteData.id);
      return { success: true, note: noteData };
    } catch (error) {
      console.error('Gnote: Failed to save note:', error);
      return { success: false, error: error.message };
    }
  });

  // 保存图片文件（用于大图片优化）
  ipcMain.handle('save-image', async (event, noteId, imageData) => {
    try {
      const imagesDir = path.join(notesDir, noteId, 'images');
      
      // 确保图片目录存在
      if (!fs.existsSync(imagesDir)) {
        fs.mkdirSync(imagesDir, { recursive: true });
      }
      
      // 生成唯一文件名
      const timestamp = Date.now();
      const ext = imageData.type === 'image/png' ? 'png' : 'jpg';
      const fileName = `${timestamp}.${ext}`;
      const filePath = path.join(imagesDir, fileName);
      
      // 提取 Base64 数据
      const base64Data = imageData.base64.split(',')[1];
      const buffer = Buffer.from(base64Data, 'base64');
      
      // 写入文件
      fs.writeFileSync(filePath, buffer);
      
      console.log('Gnote: Image saved:', fileName);
      return { success: true, path: fileName };
    } catch (error) {
      console.error('Gnote: Failed to save image:', error);
      return { success: false, error: error.message };
    }
  });

  // 加载笔记内容
  ipcMain.handle('load-note', async (event, noteId) => {
    try {
      const filePath = path.join(notesDir, `${noteId}.json`);
      if (!fs.existsSync(filePath)) {
        return null;
      }
      
      const content = fs.readFileSync(filePath, 'utf8');
      return JSON.parse(content);
    } catch (error) {
      console.error('Gnote: Failed to load note:', error);
      return null;
    }
  });

  // 删除笔记
  ipcMain.handle('delete-note', async (event, noteId) => {
    try {
      const filePath = path.join(notesDir, `${noteId}.json`);
      if (fs.existsSync(filePath)) {
        fs.unlinkSync(filePath);
      }
      
      // 清理图片目录（如果存在）
      const imagesDir = path.join(notesDir, noteId);
      if (fs.existsSync(imagesDir)) {
        fs.rmSync(imagesDir, { recursive: true, force: true });
        console.log('Gnote: Images directory cleaned:', noteId);
      }
      
      console.log('Gnote: Note deleted:', noteId);
      return { success: true };
    } catch (error) {
      console.error('Gnote: Failed to delete note:', error);
      return { success: false, error: error.message };
    }
  });

  // 搜索笔记
  ipcMain.handle('search-notes', async (event, query) => {
    try {
      if (!fs.existsSync(notesDir)) {
        return [];
      }
      
      const files = fs.readdirSync(notesDir);
      const allNotes = [];
      
      for (const file of files) {
        if (file.endsWith('.json')) {
          const filePath = path.join(notesDir, file);
          const content = fs.readFileSync(filePath, 'utf8');
          const note = JSON.parse(content);
          allNotes.push({
            id: note.id,
            title: note.title,
            content: note.content || '',
            updatedAt: note.updatedAt,
            tags: note.tags || []
          });
        }
      }
      
      const lowerQuery = query.toLowerCase();
      return allNotes.filter(note => 
        note.title.toLowerCase().includes(lowerQuery) ||
        note.content.toLowerCase().includes(lowerQuery) ||
        note.tags.some(tag => tag.toLowerCase().includes(lowerQuery))
      );
    } catch (error) {
      console.error('Gnote: Failed to search notes:', error);
      return [];
    }
  });
}

关键要点：

使用 JSON 文件存储，每个笔记一个文件
笔记目录由 initNotesDir() 预先创建，IPC 中不再重复创建
get-notes-list 返回 content 字段用于列表预览
新增 save-image 处理图片文件存储（避免大 Base64 导致 JSON 臃肿）
新增 load-note 单独加载单个笔记
新增 search-notes 实现全文搜索（标题、内容、标签三维度）
删除笔记时自动清理关联的图片目录
笔记按更新时间倒序排列

3.3 第三步：设计笔记列表 UI

文件：electron-apps/gnote/index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';">
  <title>Gnote 笔记</title>
  <link rel="stylesheet" href="styles/gnote.css">
</head>
<body>
  <!-- 主容器 -->
  <div id="app-container" class="app-container">
    <!-- 左侧边栏 - 笔记列表 -->
    <div id="sidebar" class="sidebar">
      <!-- 搜索框 -->
      <div class="search-box">
        <input type="text" id="search-input" class="search-input" placeholder="搜索笔记...">
      </div>
      
      <!-- 新建笔记按钮 -->
      <button id="btn-new-note" class="btn-new-note" title="Ctrl+N">
        <span>➕</span> 新建笔记
      </button>
      
      <!-- 笔记列表 -->
      <div id="notes-list" class="notes-list">
        <!-- 笔记项会动态插入这里 -->
      </div>
    </div>

    <!-- 右侧主内容区 - 笔记编辑 -->
    <div id="main-content" class="main-content">
      <!-- 笔记标题 -->
      <input type="text" id="note-title" class="note-title" placeholder="笔记标题">
      
      <!-- 标签栏 -->
      <div class="tags-bar">
        <div id="tags-container" class="tags-container"></div>
        <input type="text" id="tag-input" class="tag-input" placeholder="添加标签...">
        <button id="btn-delete" class="btn-delete-note" title="删除笔记 (Ctrl+Delete)">🗑️ 删除</button>
      </div>
      
      <!-- 编辑工具栏 -->
      <div class="toolbar">
        <!-- 撤销/重做 -->
        <button id="btn-undo" class="toolbar-btn" title="撤销 (Ctrl+Z)">↶</button>
        <button id="btn-redo" class="toolbar-btn" title="重做 (Ctrl+Y)">↷</button>
        <div class="toolbar-separator"></div>
        
        <!-- 文本格式 -->
        <button id="btn-bold" class="toolbar-btn" title="粗体 (Ctrl+B)" style="font-weight: bold;">B</button>
        <button id="btn-italic" class="toolbar-btn" title="斜体 (Ctrl+I)" style="font-style: italic;">I</button>
        <button id="btn-underline" class="toolbar-btn" title="下划线 (Ctrl+U)" style="text-decoration: underline;">U</button>
        <button id="btn-strikethrough" class="toolbar-btn" title="删除线" style="text-decoration: line-through;">S</button>
        <div class="toolbar-separator"></div>
        
        <!-- 颜色选择器容器 -->
        <div class="color-picker-container">
          <span class="color-picker-label">字色</span>
          <input type="color" id="text-color-picker" class="color-picker" value="#000000" title="字体颜色 (Ctrl+K)">
          <span class="color-picker-label" style="margin-left: 4px;">背景</span>
          <input type="color" id="bg-color-picker" class="color-picker" value="#ffff00" title="背景颜色">
        </div>
        <div class="toolbar-separator"></div>
        
        <!-- 标题 -->
        <button id="btn-h1" class="toolbar-btn" title="一级标题 (Ctrl+1)" style="font-size: 18px; font-weight: bold;">H1</button>
        <button id="btn-h2" class="toolbar-btn" title="二级标题 (Ctrl+2)" style="font-size: 17px; font-weight: bold;">H2</button>
        <button id="btn-h3" class="toolbar-btn" title="三级标题 (Ctrl+3)" style="font-size: 16px; font-weight: bold;">H3</button>
        <button id="btn-h4" class="toolbar-btn" title="四级标题 (Ctrl+4)" style="font-size: 15px; font-weight: bold;">H4</button>
        <div class="toolbar-separator"></div>
        
        <!-- 字体大小 -->
        <button id="btn-font-decrease" class="toolbar-btn" title="减小字号 (Ctrl+[)" style="font-size: 13px;">A-</button>
        <button id="btn-font-increase" class="toolbar-btn" title="增大字号 (Ctrl+])" style="font-size: 15px;">A+</button>
        <div class="toolbar-separator"></div>
        
        <!-- 列表 -->
        <button id="btn-unordered-list" class="toolbar-btn" title="无序列表" style="font-size: 18px;">•</button>
        <button id="btn-ordered-list" class="toolbar-btn" title="有序列表" style="font-size: 14px; font-weight: bold;">1.</button>
        <div class="toolbar-separator"></div>
        
        <!-- 引用和分割线 -->
        <button id="btn-quote" class="toolbar-btn" title="引用" style="font-style: italic;">"</button>
        <button id="btn-hr" class="toolbar-btn" title="分割线">—</button>
        <div class="toolbar-separator"></div>
        
        <!-- 对齐方式 -->
        <button id="btn-align-left" class="toolbar-btn" title="左对齐">☰</button>
        <button id="btn-align-center" class="toolbar-btn" title="居中对齐">☷</button>
        <button id="btn-align-right" class="toolbar-btn" title="右对齐">☶</button>
        <div class="toolbar-separator"></div>
        
        <!-- 清除格式 -->
        <button id="btn-clear-format" class="toolbar-btn" title="清除格式 (Ctrl+Shift+R)" style="font-weight: bold;">✕</button>
      </div>
      
      <!-- 笔记内容编辑器 -->
      <div id="note-content" class="note-content" contenteditable="true" placeholder="开始输入笔记内容..."></div>
      
      <!-- 状态栏 -->
      <div class="statusbar">
        <span id="word-count">0 字</span>
        <span id="last-saved">未保存</span>
        <span id="shortcut-hints" class="shortcut-hints">Ctrl+S 保存 | Ctrl+N 新建 | Ctrl+Z/Y 撤销/重做 | Ctrl+1/2/3/4 标题 | Ctrl+K 颜色 | Ctrl+[/] 字号 | Ctrl+F 搜索</span>
      </div>
    </div>
  </div>

  <script src="renderer.js"></script>
</body>
</html>