EmmyLua 注解功能

前言

網上配置 EmmyLua 的方法很多，此處就不做贅述（因此前提是你已經安裝配置完EmmyLua）

本文僅是對 EmmyLua插件 內 注解功能 用法的代碼演示。因為網上大部分EmmyLua配置教程中都沒對此部分進行講解，而實際lua開發時EmmyLua的注解功能幾乎必不可缺，故作此文

注解的目的

我們在編寫C#腳本時，IDE的相關插件能提示各類方法或成員以及描述：

但Lua內，即便安裝完EmmyLua，不寫注解的話，也就沒有任何提示（灰色提示僅表示剛有寫過該參數而已，完全不知道是成員變量或方法）：

因此EmmyLua注解功能就是為了解決該問題：模擬實現代碼提示

用法

類的聲明

基本格式：--@class MY_TYPE[:PARENT_TYPE] [@comment]

---@class Person 人
Person = {};

---@class Gamer : Person 玩家
Gamer = {};

類的額外屬性

即使該類未持有某屬性，也可以通過添加注解，在提示內出現（PS：其實EmmyLua實現UnityAPI的提示也是基於此的）

基本格式：---@field [public|protected|private] field_name FIELD_TYPE[|OTHER_TYPE] [@comment]

---@class Person 人
---@field public Name string 名字
---@field private m_Age number 年齡
Person = {
    Name = "",
};

變量的類型

基本格式：---@type MY_TYPE[|OTHER_TYPE] [@comment]

標注數組：---@type MY_TYPE[]

標注字典：---@type table<KEY_TYPE, VALUE_TYPE>

PS：按上述官方用法，comment描述應當放在末尾，但我這試了下type不大行，可以放在頂部

---我的ID
---@type number
myId = 1;

---Gamer的實例
---@type Gamer
gamerA = Gamer:Create();

---玩家的數組
---@type Gamer[]
gamersArr = {};

---玩家的字典
---@type table<number, Gamer>
gamersTable = {};

函數

標注函數定義參數的類型：---@param param_name MY_TYPE[|other_type] [@comment]

標注函數的返回值類型：---@return MY_TYPE[|OTHER_TYPE] [@comment]

標注函數的不定參數：---@vararg TYPE

---取得台詞
---@param isCN boolean 是否是中文
---@param id number 台詞字典ID
---@return string 台詞
function GetLines(isCN, id)
    local str = "";    -- do something
    return str;
end

---累加求和
---@vararg number 累加的數字
---@return number 和
function AddNum(...)
    local total = 0;
    for _, v in pairs{...} do
        total = total + v;
    end
    return total;
end

類型的別名

對於變量類型的注解，通常采用上文的---@type即可（常用類型有 string|number|boolean|table|... 或通過 ---@class聲明的自定義類型），但倘若遇到復雜類型（如閉包函數），就可以采用別名注解，將一些復雜不容易輸入的類型注冊為一個新的別名：

基本格式：---@alias NEW_NAME TYPE

---生成 打印目標等級日志函數 的函數
---@param logLevel number 日志等級
---@return LogPrinter 打印日志函數
function GenLogPrinter(logLevel)

    ---@alias LogPrinter fun(logMsg : string) : void
    return function(logMsg)
        if(logLevel == 1) then
            print("Log : " .. logMsg);
        elseif(logLevel == 2) then
            print("Warning : " .. logMsg);
        end
    end
end

---@type LogPrinter
local LP = GenLogPrinter(1);
---@type LogPrinter
local LP_Warning = GenLogPrinter(2);

LP("a normal log.");  	         -- Log : a normal log.
LP_Warning("a warning log.");  	 -- Warning : a warning log.

region

--region 舊版region語法

--endregion

--{{{ 新版region語法

--}}}

內嵌語言

用於標注一段文本為某種代碼格式（JSON、XML、JAVA等），從而可以顯示高亮

基本格式：---@language LANGUAGE_ID

---@language JSON
local jsonText = [[{
    "name":"Joker",
    "age": 18
}]]

---@language XML
local XMLText = [[
    <Person>
        <name value = "Joker"/>
        <age value = "18"/>
    </Person>
]]

備注

在IDEA下，對目標使用Alt+Enter快捷鍵（或點小燈泡），可較方便自動補全注解：

具體示例

現有Person基類，Gamer類繼承自Person，在Main.lua內實現兩個類的創建及使用（直接粘到本地跑就行）：

Main.lua：

require("Person");
require("Gamer");

---@type Person
local pa = Person:Create("joker", 18);
pa:ShowInfo();
pa:ReName("Joker");
pa:ShowInfo()

---@type Gamer
local ga = Gamer:Create("fox", 19, nil, nil);
ga:ShowInfo();
ga:ReName("Fox");
ga:ReGamerInfo("123", "456");
ga:ShowInfo();

Person.lua：

---@class Person 人類型
---@field public Name string 名字
---@field private m_Age number 年齡
Person = {
    Name = "",
    m_Age = 0,
};

Person.__index = Person;

---Create
---@param name string
---@param age number
function Person:Create(name, age)
    ---@type Person
    local t = {};

    setmetatable(t, Person);

    t:ReName(name);
    t:ReAge(age);

    return t;
end

---ReName
---@param newName string
---@public
function Person:ReName(newName)
    self.Name = newName;
end

---ReAge
---@param newAge number
---@private
function Person:ReAge(newAge)
    self.m_Age = newAge;
end

---ShowInfo
---@public
function Person:ShowInfo()
    print("Name = " .. self.Name .. ", Age = " .. self.m_Age);
end

Gamer.lua：

require("Person")

---@class Gamer : Person 玩家
---@field private SW string SW碼
---@field private SteamId string Steam鏈接
Gamer = {
    SW = "",
    SteamId = "",
};

Gamer.__index = Gamer;
setmetatable(Gamer, Person);

function Gamer:Create(name, age, sw, steamId)
    ---@type Gamer
    local t = {};
    t = Person:Create(name, age);

    setmetatable(t, Gamer);

    t:ReGamerInfo(sw, steamId);

    return t;
end

---ReGamerInfo
---@param sw string
---@param steamId string
---@public
function Gamer:ReGamerInfo(sw, steamId)
    self.SW = sw or "0";
    self.SteamId = steamId or "0";
end

---ShowInfo
---@public
function Gamer:ShowInfo()
    print("Name = " .. self.Name .. ", Age = " .. self.m_Age .. ", SW = " .. self.SW .. ", SteamId = " .. self.SteamId);
end

PS：可以用 在Lua中實現面向對象特性——模擬類、繼承、多態 - 馬三小伙兒 大佬這篇的代碼練手

參考文章

• EmmyLua