如何在GNOME扩展中创建空白窗口？解决Gtk版本冲突报错

问题根源 #

你遇到的报错是因为GNOME Shell本身基于Gtk 3.x运行，扩展共享Shell的进程环境，无法同时加载Gtk 4.x。而Adwaita（Adw）依赖Gtk 4，直接在扩展中引入Adw会触发版本冲突。

正确实现方式 #

在GNOME扩展中创建窗口，应该使用Shell自带的St.Window类（属于Shell Toolkit，即St库），而非Gtk/Adw的窗口组件。以下是可行的示例代码：

const { St, Clutter } = imports.gi;
const ExtensionUtils = imports.misc.extensionUtils;
const Me = ExtensionUtils.getCurrentExtension();

let testWindow = null;

function enable() {
    log(`enabling ${Me.metadata.name}`);

    // 创建空白窗口
    testWindow = new St.Window({
        name: 'my-extension-window',
        title: '空白窗口',
        can_focus: true,
        has_focus: true,
        skip_taskbar: false, // 是否在任务栏显示
        modal: false,
    });

    // 添加空白容器（窗口必须有子控件才能正常渲染）
    const contentBox = new St.BoxLayout({
        style_class: 'window-content',
        vertical: true,
    });
    testWindow.set_child(contentBox);

    // 设置窗口初始大小
    testWindow.set_size(400, 300);

    // 显示窗口并获取焦点
    testWindow.show();
    testWindow.grab_key_focus();
}

function disable() {
    // 禁用扩展时销毁窗口，避免内存泄漏
    if (testWindow) {
        testWindow.destroy();
        testWindow = null;
    }
}

代码说明 #

• St.Window是GNOME Shell原生窗口类，完全兼容Shell的Gtk3环境，不会出现版本冲突。
• 窗口必须添加至少一个子控件（如示例中的St.BoxLayout），否则无法正常渲染。
• 可通过style_class绑定自定义CSS类，在扩展的stylesheet文件中定义窗口样式。
• disable函数中销毁窗口是扩展开发的最佳实践，防止残留组件导致内存泄漏。

补充说明 #

如果需要在窗口中添加按钮、文本等复杂UI元素，可直接使用St库提供的控件（如St.Button、St.Label），它们基于Clutter框架，与Shell的UI系统完全兼容。

内容的提问来源于stack exchange，提问作者Tom Klino