Qizhen Medical Client Event Dispatch

一个用于启医诊医疗客户端事件调度的 TypeScript 库，提供窗口管理和浏览器交互功能。

功能特性

• 🚀 多种窗口操作：支持打开、关闭、加载 URL、显示/隐藏主窗口等窗口管理功能
• 🔧 双环境支持：同时支持 Electron 和 Web 环境
• 📱 消息传递：提供消息传递和徽章同步功能
• 🎯 TypeScript 支持：完整的类型安全
• 📦 轻量级：易于集成
• 🔄 向后兼容：支持传统的 vintageDispatch 调度方式
• 🖥️ MAC 地址获取：支持获取设备默认 MAC 地址
• 🔔 通知窗口：专门的通知窗口支持，带有默认配置
• 🪟 主窗口控制：支持显示和隐藏主窗口

安装

npm install @clwj/qizhen-medical-client-event-dispatch

使用方法

导入方式

import eventDispatch from "@clwj/qizhen-medical-client-event-dispatch";

// 库导出两个主要对象：
// - bus: 新的事件调度器
// - oldBus: 传统调度器（包含 vintageDispatch）

基本用法

import eventDispatch from "@clwj/qizhen-medical-client-event-dispatch";

// 使用新的事件调度器
eventDispatch.bus.loadUrl({
  source: "my-app",
  url: "https://example.com",
});

// 使用传统的事件调度器（向后兼容）
eventDispatch.oldBus.vintageDispatch("load-url", {
  url: "https://example.com",
});

API 文档

类型定义

LoadUrlEventData

type LoadUrlEventData = {
  source: string; // 事件来源标识
  url: string; // 要加载的URL地址
};

OpenBrowserEventData

type OpenBrowserEventData = {
  source: string; // 事件来源标识
  url: string; // 要在浏览器中打开的URL地址
};

OpenWindowEventData

type OpenWindowEventData = {
  source: string; // 事件来源标识
  url: string; // 窗口要加载的URL地址
  name?: string; // 窗口名称（可选）
  isSingle?: boolean; // 是否为单例窗口（可选）
  options?: {
    // 窗口配置选项（可选）
    width?: number; // 窗口宽度
    height?: number; // 窗口高度
    frame?: boolean; // 是否显示边框
    alwaysOnTop?: boolean; // 是否始终置顶
  };
};

OpenNamedWindowEventData

type OpenNamedWindowEventData = {
  source: string; // 事件来源标识
  url: string; // 窗口要加载的URL地址
  name: string; // 窗口名称（必需）
  isSingle: boolean; // 是否为单例窗口（必需）
  options?: {
    // 窗口配置选项（可选）
    width?: number; // 窗口宽度
    height?: number; // 窗口高度
    frame?: boolean; // 是否显示边框
    alwaysOnTop?: boolean; // 是否始终置顶
  };
};

OpenNotificationWindowEventData

type OpenNotificationWindowEventData = {
  source: string; // 事件来源标识
  url: string; // 通知窗口要加载的URL地址
  name: string; // 窗口名称
  isSingle: boolean; // 是否为单例窗口
  options?: {
    // 窗口配置选项（可选）
    width?: number; // 窗口宽度（默认：320）
    height?: number; // 窗口高度（默认：240）
  };
};

CloseWindowEventData

type CloseWindowEventData = {
  source: string; // 事件来源标识
  name: string; // 要关闭的窗口名称
};

PassMessageEventData

type PassMessageEventData = {
  source: string; // 消息来源标识
  target: string; // 消息目标标识
  data: any; // 消息数据
};

SyncMessageBadgeEventData

type SyncMessageBadgeEventData = {
  source: string; // 事件来源标识
  messageContent: string; // 消息内容
  level: "warning" | "danger"; // 消息级别
  hoverTitle: string; // 悬停标题
  url: string; // 相关URL地址
};

WithdrawMessageBadgeEventData

type WithdrawMessageBadgeEventData = {
  source: string; // 事件来源标识
};

GetDefaultMacEventData

type GetDefaultMacEventData = {
  source: string; // 事件来源标识
};

ShowMainWindowEventData

type ShowMainWindowEventData = {
  source: string; // 事件来源标识
};

HideMainWindowEventData

type HideMainWindowEventData = {
  source: string; // 事件来源标识
};

方法

loadUrl(eventData: LoadUrlEventData)

在当前窗口或框架中加载指定的 URL。

参数：

• eventData: LoadUrlEventData - 包含 URL 和相关参数的事件数据

示例：

eventDispatch.bus.loadUrl({
  source: "my-app",
  url: "https://example.com",
});

openBrowser(eventData: OpenBrowserEventData)

在系统默认浏览器中打开指定的 URL。

参数：

• eventData: OpenBrowserEventData - 包含 URL 和浏览器相关参数的事件数据

示例：

eventDispatch.bus.openBrowser({
  source: "my-app",
  url: "https://example.com",
});

openWindow(eventData: OpenWindowEventData)

打开一个新窗口，可以指定窗口的各种配置参数。

参数：

• eventData: OpenWindowEventData - 包含窗口配置选项的事件数据

示例：

eventDispatch.bus.openWindow({
  source: "my-app",
  url: "https://example.com",
  name: "example-window",
  isSingle: true,
  options: {
    width: 800,
    height: 600,
    frame: true,
    alwaysOnTop: false,
  },
});

openNamedWindow(eventData: OpenNamedWindowEventData)

打开一个具有指定名称的窗口，支持单例模式。

参数：

• eventData: OpenNamedWindowEventData - 包含窗口配置选项（包括名称）的事件数据

示例：

eventDispatch.bus.openNamedWindow({
  source: "my-app",
  url: "https://example.com",
  name: "main-window",
  isSingle: true,
  options: {
    width: 1024,
    height: 768,
  },
});

openNotificationWindow(eventData: OpenNotificationWindowEventData)

打开一个通知窗口，具有默认的小尺寸、无边框、始终置顶的配置。

参数：

• eventData: OpenNotificationWindowEventData - 包含通知配置选项的事件数据

示例：

eventDispatch.bus.openNotificationWindow({
  source: "my-app",
  url: "https://example.com/notification",
  name: "notification-window",
  isSingle: true,
  options: {
    width: 400,
    height: 300,
  },
});

closeWindow(eventData: CloseWindowEventData)

关闭指定的窗口。

参数：

• eventData: CloseWindowEventData - 包含窗口标识和关闭选项的事件数据

示例：

eventDispatch.bus.closeWindow({
  source: "my-app",
  name: "window-to-close",
});

passMessage(eventData: PassMessageEventData)

通过事件调度系统传递消息。

参数：

• eventData: PassMessageEventData - 包含消息内容和路由信息的事件数据

示例：

eventDispatch.bus.passMessage({
  source: "sender-app",
  target: "receiver-app",
  data: { message: "Hello World", timestamp: Date.now() },
});

syncMessageBadge(eventData: SyncMessageBadgeEventData)

发送同步消息徽章事件。

参数：

• eventData: SyncMessageBadgeEventData - 包含同步消息徽章信息的事件数据

示例：

eventDispatch.bus.syncMessageBadge({
  source: "my-app",
  messageContent: "您有新的消息",
  level: "warning",
  hoverTitle: "点击查看详情",
  url: "https://example.com/messages",
});

withdrawMessageBadge(eventData: WithdrawMessageBadgeEventData)

发送撤销消息徽章事件。

参数：

• eventData: WithdrawMessageBadgeEventData - 包含撤销消息徽章信息的事件数据

示例：

eventDispatch.bus.withdrawMessageBadge({
  source: "my-app",
});

getDefaultMac(eventData: GetDefaultMacEventData)

获取默认的 MAC 地址。

参数：

• eventData: GetDefaultMacEventData - 包含获取默认 MAC 地址信息的事件数据

示例：

eventDispatch.bus.getDefaultMac({
  source: "my-app",
});

showMainWindow(eventData: ShowMainWindowEventData)

显示主窗口。

参数：

• eventData: ShowMainWindowEventData - 包含显示主窗口信息的事件数据

示例：

eventDispatch.bus.showMainWindow({
  source: "my-app",
});

hideMainWindow(eventData: HideMainWindowEventData)

隐藏主窗口。

参数：

• eventData: HideMainWindowEventData - 包含隐藏主窗口信息的事件数据

示例：

eventDispatch.bus.hideMainWindow({
  source: "my-app",
});

传统调度器 (oldBus)

除了新的事件调度器外，库还提供了一个传统的调度器用于向后兼容：

vintageDispatch

传统的事件调度函数，支持多种窗口操作事件。

语法：

eventDispatch.oldBus.vintageDispatch(eventName, args?)

支持的事件：

• resize-window - 调整窗口大小
• collapse-main-window - 最小化主窗口
• restore-main-window - 恢复主窗口
• load-url - 加载 URL
• move-main-window - 移动主窗口
• open-window - 打开窗口
• open-default-browser - 在默认浏览器中打开
• quit-app - 退出应用
• show-dialog-window - 显示对话框窗口
• close-dialog-window - 关闭对话框窗口
• open-secondary-window - 打开副窗口
• close-secondary-window - 关闭副窗口

示例：

// 调整窗口大小
eventDispatch.oldBus.vintageDispatch("resize-window", {
  width: 800,
  height: 600,
});

// 打开副窗口
eventDispatch.oldBus.vintageDispatch("open-secondary-window", {
  name: "secondary",
  url: "https://example.com",
  singleLock: true,
  frame: false,
  size: { width: 400, height: 300 },
});

环境兼容性

• ✅ Electron 环境：通过 window.electron.ipcRenderer 进行进程间通信
• ✅ Web 环境：通过 window.parent.postMessage 进行消息传递
• ✅ 向后兼容：同时支持传统的 vintageDispatch 调度方式

工作原理

库会自动检测运行环境：

1. 如果检测到 window.electron.ipcRenderer 存在，则使用 Electron 的 IPC 通信
2. 否则回退到 Web 环境的 postMessage API
3. 同时为了确保与其他系统的兼容性，新的调度器还会调用传统的 vintageDispatch 函数

内部事件名称

库内部使用以下事件名称进行通信：

• load-url - 加载 URL
• open-browser - 打开浏览器
• open-window - 打开窗口
• close-window - 关闭窗口
• pass-message - 传递消息
• floating-window:sync-message-badge - 同步消息徽章
• floating-window:withdraw-message-badge - 撤销消息徽章
• get-default-mac - 获取默认 MAC 地址
• main-window:show - 显示主窗口
• main-window:hide - 隐藏主窗口

开发

构建

npm run build

项目结构

src/
├── bus.ts              # 主要的事件调度功能
├── index.ts            # 入口文件，导出 bus 和 oldBus
├── old-bus.ts          # 传统调度器（向后兼容）
└── types/
    ├── bus.ts          # 新调度器的类型定义
    ├── old-bus.ts      # 传统调度器的类型定义
    └── global.d.ts     # 全局类型声明（window.electron）

许可证

ISC

此项目由启医诊医疗客户端团队维护