模块:Item

概述

Item 负责物品名称解析、描述读取与图标卡片渲染，是中文百科物品小卡片的统一入口。

用法

{{#invoke:Item|renderItem|苹果}}
{{#invoke:Item|getName|苹果}}
{{#invoke:Item|getDescription|苹果}}

示例

{{#invoke:Item|renderItem|苹果|x10|class=block}}

函数

• getNameByKey：按查找键返回物品名称，适合 Lua 内部调用。
• getIdByKey：按查找键返回物品 ID，适合 Lua 内部调用。
• getName：按模板参数返回物品名称。
• getId：按模板参数返回物品 ID。
• getDescription：返回物品描述。
• renderItem：渲染带 CSS 的物品卡片。
• renderItemWithArgs：渲染不重复注入 CSS 的物品卡片。
• renderPureItem：适合在 Lua 内部按参数表直接输出物品卡片。

数据来源

• 数据:Item/item_name_index.json
• 数据:Item/item_mapping.json
• 数据:Item/item_desc_index.json

---

local common = require('Module:Common')
local css = require('Module:CSS')
local item_common = require('Module:ItemCommon')

local p = {}

local name_data
local desc_data
local mapping

local LUACACHE_NAMESPACE = 'item:render'
local LUACACHE_VERSION = '2026-03-12'

local function normalize_key(value)
    return item_common.normalizeKey(value)
end

local function load_name_data()
    if name_data then
        return
    end
    name_data, mapping = item_common.loadDomainData('数据:Item/item_name_index.json', '数据:Item/item_mapping.json')
end

local function load_desc_data()
    if desc_data then
        return
    end
    desc_data = common.loadJsonData('数据:Item/item_desc_index.json') or {}
end

local function resolve_input_key(value)
    local resolved = common.trim(value)
    if resolved == '' then
        resolved = common.getCurrentTitleText()
    end
    return resolved
end

local function find_name_record(key)
    load_name_data()
    return item_common.findRecord(name_data, mapping, key)
end

local function find_desc_record(key)
    load_name_data()
    load_desc_data()

    local name_record = find_name_record(key)
    if name_record and name_record.id then
        local by_id = desc_data[normalize_key(name_record.id)]
        if by_id then
            return by_id
        end
    end

    return item_common.findRecord(desc_data, mapping, key)
end

local function resolve_item_meta(key)
    load_name_data()
    local record = find_name_record(key)
    if record then
        local id = record.id or ''
        local name = common.trim(record.name or '')
        if name ~= '' then
            return id, name
        end
        if id ~= '' then
            local mapped_name = mapping.id_to_name and mapping.id_to_name[normalize_key(id)] or ''
            if common.trim(mapped_name) ~= '' then
                return id, common.trim(mapped_name)
            end
        end
    end

    local resolved = resolve_input_key(key)
    local normalized = normalize_key(resolved)
    local mapped_id = mapping.name_to_id and mapping.name_to_id[normalized]
    local item_id = mapped_id or resolved
    local mapped_name = mapping.id_to_name and mapping.id_to_name[normalize_key(item_id)] or ''
    if common.trim(mapped_name) ~= '' then
        return item_id, common.trim(mapped_name)
    end
    return item_id, resolved
end

local function get_item_meta(key, size, suffix, custom_link, css_class)
    if common.trim(resolve_input_key(key)) == '' then
        return nil
    end

    local item_id, display_name = resolve_item_meta(key)
    local final_size = common.trim(size)
    if final_size == '' then
        final_size = '24'
    end
    local class_name = 'itemtemplate'
    if common.trim(css_class) == 'block' then
        class_name = class_name .. ' itemtemplateblock'
    end

    local file_name = item_id
    if file_name == '' then
        file_name = display_name
    end

    local link_text
    local link_target
    if common.trim(custom_link) ~= '' then
        link_target = custom_link
        link_text = ('[[%s|%s]]'):format(custom_link, display_name)
    else
        link_target = display_name
        link_text = ('[[%s]]'):format(display_name)
    end

    return {
        item_id = item_id,
        name = display_name,
        size = final_size,
        suffix = common.trim(suffix),
        link_target = link_target,
        link_text = link_text,
        class_name = class_name,
        file_name = file_name,
        key = normalize_key(resolve_input_key(key)),
    }
end

local function render_markup(meta)
    if not meta then
        return ''
    end

    local file_name = common.trim(meta.file_name or '')
    local image_name = ''
    local has_icon = false
    if file_name ~= '' then
        image_name = file_name .. '.png'
        has_icon = common.filePageExists(image_name)
    end

    local out = {}
    out[#out + 1] = ('<span class="%s">'):format(meta.class_name)
    if has_icon then
        out[#out + 1] = '<span class="item-icon-container">'
        out[#out + 1] = ('[[File:%s|%sx%spx|link=%s]]'):format(image_name, meta.size, meta.size, meta.link_target)
        out[#out + 1] = '</span>'
    end
    out[#out + 1] = '<span class="item-text">'
    out[#out + 1] = meta.link_text
    if meta.suffix ~= '' then
        out[#out + 1] = ('（%s）'):format(meta.suffix)
    end
    out[#out + 1] = '</span>'
    out[#out + 1] = '</span>'
    return table.concat(out)
end

function p.getNameByKey(key)
    local _, name = resolve_item_meta(key)
    return name
end

function p.getIdByKey(key)
    local id, _ = resolve_item_meta(key)
    return id
end

function p.getName(frame)
    local _, name = resolve_item_meta(common.getArg(frame, 1, ''))
    return name
end

function p.getId(frame)
    local id, _ = resolve_item_meta(common.getArg(frame, 1, ''))
    return id
end

function p.getDescription(frame)
    local record = find_desc_record(common.getArg(frame, 1, ''))
    if not record then
        return ''
    end
    return common.toText(record.description)
end

function p.renderItem(frame)
    local key = common.getArg(frame, 1, '')
    local size = common.getArg(frame, 'size', '')
    local suffix = common.getArg(frame, 2, '')
    local custom_link = common.getArg(frame, 'link', '')
    local css_class = common.getArg(frame, 'class', '')

    local meta = get_item_meta(key, size, suffix, custom_link, css_class)
    if not meta then
        return ''
    end

    local cache_parts = {
        meta.key,
        normalize_key(meta.item_id),
        normalize_key(meta.name),
        meta.size,
        meta.suffix,
        meta.link_target,
        meta.class_name,
    }
    local cache_key = common.buildLuaCacheKey(
        LUACACHE_NAMESPACE,
        LUACACHE_VERSION,
        table.concat(cache_parts, '|')
    )
    local output = common.luaCacheGet(cache_key)
    if output == nil then
        output = render_markup(meta)
        common.luaCacheSet(cache_key, output)
    end

    local css_out = css.quickCall('Item') or ''
    return css_out .. output
end

function p.renderItemWithArgs(frame, args)
    if not args then
        return ''
    end
    local key = common.trim(args[1] or '')
    local size = common.trim(args.size or '')
    local suffix = common.trim(args[2] or '')
    local custom_link = common.trim(args.link or '')
    local css_class = common.trim(args.class or '')
    local meta = get_item_meta(key, size, suffix, custom_link, css_class)
    if not meta then
        return ''
    end
    return render_markup(meta)
end

function p.renderPureItem(frame, args)
    local params = args
    if not params then
        if frame == mw.getCurrentFrame() and frame:getParent() then
            params = require('Module:ProcessArgs').merge(true)
        else
            params = frame
        end
    end
    if not params then
        return ''
    end
    return p.renderItemWithArgs(nil, params)
end

return p