EmmyLua 注解功能

发布于 2022年 01月 24日 00:34

前言#

网上配置 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.

内嵌语言#

用于标注一段文本为某种代码格式(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中实现面向对象特性——模拟类、继承、多态 - 马三小伙儿 大佬这篇的代码练手

参考文章#

推荐文章