API 参考 / 能力接口（capability 包）

SettingsExtension

想先跑起来？

这一页是签名与行为参考。在设置界面加自己的控件。直接做一遍：教程 · 设置项与快捷键。

设置场景扩展能力：让模组把设置项直接嵌入原生设置场景的页面列表 / 集合面板，玩家在统一设置入口即可调整。与 Mod.createConfigScene() 的「独立配置场景」不同。经 UiCustomization.settings() 获取（挂在 UI 定制能力下，避免入口分散）。

方法速览

方法	用途
`addCollection(String, String)`	注册一个设置集合（钻取子页）
`addTab(String, String)`	注册一个模组自创标签页
`addItem(SettingsItem)`	注册页面设置项（归入模组自动标签页）
`addCollectionItem(String, SettingsItem)`	向指定集合追加设置项
`removeItem(SettingsItem)`	移除已注册的设置项
`NOOP_TAB`	宿主未实现 `addTab` 时的空操作句柄

完整签名

java

public interface SettingsExtension {

    CollectionHandle addCollection(String id, String titleKey);

    default TabHandle addTab(String id, String titleKey);

    TabHandle NOOP_TAB;

    SettingHandle addItem(SettingsItem item);

    SettingHandle addCollectionItem(String collectionId, SettingsItem item);

    void removeItem(SettingsItem item);

    interface SettingHandle {

        void remove();
    }

    interface TabHandle {

        void addItem(String afterKey, SettingsItem item);

        void remove();
    }

    interface CollectionHandle {

        void addItem(String afterKey, SettingsItem item);

        void remove();
    }
}

addCollection(String id, String titleKey)

签名：

java

CollectionHandle addCollection(String id, String titleKey);

行为：注册一个设置集合，返回句柄用于追加项 / 移除。集合 id 为模组内唯一，全键为 模组id:id；设置项的 targetCollection() 指向该全键即可实现「跳转集合」。

id 为 null 或空串抛 IllegalArgumentException。
同 id 重复注册属幂等：复用既有集合，titleKey 非 null 时更新标题。
titleKey 为译键（缺失时回退原文显示）；传 null 时保留原值 / 空串。
呈现形式由宿主决定：接口只声明"集合里有哪些项、标题叫什么"，当前宿主把它呈现为「设置页内的钻取子页」（进入时替换页面内容并给出面包屑，可逐层返回）。集合成员项的语义与页内设置项完全一致。
集合成员不占标签页；只能经 JUMP / JUMP_VALUE 项钻取抵达。

示例：

java

SettingsExtension.CollectionHandle col =
        ctx.uiCustomization().settings().addCollection("advanced", "mymod.collection.advanced");

addTab(String id, String titleKey)

签名：

java

default TabHandle addTab(String id, String titleKey);

行为：注册一个模组自创标签页，返回页句柄；页内成员经 TabHandle.addItem(afterKey, item) 追加，remove() 移除整页（含其已注册项）。

顺序 / 位置由宿主决定：模组页一律排在全部宿主页与自动页之后，多页之间按注册顺序（先注册的在前）。
id 为 null 或空串抛 IllegalArgumentException（宿主实现）；同 id 重复注册复用该页，titleKey 非 null 时更新标题。
titleKey 为译键（缺失时回退原文显示）。
呈现形式由宿主决定：当前宿主把整页渲染为一个分节，分节标题取 titleKey。
加性 default：未实现该方法的宿主返回 NOOP_TAB（空操作句柄），模组应据此认为「该页没有建起来」而不是崩溃。

示例：

java

SettingsExtension.TabHandle page =
        ctx.uiCustomization().settings().addTab("tools", "mymod.tab.tools");
page.addItem(null, myProbeItem);

NOOP_TAB

签名：

java

TabHandle NOOP_TAB;

行为：空操作标签页句柄（addItem / remove 均不做事），是 addTab 的默认返回值。存在的原因是 addTab 必须是 default（1.x 只增不破），而返回 null 会让直接调用 addItem 的模组触发 NPE。

示例：

java

SettingsExtension.TabHandle page = ext.addTab("tools", "mymod.tab.tools");
page.addItem(null, item);   // 旧宿主：静默无效，不抛异常

addItem(SettingsItem item)

签名：

java

SettingHandle addItem(SettingsItem item);

行为：注册一个页面设置项。落点现状：注册的页面项一律归入该模组的自动标签页——有页面项的模组各得一页，标题 = 模组显示名（未注册模组回退模组 id）；自动页排在宿主页之后、显式自创页（addTab）之前；无页面项的模组不产生页。

item 为 null 或 item.id() 为空抛 IllegalArgumentException。
全键为 模组id:itemId；同键重复注册属幂等（替换描述器）。
SettingsItem.anchorBefore() / anchorAfter() 为遗留字段、设置场景已忽略（见 SettingsItem）。
返回句柄 remove() 可移除该项（下次进入设置场景 / 渲染帧生效）。

示例：

java

SettingsExtension ext = ctx.uiCustomization().settings();
ext.addItem(new MySwitchItem(cfg));

addCollectionItem(String collectionId, SettingsItem item)

签名：

java

SettingHandle addCollectionItem(String collectionId, SettingsItem item);

行为：向指定集合追加一个设置项。

collectionId 是集合全键（模组id:collectionId），不是模组内 id；传 null 抛 IllegalArgumentException。
item 为 null 或 id 为空抛 IllegalArgumentException。
集合不存在时抛 IllegalArgumentException("集合不存在: ...")。
项的全键为调用方模组 id + : + item.id()；同键在集合内重复加入属幂等（替换）。
返回句柄 remove() 只移除该项的注册（含集合成员身份），幂等。

示例：

java

ext.addCollectionItem("mymod:advanced", new MyNumberItem(cfg));

removeItem(SettingsItem item)

签名：

java

void removeItem(SettingsItem item);

行为：移除某个已注册的设置项（页面项、集合成员、自创页成员三处一并清理）。只有实例本身相同的注册项会被移除；item 为 null 时无操作；幂等。宿主在模组停用时也会自动清理。

示例：

java

ext.removeItem(myItem);

SettingHandle.remove()

签名：

java

void remove();

行为：移除 addItem / addCollectionItem 返回句柄对应的设置项，下次进入设置场景 / 渲染帧生效；幂等。

示例：

java

SettingsExtension.SettingHandle h = ext.addItem(item);
h.remove();

TabHandle.addItem(String afterKey, SettingsItem item)

签名：

java

void addItem(String afterKey, SettingsItem item);

行为：向该自创页追加设置项。afterKey 置空（null / 空串）为追加到末尾；否则插入到该锚点之后——锚点可以是页内既有项的全键，也可以是它的模组内 id（两者都匹配不到时追加到末尾）。item 为 null 或 id 为空抛 IllegalArgumentException；页已被移除时抛 IllegalArgumentException("标签页不存在: ...")。同键重复加入属幂等（替换并保持位置）。

示例：

java

page.addItem("firstItem", secondItem);   // 排在 firstItem 之后

TabHandle.remove()

签名：

java

void remove();

行为：移除整个标签页（含其已注册项），幂等。

示例：

java

page.remove();

CollectionHandle.addItem(String afterKey, SettingsItem item)

签名：

java

void addItem(String afterKey, SettingsItem item);

行为：向该集合追加设置项。afterKey 置空为追加到末尾；否则插入到该锚点之后（锚点可为集合成员的全键或模组内 id，均匹配不到时追加到末尾）。

item 为 null 或 id 为空抛 IllegalArgumentException；集合已被移除时抛 IllegalArgumentException("集合不存在: ...")。
项的全键使用集合所属模组的 id（即创建集合时的模组）。
同键重复加入属幂等（替换并保持位置）。

示例：

java

col.addItem(null, mySwitch);

CollectionHandle.remove()

签名：

java

void remove();

行为：移除整个集合（含其成员），幂等。集合成员不进入页面项表，因此不会在标签页留下空页。

示例：

java

col.remove();

线程：注册 / 更新 / 移除任意线程可调用（宿主注册表以 synchronized 保护）；交互回调（SettingsItem.onEnter()、SettingsItem.onAdjust(int)）在游戏线程触发。

生命周期：模组停用或游戏退出时宿主自动清理注册项，模组无需（也不应在 onUnload 中逐个 remove）。

稳定性：2.0 起冻结：2.x 内只增不破。

上一页CursorState 下一页SettingsItem