GTK4 Python模板加载异常：子控件未渲染、标题不更新求助

我是GTK新手，正在构建Hello World应用，UI元素定义在main.ui文件中，使用模板加载该文件。但仅显示空白窗口，按钮未渲染，窗口标题也未更新，推测模板未生效，恳请协助解决。

UI文件(main.ui) #

<?xml version='1.0' encoding='UTF-8'?>
<!-- Created with Cambalache 1.0.2 -->
<interface>
  <!-- interface-name ui.ui -->
  <requires lib="gtk" version="4.0"/>
  <object class="GtkApplicationWindow">
    <property name="title">Hello</property>
    <child>
      <object class="GtkButton">
        <property name="label">Click Me</property>
      </object>
    </child>
  </object>
</interface>

Python代码 #

import gi

gi.require_version("Gtk", "4.0")
from gi.repository import Gtk


@Gtk.Template(filename="ui/main.ui")
class MainWindow(Gtk.ApplicationWindow):
    __gtype_name__ = "MainWindow"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.init_template()


def on_activate(app):
    win = MainWindow()
    win.set_application(application=app)
    win.present()


app = Gtk.Application()
app.connect("activate", on_activate)
app.run(None)

实际显示效果 #

预期效果 #

问题原因与修复方案 #

问题出在UI文件的定义上：使用Gtk模板时，UI中的根对象需要明确关联到自定义窗口类，并且启用模板标记。

修复后的UI文件(main.ui) #

<?xml version='1.0' encoding='UTF-8'?>
<!-- Created with Cambalache 1.0.2 -->
<interface>
  <requires lib="gtk" version="4.0"/>
  <!-- 指定自定义类名，并启用模板 -->
  <object class="MainWindow" template="true">
    <property name="title">Hello</property>
    <child>
      <object class="GtkButton">
        <property name="label">Click Me</property>
      </object>
    </child>
  </object>
</interface>

额外注意事项 #

• 确保代码里的__gtype_name__ = "MainWindow"和UI中的class="MainWindow"完全一致，大小写敏感。
• 检查filename="ui/main.ui"的路径是否正确，若脚本和UI不在对应目录，可改用绝对路径测试。
• 删掉UI中<!-- interface-name ui.ui -->这类注释，避免路径混淆。

修复后运行代码，窗口会正常显示标题和按钮。

内容的提问来源于stack exchange，提问作者Jijo Joseph