SDK API

GM Web SDK API 参考文档

本文档介绍 GM Web SDK 中面向微应用开发的公开 API。通过这些 API，应用可以调用由 GM 主应用提供的界面、文件、窗口和服务通信能力。

快速开始

全局访问：所有 API 通过全局对象 $gm 访问
初始化：包含后端服务的应用，应在发起业务请求前等待 $gm.init() 成功
兼容性：SDK 运行时与主应用版本可能存在能力差异，使用可选 API 前应检查方法是否存在

重要提醒

部分由主应用注入的 API 会随 GMSSH 版本变化。对于非基础能力，可使用 typeof $gm.methodName === "function" 进行功能检测。

信息提示

$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`	创建默认类型的信息
loading	`(content: string \| (() => VNodeChild), option?: MessageOption) => MessageReactive`	显示加载信息

MessageOption 属性

名称	类型	说明
closable	`boolean`	是否显示关闭图标
duration	`number`	信息展示的时长
icon	`() => VNodeChild`	信息图标
keepAliveOnHover	`boolean`	鼠标悬停时是否保持显示
render	`MessageRenderMessage`	消息的渲染函数
showIcon	`boolean`	是否展示图标
type	`'info' \| 'success' \| 'warning' \| 'error' \| 'loading' \| 'default'`	消息类型
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`	创建对话框，类型由 `options.type` 决定
error	`(options: DialogOptions) => DialogReactive`	创建错误对话框
info	`(options: DialogOptions) => DialogReactive`	创建信息对话框
success	`(options: DialogOptions) => DialogReactive`	创建成功对话框
warning	`(options: DialogOptions) => DialogReactive`	创建警告对话框

DialogOptions 属性

名称	类型	默认值	说明
`action`	`() => VNodeChild`	`undefined`	操作区域的渲染函数。设置后会替代默认按钮区域。
`actionClass`	`string \| Array<string \| undefined>`	`undefined`	操作区域的类名。
`actionStyle`	`string \| CSSProperties`	`undefined`	操作区域的内联样式。
`autoFocus`	`boolean`	`true`	打开后是否自动聚焦第一个可聚焦元素。
`blockScroll`	`boolean`	`true`	打开时是否禁止页面主体滚动。
`bordered`	`boolean`	`false`	是否显示对话框边框。
`class`	`any`	`undefined`	对话框根元素的类名。
`closable`	`boolean`	`true`	是否显示关闭图标。
`closeOnEsc`	`boolean`	`true`	按下 Esc 键时是否关闭对话框。
`content`	`string \| (() => VNodeChild)`	`undefined`	对话框内容，可以传入文本或渲染函数。
`contentClass`	`string \| Array<string \| undefined>`	`undefined`	内容区域的类名。
`contentStyle`	`string \| CSSProperties`	`undefined`	内容区域的内联样式。
`icon`	`() => VNodeChild`	`undefined`	图标的渲染函数。
`iconPlacement`	`'left' \| 'top'`	`'left'`	图标相对于标题和内容的位置。
`loading`	`boolean`	`false`	是否显示确认按钮的加载状态；加载时确认按钮不可用。
`maskClosable`	`boolean`	`true`	点击遮罩时是否关闭对话框。
`negativeButtonProps`	`ButtonProps`	`undefined`	取消按钮的属性。
`negativeText`	`string`	`undefined`	取消按钮文字；未设置时不显示取消按钮。
`positiveButtonProps`	`ButtonProps`	`undefined`	确认按钮的属性。
`positiveText`	`string`	`undefined`	确认按钮文字；未设置时不显示确认按钮。
`showIcon`	`boolean`	`true`	是否显示图标。
`style`	`string \| CSSProperties`	`undefined`	对话框根元素的内联样式。
`title`	`string \| (() => VNodeChild)`	`undefined`	标题，可以传入文本或渲染函数。
`titleClass`	`string \| Array<string \| undefined>`	`undefined`	标题区域的类名。
`titleStyle`	`string \| CSSProperties`	`undefined`	标题区域的内联样式。
`transformOrigin`	`'mouse' \| 'center'`	`'mouse'`	对话框动画的变换原点。
`type`	`'default' \| 'info' \| 'success' \| 'warning' \| 'error'`	`'default'`	对话框类型。调用 `info`、`success`、`warning` 或 `error` 时会由对应方法覆盖。
`onAfterEnter`	`() => void`	`undefined`	进入动画完成后的回调。
`onAfterLeave`	`() => void`	`undefined`	离开动画完成后的回调。
`onClose`	`() => unknown \| Promise<unknown>`	`undefined`	点击关闭图标时触发；返回或解析为 `false` 可阻止关闭。
`onEsc`	`() => void`	`undefined`	按下 Esc 键时触发。是否关闭仍由 `closeOnEsc` 决定。
`onNegativeClick`	`(e: MouseEvent) => unknown \| Promise<unknown>`	`undefined`	点击取消按钮时触发；返回或解析为 `false` 可阻止关闭。
`onPositiveClick`	`(e: MouseEvent) => unknown \| Promise<unknown>`	`undefined`	点击确认按钮时触发；返回或解析为 `false` 可阻止关闭。
`onMaskClick`	`(e: MouseEvent) => void`	`undefined`	点击遮罩时触发。

DialogReactive 包含当前对话框的全部响应式配置，以及只读的 key 和 destroy()。可通过返回值更新标题、内容或加载状态，也可以主动关闭对话框：

const dialog = $gm.dialog.warning({
  title: "提示",
  content: "正在处理，请稍候",
  positiveText: "确定",
  loading: true,
});

dialog.content = "处理完成";
dialog.loading = false;
dialog.destroy();

关闭当前子应用

$gm.closeApp 用于请求主应用关闭当前微应用窗口。

使用场景：

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

注意事项

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

基础用法：

$gm.closeApp();

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

关闭指定应用

$gm.closeOtherApp 用于关闭与指定应用唯一标识匹配的已打开窗口。

应用场景：

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

应用名称格式

应用名称需要使用 {开发者名}/{应用名} 的格式，例如：myorg/myapp

基础用法：

$gm.closeOtherApp("official/example");

名称	类型	说明
closeOtherApp	`(name: string) => void`	`name` 为 `{developer-name}/{app-name}` 格式的应用唯一标识

选取文件夹

$gm.chooseFolder 用于打开 GMSSH 服务器文件夹选择窗口。可以指定初始路径，选择完成后通过回调返回服务器绝对路径。

功能特点：

GMSSH 服务器文件夹选择窗口
支持指定默认打开路径
回调函数返回选择结果

使用场景：

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

效果展示：
选取文件夹

基础用法：

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

名称	类型	说明
chooseFolder	`(callback: (path: string) => void, initialPath?: string) => void`	选取服务器文件夹；`initialPath` 默认为 `/`

选取文件

$gm.chooseFile 用于打开 GMSSH 服务器文件选择窗口。可以指定初始路径，选择完成后通过回调返回服务器绝对路径。

功能特点：

GMSSH 服务器文件选择窗口
支持指定默认打开路径
回调函数返回选择结果

使用场景：

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

效果展示：
选取文件

基础用法：

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

名称	类型	说明
chooseFile	`(callback: (path: string) => void, initialPath?: string) => void`	选取服务器文件；`initialPath` 默认为 `/`

获取当前应用窗口尺寸

$gm.getRectSize 返回 SDK 最后一次收到的微应用窗口宽高。

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

基础用法：

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

名称	类型	说明
getRectSize	`() => { width: number; height: number }`	获取最后一次收到的窗口尺寸

调用时机

SDK 中的初始宽高均为 0。如果尚未收到主应用发送的首次 resize 消息，getRectSize() 可能返回 { width: 0, height: 0 }。需要可靠获取尺寸时，应同时注册 childRectListener。

监听对应用的 GMC 消息推送

$gm.mainGMCListener 用于接收主应用发送的 GMC 消息。该能力仅适用于会收到 GMC 消息的应用。

基础用法：

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

名称	类型	说明
mainGMCListener	`(callback: (message: unknown) => void) => void`	监听主应用向当前微应用发送的 GMC 消息

注册方式

SDK 同一时间只保留一个 GMC 回调。重复调用 mainGMCListener 会覆盖之前注册的回调，并且当前实现不返回取消监听函数。

监听服务器激活状态

$gm.serveActiveListener 用于接收主应用发送的服务器激活状态。

$gm.serveActiveListener((status) => {
  console.log("服务器激活状态：", status);
});

名称	类型	说明
serveActiveListener	`(callback: (status: number) => void) => void`	监听服务器激活状态变化

SDK 同一时间只保留一个状态回调，重复注册会覆盖之前的回调。

向主应用发送消息

$gm.emitParent 是向主应用发送 postMessage 消息的底层桥接方法。

$gm.emitParent({
  type: "customEvent",
  data: { id: "task-1" },
});

名称	类型	说明
emitParent	`(message: unknown) => void`	将一条消息发送给主应用

使用限制

仅在主应用明确实现了对应消息协议时使用。如果 SDK 已提供具体功能方法，应优先调用具体方法。

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

$gm.childRectListener 用于监听微应用窗口的宽高变化。
效果展示：
监听子应用窗口尺寸实时变化

基础用法：

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

// 不再需要监听时取消订阅
unsubscribe();

名称	类型	说明
childRectListener	`(callback: (v: { width: number; height: number }) => void) => () => void`	监听子应用窗口尺寸变化，并返回取消监听函数

打开文件系统

$gm.openFolder 用于在 GMSSH 文件管理器中打开连接服务器上的指定目录。

效果展示：
打开文件系统

基础用法：

$gm.openFolder("/");

名称	类型	说明
openFolder	`(path: string) => void`	`path` 为连接服务器上的文件夹路径

打开文件编辑器

$gm.openCodeEditor 用于在 GMSSH 代码编辑器中打开连接服务器上的指定文件。

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

基础用法：

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

名称	类型	说明
openCodeEditor	`(path: string) => void`	`path` 为连接服务器上的文件路径

打开终端

$gm.openShell 用于打开 GMSSH 终端，并向终端传入命令数组。
效果展示：
打开终端
基础用法：

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

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

安全提示

不要将未经校验的用户输入、URL 参数或服务端错误文本直接拼接成命令。

打开日志

$gm.openLog 用于打开 GMSSH 日志窗口。fun 在窗口打开时调用；开启 flushed 后，日志窗口会定时重新调用 fun。
效果展示：

基础用法：

$gm.openLog("应用日志", {
  fun: () => {
    return Promise.resolve({
      content: "日志内容 " + new Date().toLocaleTimeString(),
      end: false,
    });
  },
  flushed: true,
  control: [
    {
      label: "确认",
      type: "negative",
      fun: () => {
        console.log("确认");
      },
    },
  ],
});

名称	类型	说明
openLog	`(name: string, initData: InitData) => void`	打开日志窗口，`name` 为窗口名称

InitData

属性	类型	必填	说明
`fun`	`() => void \| Promise<{ content: string; end?: boolean }>`	是	获取日志内容。返回 Promise 时，`content` 用于显示日志，`end: true` 用于停止轮询。
`flushed`	`boolean`	否	是否定时刷新日志，默认为 `false`。
`control`	`Control[]`	否	自定义操作按钮。
`delFun`	`() => Promise<unknown>`	否	清空日志时调用；设置后日志窗口提供清空操作。

Control

属性	类型	必填	说明
`label`	`string`	是	按钮文本。
`fun`	`() => void`	是	按钮点击回调。
`disabled`	`boolean`	否	是否禁用按钮，默认为 `false`。
`type`	`string`	否	按钮类型。值为 `negative` 时，日志返回 `end: true` 后会解除该按钮的禁用状态。

上传文件到服务器

$gm.openUpload 用于打开 GMSSH 上传窗口，将浏览器选择的文件上传到连接服务器的指定目录。

功能特点：

支持单文件和多文件上传
实时上传进度显示
分片上传
上传进度和速度显示
上传窗口存续期间可暂停、继续或取消
可选的单文件上传结果回调

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

基础用法：

const getWinFiles = async () => {
  // 创建文件选择元素
  const input = document.createElement("input");
  input.setAttribute("type", "file");
  input.hidden = true;
  input.multiple = true;
  document.body.appendChild(input);
  input.click();
  return await new Promise((resolve) => {
    input.addEventListener("change", (e) => {
      const files = e.target.files || [];
      document.body.removeChild(input);
      resolve(files);
    });
  });
};
const files = await getWinFiles();
$gm.openUpload({
  files,
  path: "/www",
  func: (e) => {
    console.log(e);
  },
});

名称	类型	说明
openUpload	`(options: UploadOptions) => void`	打开上传窗口

UploadOptions

属性	类型	必填	说明
`files`	`FileList \| File[]`	是	需要上传的浏览器文件对象。
`path`	`string`	是	连接服务器上的目标文件夹路径。
`func`	`(result: UploadResult) => void`	否	每个文件上传成功或失败时触发。

UploadResult 的结构为 { name: string; path: string; status: "success" | "error" }，其中 path 为目标文件夹路径。

设置桌面壁纸

$gm.setDesktopWallpaper 用于将指定图片 URL 设置为 GMSSH 桌面背景。图片地址必须是当前环境可访问的 URL。

效果展示：
设置桌面壁纸

基础用法：

$gm
  .setDesktopWallpaper(
    "https://example.com/wallpaper.png"
  )
  .then(() => {
    console.log("设置桌面成功");
  });

名称	类型	说明
setDesktopWallpaper	`(url: string) => Promise<boolean>`	设置桌面壁纸；设置成功时 Promise 解析为 `true`

初始化

$gm.init 用当前应用的 name、version 和 communicationType 请求 /api/center/check_status，由 GMSSH 检查包含后端服务的应用是否可用。

功能特点：

请求 GMSSH 检查当前应用的服务状态
将应用名称、版本和通信类型传递给状态检查接口
返回 $gm.request 产生的 Promise

初始化流程：

读取 $gm.name、$gm.version 和 $gm.communicationType
向 /api/center/check_status 发起 POST 请求
根据请求结果解析或拒绝 Promise

使用场景：

包含后端服务的微应用启动
发起 /api/call/{developer-name}/{app-name}/{method} 业务请求前的服务状态检查

重要提醒

包含后端服务的应用，必须在首次业务请求前等待 init() 成功。message、dialog 等由主应用直接注入的界面 API 不依赖 init() 建立通信。

基础用法：

try {
  await $gm.init();
  // 初始化成功后再发起应用服务请求
} catch (error) {
  console.error("应用服务初始化失败", error);
}

名称	类型	说明
init	`() => Promise<unknown>`	不接收配置参数；Promise 的解析值为 `check_status` 请求的返回结果

SDK 未对重复调用进行缓存或去重。应用通常只需在启动时调用一次；如果初始化失败，可由应用在用户触发重试时再次调用。

打开自定义窗口

$gm.renderChildWindow 用于打开一个由 GMSSH 管理的子窗口，并在窗口内通过 iframe 加载指定 URL。

功能特点：

自定义窗口标题、图标和内容 URL
可选的最小宽度和最小高度
URL 内容在独立 iframe 中显示

应用场景：

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

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

基础用法：

// 打开远程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`	否	`660`	窗口最小宽度，单位为像素
minHeight	`number`	否	`400`	窗口最小高度，单位为像素
icon	`string`	是	-	窗口图标展示

设置应用窗口尺寸

$gm.setAppRectStyle 用于请求主应用调整当前微应用窗口的宽度或高度。

功能特点：

宽度和高度可以同时设置，也可以单独设置
仅接受 number 类型的像素值
主应用接收消息后直接更新窗口尺寸

应用场景：

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

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

基础用法：

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

// 仅调整窗口宽度
$gm.setAppRectStyle({
  width: 1000,
});

参数说明：

名称	类型	必填	默认值	说明
width	`number`	否	-	窗口宽度，单位为像素
height	`number`	否	-	窗口高度，单位为像素

重要限制

至少传入 width 或 height 之一才有实际效果。
主应用会忽略不大于当前最小尺寸阈值的数值。
该方法不返回调整结果；如果需要确认最终尺寸，请通过 childRectListener 获取。

刷新桌面

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

功能特点：

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

应用场景：

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

基础用法：

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

参数说明：

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