KDE Plasma 6.0 Hello World KWin脚本打包无效问题排查与解决

问题背景 #

为KDE Plasma 6.0创建简易"Hello World" KWin脚本，通过AI生成main.qml，metadata.json取自KDE官方文档，但将文件压缩为ZIP并修改后缀后，系统设置提示打包无效。

问题原因分析 #

1. 目录结构不匹配：metadata.json中指定X-Plasma-MainScript为code/main.qml，但实际打包时未将main.qml放入code目录，导致系统无法定位主脚本文件。
2. API版本不兼容：Plasma 6.0对应的KWin QML API版本为6.0，代码中使用的import org.kde.kwin 2.0属于旧版本，存在兼容性冲突。
3. 打包格式错误：压缩时将文件放入了额外的外层文件夹，而非直接压缩metadata.json和code目录；或未正确将后缀修改为.kwinscript。

修复步骤 #

1. 修正目录结构 #

确保包内文件结构严格符合如下格式：

metadata.json
code/
    main.qml

2. 更新QML API版本 #

修改main.qml中的导入语句，适配Plasma 6.0环境：

// main.qml
import QtQuick 6.0
import org.kde.kwin 6.0

Item {
    anchors.fill: parent

    Text {
        id: helloText
        text: "Hello World"
        y: 50
        x: (parent.width - width) / 2
        font.pixelSize: 24
        color: "white" // 增加文字颜色，确保在深色桌面环境下可见
    }
}

3. 正确打包脚本 #

• 选中metadata.json文件和code文件夹，直接压缩为ZIP文件（不要将它们放入额外的父文件夹）
• 将ZIP文件的后缀名修改为.kwinscript

4. 优化metadata.json配置（可选） #

调整配置字段使其更规范，示例如下：

{
    "KPlugin": {
        "Name": "Hello World KWin Script",
        "Description": "A simple KWin script that displays Hello World on the screen",
        "Icon": "preferences-system-windows",
        "Authors": [
            {
                "Email": "username@gmail.com",
                "Name": "Firstname Lastname"
            }
        ],
        "Id": "helloworld.kwin.script",
        "Version": "1.0",
        "License": "GPLv3",
        "Website": "https://github.com/username/myscript"
    },
    "X-Plasma-API": "declarativescript",
    "X-Plasma-MainScript": "code/main.qml",
    "KPackageStructure": "KWin/Script"
}

测试方法 #

将修复后的.kwinscript文件导入系统设置的KWin脚本界面，即可正常加载并显示"Hello World"文字。

内容的提问来源于stack exchange，提问作者Damn Vegetables