SDK API

GM Web SDK API 参考文档

本文档提供了 GM Web SDK 的完整 API 参考，涵盖了所有可用的接口和功能。通过这些 API，您可以实现应用与 GM 主应用的深度集成，构建功能丰富的桌面应用体验。

快速开始

全局访问：所有 API 通过全局对象 $gm 访问
初始化：建议在应用启动时调用 $gm.init() 完成初始化
兼容性：确保 SDK 已正确加载后再调用相关 API
:::

重要提醒

部分 API（如通知监听、GMC 消息）仅在特定应用场景下可用，请根据实际需求选择使用。

信息提示

$gm.message 提供了丰富的消息提示功能，支持成功、警告、错误等多种类型的消息展示。所有消息都会调用主应用的 message API 进行统一渲染。

功能特点：

多种消息类型（info、success、warning、error、loading）
自定义显示时长
支持鼠标悬停保持
可自定义图标和渲染函数
支持批量销毁

效果展示：
信息提示

基础用法：

$gm.message.success("演示消息提示");

参数介绍：

名称	类型	说明
destroyAll	`() => void`	销毁所有弹出的信息
info	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	显示信息
success	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	显示成功信息
warning	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	显示警告信息
error	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	显示错误信息
create	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	调用 create 类型的信息
loading	`(content: string ｜ (() => VNodeChild), option?: MessageOption) => MessageReactive`	调用 loading 类型的信息

MessageOption 属性

名称	类型	说明
closable	`boolean`	是否显示 close 图标
duration	`number`	信息展示的时长
icon	`() => VNodeChild`	信息图标
keepAliveOnHover	`boolean`	Hover 到信息上是否不销毁
render	`MessageRenderMessage`	消息的渲染函数
showIcon	`boolean`	是否展示图标
type	`'info' ｜ 'success' ｜ 'warning' ｜ 'error' ｜ 'loading' ｜ 'default'`	调用 loading 类型的信息
onAfterLeave	`() => void`	信息消失动画结束的回调
onClose	`() => void`	点击关闭图标的回调
onLeave	`() => void`	信息开始消失的回调

对话框

$gm.dialog 提供了功能完整的对话框组件，支持多种类型的交互式对话框。所有对话框都会调用主应用的 dialog API 进行渲染，确保与系统界面风格一致。

功能特点：

多种对话框类型（info、success、warning、error）
丰富的自定义选项（标题、内容、按钮等）
支持拖拽和遮罩点击关闭
键盘快捷键支持（ESC 关闭）
Promise 风格的回调处理
灵活的渲染函数支持

效果展示：
对话框示例

基础用法：

$gm.dialog.warning({
  title: "提示",
  content: "这是提示的内容",
  positiveText: "确定",
  negativeText: "取消",
  maskClosable: false,
  onPositiveClick: () => {
    console.log("确定");
  },
});

参数介绍：

名称	类型	说明
destroyAll	`() => void`	销毁所有弹出的对话框
create	`(options: DialogOptions) => DialogReactive`	创建对话框
error	`(options: DialogOptions) => DialogReactive`	调用 error 类型的对话框
info	`(options: DialogOptions) => DialogReactive`	调用 info 类型的对话框
success	`(options: DialogOptions) => DialogReactive`	调用 success 类型的对话框
warning	`(options: DialogOptions) => DialogReactive`	调用 warning 类型的对话框

DialogOptions 属性

名称	类型	默认值	说明
action	`() => VNodeChild`	`undefined`	操作区域的内容，需要是渲染函数
actionClass	`string`	`undefined`	操作区域的类名
actionStyle	`Object ｜ string`	`undefined`	操作区域的样式
autoFocus	`boolean`	`true`	是否自动聚焦 Modal 第一个可聚焦的元素
blockScroll	`boolean`	`true`	是否在打开时禁用 body 滚动
bordered	`boolean`	`false`	是否显示 border
class	`any`	`undefined`	类名
closable	`boolean`	`true`	是否显示 close 图标
closeOnEsc	`boolean`	`true`	是否在摁下 Esc 键的时候关闭对话框
content	`string ｜ (() => VNodeChild)`	`undefined`	对话框内容，可以是渲染函数
contentClass	`string`	`undefined`	内容的类名
contentStyle	`Object ｜ string`	`undefined`	内容的样式
draggable	`boolean ｜ { bounds?: 'none' }`	`false`	是否可拖拽
iconPlacement	`'left' ｜ 'top'`	`'left'`	图标的位置
icon	`() => VNodeChild`	`undefined`	对话框 icon, 需要是渲染函数
loading	`boolean`	`false`	是否显示 loading 状态
maskClosable	`boolean`	`true`	是否可以通过点击 mask 关闭对话框
negativeButtonProps	`ButtonProps`	`undefined`	取消按钮的属性
negativeText	`string`	`undefined`	取消按钮的文字，不填对应的按钮不会出现
positiveButtonProps	`ButtonProps`	`undefined`	确认按钮的属性
positiveText	`string`	`undefined`	确认按钮的文字，不填对应的按钮不会出现
showIcon	`boolean`	`true`	是否显示 icon
style	`string ｜ Object`	`undefined`	样式
title	`string ｜ (() => VNodeChild)`	`undefined`	标题，可以是渲染函数
titleClass	`string`	`undefined`	标题的类名
titleStyle	`Object ｜ string`	`undefined`	标题的样式
transformOrigin	`'mouse' ｜ 'center'`	`'mouse'`	对话框动画出现的位置
type	`'error ｜ 'success' ｜ 'warning'`	`'warning'`	对话框类型
onAfterEnter	`() => void`	`undefined`	出现动画完成执行的回调
onAfterLeave	`() => void`	`undefined`	关闭动画完成执行的回调
onClose	`() => boolean ｜ Promise<boolean> ｜ any`	`undefined`	默认行为是关闭确认框。返回 false 或者 resolve false 或者 Promise 被 reject 会避免默认行为
onNegativeClick	`(e: MouseEvent) => boolean ｜ Promise<boolean> ｜ any`	`undefined`	默认行为是关闭确认框。返回 false 或者 resolve false 或者 Promise 被 reject 会避免默认行为
onPositiveClick	`(e: MouseEvent) => boolean ｜ Promise<boolean> ｜ any`	`undefined`	默认行为是关闭确认框。返回 false 或者 resolve false 或者 Promise 被 reject 会避免默认行为
onMaskClick	`() => void`	`undefined`	点击蒙层后执行的回调

关闭当前子应用

$gm.closeApp 用于关闭当前运行的子应用。调用此方法会触发应用的正常关闭流程，并执行 childDestroyedListener 事件回调。

使用场景：

应用完成任务后的主动退出
用户操作触发的应用关闭
错误处理中的安全退出

注意事项

调用此方法后，当前应用将被立即关闭，请确保在关闭前保存重要数据。

基础用法：

$gm.closeApp();

名称	类型	说明
closeApp	`() => void`	关闭当前子应用

关闭第三方应用

$gm.closeOtherApp 允许当前应用关闭指定的第三方应用。这在应用间协作或管理场景中非常有用。

应用场景：

应用管理器功能
工作流程控制
资源管理和清理

应用名称格式

应用名称需要使用 {组织名}/{应用名} 的格式，例如：myorg/myapp

基础用法：

$gm.closeOtherApp("xxx");

名称	类型	说明
closeOtherApp	`(name: string) => void`	name 为第三方应用的名称，{组织名}/

当前子应用销毁的回调

$gm.childDestroyedListener 用于监听当前子应用的销毁事件。当子应用被关闭时，会触发注册的回调函数，便于进行清理工作或状态更新。

使用场景：

应用生命周期管理
资源清理和释放
状态同步和更新
用户界面刷新

事件触发时机：

子应用主动调用 closeApp()
用户手动关闭子应用窗口
系统强制关闭应用

基础用法：

$gm.childDestroyedListener(() => {
  console.log("子应用销毁了");
});

名称	类型	说明
childDestroyedListener	`(callback) => void`	当前子应用销毁的回调

选取文件夹

$gm.chooseFolder 提供了原生的文件夹选择功能，支持指定默认路径，用户可以通过系统原生对话框选择目标文件夹。

功能特点：

原生系统文件夹选择对话框
支持指定默认打开路径
回调函数返回选择结果
跨平台兼容性

使用场景：

项目目录选择
文件保存位置指定
工作空间设置
批量文件操作的目标目录

效果展示：
选取文件夹

基础用法：

$gm.chooseFolder((res) => {
  console.log("选择文件夹成功", res);
}, "/www");

名称	类型	说明
chooseFolder	`(callback: (v: string) => void, path = '/')=>void`	选取文件夹，参数 1 为回调函数，返回选择的路径，参数 2 为默认打开的路径，默认为'/'

选取文件

$gm.chooseFile 提供了原生的文件选择功能，支持单文件选择和路径指定，通过系统原生对话框提供良好的用户体验。

功能特点：

原生系统文件选择对话框
支持指定默认打开路径
回调函数返回选择结果
跨平台兼容性

使用场景：

配置文件选择
导入文件功能
文件处理和分析
媒体文件选择

效果展示：
选取文件

基础用法：

$gm.chooseFile((res) => {
  console.log("选择文件成功", res);
}, "/www");

名称	类型	说明
chooseFile	`(callback: (v: string) => void, path = '/')=>void`	选取文件，参数 1 为回调函数，返回选择的路径，参数 2 为默认打开的路径，默认为'/'

获取当前应用尺寸信息宽高

getRectSize：包含宽高

效果展示：
获取当前应用尺寸信息

示例 demo

const { width, height } = $gm.getRectSize();
console.log("获取应用初始尺寸，宽：" + width + "，高：" + height);

名称	类型	说明
getRectSize	`()=>{width:number;height:number}`	获取当前应用尺寸信息，通常用于初始化时获取

监听对应用的通知消息推送

mainNotificationListener：：并非是每个子应用都会收到，只有部分应用才需要。

示例 demo

$gm.mainNotificationListener((res) => {
  console.log("收到主应用推送的通知消息", res);
});

名称	类型	说明
mainNotificationListener	`(callback: (v: any) => void)=>void`	监听主应用对单个子应用的通知消息推送

监听对应用的 GMC 消息推送

mainGMCListener：GMC 消息是终端消息推送，并非是每个子应用都会收到，只有部分应用才需要。

示例 demo

$gm.mainGMCListener((res) => {
  console.log("收到主应用推送的GMC消息", res);
});

名称	类型	说明
mainGMCListener	`(callback: (v: any) => void)=>void`	监听主应用对单个子应用的 GMC 通知消息推送

监听子应用窗口尺寸实时变化

childRectListener
效果展示：
监听子应用窗口尺寸实时变化

示例 demo

$gm.childRectListener((res) => {
  const { width, height } = res;
  console.log("实时获取应用窗口尺寸，宽：" + width + "，高：" + height);
});

名称	类型	说明
childRectListener	`(callback: (v: {width:number;height:number}) => void)=>void`	监听子应用窗口尺寸实时变化

打开文件系统

openFolder

效果展示：
打开文件系统

示例 demo

$gm.openFolder("/");

名称	类型	说明
openFolder	`(path:string) => void`	打开文件系统，path 为默认打开的文件夹路径

打开文件编辑器

openCodeEditor

效果展示：
打开文件编辑器

示例 demo

$gm.openCodeEditor("/root/.bashrc");

名称	类型	说明
openCodeEditor	`(path:string) => void`	打开代码编辑器，path 为文件所在路径

打开终端

openShell
效果展示：
打开终端
示例 demo

$gm.openShell({ arr: ["cd /www\n"] });

名称	类型	说明
openShell	`({arr:string[]}) => void`	打开终端，arr 为可执行命令数组

打开日志

openLog
效果展示：

示例 demo

$gm.openLog("日志演示", {
  fun: () => {
    return new Promise((resolve) => {
      //模拟异步操作
      setTimeout(() => {
        resolve({
          content: "日志内容" + new Date().getTime(),
          // end: true, // 结束标志
        });
      }, 1000);
    });
  },
  flushed: true,
  control: [
    {
      label: "确认",
      type: "negative",
      fun: () => {
        console.log("确认");
      },
    },
  ],
});

名称	类型	说明
openLog	`(name:string,initData:InitData) => void`	打开日志，name：日志名称，initData：自定义数据

InitData

属性	类型	说明
fun	`() => void`	刷新日志的函数，非必填
flushed	`bollen`	默认 false，是否开启轮询查看日志
control	`Control[]`	control 自定义按钮数组，非必填

Control

属性	类型	说明
label	`string`	按钮名称
fun	`() => void`	该按钮点击执行的函数
disabled	`bollen`	默认 false，是否 disabled

上传文件到服务器

$gm.openUpload 提供了便捷的文件上传功能，支持多种上传方式和进度监控。集成了文件选择、上传进度显示和结果处理的完整流程。

功能特点：

支持单文件和多文件上传
实时上传进度显示
灵活的文件类型限制
支持断点续传（部分场景）
异步上传处理
文件大小和类型验证

支持的上传场景：

图片和媒体文件上传
文档和配置文件上传
批量文件处理
拖拽上传支持

效果展示：
上传文件到服务器

基础用法：

const getWinFiles = async () => {
  // 创建文件选择元素
  const input = document.createElement("input");
  input.setAttribute("type", "file");
  input.setAttribute("style", "display:none");
  input.setAttribute("multiple", "true"); // 多选
  input.setAttribute("accept", ""); // 文件上传格式限制
  // 将文件选择元素添加到文档中
  document.body.appendChild(input);
  // 触发文件选择元素的点击事件
  input.click();
  // 等待文件选择元素的change事件
  return await new Promise((resolve) => {
    input.addEventListener("change", (e) => {
      const files = e.target.files || [];
      // 从文档中移除文件选择元素
      document.body.removeChild(input);
      // 抛出附件，并生成附件uid
      resolve(files);
    });
  });
};
const files = await getWinFiles();
$gm.openUpload({
  files,
  path: "/www",
  func: (e) => {
    console.log(e);
  },
});

名称	类型	说明
openUpload	`({files:files,path:string,func: (v: {name:string;path:string;status:'success' ｜ 'error'}) => void}) => void`	files 为文件对象，可配合 input 上传使用，path 为上传对应服务器文件夹的路径，func 为上传结束的回调函数，返回参数包含（文件名、上传路径、状态）

设置桌面壁纸

$gm.setDesktopWallpaper 提供了系统桌面壁纸设置功能，支持多种图片格式和设置模式。可以将指定的图片文件设置为系统桌面背景。

功能特点：

支持多种图片格式（JPG、PNG、BMP 等）
多种壁纸显示模式（拉伸、平铺、居中等）
跨平台兼容性
即时生效

支持的图片格式：

JPEG/JPG 格式
PNG 格式（支持透明度）
BMP 位图格式
其他系统支持的格式

应用场景：

个性化桌面定制
主题切换功能
壁纸管理应用
系统美化工具

效果展示：
设置桌面壁纸

基础用法：

$gm
  .setDesktopWallpaper(
    "https://gips2.baidu.com/it/u=499242045,3259685313&fm=3074&app=3074&f=PNG?w=2560&h=1440"
  )
  .then((res) => {
    console.log("设置桌面成功");
  });

名称	类型	说明
setDesktopWallpaper	`(url: string) => Promise<void>`	设置桌面壁纸，注意：url 参数为图片地址，并返回设置成功回调函数

初始化

$gm.init 是 GM Web SDK 的核心初始化方法，用于建立应用与 GM 主应用之间的通信连接。所有其他 API 的正常使用都依赖于此方法的成功调用。

功能特点：

建立与主应用的通信连接
验证应用权限和环境
异步初始化处理
支持重复调用（幂等性）

初始化流程：

检查 SDK 运行环境
建立与主应用的 IPC 通信
验证应用身份和权限
注册必要的事件监听器
返回初始化结果

使用场景：

应用启动时的首次初始化
应用恢复时的重新连接
权限验证和环境检查

重要提醒

在调用任何其他 GM SDK API 之前，必须确保 init() 方法已成功执行。建议在应用的入口文件中优先调用此方法。

基础用法：

//推荐在应用加载完毕调用一次init方法
$gm.init().then((res) => {
  //init方法调用成功，后续可以与GM进行服务通信
});

名称	类型	说明
init	`() => Promise<void>`	返回一个 Promise 对象，注意：如果您的应用需要与 GM 进行服务通信，请务必等待调用此方法成功的回调函数成功后方可执行，推荐在应用加载完毕调用一次 init 方法

打开自定义窗口

$gm.renderChildWindow 提供了创建和管理自定义子窗口的功能，支持灵活的窗口配置和内容展示。可以用于创建独立的功能窗口、弹出式对话框或嵌入式应用界面。

功能特点：

支持自定义窗口尺寸和位置
灵活的窗口标题和图标设置
支持模态和非模态窗口模式
自动内存管理和窗口生命周期控制
跨平台兼容性

应用场景：

设置和配置界面
帮助文档和说明窗口
独立的功能模块界面
第三方服务集成窗口
调试和开发工具窗口

效果展示：
打开自定义窗口

基础用法：

// 打开远程URL窗口
$gm.renderChildWindow({
  title: "百度搜索",
  url: "https://www.baidu.com",
  minWidth: 1000,
  minHeight: 800,
  icon: "https://www.baidu.com/favicon.ico",
});

参数说明：

名称	类型	必填	默认值	说明
title	`string`	是	-	窗口标题，显示在窗口顶部标题栏
url	`string`	是	-	窗口内容，远程 URL
minWidth	`number`	是	-	窗口最小宽度，单位为像素
minHeight	`number`	是	-	窗口最小高度，单位为像素
icon	`string`	是	-	窗口图标展示

设置应用窗口尺寸

$gm.setAppRectStyle 提供了动态调整应用主窗口尺寸的功能，允许开发者根据应用需求灵活设置窗口的宽度和高度。适用于需要根据内容或用户偏好动态调整窗口大小的场景。

功能特点：

动态调整应用主窗口尺寸
支持像素级精确控制
实时生效，无需重启应用
自动适配系统限制
保持窗口居中显示

应用场景：

根据内容动态调整窗口大小
用户自定义窗口尺寸设置
响应式界面布局适配
多分辨率屏幕适配
工作区域优化

效果展示：
设置应用窗口尺寸

基础用法：

// 设置窗口为800x600
$gm.setAppRectStyle({
  width: 800,
  height: 600,
});

// 设置为正方形窗口
$gm.setAppRectStyle({
  width: 1000,
  height: 1000,
});

// 设置为宽屏比例
$gm.setAppRectStyle({
  width: 1200,
  height: 800,
});

参数说明：

名称	类型	必填	默认值	说明
width	`number`	是	-	窗口宽度，单位为像素，不能小于应用最小宽度限制
height	`number`	是	-	窗口高度，单位为像素，不能小于应用最小高度限制

重要限制

设置的窗口尺寸不能小于应用上架时设定的最小宽高限制
如果设置的尺寸小于最小限制，设置将不会生效
窗口尺寸受系统屏幕分辨率限制，不能超过屏幕可用区域
确保在调用此方法前已成功执行 $gm.init() 初始化

刷新桌面

$gm.updateDesktop 提供了刷新桌面的功能，用于手动触发桌面界面的重新渲染和更新。当桌面内容发生变化或需要强制刷新显示时，可以调用此方法来确保桌面界面与实际状态保持同步。该功能能够重新加载桌面图标、更新布局排列，并确保所有可视元素显示正确。

功能特点：

立即刷新桌面图标和布局
同步更新桌面状态
触发桌面组件重新渲染
无需参数，调用即生效
轻量级操作，性能消耗低

应用场景：

安装或卸载应用后更新桌面图标
桌面布局调整后的刷新
应用状态变更后同步桌面显示
用户手动刷新桌面操作
系统主题或配置更改后更新桌面

基础用法：

// 刷新桌面
$gm.updateDesktop();

参数说明：

名称	类型	说明
updateDesktop	`() => void`	刷新桌面