模块:Common

概述

Common 提供中文百科 Lua 模块的基础通用能力，包括参数读取、JSON 数据页加载、文件存在判断和 LuaCache 辅助。

用法

local common = require('Module:Common')

local title = common.getCurrentTitleText()
local data = common.loadJsonData('数据:Item/item_mapping.json')
local key = common.normalizeKey(title)

示例

local common = require('Module:Common')

local cache_key = common.buildLuaCacheKey('demo', '1', 'example')
local cached = common.luaCacheGet(cache_key)
if cached == nil then
    cached = common.trim(' test ')
    common.luaCacheSet(cache_key, cached, 300)
end
return cached

函数

• trim：去除首尾空白。
• getArg：从 frame 与父级模板中读取参数。
• toText：将布尔值、数组或普通值转成文本。
• normalizeKey：统一键名格式。
• loadJsonData：安全读取数据页 JSON。
• getCurrentTitleText：返回当前页面标题。
• filePageExists：判断文件页是否存在。
• getFilePath：获取文件路径缓存值。
• buildLuaCacheKey、luaCacheGet、luaCacheSet：LuaCache 辅助函数。

---

local p = {}

local cache = {}
local lua_cache = mw.ext and mw.ext.LuaCache or nil

local FILEPATH_CACHE_TTL = 3600

function p.trim(value)
    if value == nil then
        return ''
    end
    return mw.text.trim(tostring(value))
end

function p.getArg(frame, key, default)
    local value = frame.args[key]
    if value == nil and frame:getParent() then
        value = frame:getParent().args[key]
    end
    value = p.trim(value)
    if value == '' then
        return default or ''
    end
    return value
end

function p.toText(value, sep)
    if value == nil then
        return ''
    end
    if type(value) == 'boolean' then
        return value and '是' or '否'
    end
    if type(value) == 'table' then
        local parts = {}
        for _, item in ipairs(value) do
            parts[#parts + 1] = tostring(item)
        end
        return table.concat(parts, sep or '、')
    end
    return tostring(value)
end

function p.normalizeKey(value)
    return mw.ustring.lower(p.trim(value))
end

function p.loadJsonData(titleText)
    local pageName = p.trim(titleText)
    if pageName == '' then
        return nil
    end

    local cacheKey = 'json:' .. pageName
    if cache[cacheKey] ~= nil then
        return cache[cacheKey] or nil
    end

    local ok, data = pcall(mw.loadJsonData, pageName)
    if not ok or type(data) ~= 'table' then
        cache[cacheKey] = false
        return nil
    end

    cache[cacheKey] = data
    return data
end

p.readJsonPage = p.loadJsonData

function p.getCurrentTitleText()
    return mw.title.getCurrentTitle().text
end

function p.filePageExists(fileName)
    local name = p.trim(fileName)
    if name == '' then
        return false
    end

    local cacheKey = 'file-exists:' .. name
    if cache[cacheKey] ~= nil then
        return cache[cacheKey]
    end

    local frame = mw.getCurrentFrame()
    local path = ''
    if frame then
        path = p.trim(frame:preprocess('{{filepath:' .. name .. '}}'))
    end
    local exists = path ~= ''
    cache[cacheKey] = exists
    return exists
end

function p.getFilePath(frame, fileName)
    local name = p.trim(fileName)
    if name == '' then
        return ''
    end

    local cacheKey = 'filepath:' .. name
    local lua_cached = p.luaCacheGet(cacheKey)
    if lua_cached ~= nil then
        return lua_cached
    end
    if cache[cacheKey] ~= nil then
        return cache[cacheKey]
    end

    local title = mw.title.new('File:' .. name)
    local path = ''
    if title and title.exists then
        path = name
    end

    cache[cacheKey] = path
    p.luaCacheSet(cacheKey, path, FILEPATH_CACHE_TTL)
    return path
end

function p.buildLuaCacheKey(namespace, version, key)
    local ns = p.trim(namespace)
    if ns == '' then
        ns = 'cache'
    end
    local ver = tostring(version or '1')
    local suffix = p.trim(key)
    if suffix == '' then
        return ns .. ':' .. ver
    end
    return ns .. ':' .. ver .. ':' .. suffix
end

function p.luaCacheGet(key)
    local k = p.trim(key)
    if k == '' then
        return nil
    end
    if not lua_cache or type(lua_cache.get) ~= 'function' then
        return nil
    end
    return lua_cache.get(k)
end

function p.luaCacheSet(key, value, ttl)
    local k = p.trim(key)
    if k == '' then
        return value
    end
    if not lua_cache or type(lua_cache.set) ~= 'function' then
        return value
    end
    if ttl ~= nil then
        lua_cache.set(k, value, ttl)
    else
        lua_cache.set(k, value)
    end
    return value
end

return p