---
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开始设置。优先级会影响控件排列顺序，升序排列。