跳到主要内容

容器类标签使用说明

最后更新：2026-02-15

1. 总体模型​

当前统一语义如下：

  • 只使用一个槽位标签：<slot>
  • slot 通过 mode 分为：
    • bound：绑定真实菜单槽位
    • virtual：纯展示槽位
  • container 使用 layout 描述槽位布局（仅布局，不负责一般性自动补齐实例）
  • container 的标题由容器内首个 div 承担（缺失时自动注入）
  • recipe 生成的槽位始终是 virtual

2. container 属性​

2.1 bind​

  • 绑定数据源（如 player / saved_data / block_entity / entity）

2.2 layout​

  • 槽位布局规则（网格或预设）
  • 示例：
    • layout="[27,3,9]"
    • layout="preset:player"

说明：layout 仅影响布局，不会在普通场景自动创建缺失槽位实例。

2.3 title​

  • 标题渲染位置：容器内部（不再固定绘制到屏幕左上角）
  • 标题来源规则：
    • 若容器第一个直接子节点是 div，其文本优先作为标题
    • 否则自动注入标题 div
    • 注入标题文本优先取 container.title
    • 若 title 也未声明，则回退到翻译键 screen.apricityui.container.<menuKey>

示例（显式标题 div）：

<container primary="true" bind="player" layout="preset:player">
  <div class="demo-title">我的标题（跟随容器布局）</div>
  <slot mode="bound" slot-index="0" repeat="36"></slot>
</container>

3. slot 属性​

3.1 mode​

  • bound|virtual
  • 未显式声明时：
    • 在 container 内默认 bound
    • 在 container 外默认 virtual

3.2 repeat​

  • 批量生成，总数语义
  • repeat="36" 表示总共 36 个槽位（模板本身算第 0 个）

3.3 bound 常用属性​

  • slot-index：本地槽位索引
  • disabled：禁用交互
  • CSS（position/top/left/...）可用于手动布局

3.4 virtual 常用属性​

  • item：物品 id 或标签 id（#namespace:path）
  • count：显示数量
  • hover：悬浮文本
  • rotate-interval：标签候选轮播间隔（ms）

4. 玩家容器默认 36 格​

当 container.bind="player" 且容器内没有任何 bound 槽位时，系统会隐式注入玩家背包槽位：

  • inv：27 格（3x9）
  • hotbar：9 格（1x9）
  • 默认间距：4px

若你已经显式声明 bound 槽位，则不会触发上述隐式注入。

5. recipe 规则​

  • <recipe> 可独立用于普通 HTML 展示
  • 在容器内可放多个 <recipe>，每个 recipe 独立子布局
  • recipe 生成槽位固定为 virtual，不参与真实菜单绑定

6. 运行时性能机制（2026-02-15）​

本轮 container/slot/recipe/runtime 合并后，运行时新增以下优化：

  1. Container Runtime Cache：
    • 首次 bind 后缓存 container 分区、全局槽位索引映射与分组结果；
    • needsRebind() 为 false 时直接复用，减少重复 DOM 扫描与分组。
  2. findSlotElement O(1)：
    • 通过全局槽位索引缓存直接命中 slot 元素；
    • 降低 hover 同步路径开销。
  3. 布局写回脏标记：
    • syncMenuSlotPositions 改为按脏触发；
    • 仅在 bind、relayout、recipe 预览变化 等场景同步，避免每帧重复写回。
  4. 容器级 metrics 缓存：
    • 缓存 slot-size / slot-gap / 默认背景候选 的解析结果；
    • 减少重复属性解析和背景探测。
  5. RecipePreviewCache 有界 LRU：
    • Recipe 预览缓存改为访问顺序 LRU；
    • 默认上限 256，避免长期运行内存膨胀。

7. 示例与触发入口​

  • minecraft:diamond -> run/apricity/test/index.html
  • minecraft:emerald -> run/apricity/test/saved_data.html
  • minecraft:amethyst_shard -> run/apricity/test/virtual_slots.html
  • minecraft:nether_star -> run/apricity/test/multi_recipe.html
  • minecraft:lapis_lazuli -> run/apricity/test/runtime_cache_dirty.html（运行时缓存/脏同步/LRU 压力示例）

示例片段（玩家容器）：

<container primary="true" bind="player" layout="preset:player" title="玩家背包">
  <div class="demo-title">玩家背包（首个 div 优先）</div>
  <slot mode="bound" repeat="36" slot-index="0"></slot>
</container>

<slot mode="virtual" item="minecraft:diamond" count="12" hover="示例物品"></slot>
<recipe recipe-id="minecraft:crafting_table"></recipe>