@sky-hi/window-manager

一个用于 Electron 应用的窗口管理库，提供了简单而强大的窗口管理功能。

特性

• 窗口创建和管理
• 窗口组管理
• 支持开发环境和生产环境
• 自定义协议支持
• 窗口状态管理（最大化、最小化、还原等）
• 窗口事件监听
• 安全的渲染进程 API
• TypeScript 支持
• 完整的类型定义

安装

npm install @sky-hi/window-manager
# 或
yarn add @sky-hi/window-manager
# 或
pnpm add @sky-hi/window-manager

使用方法

主进程

import { app } from 'electron';
import WindowManager from '@sky-hi/window-manager';

let windowManager: WindowManager;

// 启动应用
app.whenReady().then(() => {
  // 创建窗口管理器实例
  windowManager = new WindowManager({
    rendererDirectoryName: 'dist', // 渲染进程目录名
    devServerUrl: 'http://localhost:5173', // 开发服务器 URL（可选）
    webPreferences: {
      // 自定义 webPreferences
    }
  });

  // 创建主窗口
  const mainWindow = windowManager.createWindow({
    isMainWin: true,
    route: '/',
    width: 800,
    height: 600,
    maximize: true // 是否最大化
  });

  // 创建子窗口
  const childWindow = windowManager.createWindow({
    parentId: mainWindow.id,
    route: '/child',
    width: 400,
    height: 300
  });
});

// 清理
app.on('window-all-closed', () => {
  windowManager.closeAllWindow();
});

渲染进程

// 类型定义已包含在库中
declare global {
  interface Window {
    windowManager: {
      createWindow: (options?: WindowOptions) => Promise<number>;
      closeWindow: (winId?: number) => Promise<void>;
      hideWindow: (winId?: number) => Promise<void>;
      showWindow: (winId?: number) => Promise<void>;
      minimizeWindow: (winId?: number) => Promise<void>;
      maximizeWindow: (winId?: number) => Promise<void>;
      toggleMaximizeWindow: (winId?: number) => Promise<void>;
      restoreWindow: (winId?: number) => Promise<void>;
      reloadWindow: (winId?: number) => Promise<void>;
      focusWindow: (winId: number) => Promise<void>;
      getWindowInfo: (params?: WindowInfoParams) => Promise<WindowInfo>;
      getDisplayInfo: () => Promise<Electron.Display[]>;
    };
  }
}

// 使用示例
async function example() {
  // 创建新窗口
  const winId = await window.windowManager.createWindow({
    route: '/new-window',
    width: 400,
    height: 300
  });

  // 获取窗口信息
  const windowInfo = await window.windowManager.getWindowInfo({
    isBounds: true,
    isMaximized: true,
    isFocused: true
  });

  // 获取显示器信息
  const displays = await window.windowManager.getDisplayInfo();
}

渲染进程详细使用说明

1. 窗口创建

// 创建独立窗口
const winId = await window.windowManager.createWindow({
  route: '/new-window',
  width: 800,
  height: 600,
  title: '新窗口',
  webPreferences: {
    nodeIntegration: true
  }
});

// 创建模态窗口
const modalWinId = await window.windowManager.createWindow({
  route: '/modal',
  width: 400,
  height: 300,
  parentId: winId, // 指定父窗口
  modal: true
});

2. 窗口控制

// 关闭当前窗口
await window.windowManager.closeWindow();

// 关闭指定窗口
await window.windowManager.closeWindow(winId);

// 最小化窗口
await window.windowManager.minimizeWindow();

// 最大化窗口
await window.windowManager.maximizeWindow();

// 切换最大化状态
await window.windowManager.toggleMaximizeWindow();

// 还原窗口
await window.windowManager.restoreWindow();

3. 窗口状态管理

// 隐藏窗口
await window.windowManager.hideWindow();

// 显示窗口
await window.windowManager.showWindow();

// 聚焦窗口
await window.windowManager.focusWindow(winId);

// 重新加载窗口
await window.windowManager.reloadWindow();

4. 获取窗口信息

// 获取当前窗口的完整信息
const windowInfo = await window.windowManager.getWindowInfo({
  isBounds: true,      // 获取窗口位置和大小
  isMaximized: true,   // 获取最大化状态
  isMinimized: true,   // 获取最小化状态
  isFullScreen: true,  // 获取全屏状态
  isVisible: true,     // 获取可见状态
  isDestroyed: true,   // 获取销毁状态
  isFocused: true,     // 获取焦点状态
  isAlwaysOnTop: true  // 获取置顶状态
});

// 获取显示器信息
const displays = await window.windowManager.getDisplayInfo();
console.log('可用显示器:', displays);

5. 实际应用场景

// 创建设置窗口
async function openSettings() {
  const settingsWinId = await window.windowManager.createWindow({
    route: '/settings',
    width: 600,
    height: 400,
    title: '设置',
    resizable: false,
    minimizable: false
  });
}

// 创建预览窗口
async function openPreview() {
  const previewWinId = await window.windowManager.createWindow({
    route: '/preview',
    width: 1024,
    height: 768,
    title: '预览',
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    }
  });
}

// 窗口状态监听
async function monitorWindowState() {
  const windowInfo = await window.windowManager.getWindowInfo({
    isMaximized: true,
    isFocused: true
  });
  
  if (windowInfo.isMaximized) {
    console.log('窗口已最大化');
  }
  
  if (windowInfo.isFocused) {
    console.log('窗口已获得焦点');
  }
}

注意事项

1. 所有窗口操作方法都是异步的，需要使用 async/await 或 Promise 处理
2. 窗口 ID 是唯一的，建议保存需要重复操作的窗口 ID
3. 创建窗口时可以指定 parentId 来创建父子窗口关系
4. 使用 getWindowInfo 时，只请求需要的状态信息以提高性能
5. 在开发环境中，确保 devServerUrl 配置正确
6. 窗口操作失败时会抛出异常，建议使用 try-catch 处理

API 文档

WindowManager 类

构造函数选项

interface WindowManagerOptions {
  rendererDirectoryName?: string; // 渲染进程目录名
  devServerUrl?: string; // 开发服务器 URL
  icon?: string; // 窗口图标
  webPreferences?: Electron.WebPreferences; // 自定义 webPreferences
}

窗口选项

interface WindowOptions extends Electron.BrowserWindowConstructorOptions {
  id?: number;
  route?: string;
  isMultiWindow?: boolean;
  isMainWin?: boolean;
  maximize?: boolean;
  parentId?: number;
  isDevTools?: boolean;
}

窗口信息参数

interface WindowInfoParams {
  isBounds?: boolean;
  isMaximized?: boolean;
  isMinimized?: boolean;
  isFullScreen?: boolean;
  isVisible?: boolean;
  isDestroyed?: boolean;
  isFocused?: boolean;
  isAlwaysOnTop?: boolean;
}

渲染进程 API

方法

• createWindow(options?: WindowOptions): Promise<number>
• closeWindow(winId?: number): Promise<void>
• hideWindow(winId?: number): Promise<void>
• showWindow(winId?: number): Promise<void>
• minimizeWindow(winId?: number): Promise<void>
• maximizeWindow(winId?: number): Promise<void>
• toggleMaximizeWindow(winId?: number): Promise<void>
• restoreWindow(winId?: number): Promise<void>
• reloadWindow(winId?: number): Promise<void>
• focusWindow(winId: number): Promise<void>
• getWindowInfo(params?: WindowInfoParams): Promise<WindowInfo>
• getDisplayInfo(): Promise<Electron.Display[]>

注意事项

1. 确保在主进程中正确初始化 WindowManager
2. 使用 TypeScript 时，类型定义已包含在库中
3. 窗口选项中的 webPreferences 配置会被默认的安全设置覆盖，如需修改请在构造函数选项中配置
4. 支持开发环境和生产环境的不同配置
5. 使用自定义协议加载本地文件

开发

# 安装依赖
npm install

# 运行类型检查
npm run type-check

# 运行测试
npm test

# 构建
npm run build

# 代码检查
npm run lint

要求

• Electron >= 28.3.3
• Node.js >= 20

许可证

MIT © leaf