模块: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-09'

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 get_item_id(key)
    load_name_data()
    local record = find_name_record(key)
    if record and record.id then
        return record.id
    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]
    if mapped_id then
        return mapped_id
    end
    return resolved
end

local function get_item_name(key)
    load_name_data()
    local record = find_name_record(key)
    if record and common.trim(record.name) ~= '' then
        return common.trim(record.name)
    end

    local item_id = get_item_id(key)
    if item_id ~= '' then
        local mapped_name = mapping.id_to_name and mapping.id_to_name[normalize_key(item_id)] or ''
        if common.trim(mapped_name) ~= '' then
            return common.trim(mapped_name)
        end
    end

    return resolve_input_key(key)
end

function p.getName(frame)
    return get_item_name(common.getArg(frame, 1, ''))
end

function p.getId(frame)
    return get_item_id(common.getArg(frame, 1, ''))
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, '')
    if common.trim(resolve_input_key(key)) == '' then
        return ''
    end

    local display_name = get_item_name(key)
    local item_id = get_item_id(key)
    local size = common.trim(common.getArg(frame, 'size', ''))
    if size == '' then
        size = '24'
    end
    local suffix = common.trim(common.getArg(frame, 2, ''))
    local custom_link = common.trim(common.getArg(frame, 'link', ''))
    local css_class = common.trim(common.getArg(frame, 'class', ''))
    local class_name = 'itemtemplate'
    if 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 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

    local css_out = css.call('Item') or ''

    local cache_parts = {
        normalize_key(resolve_input_key(key)),
        normalize_key(item_id),
        normalize_key(display_name),
        size,
        suffix,
        link_target,
        class_name,
    }
    local cache_key = common.buildLuaCacheKey(
        LUACACHE_NAMESPACE,
        LUACACHE_VERSION,
        table.concat(cache_parts, '|')
    )
    local cached = common.luaCacheGet(cache_key)
    if cached ~= nil then
        return css_out .. cached
    end

    local out = {}
    out[#out + 1] = ('<span class="%s">'):format(class_name)
    out[#out + 1] = '<span class="item-icon-container">'
    out[#out + 1] = ('[[File:%s.png|%sx%spx|link=%s]]'):format(file_name, size, size, link_target)
    out[#out + 1] = '</span>'
    out[#out + 1] = '<span class="item-text">'
    out[#out + 1] = link_text
    if suffix ~= '' then
        out[#out + 1] = ('&nbsp;(%s)'):format(suffix)
    end
    out[#out + 1] = '</span>'
    out[#out + 1] = '</span>'

    local output = table.concat(out)
    common.luaCacheSet(cache_key, output)
    return css_out .. output
end

return p