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

SettingsItem

想先跑起来？

这一页是签名与行为参考。开关/数值等控件声明，类型只有文档列出的几种。直接做一遍：教程 · 设置项与快捷键。

设置项描述器。它是无状态的——值 / 态由模组自行持久化（如经 ModContext.config()），宿主只按描述器渲染行并回调。

方法速览

方法	用途
`id()` / `labelKey()` / `type()`	身份、标签译键、组件类型
`anchorBefore()` / `anchorAfter()`	遗留定位字段（设置场景已忽略）
`targetCollection()`	`JUMP` / `JUMP_VALUE` 的跳转集合全键
`toValueText()` / `isOn()` / `tooltipKey()`	value 区文本 / 开关态 / 悬停提示
`onEnter()` / `onAdjust(int)`	激活 / 左右步进回调
`drawValue(RenderCanvas, boolean)`	`CUSTOM` 自绘 value 区
`staged()` / `isDirty()` / `onCommit()` / `onRevert()`	暂存（draft）协作
`persistedValue()` / `restorePersisted(Object)`	跨重启持久化

完整签名

java

public interface SettingsItem {

    enum Type {
        SWITCH,
        NUMBER,
        INPUT,
        JUMP,
        JUMP_VALUE,
        CUSTOM
    }

    String id();

    String labelKey();

    Type type();

    default String anchorBefore();

    default String anchorAfter();

    default String targetCollection();

    default String toValueText();

    default boolean isOn();

    default String tooltipKey();

    default void onEnter();

    default void onAdjust(int dir);

    default void drawValue(RenderCanvas canvas, boolean selected);

    default boolean staged();

    default boolean isDirty();

    default void onCommit();

    default void onRevert();

    default Object persistedValue();

    default void restorePersisted(Object value);
}

id() / labelKey() / type()

签名：

java

String id();

String labelKey();

Type type();

行为：

id() 为模组内唯一 id，宿主拼 模组id:id 为全键（持久化键则用点号形态 模组id.itemId）。
labelKey() 为标签译键（经 Translator.get，缺失时回退原文显示）。
type() 决定 value 区的渲染方式与交互，取值见下表。

`Type`	宿主渲染与交互
`SWITCH`	画原生开关，态取自 `isOn()`；回车 / 鼠标单击触发 `onEnter()`；不使用 `toValueText()`，不响应左右键
`NUMBER`	显示 `toValueText()`；左右键触发 `onAdjust(int)`；回车触发 `onEnter()`
`INPUT`	显示 `toValueText()`；回车触发 `onEnter()`（编辑态由模组自行维护）；不响应左右键（左右键让位给标签页切换）
`JUMP`	画 `>>>` 跳转引导；回车打开 `targetCollection()` 指定的集合，不调用 `onEnter()`；`targetCollection()` 为 `null` 时仅播放按键音
`JUMP_VALUE`	显示 `toValueText()`；左右键触发 `onAdjust(int)`；回车打开 `targetCollection()` 指定的集合（同样不调用 `onEnter()`）
`CUSTOM`	把 value 区矩形包装成 `RenderCanvas` 调 `drawValue(canvas, selected)` 由模组自绘；回车 / 单击触发 `onEnter()`

示例：

java

@Override
public Type type() {
    return Type.SWITCH;
}

anchorBefore() / anchorAfter()

签名：

java

String anchorBefore();

String anchorAfter();

行为：遗留字段——为 1.x 的「插入到指定原生设置项前 / 后」定位而设，设置场景已不再消费（签名保留、字段被忽略）。模组设置项一律归入模组自动标签页（见 SettingsExtension）。默认返回 null 表示不使用。

示例：

java

@Override
public String anchorBefore() {
    return null;   // 已无作用，保留默认即可
}

targetCollection()

签名：

java

String targetCollection();

行为：跳转集合目标全键（模组id:collectionId），仅 JUMP / JUMP_VALUE 使用。默认 null（不跳转）。

示例：

java

@Override
public String targetCollection() {
    return "mymod:advanced";
}

toValueText() / isOn() / tooltipKey()

签名：

java

String toValueText();

boolean isOn();

String tooltipKey();

行为：

toValueText()：NUMBER / INPUT / JUMP_VALUE 的 value 区文本，默认空串；SWITCH 不使用。
isOn()：SWITCH 的开关态，默认 false。
tooltipKey()：悬停提示译键，null 表示无提示。
三者均在渲染线程调用，应轻量且返回缓存结果（不要在此做 IO / 加锁等待）。

示例：

java

@Override
public String toValueText() {
    return String.valueOf(cfg.laneWidth());
}

@Override
public String tooltipKey() {
    return "mymod.settings.lane_width.tip";
}

onEnter()

签名：

java

void onEnter();

行为：行被激活时触发（回车或鼠标单击），在游戏线程执行。JUMP / JUMP_VALUE 不走本回调（宿主直接打开目标集合）。默认空实现。

示例：

java

@Override
public void onEnter() {
    cfg.setHintEnabled(!cfg.hintEnabled());   // 即时生效：自持久化
}

onAdjust(int dir)

签名：

java

void onAdjust(int dir);

行为：左右键步进回调，在游戏线程执行；dir = -1 左、+1 右。仅 NUMBER 与 JUMP_VALUE 会收到（INPUT 与其它类型不响应左右键）。默认空实现。

示例：

java

@Override
public void onAdjust(int dir) {
    cfg.setLaneWidth(Math.max(1, cfg.laneWidth() + dir));
}

drawValue(RenderCanvas canvas, boolean selected)

签名：

java

void drawValue(RenderCanvas canvas, boolean selected);

行为：CUSTOM 类型的 value 区自绘，在渲染线程执行。宿主已把画布坐标系平移到 value 区左上角，并按行高裁剪；selected 表示该行当前是否选中。默认空实现。

示例：

java

@Override
public void drawValue(RenderCanvas canvas, boolean selected) {
    canvas.setColor(selected ? java.awt.Color.ORANGE : java.awt.Color.GRAY);
    canvas.fillRect(0, 0, 40, 12);
}

staged() / isDirty() / onCommit() / onRevert()

签名：

java

boolean staged();

boolean isDirty();

void onCommit();

void onRevert();

行为：设置页底栏按桌面系统惯例工作（应用 = 提交当前改动不返回；确定 = 提交并返回；取消 = 丢弃未应用改动后返回）。模组项的值 / 态由模组自行持久化，宿主无法通用地读写 / 比较，故本组方法让模组可选择配合：

staged()：是否参与暂存。默认 false = 即时生效（交互立即落地、取消不回滚）。
isDirty()：暂存项相对「已应用值」是否有未提交改动（宿主据此决定「应用」按钮是否可用）；仅当 staged() 为 true 时由宿主在游戏线程调用，应轻量返回缓存结果。
onCommit()：宿主在「应用 / 确定」时调用，模组把当前值落地为新的「已应用值」（写 ModConfig 或自定义存储均可）。
onRevert()：宿主在「取消」时调用，模组丢弃自上次提交（或进入页面）以来的改动。

onCommit() / onRevert() 与 onEnter() 同在游戏线程触发；未申报 staged() 的项不会被调用。

示例：

java

private boolean staged;
private boolean draft;

@Override
public boolean staged() {
    return staged;
}

@Override
public boolean isDirty() {
    return draft != cfg.enabled();
}

@Override
public void onCommit() {
    cfg.setEnabled(draft);
}

@Override
public void onRevert() {
    draft = cfg.enabled();
}

persistedValue() / restorePersisted(Object value)

签名：

java

Object persistedValue();

void restorePersisted(Object value);

行为：

默认 persistedValue() 返回 null = 不参与持久化（值仍由模组自管，重启即丢）。
想跨重启保留的项应成对覆写：persistedValue() 返回当前应持久化的值（JSON 基元 Boolean / Number / String），restorePersisted(Object) 回填。
宿主在保存设置时把参与项的值写进 settings.json 的 mods 段（键 <modId>.<itemId>，点号形态）；启动装配（模组项注册后、设置页打开前）回填。值回填不是注册，不影响注册表冻结。
值经 JSON 往返后数值一律以 Number 形态到达（整数为 Long、小数为 Double），实现应做数值兼容（((Number) v).doubleValue()）而非硬转型。
单项回调异常由宿主隔离；覆盖范围含页面项、集合成员与自创页成员。
调用时机：persistedValue() 在游戏线程（保存时）调用；restorePersisted 在游戏线程（启动装配时）调用。两者都应轻量。

示例：

java

@Override
public Object persistedValue() {
    return cfg.laneWidth();          // Number
}

@Override
public void restorePersisted(Object value) {
    if (value instanceof Number n) {
        cfg.setLaneWidth(n.intValue());
    }
}

线程：isOn() / toValueText() / drawValue 在渲染线程调用；onEnter() / onAdjust(int) / staged() / isDirty() / onCommit() / onRevert() / persistedValue() / restorePersisted(Object) 在游戏线程调用。

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

上一页SettingsExtension 下一页GlobalHotkeys