UI 界面
适用版本:中国版 3.10。仅中国版可用。
本文主要记录UI 界面相关的接口,共 34 个。
网易官方文档BindVirtualWorldModel
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
绑定虚拟世界中的模型。
- 说明
- 示例
BindVirtualWorldModel(bindToObjId: int, offset: Tuple[float, float, float]) -> bool
- bindToObjId: int,绑定的模型对象的 id。
- offset: Tuple[float, float, float],UI 与绑定实体的偏移量。
返回值:bool,是否修改成功 True:成功 False:失败。
备注
- 绑定的对象销毁时 UI 不会销毁,而是会隐藏起来,建议复用或者销毁。
# 若是被绑定的UI需要创建多份,则需要使用此方式进行创建:
uiNode=clientApi.CreateUI("modNamespace","testUI", {
"bindEntityId": clientApi.GetLocalPlayerId()
})
virtualWorldComp = clientApi.GetEngineCompFactory().CreateVirtualWorld(clientApi.GetLevelId())
virtualWorldComp.VirtualWorldCreate()
objId = virtualWorldComp.ModelCreateObject("datiangou", "run")
succ = uiNode.BindVirtualWorldModel(objId, (0.0, 0.0, 0.0))
ChangeBindAutoScale
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置已绑定实体的 UI 是否根据绑定实体与本地玩家间的距离动态缩放,只对已绑定实体的 UI 界面生效,如何将 UI 与实体绑定详见CreateUI接口。
- 说明
- 示例
ChangeBindAutoScale(autoScale: int) -> bool
- autoScale: int,1:动态缩放 0:不动态缩放。
返回值:bool,是否设置成功 True:成功 False:失败。
备注
- 注意:绑定实体的 UI 缩放仅作用于根节点(比如"main"节点)下的子节点。建议在根节点下挂载一个 panel 类型的节点,然后将所有需要缩放的 UI 节点设置为百分比属性并挂载在这个 panel 节点下。
succ = uiNode.ChangeBindAutoScale(1)
ChangeBindEntityId
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
修改绑定的实体 id,只对已绑定实体的 UI 界面生效,如何将 UI 与实体绑定详见CreateUI接口。
- 说明
- 示例
ChangeBindEntityId(entityId: str) -> bool
- entityId: str,绑定的实体 id。
返回值:bool,是否修改成功 True:成功 False:失败。
succ = uiNode.ChangeBindEntityId(entityId)
ChangeBindOffset
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
修改与绑定实体之间的偏移量,只对已绑定实体的 UI 界面生效,如何将 UI 与实体绑定详见CreateUI接口。
- 说明
- 示例
ChangeBindOffset(offset: Tuple[float, float, float]) -> bool
- offset: Tuple[float, float, float],偏移量。
返回值:bool,是否修改成功 True:成功 False:失败。
备注
- 不建议在第一人称视角下,将本地玩家绑定 UI 的偏移量设为(0, 0, 0)。
succ = uiNode.ChangeBindOffset((0, 3, 0))
Clone
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
克隆一个已有的控件,修改它的名称,并将它挂接到指定的父节点上,目前文本、图片、按钮控件的克隆控件表现正常,其他复杂控件的克隆控件可能存在运行问题,建议在 json 编写的过程中,手动复制一份对应控件使用。
- 说明
- 示例
Clone(
componentPath: str,
parentPath: str,
newName: str,
syncRefresh: bool = True,
forceUpdate: bool = True,
) -> bool
- componentPath: str,为从 main 节点开始的控件路径。
- parentPath: str,为从 main 节点开始,父节点的控件路径。
- newName: str,为克隆成功后创建的新控件名称,新控件的路径为 parentPath/newName。
- syncRefresh: bool,是否需要同步刷新,默认值为 True。置 True 为游戏在同一帧计算该控件的 Size 等相关数据,置 False 则在下一帧进行计算。如同一帧有大量 clone 操作建议置 False,操作结束后调用一次 UpdateScreen 接口刷新界面及相关控件数据。
- forceUpdate: bool,是否需要强制刷新,默认值为 True。置 True 则按照 syncRefresh 逻辑进行同一帧或者下一帧刷新,置 False 则当前帧和下一帧均不刷新,需要手动调用 UpdateScreen 进行刷新。如有大量 Clone 操作且非在同一帧执行,建议设置为 False,需要更新时再调用 UpdateScreen 接口刷新界面及相关控件数据。
返回值:bool,是否克隆成功。
# 克隆text2控件,重命名为text3并以panel为父控件
parentPath = "/panel"
text2Path = "/panel/text2"
text3Name = "text3"
uiNode.Clone(text2Path, parentPath, text3Name)
# 以panel为父控件,以text_prefab为模板克隆若干控件
parentPath = "/panel"
textPrefabPath = "/panel/text_prefab"
for i in range(0, 10):
uiNode.Clone(textPrefabPath, parentPath, "text" + str(i), False)
uiNode.UpdateScreen(True)
# 在非同一帧,以panel为父控件,text_prefab为模板克隆若干控件
parentPath = "/panel"
textPrefabPath = "/panel/text_prefab"
def _tickClone(newName):
uiNode.Clone(textPrefabPath, parentPath, newName , False, False)
def _tickUpdateScreen():
uiNode.UpdateScreen(True)
comp = clientApi.GetEngineCompFactory().CreateGame(levelId)
comp.AddTimer(100, _tickClone, "text1")
comp.AddTimer(200, _tickClone, "text2")
comp.AddTimer(300, _tickUpdateScreen)
Create
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
UI 生命周期函数,当 UI 创建成功时调用。
Create() -> Any
CreateChildControl
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
在当前画布中创建子控件,如果该子控件已经存在则返回已存在的子控件。
- 说明
- 示例
CreateChildControl(
defName: str,
childName: str,
parentControl: Optional[BaseUIControl] = None,
forceUpdate: bool = True,
) -> BaseUIControl
- defName: str,UI 控件路径,格式为"namespace.controlName"。namespace 对应 uiJson 文件中"namespace"对应的值,UI 编辑器生成的 uiJson 文件该值等于文件名。controlName 对应想创建的控件的名称。
- childName: str,所创建的子控件的名称。
- parentControl: Optional[BaseUIControl],指定所创建的子节点的父节点,默认值为 None,表示直接创建在当前画布根节点下。
- forceUpdate: bool,是否需要强制刷新,默认值为 True。置 True 则进行同一帧或者下一帧刷新,置 False 则当前帧和下一帧均不刷新,需要手动调用 UpdateScreen 进行刷新。如有大量 CreateChildControl 操作且在同一帧执行,建议设置为 False,需要更新时再调用 UpdateScreen 接口刷新界面及相关控件数据。
返回值:BaseUIControl,创建的子控件节点。
# 在父控件"/panel"下创建命名空间为"ui0"的自定义控件"myImage",并取名为"myChild"
parentControl = uiNode.GetBaseUIControl("/panel")
if parentControl:
childNode = uiNode.CreateChildControl("ui0.myImage", "myChild", parentControl, True)
print childNode
Destroy
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
UI 生命周期函数,当 UI 销毁时调用。
Destroy() -> Any
GetAllChildrenPath
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取所有子节点的路径 list。
- 说明
- 示例
GetAllChildrenPath(parentPath: str) -> List[str]
- parentPath: str,为从 main 节点开始,父节点的控件路径。
返回值:List[str],返回父节点下的子节点的路径,会递归返回所有子节点,若节点无子节点,返回空 list。
# get panel's all children path
node.GetAllChildrenPath("/panel")
GetBaseUIControl
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
根据路径获取 BaseUIControl 实例。
- 说明
- 示例
GetBaseUIControl(path: str) -> BaseUIControl
- path: str,当前控件的路径。
返回值:BaseUIControl,路径对应控件的 BaseUIControl 实例。
# 根据路径获得BaseUIControl实例
text2Path = "/panel/text2"
text2UIControl = uiNode.GetBaseUIControl(text2Path)
GetBindAutoScale
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取该绑定实体的 UI 是否动态缩放,未绑定的 UI 将传回默认值 1。
- 说明
- 示例
GetBindAutoScale() -> int
返回值:int,1:动态缩放 0:不动态缩放。
autoScale = uiNode.GetBindAutoScale()
GetBindEntityId
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取该 UI 绑定的实体 id,未绑定的 UI 将传回默认值 None。
- 说明
- 示例
GetBindEntityId() -> str
返回值:str,绑定的实体 id。
entityId = uiNode.GetBindEntityId()
GetBindOffset
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取该 UI 绑定实体的偏移量,未绑定的 UI 将传回默认值(0, 0, 0)。
- 说明
- 示例
GetBindOffset() -> Tuple[float, float, float]
返回值:Tuple[float, float, float],偏移量。
offset = uiNode.GetBindOffset()
GetBindWorldPosition
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取该 UI 绑定的 worldPosition,未绑定返回默认值 None。
- 说明
- 示例
GetBindWorldPosition() -> Tuple[int, Tuple[float, float, float]]
返回值:Tuple[int, Tuple[float, float, float]],(维度,(地点)),无设置则为 None。
position = uiNode.GetBindWorldPosition()
GetChildrenName
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取子节点的名称 list。
- 说明
- 示例
GetChildrenName(parentPath: str) -> List[str]
- parentPath: str,为从 main 节点开始,父节点的控件路径。
返回值:List[str],返回父节点下的子节点的名称,不会递归返回所有子节点,若节点无子节点,返回空 list。
# get panel's children name
node.GetChildrenName("/panel")
GetIsHud
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获得本界面的输入模式。
- 说明
- 示例
GetIsHud() -> int
返回值:int,返回 1 表示该界面不屏蔽游戏操作,返回 0 则屏蔽。
# 我们需要获得本界面的输入模式
isHud = uiNode.GetIsHud()
GetRichTextItem
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
返回一个富文本控件实例。
- 说明
- 示例
GetRichTextItem(componentPath: str) -> object
- componentPath: str,为从 main 节点开始,继承自 rich_text.RichTextPanel 控件的路径。
返回值:object,RichTextItem 返回一个富文本控件实例。
# we want get a rich-text-item
richTextPath = "/RichTextPanel"
richTextItem = uiNode.GetRichTextItem(richTextPath)
GetScreenName
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获得本界面的名称。
- 说明
- 示例
GetScreenName() -> str
返回值:str,返回本界面的名称。仅当该界面是调用 PushScreen 方法生成的时候才有返回值,返回值为注册 UI 时(调用 RegisterUI)所使用的参数 uiScreenDef,否则为 None。
# 我们需要获得本界面名称
screenName = uiNode.GetScreenName()
GetSelf
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
获取零件界面自身。
GetSelf() -> ScreenNode
返回值:ScreenNode,零件界面自身。
OnActive
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
UI 生命周期函数,当 UI 重新回到栈顶时调用。
OnActive() -> Any
备注
- 不建议使用在 OnDeactive 函数中调用 SetScreenVisible(False),在 OnActive 函数中调用 SetScreenVisible(True)的方式实现打开新界面时隐藏原界面,新界面关闭时自动显示原界面的功能,由于隐藏接口不会改动 UI 栈,多 Mod 容易形成冲突。推荐使用 PushScreen,PopScreen 接口实现。调用 OpenPauseGui、OpenChatGui、OpenInventoryGui 等原生 UI 函数弹出的 UI 被关闭时,不会调用此函数。
OnDeactive
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
UI 生命周期函数,当栈顶 UI 有其他 UI 入栈时调用。
OnDeactive() -> Any
备注
- 不建议使用在 OnDeactive 函数中调用 SetScreenVisible(False),在 OnActive 函数中调用 SetScreenVisible(True)的方式实现打开新界面时隐藏原界面,新界面关闭时自动显示原界面的功能,由于隐藏接口不会改动 UI 栈,多 Mod 容易形成冲突。推荐使用 PushScreen,PopScreen 接口实现。调用 OpenPauseGui、OpenChatGui、OpenInventoryGui 等原生 UI 函数时不会调用此函数。
RemoveChildControl
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
移除当前画布中的子控件。
- 说明
- 示例
RemoveChildControl(childControl: BaseUIControl) -> bool
- childControl: BaseUIControl,所要移除的子控件。
返回值:bool,True 表示移除成功,False 表示移除失败。
# 移除"/panel/myChild"控件
childControl = uiNode.GetBaseUIControl("/panel/myChild")
if childControl:
ret = uiNode.RemoveChildControl(childControl)
print ret
RemoveComponent
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
动态删除某一控件。
- 说明
- 示例
RemoveComponent(componentPath: str, parentPath: str) -> Any
- componentPath: str,为从 main 节点开始,被删除控件路径。
- parentPath: str,为从 main 节点开始,父节点的控件路径。
# we want to remove text2
text2Path = "/panel/text2"
parentPath = "/panel"
uiNode.RemoveComponent(text2Path, parentPath)
SetBindWorldPosition
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置 UI 绑定的 worldPosition。
- 说明
- 示例
SetBindWorldPosition(dimension: int, position: Tuple[float, float, float]) -> bool
- dimension: int,维度 id。
- position: Tuple[float, float, float],坐标。
返回值:bool,是否设置成功。
uiNode.SetBindWorldPosition(0, (100,60,100))
SetIsHud
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置本界面的输入模式。
- 说明
- 示例
SetIsHud(isHud: int) -> Any
- isHud: int,设置 1 表示该界面不屏蔽游戏操作,设置 0 则屏蔽。
备注
- CreateUI 的 isHud 参数设置为 0 或不传时,会在比当前 UI 的层级大 1000 的地方生成,生成后再调用 SetIsHud 接口无法再修改层级!
# 我们需要设置本界面为HUD操作模式
uiNode.SetIsHud(1)
SetRemove
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
删除本界面节点。
- 说明
- 示例
SetRemove() -> Any
# we want to remove this screen
uiNode.SetRemove()
SetScreenVisible
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置是否显示本界面。
- 说明
- 示例
SetScreenVisible(visible: bool) -> Any
- visible: bool,False 为隐藏该界面,True 为显示该界面。
# 我们隐藏当前UI的界面
uiNode.SetScreenVisible(False)
SetSelectControl
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置当前焦点所在的控件,当设置控件为文本输入框时会弹出系统小键盘。
- 说明
- 示例
SetSelectControl(componentPath: str, enable: bool) -> Any
- componentPath: str,为从 main 节点开始,所要选中控件的路径。
- enable: bool,True 为选中 componentPath 所代表的控件,False 为取消选中。
path = "/text_edit_box0"
uiNode.SetSelectControl(path, True)
SetStackGridCount
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置 StackGrid 控件的大小。
- 说明
- 示例
SetStackGridCount(componentPath: str, count: int) -> Any
- componentPath: str,为从 main 节点开始,Grid 控件的路径。
- count: int,设置 StackGrid 的内容数量。
# we want change stackgrid count
stackgridPath = "/stack_grid1"
uiNode.SetStackGridCount(stackgridPath, 3)
SetUiEntity
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置 PaperDoll 控件需要显示的生物模型,PaperDoll 控件的配置方式详见控件介绍 PaperDoll。
- 说明
- 示例
SetUiEntity(componentPath: str, entityIdentifier: str) -> Any
- componentPath: str,为从 main 节点开始的控件路径。
- entityIdentifier: str,生物定义中设定的 identifier。
备注
- 暂不支持的微软原版模型:minecraft:horse(马)、minecraft:donkey(驴)、minecraft:mule(骡子)、minecraft:skeleton_horse(骷髅马)、minecraft:zombie_horse(僵尸马)、minecraft:llama(羊驼)、minecraft:tropicalfish(热带鱼)、minecraft:slime(史莱姆)、minecraft:magma_cube(岩浆怪)、minecraft:ghast(恶魂)、minecraft:shulker(潜影贝)、minecraft:ender_dragon(末影龙)、minecraft:thrown_trident(三叉戟)、minecraft:ender_crystal(末影水晶)、minecraft:boat(船)、minecraft:tnt(TNT)。
# we want to show an entity model
imagePath = "/paper_doll0"
uiNode.SetUiEntity(imagePath, 'minecraft:cat')
SetUiModel
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置 PaperDoll 控件需要显示的模型,PaperDoll 控件的配置方式详见控件介绍 PaperDoll。
- 说明
- 示例
SetUiModel(componentPath: str, modelName: str, animateName: str = 'idle', looped: bool = True) -> bool
- componentPath: str,为从 main 节点开始的控件路径。
- modelName: str,骨骼模型的名称。
- animateName: str,动画名称,默认为'idle'。
- looped: bool,是否循环播放动画,默认为 True。
返回值:bool,是否设置成功。
# we want to change model
imagePath = "/paper_doll0"
uiNode.SetUiModel(imagePath, 'saber', 'idle', True)
SetUiModelScale
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
设置 PaperDoll 控件模型的缩放比例。
- 说明
- 示例
SetUiModelScale(componentPath: str, scale: float = 1.0) -> Any
- componentPath: str,为从 main 节点开始,PaperDoll 控件路径。
- scale: float,PaperDoll 的缩放比例,默认为 1.0。
备注
- 当设置为原版生物模型时会导致偏移,建议开发者自行调整位置。
imagePath = "/paper_doll0"
uiNode.SetUiModelScale(imagePath, 1.2)
Update
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
客户端每帧调用,1 秒有 30 帧。
Update() -> Any
UpdateScreen
客户端
界面方法,在自定义 ScreenNode 子类中直接调用。
刷新界面,重新计算各个控件的相关数据。
- 说明
- 示例
UpdateScreen(syncRefresh: bool = True) -> Any
- syncRefresh: bool,是否需要同步刷新,默认值为 True。置 True 为游戏在同一帧计算各个控件的相关数据,置 False 则在下一帧进行计算。若置 True 不建议在同一帧调用多次。
# 当前帧刷新界面
uiNode.UpdateScreen(True)
# 下一帧刷新界面
uiNode.UpdateScreen(False)