diff --git a/mcguide/9-规范开发/8-通用设置规范.md b/mcguide/9-规范开发/8-通用设置规范.md new file mode 100644 index 0000000..d9cd993 --- /dev/null +++ b/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 + +客户端 + +method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient + +- 描述 + + 关闭模组信息界面 + +- 参数 + + 无 + +- 返回值 + + |
数据类型
| 说明 | + | :--- | :--- | + | bool | 是否关闭成功 | + +- 备注 + - 该接口在modPC环境下,将是关闭局内json ui + +- 示例 + +```python +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。 + +- 示例 + +```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 + +客户端 + +method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient + +- 描述 + + 在模组信息界面中打开设置页面(此操作仅可访问本模组的配置选项) + +- 参数 + + 无 + +- 返回值 + + |
数据类型
| 说明 | + | :--- | :--- | + | bool | 是否打开成功 | + +- 备注 + - 该接口在modPC环境下,将是打开局内json ui + +- 示例 + +```python +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名称冲突。 + +- 示例 + +```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开始设置。优先级会影响控件排列顺序,升序排列。 + diff --git a/mcguide/9-规范开发/images/image.png b/mcguide/9-规范开发/images/image.png new file mode 100644 index 0000000..7e95b30 Binary files /dev/null and b/mcguide/9-规范开发/images/image.png differ