bugfix250729.1

全站通知：

模块:批量角色头像/doc

来自CrashFeverWIKI_BWIKI_哔哩哔哩
跳到导航 跳到搜索

这是模块:批量角色头像的文档页面

按右上角“WIKI功能→编辑”即可修改页面内容。“刷新页面”即可查看最新内容。
觉得WIKI有帮助，请推荐给朋友哦～(◕ω＜)☆

模块导读：批量角色头像渲染系统

本模块（模块:批量角色头像）用于在页面中批量生成角色的小头像/大头像，并附带对应的属性角标与角色名称。

💡 核心优化：底层发动机重构

在过去，我们用于批量生成头像的工具 Template:批量获取Min角色头像，其底层代码使用的是 #arraymap 配合 #ask 的逐条查询逻辑。

  • 旧逻辑的灾难：如果一个页面上（如新卡池介绍）有 60 个角色头像，系统就会发出 60 次独立的数据库查询。这会导致重度依赖该功能的页面加载极其缓慢，甚至触发 SMW 内存溢出报错。
  • 无感知的架构飞跃：为了解决这个问题，我们编写了本 Lua 模块来完全接管底层的查询逻辑。它会将传入的几十个 ID 自动去重，并每 12 个打包成一批发送给数据库。60 个头像现在只需要 5 次查询！性能提升了十倍以上。
  • 最好的部分：对于全站的编辑者而言，调用方式没有任何改变。所有旧页面自动享受了性能升级。

⚠️ 适用场景与避坑指南 (Best Practices)

本模块是为了优化“手动指定一小批特定角色”的渲染性能而诞生的。

  • 正确用法（适用本模块）：当你需要在一个页面（如关卡攻略、特定队伍推荐、新卡展示）中，展示几个毫不相关的指定角色时。使用本模块可以极大地优化查询性能。
  • 错误用法（请勿使用本模块）：如果你想查询的是“某一类具有共同特征的角色”（例如：所有的红属性角色、所有的妖精种族角色），请绝对不要手动收集它们的 ID 并使用本模块。对于这种情况，请直接使用 #ask 配合 [[分类:红属性]] 或 [[角色属性::红]] 进行常规的聚合检索。

1. 如何调用 (Usage)

面向普通编辑者（外部调用）

在任何条目、攻略页面中，请继续使用封装好的友好模板。支持逗号分隔的多个 ID： 

{{批量获取Min角色头像|角色ID=1001, 1002, 1003}}

{{批量获取Min角色头像|角色ID={{{新卡|}}}}}

面向模板维护者（内部重构参考）

如果你正在维护或新建类似的批量模板，请不要再使用 #arraymap，而是像下面这样直接呼叫本模块： 

{{#arraymap:{{{角色ID|}}}|,|@|{{获取Min角色头像|角色ID=@}}|}}

{{#invoke:批量角色头像|render|模板名=新Min图鉴样式|角色ID={{{角色ID|}}}}}

模块参数说明

参数名 默认值 描述
角色ID / 1 （无，必填） 角色ID列表。支持逗号分隔的字符串。模块会自动去除空格并过滤重复 ID。
模板名 新Min图鉴样式 前端渲染模板。决定头像的最终外观。目前支持 新Min图鉴样式（带名字的小图）和 新图鉴样式（不带名字的大图）。

2. 系统运行逻辑 (Data Flow)

Step 1: ID 清洗与打包 (Chunking)

模块首先接收逗号分隔的 角色ID 字符串。通过 string.gmatch 进行拆解，去除两端空格，并利用一个 idSet 表实现自动去重。 清洗后的纯净 ID 会被切分为每组 12 个的 Chunk（批次）。

⚙️ 架构解密：为什么每批次固定查询 12 个？

在源码中，chunkSize 被严格设定为 12。这是一个经过大量实战测试的性能甜点区（Sweet Spot），主要基于以下考量：

  1. SQL 复杂度墙 (SQL Complexity)：像 [[角色ID::A||B||C...]] 这样的条件，在底层会被转换为数据库的长串 OR 或 IN 语句。如果一次性塞入几十个 ID，会导致数据库查询优化器放弃索引，引发严重卡顿。
  2. 内存与网络平衡 (Memory & Network)：如果分批太小（如 3个/批），查询次数依然过多；如果太大（如 30个/批），返回的单条超长字符串会让 Lua 在执行正则切分时内存飙升。12 个一批完美平衡了“极少查询次数”与“单次毫秒级解析”。

Step 2: 批量语义检索

针对每一个 Chunk，模块构造形如 [[角色ID::1001||1002||...]] 的复合查询条件，一次性向 SMW 索取这些角色的 ?角色ID、?角色属性 和 ?名字。

Step 3: 多属性脏数据清洗 (Data Cleaning)

这是本模块解决的一个隐藏痛点。SMW 在返回多个属性值时，底层会强制塞入类似 <MANY> 的 HTML 标记，导致前端解析崩溃。 模块内置了核心修复机制： 

attrRaw = mw.text.decode(attrRaw)
attrRaw = string.gsub(attrRaw, "<[^>]+>", ",") -- 将 HTML 标记转为纯逗号
attrRaw = string.gsub(attrRaw, "%s+", "")     -- 清除空格
attrRaw = string.gsub(attrRaw, ",+", ",")     -- 归并重复逗号

经过清洗，前端模板将收到绝对干净的字符串（如 "红属性,病毒无效"），方便使用 #arrayindex 提取。

Step 4: 渲染与缺省回退 (Fallback)

  • 成功查询：模块调用指定的 模板名，并将清洗好的数据按固定顺位（2=ID, 3=属性, 4=名字）传递过去。如果调用的是“新图鉴样式”（大图），会额外传递参数 [5]=1 来隐藏名字文本。
  • 未收录提示：如果在数据库中没查到该 ID，模块不会报错，而是直接输出一个带有粉红色边框的【未收录】占位方块，并自带一键创建该数据的编辑链接（带有 action=edit 参数）。

3. 关联模板与 CSS (Dependencies)

本模块不直接生成最终的图像 HTML，而是交由以下展示层模板进行最终装配：

  • [[Template:新Min图鉴样式]]：50px 小图卡片。接收属性后，提取最后一条属性渲染右下角 Overlay 角标，并在底部显示角色名。
  • [[Template:新图鉴样式]]：70px 大图卡片。机制与上述相同，但通过参数控制隐藏了底部的名字文本。

前端样式依赖： 需确保 Common.css 中已定义 .character-card, .character-image-container, .character-overlay-image, .character-name 等类名。

取自“https://wiki.biligame.com/crashfever/index.php?title=模块:批量角色头像/doc&oldid=92723”