使用 Lua 扩展 Qt Creator

Qt Creator 可以通过 Lua 脚本进行扩展。包含的 Lua 引擎基于 Lua 5.4.6。

编写 Lua 扩展

要创建一个新的 Lua 扩展，请选择文件 > 新建项目 > 库 > Qt Creator Lua 插件。

为了测试您的新扩展，启动您的项目。您的 应用程序输出 应该显示 Hello from Lua!。

Lua 扩展规范

Lua 扩展由一个与所在文件夹同名 Lua 脚本组成。这对于扩展被加载是必要的。

此脚本定义了扩展的规范，例如其显示名称、供应商、版权。

--- MyExtension.lua
return {
    Name = "MyExtension",
    Version = "1.0.0",
    CompatVersion = "1.0.0",
    Vendor = "My Company",
    Category = "Tests",
    Description = "Describe what your extension does in a sentence.",
    LongDescription = [[
        Tell users more about your extension.
    ]],
    Dependencies = {
        { Name = "Core", Version = "13.0.82", Required = true },
        { Name = "Lua",  Version = "13.0.82", Required = true }
    },
    setup = function() print("Hello from Lua!") end,
    printToOutputPane = true,
} --[[@as QtcPlugin]]

设置函数

设置函数在扩展加载时被调用。这是您设置扩展功能的地方。由于规范文件解析权限非常有限，您需要引导入实现实际功能的模块。

--- MyExtension.lua
return {
    Name = "MyExtension",
    Version = "1.0.0",
    ...,
    --- This is the setup function that is called when the extension is loaded.
    --- It requires the 'init' module and calls the setup function from the returned table.
    setup = function() require 'init'.setup() end,
}

--- init.lua
function setup()
    print("Hello from Lua!")
end

-- Returns a table with a single field 'setup' that points to the setup function.
return {
    setup = setup
}

异步操作

一些内置的操作是异步的。要处理这种情况，请使用 Async 模块。

local a = require 'async'
local u = require 'Utils'

a.sync(function()
    print("Lets wait for 5 seconds ...")
    a.wait(u.waitms(5000))
    print("... done!")
end)

交互式帮助

当您第一次在编辑器中打开 .lua 文件时，会被询问下载 Lua 语言服务器。这对于提供上下文相关帮助和自动完成非常有用。

Qt Creator API

Qt Creator API 通过多个模块，您可以使用 require 函数导入这些模块来提供给 Lua 扩展。C++ 扩展可以提供额外的模块。一个例子是 LanguageServer 扩展，它提供了一个用于创建语言服务器客户端的模块。

您可以在 Qt Creator 安装目录下找到 Lua 模块的 API 文档文件。在 macOS 上，您可以在 Qt Creator.app/Contents/Resources/lua/meta 下找到它们。

core.lua	访问和与 Qt Creator 的核心功能交互。
action.lua	在 Qt Creator 中创建用户界面动作。
async.lua	使用 async/await Lua API 处理异步操作。
fetch.lua	从互联网上获取数据。
gui.lua	创建用户界面。
lsp.lua	注册语言服务器客户端。
messagemanager.lua	向用户显示消息。
process.lua	运行外部进程。
qt.lua	访问 Qt 功能。
qtc.lua	访问和扩展 Qt Creator。
settings.lua	读取和写入设置。
simpletypes.lua	访问简单类型。
utils.lua	通用的实用函数和类。

使用 C++ 扩展 Lua API

要向 Lua 接口添加功能，您需要向 Lua 引擎注册一个新的模块。

#include <lua/luaengine.h>

class MyCppExtension final : public ExtensionSystem::IPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "MyCppExtension.json")

public:
    MyCppExtension() {}

private:
    void initialize() final {
        // The registered function will be called when the Lua module 'MyCppExtension' is required.
        // The returned table will be returned from the require call in Lua.
        ::Lua::LuaEngine::registerProvider("MyCppExtension", [](sol::state_view lua) -> sol::object {
            sol::table result = lua.create_table();
            result["myFunction"] = [](int a, int b) { return a + b; };
            return result;
        });
     }
};

然后您可以从Lua脚本中访问 MyCppExtension.myFunction ，如下所示

local MyCppExtension = require 'MyCppExtension'
--- MyCppExtension is now a table with a single field 'myFunction', as it is returned from the
--- C++ function registered via 'LuaEngine::registerProvider(...)'.
print(MyCppExtension.myFunction(1, 2))

有关如何注册C++功能的更多信息，请参阅 sol2。

示例

语言服务器

Qt Creator LuaLanguageClient插件提供了支持注册您自己的语言服务器客户端。您可以在Qt Creator扩展“Lua语言服务器”和“Rust语言服务器”中找到如何使用该功能的示例。