Files
netease-bedrock-wiki/mcguide/9-规范开发/8-通用设置规范.md
2026-03-25 18:50:53 +08:00

789 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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