[自动同步] 新增 2 个文件 - 2026-03-25 18:50:52

mcguide/9-规范开发/8-通用设置规范.md

@@ -0,0 +1,788 @@
+---
+hard: 入门
+time: 15分钟
+selection: true
+---
+
+# 通用设置接口规范
+
+欢迎使用由官方牵头，允许开发者通过接口快速注册设置选项的工具。
+
+下面我们将介绍如何使用通用设置接口。
+
+由于通用设置接口不更改引擎内容，可不需要跟整包更新，补全库更新后即可使用。
+
+## 注册通用设置界面
+
+我们首先需要获取通用设置接口的Comp组件，然后在Comp组件中使用`RegisterSettingInst`方法
+
+```python
+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使用进行测试
+
+## 注册控件
+
+控件是指在设置页面中的设置选项，例如按钮、开关、输入框等
+
+控件注册允许链式调用
+
+```python
+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`是回调函数
+
+```python
+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](./images/image.png)
+
+> 设置页面集束在 暂停菜单 - 模组 中
+
+我们不限制开发者必须把模组设置做在通用设置界面中，但设置入口一定要在这个界面中，减少玩家寻找模组设置的时间成本。
+
+您可以只在通用设置界面注册一个按钮，点击按钮可以跳转到你们的设置页面中
+
+## 疑难解答
+
+Q1：怎么没有翻页功能？
+
+A：为了确保与原本UI风格一致，我们没有做翻页功能，而是内置了滚动功能。
+
+Q2：怎么不能加图片？
+
+A：为了确保各开发者风格一致，我们没有做图片功能，以免开发者随心所欲添加图片造成设置界面杂乱无章
+
+Q3：限制有点大，我不想用你们的设置怎么办？
+
+A：我们不限制开发者使用自己的设置界面，但为了提高玩家体验，减少模组设置学习成本，开发者可以即使不适用官方提供的设置接口，也可以在这个页面注册按钮，允许玩家点击按钮打开开发者自己定义的设置界面中
+
+## 接口速查
+
+### CloseSettingUI
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient
+
+- 描述
+
+    关闭模组信息界面
+
+- 参数
+
+    无
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否关闭成功 |
+
+- 备注
+    - 该接口在modPC环境下，将是关闭局内json ui
+
+- 示例
+
+```python
+import mod.client.extraClientApi as clientApi
+levelId = clientApi.GetLevelId()
+comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
+# 关闭界面
+result = comp.CloseSettingUI()
+```
+
+
+
+### GetSettingInst
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient
+
+- 描述
+
+    获取当前模组的通用设置实例
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | modNamespace | str | 组件命名空间，需唯一性，仅在开发环境预览使用 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | SettingInst | 返回实例对象，未注册则返回None |
+
+- 备注
+    - 请先使用RegisterSettingInst注册，再使用GetSettingInst获取。
+    - 开发环境中，将会获取modNamespace对应的通用设置实例；正式环境中则仅能获取当前模组注册的实例。
+    - 建议不要在__init__的时候就获取实例，过早获取会返回None。
+
+- 示例
+
+```python
+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
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient
+
+- 描述
+
+    在模组信息界面中打开设置页面（此操作仅可访问本模组的配置选项）
+
+- 参数
+
+    无
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否打开成功 |
+
+- 备注
+    - 该接口在modPC环境下，将是打开局内json ui
+
+- 示例
+
+```python
+import mod.client.extraClientApi as clientApi
+levelId = clientApi.GetLevelId()
+comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
+# 打开界面
+result = comp.OpenSettingUI()
+```
+
+
+
+### RegisterSettingInst
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient
+
+- 描述
+
+    注册通用设置实例
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | modNamespace | str | 组件命名空间，需唯一性，仅在开发环境预览使用 |
+    | modName | str | 组件名字，默认为None，仅在开发环境预览使用 |
+    | iconPath | str | 组件icon图路径，默认为None，仅在开发环境预览使用 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | SettingInst | 返回实例对象，系统未初始化则返回None |
+
+- 备注
+    - 每个模组仅能注册一个通用设置实例，重复注册会返回同样的实例。
+    - 建议在UiInitFinished触发时再注册，注册过早会导致注册失败而返回None。
+    - 设置界面的注册是通过Scripts文件夹名称来判断是由哪个模组注册的实例，开发者的Scripts名称需要确保不与其他模组作者的Scripts名称冲突。
+
+- 示例
+
+```python
+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
+
+添加文本控件。
+
+```python
+def AddText(self, key, name, priority=None)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | name | str | 控件的文字描述 |
+    | priority | int或None | 显示顺序优先级，默认根据添加顺序排列 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### AddToggle
+
+添加开关控件。
+
+```python
+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
+
+添加滑动条控件。
+
+```python
+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
+
+添加下拉选项控件。
+
+```python
+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
+
+添加输入框控件。
+
+```python
+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
+
+添加按钮控件。
+
+```python
+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
+
+获取开关控件的默认值。
+
+```python
+def GetToggleDefault(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | bool | 开关状态 |
+
+---
+
+#### GetInputDefault
+
+获取输入框的默认输入文本。
+
+```python
+def GetInputDefault(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | str | 输入框的文本 |
+
+---
+
+#### GetDropDownDefault
+
+获取下拉选项控件的默认值。
+
+```python
+def GetDropDownDefault(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | str | 默认选项在列表中的索引 |
+
+---
+
+#### GetSliderDefault
+
+获取滑动条控件的默认值。
+
+```python
+def GetSliderDefault(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | int | 滑块的值 |
+
+---
+
+#### GetText
+
+获取文字控件的文本。
+
+```python
+def GetText(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | str | 显示的文本 |
+
+---
+
+#### SetToggleDefault
+
+设置开关控件的默认值。
+
+```python
+def SetToggleDefault(self, key, value)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | value | bool | 开关的值 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetInputDefault
+
+设置输入框控件的默认文本。
+
+```python
+def SetInputDefault(self, key, value)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | value | str | 显示的文本 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetDropDownDefault
+
+设置下拉选项控件的默认选项。
+
+```python
+def SetDropDownDefault(self, key, option)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | option | str | 选项文字，如文字不在选项列表里，会自动添加到列表 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetSliderDefault
+
+设置滑动条控件的默认值。
+
+```python
+def SetSliderDefault(self, key, value)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | value | int | 滑块的值 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetButtonText
+
+设置按钮控件的文字。
+
+```python
+def SetButtonText(self, key, value)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | value | str | 显示的文字 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetText
+
+设置文本控件的值。
+
+```python
+def SetText(self, key, value)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | value | str | 显示的文本 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### SetLockSettingComp
+
+设置锁定控件，锁定后无法点击。
+
+```python
+def SetLockSettingComp(self, key, is_locked)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+    | is_locked | bool | 是否锁定 |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | SettingInst | 当前实例，支持链式调用 |
+
+---
+
+#### GetFormatData
+
+获取当前实例的结构化数据，控件数据根据priority的值升序排序。
+
+```python
+def GetFormatData(self)
+```
+
+- 参数
+
+    无
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | dict | 结构化数据 |
+
+- 返回格式
+
+    ```json
+    {
+        "modId": "str  // 模组ID",
+        "name": "str  // 名称",
+        "icon": "str  // 图标路径",
+        "settings": "list  // 设置项列表，按priority升序排序"
+    }
+    ```
+
+---
+
+#### GetSettingsControl
+
+获取控件的结构化数据。
+
+```python
+def GetSettingsControl(self, key)
+```
+
+- 参数
+
+    | 参数名 | 数据类型 | 说明 |
+    | :--- | :--- | :--- |
+    | key | str | 控件id |
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | dict | 控件的结构化数据 |
+
+---
+
+#### GetModId
+
+获取实例的modId。
+
+```python
+def GetModId(self)
+```
+
+- 参数
+
+    无
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | str | 模组ID |
+
+---
+
+#### GetAutoPriority
+
+获取自动设置的优先级的值。
+
+```python
+def GetAutoPriority(self)
+```
+
+- 参数
+
+    无
+
+- 返回值
+
+    | 数据类型 | 说明 |
+    | :--- | :--- |
+    | int | 当前自动优先级的值 |
+
+- 备注
+
+    当添加控件时，如果不设置优先级，则会自动从0开始设置。优先级会影响控件排列顺序，升序排列。
+