xiaokun/netease-bedrock-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9cd2bb07a092385f2966e7038613a7bd561ebc41
netease-bedrock-wiki/mcguide/9-规范开发/8-通用设置规范.md
MCNeteaseDevs e5ecce5841 [自动同步] 新增 2 个文件 - 2026-03-25 18:50:52
2026-03-25 18:50:53 +08:00

17 KiB
Raw Blame History

hard, time, selection
hard time selection
入门 15分钟 true

通用设置接口规范

欢迎使用由官方牵头，允许开发者通过接口快速注册设置选项的工具。

下面我们将介绍如何使用通用设置接口。

由于通用设置接口不更改引擎内容，可不需要跟整包更新，补全库更新后即可使用。

注册通用设置界面

我们首先需要获取通用设置接口的Comp组件，然后在Comp组件中使用RegisterSettingInst方法

comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(playerId)

# 第一个参数必须要填写 ItemID，我们强烈建议您先上传一个模组，获取到ItemID再进行开发。

# 后面两个参数是为了在 ModPC 中测试开发而引入的参数，在正式服中后面两个参数没有任何作用。

settingInst = comp.RegisterSettingInst("itemId", "模组1", "textures/ui/abc")

由于要传入 itemId，你需要先在开平上传一个模组，获取到 itemId，然后再通过此方法注册

由于页面注册的到的是 Cocos UI 页面，页面里的模组数据都是从开平上传的模组中获取的，所以才需要传入 itemId

由于ModPC不自带 Cocos UI 页面，所以需要传入后面两个参数，以便ModPC使用进行测试

注册控件

控件是指在设置页面中的设置选项，例如按钮、开关、输入框等

控件注册允许链式调用

if settingInst:

    # 允许链式调用，添加多个控件

    (settingInst
        .AddText("text_uid_01", "这是一段文字",5)
        .AddToggle("toggle_uid_01", "开关按钮", callbackFunction, 1, False)
        .AddToggle("toggle_uid_02", "开关按钮2", callbackFunction, 3, False)
        .AddToggle("toggle_uid_03", "开关按钮3", callbackFunction, 4, True)
        .AddInput("input_uid_01", "输入框", callbackFunction, 2, "神秘")
        .AddButton("button_uid_01", "按钮", "点击前往设置页面", callback, 2))

callbackFunction与callback是回调函数

def callbackFunction(*args):

    # args1 参数是 key 值，用于获取控件ID
    # args2 参数是 value 值，用于获取控件的当前值

    if settingInst.GetToggleDefault("toggle_uid_01"):

        #获取 控件1 的默认值，如果是True，则将默认值改成 False，下次打开页面就会显示False了

        #  settingInst.SetToggleDefault("toggle_uid_01", False)

        settingInst.SetLockSettingComp("toggle_uid_02", False)
        
    else:

        # 这里我们判断，如果从 False 改成 True了，我们还会给控件 toggle_uid_02 上锁

        # settingInst.SetToggleDefault("toggle_uid_01", True)

        settingInst.SetLockSettingComp("toggle_uid_02", True)

def callback(*args):

    # args1 参数是 key 值，用于获取控件ID
    # args2 参数是 value 值，用于获取控件的当前值

    comp.CloseSettingUI()

上述内容完成后您就成功注册了设置界面中的控件，并且可以通过设置页面中的按钮进行调用。

此时你就可以前往开发者测试服查看效果

alt text

设置页面集束在 暂停菜单 - 模组 中

我们不限制开发者必须把模组设置做在通用设置界面中，但设置入口一定要在这个界面中，减少玩家寻找模组设置的时间成本。

您可以只在通用设置界面注册一个按钮，点击按钮可以跳转到你们的设置页面中

疑难解答

Q1：怎么没有翻页功能？

A：为了确保与原本UI风格一致，我们没有做翻页功能，而是内置了滚动功能。

Q2：怎么不能加图片？

A：为了确保各开发者风格一致，我们没有做图片功能，以免开发者随心所欲添加图片造成设置界面杂乱无章

Q3：限制有点大，我不想用你们的设置怎么办？

A：我们不限制开发者使用自己的设置界面，但为了提高玩家体验，减少模组设置学习成本，开发者可以即使不适用官方提供的设置接口，也可以在这个页面注册按钮，允许玩家点击按钮打开开发者自己定义的设置界面中

接口速查

CloseSettingUI

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

  • 描述

    关闭模组信息界面

  • 参数

    无

  • 返回值

    数据类型
    		 说明
    bool 是否关闭成功

  • 备注

    • 该接口在modPC环境下，将是关闭局内json ui

  • 示例

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
# 关闭界面
result = comp.CloseSettingUI()

GetSettingInst

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

  • 描述

    获取当前模组的通用设置实例

  • 参数

    参数名
    数据类型
    		 说明
    modNamespace str 组件命名空间，需唯一性，仅在开发环境预览使用

  • 返回值

    数据类型
    		 说明
    SettingInst 返回实例对象，未注册则返回None

  • 备注

    • 请先使用RegisterSettingInst注册，再使用GetSettingInst获取。
    • 开发环境中，将会获取modNamespace对应的通用设置实例；正式环境中则仅能获取当前模组注册的实例。
    • 建议不要在__init__的时候就获取实例，过早获取会返回None。

  • 示例

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
settingInst = comp.GetSettingInst()
if settingInst:
    settingInst.AddText("text_uid_01", "这是一段文字").AddToggle("toggle_uid_01", "开关按钮", False, callbackFunction)

OpenSettingUI

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

  • 描述

    在模组信息界面中打开设置页面（此操作仅可访问本模组的配置选项）

  • 参数

    无

  • 返回值

    数据类型
    		 说明
    bool 是否打开成功

  • 备注

    • 该接口在modPC环境下，将是打开局内json ui

  • 示例

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
# 打开界面
result = comp.OpenSettingUI()

RegisterSettingInst

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

  • 描述

    注册通用设置实例

  • 参数

    参数名
    数据类型
    		 说明
    modNamespace str 组件命名空间，需唯一性，仅在开发环境预览使用
    modName str 组件名字，默认为None，仅在开发环境预览使用
    iconPath str 组件icon图路径，默认为None，仅在开发环境预览使用

  • 返回值

    数据类型
    		 说明
    SettingInst 返回实例对象，系统未初始化则返回None

  • 备注

    • 每个模组仅能注册一个通用设置实例，重复注册会返回同样的实例。
    • 建议在UiInitFinished触发时再注册，注册过早会导致注册失败而返回None。
    • 设置界面的注册是通过Scripts文件夹名称来判断是由哪个模组注册的实例，开发者的Scripts名称需要确保不与其他模组作者的Scripts名称冲突。

  • 示例

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
settingInst = comp.RegisterSettingInst("123456789", "模组1", "textures/ui/abc")
if settingInst:
    settingInst.AddText("text_uid_01", "这是一段文字").AddToggle("toggle_uid_01", "开关按钮", False, callbackFunction)

SettingInst 下的方法

AddText

添加文本控件。

def AddText(self, key, name, priority=None)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    priority int或None 显示顺序优先级，默认根据添加顺序排列

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

AddToggle

添加开关控件。

def AddToggle(self, key, name, callback, priority=None, default=False)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    callback function 控件的回调函数，定义：def callback(*args)
    priority int或None 显示顺序优先级，默认根据添加顺序排列
    default bool 默认值，默认为False

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

AddSlider

添加滑动条控件。

def AddSlider(self, key, name, step, callback, priority=None, default=0)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    step int 滑动条的最大值，范围：0~step
    callback function 控件的回调函数，定义：def callback(*args)
    priority int或None 显示顺序优先级，默认根据添加顺序排列
    default int 默认值，默认为0

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

AddDropDown

添加下拉选项控件。

def AddDropDown(self, key, name, options, callback, priority=None, default=None)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    options list[str] 下拉选项列表
    callback function 控件的回调函数，定义：def callback(*args)
    priority int或None 显示顺序优先级，默认根据添加顺序排列
    default str或None 默认选项，该值需在options中

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

AddInput

添加输入框控件。

def AddInput(self, key, name, callback, priority=None, default="")

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    callback function 控件的回调函数，定义：def callback(*args)
    priority int或None 显示顺序优先级，默认根据添加顺序排列
    default str 默认显示的文本，默认为空字符串

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

AddButton

添加按钮控件。

def AddButton(self, key, name, buttonText, callback, priority=None)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    name str 控件的文字描述
    buttonText str 按钮的文字描述
    callback function 控件的回调函数，定义：def callback(*args)
    priority int或None 显示顺序优先级，默认根据添加顺序排列

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

GetToggleDefault

获取开关控件的默认值。

def GetToggleDefault(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    bool 开关状态

GetInputDefault

获取输入框的默认输入文本。

def GetInputDefault(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    str 输入框的文本

GetDropDownDefault

获取下拉选项控件的默认值。

def GetDropDownDefault(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    str 默认选项在列表中的索引

GetSliderDefault

获取滑动条控件的默认值。

def GetSliderDefault(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    int 滑块的值

GetText

获取文字控件的文本。

def GetText(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    str 显示的文本

SetToggleDefault

设置开关控件的默认值。

def SetToggleDefault(self, key, value)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    value bool 开关的值

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetInputDefault

设置输入框控件的默认文本。

def SetInputDefault(self, key, value)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    value str 显示的文本

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetDropDownDefault

设置下拉选项控件的默认选项。

def SetDropDownDefault(self, key, option)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    option str 选项文字，如文字不在选项列表里，会自动添加到列表

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetSliderDefault

设置滑动条控件的默认值。

def SetSliderDefault(self, key, value)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    value int 滑块的值

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetButtonText

设置按钮控件的文字。

def SetButtonText(self, key, value)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    value str 显示的文字

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetText

设置文本控件的值。

def SetText(self, key, value)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    value str 显示的文本

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

SetLockSettingComp

设置锁定控件，锁定后无法点击。

def SetLockSettingComp(self, key, is_locked)

  • 参数

    参数名 数据类型 说明
    key str 控件id
    is_locked bool 是否锁定

  • 返回值

    数据类型 说明
    SettingInst 当前实例，支持链式调用

GetFormatData

获取当前实例的结构化数据，控件数据根据priority的值升序排序。

def GetFormatData(self)

  • 参数

    无

  • 返回值

    数据类型 说明
    dict 结构化数据

  • 返回格式

    {
    "modId": "str  // 模组ID",
    "name": "str  // 名称",
    "icon": "str  // 图标路径",
    "settings": "list  // 设置项列表，按priority升序排序"
}

GetSettingsControl

获取控件的结构化数据。

def GetSettingsControl(self, key)

  • 参数

    参数名 数据类型 说明
    key str 控件id

  • 返回值

    数据类型 说明
    dict 控件的结构化数据

GetModId

获取实例的modId。

def GetModId(self)

  • 参数

    无

  • 返回值

    数据类型 说明
    str 模组ID

GetAutoPriority

获取自动设置的优先级的值。

def GetAutoPriority(self)

  • 参数

    无

  • 返回值

    数据类型 说明
    int 当前自动优先级的值

  • 备注

    当添加控件时，如果不设置优先级，则会自动从0开始设置。优先级会影响控件排列顺序，升序排列。