@gd-kirie/platform

中文文档
0.16.0发布于 2026/10/29TypeScriptES Module构建来源已验证近 30 天下载 8699
中文使用文档
文档目录4 节
  1. 外部網址
  2. 主机窗口
  3. 全球快捷键
  4. 系统返回

@gd-kirie/platform

@gd-kirie/platform 曝光浏览器侧式桌面能力 古多特东道. 从已有的创建客户端 @gd-kirie/ipc-eventa 上下文.

import { createContext } from "@gd-kirie/ipc-eventa";
import { createPlatformClient, hostWindowPointerPositionChanged } from "@gd-kirie/platform";

const eventa = createContext();
const platform = createPlatformClient(eventa.context);

await platform.hostWindow.setAlwaysOnTop(true);

const windowBounds = await platform.hostWindow.getBounds();
const displayBounds = await platform.hostWindow.getCurrentDisplayBounds();
const stopPointer = eventa.context.on(hostWindowPointerPositionChanged, ({ body }) => {
  console.log(body);
});
const pointer = await platform.hostWindow.getPointerPosition();
const windowState = await platform.hostWindow.getState();
console.log(windowBounds, displayBounds, pointer, windowState);
stopPointer();
eventa.dispose();

请求/响应能力是返回客户端的方法. 主机发起 导出事件 @moeru/eventa 合同; 以相同方式签署合同 上下文和返回的函数取消订阅.

外部網址

使用 openExternalUrl() 用系统打开一个绝对的 HTTP 或 HTTPS URL 浏览器 :

await platform.openExternalUrl("https://example.com");

Godot主机拒绝相对的URL和其他URI方案. 用这个 OS.shell_open() 来选择系统浏览器.

使用 openApplicationDataDirectory() 打开当前 Godot 应用程序 数据目录并接收其绝对路径 :

const path = await platform.openApplicationDataDirectory();

这种能力不接受任意路径.

主机窗口

  • 窗口位置和屏幕坐标大小
  • 当前显示位置和屏幕坐标大小
  • 相对于主机窗口的指针位置, 包括此时 点击通过
  • 指针通过
  • 本地移动和调整手势大小
  • 总是在顶上
  • 以当前显示为中心
  • 可见度、重点和最小化状态快照和变化事件

指针坐标使用主机-窗口像素,不与正态化 浏览器取景口. 订阅 hostWindowPointerPositionChanged 先说 礛 调用 getPointerPosition() 获取快照并开始本地观察. 主机在窗口不突出重点或点击通过时发出后期更改.

getState() 返回一个生命周期快照并开始原生状态观察. 设置时叫它一次 后来的更改以 hostWindowStateChanged 事件; 订阅 context.on(hostWindowStateChanged, ({ body }) => ...) 并调用返回的函数以取消订阅.

全球快捷键

MacOS 和 Windows 主机可以注册一个仍然活动的快捷键 godot 窗口被隐藏或未聚焦 :

const shortcut = {
  keycode: 0x4b, // Godot Key.K
  shiftPressed: false,
  altPressed: false,
  ctrlPressed: false,
  metaPressed: false,
  commandOrControlAutoremap: true,
};

await platform.globalShortcuts.register(shortcut, ({ state }) => {
  console.log(state); // "pressed" or "released"
});

await platform.globalShortcuts.unregister(shortcut);

keycode 使用 Godot 逻辑 Key 数值。 需要每个修改字段; commandOrControlAutoremap 在 MacOS 和 Windows 控制上选择命令. 一个 onKeyEvent 处理器接收两个状态; 键盘自动重排不 产生额外的呼叫.

系统返回

Android将系统后按键作为平台事件交付. 申请 决定Back的含义:

import { backRequested } from "@gd-kirie/platform";

const stop = context.on(backRequested, () => {
  console.log("The system Back button was pressed.");
});

stop();

要处理返回而不是让Android关闭应用程序, 设置 SceneTree.quit_on_go_back 改为 false。没有系统后键,该事件不会在平台上发布.

版本与发布记录

@gd-kirie/platform 共发布 28 个版本,首次发布于 2026/08/27;过去 12 个月发布了 28 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.16.0latest2026/10/2917 天前
0.15.32026/10/2917 天前
0.15.22026/10/2818 天前
0.15.12026/10/2818 天前
0.15.02026/10/2125 天前
0.14.22026/10/1729 天前

关于 @gd-kirie/platform 的常见问题

如何安装 @gd-kirie/platform?

在项目目录运行 npm install @gd-kirie/platform,或使用 pnpm add / yarn add / bun add。

@gd-kirie/platform 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gd-kirie/platform 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gd-kirie/platform 可以商用吗?

@gd-kirie/platform 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@gd-kirie/platform 的下载量有多少?

根据 npm 官方下载统计,@gd-kirie/platform 在 2026/10/16 – 2026/11/14 这 30 天内被下载 8,699 次,日均约 290 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gd-kirie/platform 还在维护吗?

最新版本 0.16.0 发布于 2026/10/29(17 天前);至今共发布 28 个版本,其中过去 12 个月发布了 28 个;首次发布于 2026/08/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。