Electron for 鸿蒙PC项目实战之tooltip-component组件

项目介绍

这是一个基于Electron开发的工具提示（Tooltip）组件示例项目，展示了如何在桌面应用中实现功能丰富、样式多样的工具提示效果。

功能特点

• 多方位定位：支持顶部、右侧、底部、左侧四个方向的工具提示显示
• 多种触发方式：支持悬停（hover）、点击（click）、长按（longpress）三种触发方式
• 样式变体：提供默认、信息、警告、错误、成功五种不同样式的工具提示
• 自定义内容：支持纯文本和HTML富文本内容
• 高级配置：支持延迟显示、持久化显示等高级功能
• 交互式演示：提供实时配置工具提示的交互式演示界面
• 响应式设计：适配不同屏幕尺寸，自动调整位置以避免超出视口
• 深色主题支持：自动适配浅色和深色主题模式

技术实现

主进程（main.js）

主进程负责创建和管理应用窗口，设置必要的WebPreferences以确保安全性，如启用上下文隔离和禁用Node.js集成。

预加载脚本（preload.js）

预加载脚本使用contextBridge安全地暴露Electron API到渲染进程，提供了显示和隐藏工具提示的功能接口。

渲染进程（renderer.js）

渲染进程实现了工具提示的核心逻辑，包括：

• 多触发方式处理（悬停、点击、长按）
• 智能位置计算和边界检测
• 延迟显示和动画效果
• 交互式配置功能
• 全局事件处理

样式实现（style.css）

样式文件实现了五种不同类型的工具提示样式，以及响应式设计和深色主题支持。通过CSS动画和过渡效果，提供了流畅的用户体验。

代码结构

• main.js - Electron主进程代码
• preload.js - 预加载脚本，安全暴露API
• index.html - 应用界面结构
• style.css - 样式定义
• renderer.js - 渲染进程交互逻辑

核心代码示例

1. 工具提示显示逻辑

function showTooltip(trigger, event) {
  // 隐藏现有tooltip
  hideTooltip();
  
  // 获取配置参数
  const position = trigger.dataset.position || 'top';
  const style = trigger.dataset.style || 'default';
  const content = trigger.dataset.tooltip || '';
  
  // 创建并定位tooltip元素
  // ...
  
  // 显示动画
  tooltipContainer.style.opacity = '1';
  tooltip.classList.add('show');
}

2. 位置计算和边界检测

// 根据位置类型计算基础位置
switch (position) {
  case 'top':
    left = triggerRect.left + triggerRect.width / 2 - tooltipRect.width / 2;
    top = triggerRect.top - tooltipRect.height - 10;
    break;
  // 其他位置计算...
}

// 边界检查和调整，确保tooltip不会超出视口
const viewportWidth = window.innerWidth;
const viewportHeight = window.innerHeight;

if (left < 10) left = 10;
else if (left + tooltipRect.width > viewportWidth - 10) {
  left = viewportWidth - tooltipRect.width - 10;
}

// 垂直边界检查...

3. 多触发方式支持

// 根据data-trigger属性选择不同的触发方式
switch (triggerType) {
  case 'hover':
    trigger.addEventListener('mouseenter', handleMouseEnter);
    trigger.addEventListener('mouseleave', handleMouseLeave);
    break;
  case 'click':
    trigger.addEventListener('click', handleClick);
    break;
  case 'longpress':
    trigger.addEventListener('mousedown', handleMouseDown);
    trigger.addEventListener('mouseup', handleMouseUp);
    break;
}

如何使用

基本使用

1. 在HTML元素上添加tooltip-trigger类和相应的data属性：

<div class="tooltip-trigger" 
     data-tooltip="这是一个工具提示" 
     data-position="top" 
     data-style="default">
  悬停显示提示
</div>

高级配置

• HTML内容 ：使用data-tooltip-html属性
• 延迟显示 ：使用data-delay属性（毫秒）
• 持久显示 ：使用data-persistent="true"属性

JavaScript API

也可以通过JavaScript API手动控制工具提示：

// 显示工具提示
window.tooltip.show(element, {
  content: '提示内容',
  position: 'right',
  style: 'info',
  persistent: false
});

// 隐藏工具提示
window.tooltip.hide();

// 切换工具提示显示状态
window.tooltip.toggle(element);

运行方法

1. 安装依赖

npm install

2. 启动应用

npm start

扩展建议

1. 添加自定义动画效果
2. 支持更多样式变体
3. 实现工具提示的内容动态更新
4. 添加键盘导航支持
5. 实现工具提示的主题定制

注意事项

• 使用HTML内容时请注意XSS安全风险
• 在移动设备上长按触发可能需要额外的触摸事件处理
• 确保为工具提示内容提供足够的对比度以符合可访问性标准
  鸿蒙PC适配改造指南

1. 环境准备

• 系统要求：Windows 10/11、8GB RAM以上、20GB可用空间

• 工具安装 ：

  DevEco Studio 5.0+（安装鸿蒙SDK API 20+）

• Node.js 18.x+

2. 获取Electron鸿蒙编译产物

1. 登录Electron 鸿蒙官方仓库

2. 下载Electron 34+版本的Release包（.zip格式）

3. 解压到项目目录，确认electron/libs/arm64-v8a/下包含核心.so库

3. 部署应用代码

将Electron应用代码按以下目录结构放置：

web_engine/src/main/resources/resfile/resources/app/
├── main.js
├── package.json
└── src/
    ├── index.html
    ├── preload.js
    ├── renderer.js
    └── style.css

4. 配置与运行

1. 打开项目：在DevEco Studio中打开ohos_hap目录

2. 配置签名 ：

   进入File → Project Structure → Signing Configs

3. 自动生成调试签名或导入已有签名

4. 连接设备 ：

   启用鸿蒙设备开发者模式和USB调试

5. 通过USB Type-C连接电脑

6. 编译运行：点击Run按钮或按Shift+F10

5. 验证检查项

• ✅ 应用窗口正常显示

• ✅ 窗口大小可调整，响应式布局生效

• ✅ 控制台无"SysCap不匹配"或"找不到.so文件"错误

• ✅ 动画效果正常播放

跨平台兼容性

平台	适配策略	特殊处理
Windows	标准Electron运行	无特殊配置
macOS	标准Electron运行	保留dock图标激活逻辑
Linux	标准Electron运行	确保系统依赖库完整
鸿蒙PC	通过Electron鸿蒙适配层	禁用硬件加速，使用特定目录结构

鸿蒙开发调试技巧

1. 日志查看

在DevEco Studio的Log面板中过滤"Electron"关键词，查看应用运行日志和错误信息。

2. 常见问题解决

• "SysCap不匹配"错误：检查module.json5中的reqSysCapabilities，只保留必要系统能力

• "找不到.so文件"错误：确认arm64-v8a目录下四个核心库文件完整

• 窗口不显示：在main.js中添加app.disableHardwareAcceleration()

• 动画卡顿：简化CSS动画效果，减少重绘频率