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.renderCustomWindow 允许创建和管理自定义窗口，提供了灵活的窗口配置选项。适用于创建独立的功能窗口、工具面板或模态对话框。

功能特点：

• 完全自定义的窗口样式
• 灵活的尺寸和位置控制
• 支持透明度和装饰设置
• 窗口状态管理（最小化、最大化等）
• 拖拽和调整大小支持
• 独立的渲染上下文

应用场景：

• 工具面板和侧边栏
• 独立的设置窗口
• 浮动工具箱
• 多窗口应用架构

基础用法：

  $gm.renderCustomWindow({
    render: h('div', {
        style: {
            minHeight: '100%',
            background: '#fff',
        },
        innerHTML: html,
    }),
    title: '标题',
});

名称	类型	说明
renderCustomWindow	({render:render,title:string}) => void	渲染一个自定义窗口，注：render函数需要特殊支持，如vue框架等

打开一个子应用窗口

$gm.renderChildWindow 用于创建和管理子应用窗口，提供了完整的子应用生命周期管理。支持传递初始化数据和自定义窗口属性。

功能特点：

• 独立的子应用运行环境
• 支持自定义窗口尺寸
• 应用间数据传递
• 完整的生命周期管理
• 灵活的窗口配置

应用场景：

• 模块化应用架构
• 独立功能窗口
• 工作流程管理
• 多任务处理界面

基础用法：

    $gm.renderChildWindow({
        name: '名称',
        url: url,
        mini: false,
        data: {},
        width: 1000,
    });

名称	类型	说明
renderChildWindow	(data:{name:string;url:string;mini:boolean;data:any;width:number}) => void	打开一个子应用窗口

设置桌面壁纸

$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 的正常使用都依赖于此方法的成功调用。

功能特点：

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

初始化流程：

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

使用场景：

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

重要提醒

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

基础用法：

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

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