下载开发工作台 下载课程到本地
[退出]
返回首页

扫一扫关注
开发者QQ频道

扫一扫关注
微信公众号

扫一扫关注
网易大神

扫一扫关注
开发者B站

开发者论坛

问题反馈

登录

18-界面与交互 > 30-UI说明文档
搜索

# UI说明文档

# 文件命名说明

  • json文件名 json中的namespace python文件名 三者需要一致

  • 示例中为"myUIName"

    myUIName.json

    "namespace" : "myUIName"

    myUIName.py

# JSON编写说明

Json是UI界面的显示内容和绑定的集合，UI是一种树状的组织结构，界面和界面中的控件都是一个UI Node节点，后续的很多方法的调用也需要这个树状结构的路径来标识。

  • 注：目前MCStudio已提供UI编辑器，开发者可以在UI编辑器内对界面进行可视化编辑，并导出可以使用的json文件。各个控件在UI编辑器中的使用介绍将在下文中详细介绍。

# 命名空间

命名空间是这个界面的名称，我们规定json文件名和namespace一致。

	"namespace" : "myUIName"

# Main Screen

main是这个界面名称，我们规定使用main，即一个json文件是一个界面。

controls中的内容是该界面下的树状节点，即子节点。

	"main@common.base_screen" : {
		"controls" : [
		]
	}
变量 解释
main@common.base_screen 表示main screen是common.base_screen的一个子类
my_namespace
|____main
     |test_image
	 |test_panel
              |test_label
  • 关于控件的适配问题，固定大小像素能在屏幕像素发生变化时保持形状大小不变，而百分比则能够保持与屏幕分辨率一致的比例，可能导致控件变形。

# 特殊情况下的根节点路径变化

一般地，在使用UI API时，对某控件进行操作时我们需要通过传入该控件相对于展示screen的相对路径来对控件实例进行操作，例如如下UI界面结构

my_namespace
| main
	| panel0
		| text0

text0的路径为

path = "/panel0/text0"

但是当展示screen为了使用原生的功能而继承了common.base_screen时，部分功能的生效会伴随着根节点路径的修改，因此在使用UI API时控件的路径都发生了变化。

# 适配异形屏

为了适配异形屏，我们可以展示screen中的内容通过引用的形式写在screen的$screen_content属性中。

	"main@common.base_screen" : {
		"$screen_content":"myUIName.panel0"
    },
    "panel0":{
        "controls" : [
            {
                "text0@myUIName.text0" : {}
            }
        ],
        "type" : "panel"
    },
    "text0" : {
      "text" : "Hello World!",
      "type" : "label",
      "visible" : true
   }

被$screen_content引用的内容，其显示内容的范围不会被异形屏遮挡。此时text0的路径为

base_path = "/variables_button_mappings_and_controls/safezone_screen_matrix/inner_matrix/safezone_screen_panel/root_screen_panel"
path = base_path + "/text0"

可见控件的路径相对于展示screen的相对路径前还需要加上base_path路径才能正确拿到对应text0控件的路径，有关text0的api才会生效。

# 控件介绍

# screen

screen，即画布控件，是游戏中一个UI界面的根节点，所有其他控件只有挂在画布下才能被正确显示出来。

"main1" : {
      "absorbs_input" : true,
      "always_accepts_input" : false,
      "controls" : [
         {
            "label0@test.label0" : {}
         }
      ],
      "force_render_below" : false,
      "is_showing_menu" : true,
      "render_game_behind" : true,
      "render_only_when_topmost" : true,
      "should_steal_mouse" : false,
      "type" : "screen"
   },
   "main2@common.base_screen" : {
      "$screen_content" : "test.netease_editor_root_panel_base_screen0",
      "absorbs_input" : true,
      "always_accepts_input" : false,
      "force_render_below" : false,
      "is_showing_menu" : true,
      "render_game_behind" : true,
      "render_only_when_topmost" : true,
      "should_steal_mouse" : false
   },
   "netease_editor_root_panel_base_screen0" : {
      "anchor_from" : "top_left",
      "anchor_to" : "top_left",
      "controls" : [
         {
            "label1@test.label1" : {}
         }
      ],
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "size" : [ "100%", "100%" ],
      "type" : "panel",
      "visible" : true
   }
变量
 解释
type 当前控件类型
absorbs_input 是否阻挡输入，默认值为true，置false时方向键生效
always_accepts_input 是否始终接受鼠标事件，默认值为false，置true时该界面不在堆栈顶部也可以接受事件
force_render_below 是否渲染下方的界面，默认值为false，置true时被该界面覆盖的界面也会被渲染
is_showing_menu 是否是非常驻UI界面，默认为true，置false时该界面不会影响hud_screen的渲染
render_game_behind 是否在该界面创建时依然渲染游戏，默认值为true，置false时该界面创建时游戏界面定格
render_only_when_topmost 是否仅在堆栈顶部时渲染，默认值为true，置false时即使该界面被其他界面覆盖也会被渲染
should_steal_mouse 是否隐藏鼠标，默认值为false，置true时该界面被创建时将不会出现鼠标
gamepad_cursor_deflection_mode 是否开启手柄光标偏转模式，默认值为false，主要用于手柄适配轮盘控件
$screen_content 当该画布继承自common.base_screen时生效，会将该属性对应的控件作为该画布的内容显示，该内容将会适配异形屏
  • 注

always_accepts_input，force_render_below， render_game_behind， render_only_when_topmost属性仅在调用PushScreen接口创建UI时才会正常生效。

absorbs_input暂时无法生效，等待后续修复。

下图为UI编辑器中画布属性编辑面板

画布属性

变量
 解释
始终支持按键 对应always_accepts_input字段
创建时运行游戏 对应render_game_behind字段
强制持续渲染 对应force_render_below字段
仅在顶层渲染 对应render_only_when_topmost字段
继承基类画布 是否继承基类控件，若勾选，UI编辑器会自动创建一个不可见的，以netease_editor_root_panel开头的panel，并将该画布的内容放置在该panel下，并将$screen_content属性代表的控件指向该panel。继承基类控件后，画布内容将会适配异形屏。

# 通用属性

通用属性是每个控件都支持编辑的属性，对每个控件的位置、大小等基本属性进行设置。

变量
 解释
anchor_from 挂接在父节点锚点的位置，取值范围["top_left", "top_middle", "top_right", "left_middle", "center", "right_middle", "bottom_left", "bottom_middle", "bottom_right"]
anchor_to 自身挂接锚点的位置，取值同anchor_from
layer 当前控件相对父节点的层级，最终显示层级取决于父节点到该节点的layer之和
offset 自身相对父节点的偏移，值为百分比+像素(1个像素等于屏幕上3个像素)
size 相对父节点的大小，取值同offset
max_size 最大尺寸，取值同offset。当该控件尺寸可变时，最大不能超过该属性配置的尺寸
min_size 最小尺寸，取值同offset。当该控件尺寸可变时，最小不能小于该属性配置的尺寸
clips_children 裁剪子控件，取值bool值，开启后该控件范围外的子控件将不会被渲染
clip_offset 裁剪偏移，取值[x,y]。当开启裁剪子控件后，用来调整裁剪范围的偏移
alpha 透明度，取值0-1.0。调整控件的透明度
propagate_alpha 透明度传递，取值bool。该控件的透明度是否会影响子控件
enable 是否可交互，取值bool。关闭该属性后按钮等控件变得不可交互
type 当前控件类型
visible 默认是否显示，true为显示，false为不显示

下图为UI编辑器中控件的通用属性编辑面板

通用属性

变量
 解释
锚点 左右两侧的按钮组分别代表anchor_from字段和anchor_to字段的值，从左到右从上到下依次代表取值范围中["top_left", "top_middle", "top_right", "left_middle", "center", "right_middle", "bottom_left", "bottom_middle", "bottom_right"]的其中一个
名称 改变控件的名称，只接受字母、数字、下划线的组合
隐藏控件 对应visible字段，设置visible属性会实时的反映在UI编辑器左侧的控件结构窗口里
层级 对应layer字段， 当UI编辑器关闭自动层级调整功能时，该属性会在属性窗口中出现。该属性仅支持正整数。
位移X 对应offset字段的第一个数据，用于控制该控件相对于锚点位置的偏移。位移的形式为%+Px，Px表示像素，%表示百分比跟随，以位移X为例，跟随有["无", "父控件尺寸X", "最大兄弟控件尺寸X", "子控件尺寸X", "最大子控件尺寸X", "尺寸Y"]选项。详情见注。点击"PX"和"%"按钮将实现百分比跟随和像素的相互转换。
位移Y 对应offset字段的第二个数据，用于控制该控件相对于锚点位置的偏移，和位移X组成该控件的offset属性
尺寸X 对应size字段的第一个数据，配置形式同位移，界面和位移属性基本相同，不同在“适应”属性勾选框。勾选后尺寸的宽度将适应该控件的内容，如Label控件的文本内容或图片控件的图片宽度，生成的json中尺寸样式为"default"
最大尺寸 对应max_size字段。
最小尺寸 对应min_size字段。
裁剪内容 对应clips_children字段。
裁剪偏移 对应clip_offset字段。
透明度 对应alpha字段。若勾选影响子控件，则会将该控件的propagate_alpha属性置True，繁殖则置False
交互 对应enable字段。
可被继承 若勾选可被继承，则该控件可以被继承控件继承使用，反之则不能被继承。勾选后，该控件会生成在json文件的最外层，和main处在同一层级，即一个命名空间下唯一，不勾选则生成在该控件父节点的controls字段中

注 以位移X为例的跟随选项解释

选项
 解释
无 无跟随，仅Px生效，生成json中位移样式类似"100px"或100
父控件尺寸X 跟随父控件的宽度，生成json中位移样式类似"100%+100px"
最大兄弟控件尺寸X 跟随其兄弟控件中控件宽度最大控件的宽度,选中后百分比将锁定为100，生成json中位移样式类似"100%sm+100px"
子控件尺寸X 跟随子控件的宽度之和，生成json中位移样式类似"100%c+100px"
最大子控件尺寸X 跟随其子控件中控件宽度最大控件的宽度,选中后百分比将锁定为100，生成json中位移样式类似"100%cm+100px"
尺寸Y 跟随自身控件的高度，生成json中位移样式类似"100%y+100px"

位移Y，尺寸X， 尺寸Y类似

# Label

Label 是文本框控件，用来显示文本信息，默认的字体是MC字体，如果有中文会变成中文字体格式，暂时不支持换字体，可以通过接口统一设置字体，如果需要设置后续有介绍。

  "label0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "color" : [ 1, 1, 1 ],
      "font_scale_factor" : 1.0,
      "font_size" : "normal",
      "font_type" : "smooth",
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "shadow" : false,
      "size" : [ 100, 100 ],
      "text" : "Hello World!",
      "text_alignment" : "center",
      "line_padding" : 0.0,
      "type" : "label",
      "visible" : true
   },
变量
 解释
color 字体颜色（r , g, b, a）取值范围[0 , 1]
font_size 字体大小，取值["large", "normal", "small"]
font_scale_factor 字体缩放比例
shadow MC自带的字体阴影，true为显示，false则不显示
text 该Label显示的内容，可以通过后续的API在代码中设置该值
text_alignment Label中文字的对齐方式，取值为["left", "center", "right"]
line_padding 行间距，可以设置每行文字之间的间距
font_type 字体，取值["smooth", "unicode", "default", "rune"]

下图为UI编辑器中文本控件的属性编辑面板

控件表现

属性编辑

变量
 解释
内容 对应text字段，支持任何形式的文本
显示投影 对应shadow字段
字体 对应font_type字段，可以修改文本的字体。需要注意的是当文本中出现中文时，该字体显示将强制转为unicode，该属性将不会生效。
对齐 对应text_alignment字段，左中右对应["left", "center", "right"]数据
文本颜色 对应color字段，点击按钮弹出颜色选择窗口，可以在调色板上取色或者使用吸管吸取界面上的颜色
字号 对应font_size和font_scale_factor字段，以一定的规则同时设置两个字段达到字号的效果
行间距 对应line_padding字段

注

由于游戏的UI框架遵循整数倍缩放, 不同分辨率的机型，其缩放倍率和表现存在些微区别，其中文本控件受影响较大，当字体大小较小时会出现部分机型文字显示模糊的情况。经过测试，在UI编辑器中字体大小定为8及以上

最小字体

即属性font_size为normal，font_scale_factor为1.0及以上时

最小字体

该文字在任何机型上都不会模糊。当字体大小小于这个标准时，将不保证该文字在任意机型下都能清晰显示。

由于格式控制符的存在，文本中尽量不要使用“%”。若一定需要显示“%”，应当在代码中输入"%%%%"方可生效。

# Image

Image是指图片控件，具有图片裁剪，图片九宫格，颜色叠加，uv偏移，旋转显示的额外属性。

   "image0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "is_new_nine_slice" : false,
      "layer" : 2,
      "nine_slice_buttom" : 0,
      "nine_slice_left" : 0,
      "nine_slice_right" : 0,
      "nine_slice_top" : 0,
      "offset" : [ 0, 0 ],
      "size" : [ 100, 100 ],
      "texture" : "textures/netease/common/image/default",
      "nineslice_size" : [ 0, 0, 0, 0 ],
      "grayscale" : false,
      "keep_ratio" : true,
      "clip_direction" : "left",
      "clip_ratio" : 0.0,
      "type" : "image",
      "uv" : [ 0, 0 ],
      "uv_size" : [ 107, 107 ],
      "rotate_pivot": [0.5, 0.5],
      "rotate_angle": 0,
      "visible" : true
   },
变量
 解释
texture 贴图的路径，该路径从resouce_pack中的textures目录开始
uv uv坐标的初始值为[0, 0]。uv坐标为[x,y]表示图片控件以所选图片左上角为原点，偏移(x,y)像素开始截取图片。
uv_size uv尺寸表示需要显示的尺寸，默认值为图片的宽高。uv尺寸为[x,y]表示图片控件将截图x*y像素的图片范围显示在控件中。
keep_ratio 保持宽高比。取值bool。
grayscale 是否去色，取值bool。勾选后该图片变为黑白图片。
clip_direction 裁剪方向，取值范围["left", "right", "up", "down", "center"]
clip_ratio 裁剪尺寸,取值范围0-1.0。0表示不裁剪，1表示完全裁剪，即该控件不渲染
is_new_nine_slice 设置为true标记该图片开启九宫格显示的功能，与下方的nine_slice_bottom,nine_slice_left,nine_slice_right,nine_slice_top共同设置旧版九宫属性
nine_slice_bottom 切片距离下边的距离，默认值为0
nine_slice_left 切片距离左边的距离，默认值为0
nine_slice_right 切片距离右边的距离，默认值为0
nine_slice_top 切片距离上边的距离，默认值为0
nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。当设置了旧版九宫属性时优先旧版属性。该值支持数组和单个数字，数组代表[left,top,right,down]九宫属性，单个数值代表上下左右均采用该数值作为九宫属性，当四个方向的数值均为0时表示不开启原版九宫
rotate_pivot 旋转锚点，数值类型为[float, float]，默认值为[0.5, 0.5]，具体见下文旋转说明
rotate_angle 旋转角度，数值类型为float，默认值为0，具体见下文旋转说明

当Image控件进行旋转操作时，它是以旋转锚点为基准进行变换，而rotate_pivot是用来计算控件旋转锚点坐标的属性。旋转锚点坐标系的原点位于控件的左上角，X轴正方向向右，Y轴正方向向下（和图像坐标系一样）。rotate_pivot属性的值是一个二维向量，取值范围不限，实际的 旋转锚点的坐标 =（控件的x坐标 + rotate_pivot[0] * 控件的宽度， 控件的y坐标 + rotate_pivot[1] * 控件的高度)，比如(0,0)表示控件的左上角，(1,1)表示控件的右下角。

这是以左上角作为旋转锚点的旋转，rotate_pivot = (0, 0)

旋转1

这是以右上角作为旋转锚点的旋转，rotate_pivot = (1, 0)

旋转2

旋转锚点不仅仅是在图片内，也可以去到图片外，需要注意的是，旋转这个变换是最后作用的变换，图片控件先是算出当前的位置大小，再根据当前的位置大小算出旋转锚点，然后再应用旋转，并且这个旋转也只是视觉上的旋转，并不是控件真实的位置发生了改变（红框才是控件本身的位置信息和大小信息）。明白这点后，我们可以用一些常见例子来完成一些复杂的效果，比如给一张旋转的图添加水平运动动画。

旋转3

json如下：

{
   "main" : {
      "controls" : [
         {
            "panel":
            {
               "size": [200, 200],
               "controls": [
                  {
                     "testImage@UIDemo.image": {}
                  }
               ],
               "type": "panel"
            }
         }
      ],
      "type" : "screen"
   },
    "image" : {
      "layer": 3,
      "size": [ 100, 100 ],
      "offset": "@UIDemo.animation_in",
      "texture": "textures/netease/common/image/default",
      "is_new_nine_slice": false,
      "nine_slice_buttom" : 0,
      "nine_slice_left" : 0,
      "nine_slice_right" : 0,
      "nine_slice_top" : 0,
      "nineslice_size" : [0, 0, 0, 0],
      "type": "image"
    },
    "animation_in": {
      "anim_type": "offset",
      "duration": 1.5,
      "from": [ -100, 0 ],
      "to": [ 100, 0 ],
      "next": "@UIDemo.animation_out"
    },
    "animation_out": {
      "anim_type": "offset",
      "duration": 1.5,
      "from": [ 100, 0 ],
      "to": [ -100, 0 ],
      "next": "@UIDemo.animation_in"
    },
   "namespace" : "UIDemo"
}

可以从上面看出来，根据旋转锚点做的旋转，本质上是一种自转，对应于接口 Rotate ，如果想进行的是绕着某个固定点旋转，则需要用到接口 RotateAround（和公转的概念是一致的），这两种旋转是能复合到一起的，具体如何一起使用做出稍微复杂的效果可以参考 Demo，需要注意无论是哪种旋转，本质上都只是视觉上的效果，并不是实际的坐标和大小。

下图为UI编辑器中图片控件的属性编辑面板

控件表现

图片属性

变量
 解释
使用贴图 对应texture字段，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
图片适配 普通表示不开启九宫并保持宽高比，填充表示填满当前控件，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。
去色 对应grayscale字段。
裁剪方向 对应clip_direction字段。分别对应["从右向左裁剪","从左向右裁剪","从下向上裁剪","从上向下裁剪","从四周向中心裁剪"]
裁剪尺寸 对应clip_ratio字段。
uv起点 对应uv字段，默认为0，0
uv尺寸 对应uv_size字段，默认值为该texture的宽高
旋转角度 对应rotate_angle字段，默认为 0
旋转锚点 对应rotate_pivot字段，默认为 0.5，0.5

# Image Button

Button 是按钮控件，同时含有Image和Label。按钮有三种状态，分别为default/hover/pressed，可以分别对应不同的贴图。

  • 注 $符号表示定义变量
  • controls表示控制的子节点，
   "button0@common.button" : {
      "$default_texture" : "textures/netease/common/button/default",
      "$hover_texture" : "textures/netease/common/button/hover",
      "$is_new_nine_slice" : false,
      "$label_color" : [ 1, 1, 1 ],
      "$label_font_scale_factor" : 1.0,
      "$label_font_size" : "large",
      "$label_layer" : 3,
      "$label_offset" : [ 0, 0 ],
      "$label_text" : "Button",
      "$nine_slice_buttom" : 0,
      "$nine_slice_left" : 0,
      "$nine_slice_right" : 0,
      "$nine_slice_top" : 0,
      "$nineslice_size" : [ 0, 0, 0, 0 ],
      "$pressed_button_name" : "%fpsBattle.click",
      "$pressed_texture" : "textures/netease/common/button/pressed",
      "$texture_layer" : 2,
      "anchor_from" : "center",
      "anchor_to" : "center",
      "is_handle_button_move_event" : true,
      "button_mappings" : [],
      "bindings" : [
         {
            "binding_collection_name" : "",
            "binding_condition" : "always_when_visible",
            "binding_type" : "collection_details"
         }
      ],
      "controls" : [
         {
            "default@fpsBattle.default" : {}
         },
         {
            "hover@fpsBattle.hover" : {}
         },
         {
            "pressed@fpsBattle.pressed" : {}
         },
         {
            "button_label@fpsBattle.button_label" : {}
         }
      ],
      "default_control" : "default",
      "hover_control" : "hover",
      "layer" : 3,
      "offset" : [ 0, 0 ],
      "pressed_control" : "pressed",
      "size" : [ 100, 50 ],
      "type" : "button",
      "visible" : true
   },
   "button_label" : {
      "color" : "$label_color",
      "font_scale_factor" : "$label_font_scale_factor",
      "font_size" : "$label_font_size",
      "font_type" : "smooth",
      "layer" : "$label_layer",
      "max_size" : [ "100%", "100%" ],
      "offset" : [ 0, 0 ],
      "shadow" : false,
      "text" : "$label_text",
      "text_alignment" : "center",
      "type" : "label"
   },
   "default" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "layer" : "$texture_layer",
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$default_texture",
      "type" : "image"
   },
   "hover" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "layer" : "$texture_layer",
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$hover_texture",
      "type" : "image"
   },
   "pressed" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "layer" : "$texture_layer",
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$pressed_texture",
      "type" : "image"
   },
变量
 解释
default 表示按钮默认状态下的显示的图片内容
hover 表示按钮处于悬浮状态下的图片内容
pressed 表示按钮处于按下状态下的图片内容
$is_new_nine_slice 设置为true标记该图片开启九宫格显示的功能,从Json结构里可以看出三张图片的九宫设置用的是同一个
$nine_slice_bottom 切片距离下边的距离，默认值为0
$nine_slice_left 切片距离左边的距离，默认值为0
$nine_slice_right 切片距离右边的距离，默认值为0
$nine_slice_top 切片距离上边的距离，默认值为0
$nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。当设置了旧版九宫属性时优先旧版属性。该值支持数组和单个数字，数组代表[left,top,right,down]九宫属性，单个数值代表上下左右均采用该数值作为九宫属性，当四个方向的数值均为0时表示不开启原版九宫
$pressed_button_name fpsBattle代表编写UI逻辑的python类名，click代表按钮按下时会执行该python类的click函数。也可以使用API AddTouchEventHandler 动态注册按钮回调
is_handle_button_move_event 表示按钮是否可以响应按钮移动事件，需置true配合API AddTouchEventHandler使用
button_mappings 表示按钮事件响应映射网，需置[]配合API AddTouchEventHandler使用

下图为UI编辑器中按钮控件的属性编辑面板。

控件表现

按钮属性

变量
 解释
文本 对应button_label/text字段所引用的值，支持任何形式的文本
文本颜色 对应button_label/color字段所引用的值，点击按钮弹出颜色选择窗口，可以在调色板上取色或者使用吸管吸取界面上的颜色
字号 对应button_label/font_size和button_label/font_scale_factor字段，以一定的规则同时设置两个字段达到字号的效果
文本偏移 对应button_label/offset字段所引用的值，设置按钮上的文字相对中心点的偏移
使用贴图 分别对应default/texture,pressed/texture,hover/texture字段所引用的值，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图
图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。

# Panel

panel为面板控件，主要是用来将控件进行分类和管理，类似文件夹。

   "panel" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 0,
      "offset" : [ 0, 0 ],
      "size" : [ "50.000000%+0 px", "50.000000%+0px" ],
      "type" : "panel",
      "visible" : true
   }
变量 解释
type 类型为panel

面板控件暂时没有专属的属性，如有，后续在此处添加。

# InputPanel

input_panel与panel类似，可以用来放置其他控件，但除此之外还可以用来拖动，或实现“模态框”功能。

"InputPanel" : {
      "anchor_from" : "top_left",
      "anchor_to" : "top_left",
      "button_mappings": [
         {
           "from_button_id": "button.menu_select",
           "to_button_id": "#netease_to_button_id",
           "mapping_type": "pressed"
         }
      ],
      "layer" : 10,
      "modal" : true,
      "is_swallow": true,
      "contained": true,
      "draggable": "both",
      "offset" : [ 0.0, 0.0 ],
      "size" : [ 198.0, 137.0 ],
      "type" : "input_panel",
      "visible" : true
}
变量 默认值 解释
modal false 设为true时，该InputPanel视为模态框，见注2
is_swallow false 设为true时，该InputPanel的输入会吞噬事件，见注3
draggable not_draggable 当前控件可拖拽方式，默认为not_draggable不可拖拽，"horizontal"代表水平拖拽，"vertical"代表垂直拖拽，"both"代表自由拖拽
contained false 该控件可拖动时，是否会被父控件的大小范围所限制，默认值为false，见注4
button_mappings [] 该值为开启拖拽功能所必须的属性，可以理解成开启接受屏幕点击事件
  • 注1
该控件的拖动功能也遵循UI控件的碰撞规则，当InputPanel中有按钮、滚动列表等接受鼠标事件的控件时，点击在这些控件并不会触发InputPanel的拖动操作。
  • 注2
“模态框”是指将用户的UI点击操作限制在这个控件及其子控件，而其他的控件都不会响应用户操作。

如果界面上同时存在多个模态框，其中层级最高的生效。

可以用来处理ScrollView控件上显示其他控件时，点击会穿透到ScrollView的问题，可参考UIDemo示例的“InputPanel演示”

界面编辑器暂不支持，可先用Panel搭建后手动在json中修改属性。
  • 注3
吞噬事件是指点击该面板时，点击事件不会穿透到世界。如破坏方块、镜头转向不会被响应。
  • 注4
InputPanel维护着一个拖拽偏移量，它代表着在整个拖拽过程中，InputPanel相对于控件出生点坐标的偏移量，**与控件自身的offset无关**。举个例子，InputPanel经过了5次手动拖拽后位置向右移动了5像素，则拖拽偏移量的值为(5, 0)。

当contained为true时，拖拽偏移量存在限制，最小不能超过(0,0)，最大不能超过父控件的大小减去InputPanel控件的大小。

这也就意味着无论InputPanel是否设置了offset，由于初始拖拽偏移量为(0,0), 使控件无法负方向移动，因此需要将InputPanel放置在其父控件的左上角，或调用SetOffsetDelta接口手动设置拖拽偏移量。

# StackPanel

布局面板，用于自动布局该控件的子控件

"stack_panel0" : {
      "alpha" : 1.0,
      "anchor_from" : "center",
      "anchor_to" : "center",
      "clip_offset" : [ 0, 0 ],
      "clips_children" : false,
      "enabled" : true,
      "layer" : 1,
      "max_size" : [ 0, 0 ],
      "min_size" : [ 0, 0 ],
      "offset" : [ 0, 0 ],
      "orientation" : "vertical",
      "propagate_alpha" : false,
      "size" : [ 100, 100 ],
      "type" : "stack_panel",
      "visible" : true
   },
变量 解释
orientation 当前控件布局方式方式，"horizontal"代表水平排布，"vertical"代表垂直排布
type 类型为stack_panel

下图为UI编辑器中布局面板控件的属性编辑面板。

控件表现

布局面板属性

变量 解释
排列方式 对应orientation字段

注

排序的顺序和子控件的排序有关，需要手动调整。

# TextEditBox

TextEditBox是输入框控件，用来输入文字信息，可以获取输入内容，设置输入框内容，触发输入中和输入完成事件，设置最大输入值等。下面的示例展示了一个搜索框的信息。

  "text_edit_box0@common.text_edit_box" : {
      "$edit_box_default_texture" : "textures/ui/edit_box_indent",
      "$edit_box_hover_texture" : "textures/ui/edit_box_indent_hover",
      "$font_size" : "normal",
      "$is_new_nine_slice" : false,
      "$nine_slice_buttom" : 0,
      "$nine_slice_left" : 0,
      "$nine_slice_right" : 0,
      "$nine_slice_top" : 0,
      "$nineslice_size" : [ 0, 0, 0, 0 ],
      "$place_holder_text" : "请输入内容",
      "$place_holder_text_color" : [ 0.50, 0.50, 0.50 ],
      "$text_background_default" : "fpsBattle.edit_box_background_default",
      "$text_background_hover" : "fpsBattle.edit_box_background_hover",
      "$text_box_name" : "%fpsBattle.message_text_box",
      "$text_box_text_color" : [ 1, 1, 1 ],
      "$text_edit_box_content_binding_name" : "#fpsBattle.message_text_box_content",
      "anchor_from" : "center",
      "anchor_to" : "center",
      "enabled_newline" : false,
      "layer" : 5,
      "max_length" : 512,
      "offset" : [ 0, 0 ],
      "size" : [ 300, 27 ],
      "type" : "edit_box",
      "visible" : true
   },
   "edit_box_background_default" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$edit_box_default_texture",
      "type" : "image"
   },
   "edit_box_background_hover" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$edit_box_hover_texture",
      "type" : "image"
   },
变量
 解释
max_length 初始最大输入长度，后续可代码设置
$text_box_name 获取输入到的信息，监听了BF_EditChanged和BF_EditFinished的函数Textbox，会在输入框内容修改和输入完成时调到该函数，可参考下面的注1
$text_edit_box_content_binding_name 输入框显示ReturnTextString中返回的内容，这与上面形成了一个双向绑定，可参考下面的注1
$place_holder_text 输入框初始化没有输入时的提示语
$is_new_nine_slice 设置为true标记该图片开启九宫格显示的功能,从Json结构里可以看出两张图片的九宫设置用的是同一个
$nine_slice_bottom 切片距离下边的距离，默认值为0
$nine_slice_left 切片距离左边的距离，默认值为0
$nine_slice_right 切片距离右边的距离，默认值为0
$nine_slice_top 切片距离上边的距离，默认值为0
$nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。当设置了旧版九宫属性时优先旧版属性。该值支持数组和单个数字，数组代表[left,top,right,down]九宫属性，单个数值代表上下左右均采用该数值作为九宫属性，当四个方向的数值均为0时表示不开启原版九宫
  • 注1
class TestScreen(ScreenNode):
	def __init__(self, namespace, name, param):
		ScreenNode.__init__(self, namespace, name, param)
        self.text = ""
        self.holder = str("请输入姓名")

    @ViewBinder.binding(ViewBinder.BF_EditChanged | ViewBinder.BF_EditFinished)
	def TextBox(self, args):
		print "SearchTextBox  ", args
		self.text = args["Text"]
		return ViewRequest.Refresh

	@ViewBinder.binding(ViewBinder.BF_BindString)
	def ReturnTextString(self):
		return self.text
  • 注2

max_length 可以通过接口SetEditTextMaxLength，接口详细调用可见下文。

注意：输入框推荐在创建UI的isHud为0的情况下使用，如：

clientApi.CreateUI("testMod", "testUI", {"isHud":0})

因为在安卓机器上，当isHud为1时，选中文本输入框后单指无法取消选中，需要双指点击屏幕取消选中，如下图：

问题gif

PC和IOS平台没有这个问题

下图为UI编辑器中文本输入框控件的属性编辑面板。

控件表现

文本输入框属性

变量
 解释
提示文字 对应$place_holder_text字段，代表没有文本输入时底部显示
提示文字颜色 对应$place_holder_text_color字段，代表提示文字的颜色，点击按钮弹出颜色选择窗口，可以在调色板上取色或者使用吸管吸取界面上的颜色
输入文本颜色 对应$text_box_text_color字段，代表输入文本的颜色
绑定输入框交互 对应$text_box_name字段
绑定输入框内容 对应$text_edit_box_content_binding_name字段
提示文字字号 对应$font_size字段，可供选择的有["small","middle","large"],对应值[4，8，16]
文字最大长度 对应max_length字段，即代表可输入文本的最大长度
使用贴图 分别对应$edit_box_default_texture控件默认状态,$edit_box_hover_texture控件鼠标悬浮状态字段所引用的值，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认
图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。

# PaperDoll

该控件可以用于在ui上显示骨骼模型

"paper_doll0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "animation" : "",
      "animation_looped": true,
      "layer" : 7,
      "modelname" : "",
      "modelsize" : 1.0,
      "offset" : [ 0, 0 ],
      "renderer" : "paper_doll_renderer",
      "size" : [ 100, 100 ],
      "type" : "custom",
      "visible" : true,
      "enable_scissor_test" : false,
   },
变量
 解释
modelname 要显示的骨骼模型的名称，可通过API中的SetUiModel接口动态修改
animation 骨骼模型播放的动作，可通过API中的SetUiModel接口动态修改
animation_looped 骨骼模型播放动作是否循环播放，可通过API中的SetUiModel接口动态修改
modelsize 骨骼模型的显示缩放
renderer 对纸娃娃控件自定义的渲染模块，不建议改动该字段
enable_scissor_test 超出父控件区域后是否裁剪，默认为false, 该属性需要父控件开启clips_children属性才能生效，RenderPaperDoll (opens new window)

下图为UI编辑器中纸娃娃控件的属性编辑面板。

控件表现

纸娃娃控件属性

变量
 解释
模型类型 可选原版模型和FBX模型，FBX模型可通过资源管理器界面导入。选中FBX模型时显示模型名称选项，可选导入的FBX模型。选中原版模型时默认modelname使用steve
模型名称 对应modelname字段
模型缩放 对应modelsize字段，支持0-100的正整数

# NeteasePaperDoll

该控件可以用于在ui上显示：

1）生物，包括玩家与普通生物；

2）骨骼模型展示；

3）生物类型原版模型展示。

"paper_doll0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 22,
      "offset" : [ 0.0, 0.0 ],
      "renderer" : "netease_paper_doll_renderer",
      "init_rot_y": 60.0,
      "rotation": "gesture_x",
      "screen_scale": 1.0,
      "size" : [ 100, 100 ],
      "type" : "custom",
      "visible" : true,
      "enable_scissor_test" : false,
}

相关字段说明：

变量
 解释
renderer 不能改动该字段
rotation 渲染模型的朝向，可选的值有：
none：默认值，没有任何旋转角度
auto：随着时间而旋转
gesture_x：可以通过触控以Y轴旋转, 但需要InputPanel控件配合生效。详情请参考UIDemoMod中的纸娃娃演示示例
freedom_gesture：可以自主选择绕xyz轴旋转, 但需要InputPanel控件配合生效。详情请参考官网Mod 中的NeteasePaperDollDemoMod
init_rot_y 初始朝向（Y轴为旋转轴），单位：角度，RenderPaperDoll参数init_rot_y动态设置
screen_scale 放缩系数，默认为1，基于UI的size进行放缩，RenderPaperDoll参数scale动态设置
skeleton_model_name 骨骼模型名称，默认为空字符，RenderPaperDoll参数skeleton_model_name动态设置
animation 骨骼模型动画名称，默认为idle，RenderPaperDoll参数animation动态设置
animation_looped 骨骼动画是否循环播放，默认为true，RenderPaperDoll参数animation_looped动态设置
entity_identifier 生物标识，如minecraft:cat，默认为空字符，RenderPaperDoll参数entity_identifier动态设置
enable_scissor_test 超出父控件区域后是否裁剪，默认为false, 该属性需要父控件开启clips_children属性才能生效，RenderPaperDoll (opens new window)

接口使用例子以及说明：

1）渲染玩家或者生物，包括玩家的装备等物品的渲染

path = '/demoPanel/dollPanel/viewer_panel/paper_doll_panel/paper_doll'
param = {
    "entity_id": "-8589934591", # 玩家或生物Id
    "scale": 0.5, # 放缩系数
    "render_depth": -50, # 渲染深度，对于玩家默认-50，普通生物-15，该参数可解决UI遮挡剔除问题
    "init_rot_y": 60, # 初始朝向
    "molang_dict": {"variable.liedownamount": 1} # molang变量dict，其中key为字符串，value为float类型
}
uiNode.RenderPaperDoll(path, param)

2）渲染骨骼模型

path = '/demoPanel/dollPanel/viewer_panel/paper_doll_panel/paper_doll'
param = {
    "skeleton_model_name": "datiangou", # 大天狗模型
    "scale": 1.0,
    "animation": "fengxi", # 动画名称
    "animation_looped": False, # 是否循环播放
}
uiNode.RenderPaperDoll(path, param)

3）渲染原版生物模型（不需要生物实例）

path = '/demoPanel/dollPanel/viewer_panel/paper_doll_panel/paper_doll'
param = {
    "scale": 1.0,
    "entity_identifier": "minecraft:cat", # 渲染猫的原版模型
    "init_rot_y": 60,
    "molang_dict": {"variable.state": 2, "variable.liedownamount": 1} # 通过molang变量来调整渲染效果（坐下的猫）
}
uiNode.RenderPaperDoll(path, param)

使用注意事项：

1）如果渲染位置不正确，请调整UI的位置；

2）如果渲染模型过大或者过小，请调整UI的大小或者参数scale；

3）如果生物模型被裁剪，请调整参数render_depth或者UI的layer；

4）可以通过使用参数molang_dict来驱动原版模型的渲染，如果发生如下图的渲染错误，需要自行调整molang表达式；

molang渲染错误提示

# ItemRenderer

该控件可以用于在ui上显示物品

"item_renderer0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "property_bag" : {
         "#item_id_aux" : 131072
      },
      "renderer" : "inventory_item_renderer",
      "size" : [ 100, 100 ],
      "type" : "custom",
      "visible" : true
   },
变量
 解释
renderer 对显示物品自定义的渲染模块，不建议改动该字段
property_bag 控件属性信息，#item_id_aux代表物品id，131072代表草方块在游戏内的值

下图为ItemRenderer在UI编辑器中的控件表现

控件表现

物品渲染控件属性

物品渲染控件属性

变量
 解释
道具类型 可选原版道具和自定义道具，自定义道具可在关卡编辑器中设置。选中自定义道具时显示道具ID和附加值输入栏，可输入自定的道具ID和附加值。选中原版道具时隐藏道具ID和附加值输入栏，显示道具材质，点击弹出道具材质选择窗口
道具材质 点击弹出道具材质选择窗口，展示所有原版道具图片，选中后编辑器自动设置该道具对应的道具ID和附加值
道具ID和附加值 填写设置自定义道具时设置的道具ID和附加值
附魔效果 勾选后道具表现出现附魔流光效果
  • 注

道具在游戏中的物品id会根据游戏运行平台、加载Mod数量、游戏大版本等不同会发生变化，因此UI编辑器的ItemRenderer控件静态保存在json中的数据，在游戏中并不一定能正确显示，建议使用UIAPI-SetUiItem来对该控件进行动态设置，详见《UIAPI文档》。

原版道具显示正常。

# ScrollView

该控件是可以滑动的窗口，需要有其他控件附属。

   "scroll_view0@common.scrolling_panel" : {
      "$background_nine_slice_buttom" : 0,
      "$background_nine_slice_left" : 0,
      "$background_nine_slice_right" : 0,
      "$background_nine_slice_top" : 0,
      "$background_nineslice_size" : [ 0, 0, 0, 0 ],
      "$box_nine_slice_buttom" : 0,
      "$box_nine_slice_left" : 0,
      "$box_nine_slice_right" : 0,
      "$box_nine_slice_top" : 0,
      "$box_nineslice_size" : [ 0, 0, 0, 0 ],
      "$is_background_nine_slice" : false,
      "$is_box_nine_slice" : false,
      "$is_track_nine_slice" : false,
      "$scroll_background_image_control" : "fpsBattle.scroll_background_image",
      "$scroll_background_texture" : "textures/ui/ScrollRail",
      "$scroll_box_mouse_image_control" : "fpsBattle.scroll_box_image",
      "$scroll_box_texture" : "textures/ui/newTouchScrollBox",
      "$scroll_box_touch_image_control" : "fpsBattle.scroll_box_image",
      "$scroll_track_image_control" : "fpsBattle.scroll_track_image",
      "$scroll_track_texture" : "textures/ui/ScrollRail",
      "$scrolling_content" : "fpsBattle.image",
      "$show_background" : true,
      "$track_nine_slice_buttom" : 0,
      "$track_nine_slice_left" : 0,
      "$track_nine_slice_right" : 0,
      "$track_nine_slice_top" : 0,
      "$track_nineslice_size" : [ 0, 0, 0, 0 ],
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 9,
      "offset" : [ 0, 0 ],
      "size" : [ 100, 80 ],
      "type" : "scroll_view",
      "visible" : true
   },
变量
 解释
scrolling_content 这里保存了该滑动窗口的内容
show_background 是否显示背景
$is_background_nine_slice 设置为true标记背景图片开启九宫格显示的功能
$background_nine_slice_buttom 切片距离下边的距离，默认值为0
$background_nine_slice_left 切片距离左边的距离，默认值为0
$background_nine_slice_right 切片距离右边的距离，默认值为0
$background_nine_slice_top 切片距离上边的距离，默认值为0
$background_nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。当设置了旧版九宫属性时优先旧版属性。该值支持数组和单个数字，数组代表[left,top,right,down]九宫属性，单个数值代表上下左右均采用该数值作为九宫属性，当四个方向的数值均为0时表示不开启原版九宫
$is_box_nine_slice 设置为true标记滑动块图片开启九宫格显示的功能
$box_nine_slice_buttom 切片距离下边的距离，默认值为0
$box_nine_slice_left 切片距离左边的距离，默认值为0
$box_nine_slice_right 切片距离右边的距离，默认值为0
$box_nine_slice_top 切片距离上边的距离，默认值为0
$box_nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。
$is_track_nine_slice 设置为true标记滑轨图片开启九宫格显示的功能
$track_nine_slice_buttom 切片距离下边的距离，默认值为0
$track_nine_slice_left 切片距离左边的距离，默认值为0
$track_nine_slice_right 切片距离右边的距离，默认值为0
$track_nine_slice_top 切片距离上边的距离，默认值为0
$track_nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。
$scroll_background_texture 滚动列表背景图片
$scroll_box_texture 滑动块图片
$scroll_track_texture 滑轨图片

下图为UI编辑器中滚动列表控件的属性编辑面板。

控件表现

滚动列表属性

滚动列表属性

变量
 解释
滚动列表-内容 对应$scrolling_content字段，只接受其他screen画布中的控件，且被选中控件不可以是文本、图片、滚动列表控件，若被选中控件为panel，那么子节点中含有滚动列表的panel控件同样不可以被选中
滚动列表-隐藏背景 对应show_background字段
滚动列表-使用贴图 对应$scroll_background_texture字段，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
滚动列表-图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。
滚动条滑块-使用贴图 对应$scroll_box_texture字段，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
滚动条滑块-图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。
滚动条背景-使用贴图 对应$scroll_track_texture字段，将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
滚动条背景-图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。

滚动列表的内容以scrolling_content为引用可以由我们自定义，但是承载scrolling_content的父控件scrolling_view_port的size如不经修改默认为["100%","100%"]，即与我们的滚动列表定的大小相同，而可滚动区域的判定会取scrolling_content的size和其父控件scrolling_view_port作比较，两者大小之差即为可拖动范围。而我们UI控件的size是不会根据其子控件的size做到动态完全覆盖，因此如果我们的scrolling_content的大小是动态变化的，需要我们在代码中手动设置scrolling_content的size,详见UI-APISetSize

而对于scrolling_content的绝对路径，一共有以下两种，可以通过UI-APIGetAllChildrenPath清楚的看到。

scroll_view_path = "/scroll_view0"
touch_path = scroll_view_path + "/scroll_touch/scroll_view/panel/background_and_viewport/scrolling_view_port/scrolling_content"
mouse_path = scroll_view_path + "/scroll_mouse/scroll_view/stack_panel/background_and_viewport/scrolling_view_port/scrolling_content"

我们知道在PC端进行游戏时，按F11可以切换鼠标控制和遥感控制两种操作模式，而在手机端进行游戏时只有遥感控制这一种操作模式。不同的操作模式，scroll_view的scrolling_content会生成在不同的路径下，遥感模式使用touch_path获得scrolling_content的绝对路径，而鼠标控制使用mouse_path获得。

# Grid

Grid组件属于网格型的排列，可以依附在滚动条中，用来实现背包等功能。

   "grid0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "collection_name" : "test_grid",
      "grid_dimensions" : [ 2, 2 ],
      "grid_item_template" : "fpsBattle.netease_editor_template_image",
      "grid_rescaling_type" : "none",
      "maximum_grid_items" : 0,
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "size" : [ 200, 200 ],
      "type" : "grid",
      "visible" : true
   },
   "netease_editor_template_image" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "size" : [ "50%", "50%" ],
      "texture" : "textures/netease/common/image/default",
      "type" : "image",
      "uv" : [ 0, 0 ],
      "uv_size" : [ 107, 107 ],
      "visible" : true
   },
变量
 解释
grid_rescaling_type 网格调节方式，目前可取值范围["none","horizontal"]，当取值none是grid_dimensions生效，取值horizontal时maximum_grid_items生效
maximum_grid_items 最大格子数量
grid_dimensions 初始值大小2X2
grid_item_template 被当作生成网格单元的控件模板

下图为UI编辑器中网格控件的属性编辑面板。

控件表现

网格属性

网格属性

变量
 解释
集合名 对应collection_name字段
内容 对应grid_item_template字段，只接受其他screen画布中的控件，且被选中控件不可以是滚动列表、网格控件，若被选中控件为panel，那么子节点中含有滚动列表、网格的panel控件同样不可以被选中
网格调节方式 对应grid_rescaling_type字段,配置网格模式时，格子固定生成m * n个格子；配置水平模式时，格子按网格最大数量水平连续生成若干格子，一般搭配控件尺寸Y勾选"适应"使用
网格规模 对应grid_dimensions字段
网格最大数量 对应maximum_grid_items字段

注：

  1. grid是在renderer渲染的时候才创建，所以只要没有显示过该界面，调用GetChildrenName和GetAllChildrenPath都无法获取到grid的子节点信息。如果要初始化grid的信息必须在UI渲染结束后一帧再来调用这两个接口获取子节点信息并初始化

  2. 当grid控件与ScrollView一起使用时，如果grid控件中设置单个UI元素（例如按钮）的数目值超过当前grid控件显示的最大数目时，需要配合scrollview一同使用。当scrollview拉动时，由于MC内置逻辑实现方式，grid控件会将没有渲染必要的格子剔除并缓存以节约渲染成本，并在其恢复渲染必要时添加回grid的子节点列表中。在这一过程中，每个UI元素都不一定会在其原本的位置，从而导致内容错位。此时需要开发者监听GridComponentSizeChangedClientEvent事件，当收到事件后，需要通过GetAllChildrenPath接口获取grid中返回的所有UI元素的路径值，这些路径值尾部包含该UI元素在grid中的索引数目。依据索引数目，mod开发者将物品背包或者类似的显示所需的UI信息值依次设置到grid中的子元素中。建议开发者采用MVC模式控制grid中的内容显示：M代表需要显示的数据信息容器，V代表grid容器和容器中包含的子UI控件，C代表控制组装的UI元素的函数或者模块，并由初始化和监听GridComponentSizeChangedClientEvent事件触发驱动。详情请参考UIDemoMod中的滚动列表演示示例。

  3. grid控件不建议使用其子控件路径对其动态生成的格子控件直接进行SetVisible等操作，因为在每次界面刷新时grid控件会对所有的格子做一次数据更新，更新的过程中会强制将格子可见性置True。如果有需要对格子进行操作，可以使用数据绑定的方式，如下代码和json。需要注意的是在数据绑定的回调函数中需要明确grid本身是否可见，否则会造成grid子节点控件的可见性数据异常，从而影响界面操作逻辑。

   "grid1" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "collection_name" : "gridDemo",
      "grid_dimensions" : [ 2, 2 ],
      "grid_item_template" : "UIDemo.scrollviewBtn0",
      "layer" : 39,
      "offset" : [ 0, 0 ],
      "size" : [ 200, 200 ],
      "type" : "grid",
      "visible" : true
   },
   "scrollviewBtn0@UIDemo.scrollviewBtn": {
	  "bindings" : [
         {
			"binding_collection_name" : "gridDemo",
			"binding_condition" : "always",
			"binding_name" : "#UIDemo.visible",
			"binding_name_override" : "#visible",
			"binding_type" : "collection"
		}
      ],
      "visible" : "#UIDemo.visible"
   },

class UIDemoScreen(ScreenNode):
	def __init__(self, namespace, name, param):
      self.demoGridControl = None
      ......

   def Create(self):
      self.demoGridControl = self.GetBaseUIControl("/grid1")
      ......

   @ViewBinder.binding_collection(ViewBinder.BF_BindBool, "gridDemo", "#UIDemo.visible")
	def GridItemVisible(self, index):
		return index < self.showNum and self.demoGridControl.GetVisible()

可以看到grid格子的visible属性我们以"#UIDemo.visible"设置，而该字段经由bindings字段的设置取代了系统变量#visible，再在python代码中绑定了"#UIDemo.visible"字段的函数更新回调。因此每个格子的visible属性就会读取python函数的返回值进行动态的设置。有关于数据绑定详情可见UI绑定和返回

# ProgressBar

ProgressBar进度条控件，用于百分比显示进度

   "progress_bar0" : {
      "$clip_direction" : "left",
      "$clip_ratio" : 0.0,
      "$is_new_nine_slice" : false,
      "$nine_slice_buttom" : 0,
      "$nine_slice_left" : 0,
      "$nine_slice_right" : 0,
      "$nine_slice_top" : 0,
      "$nineslice_size" : [ 0, 0, 0, 0 ],
      "$progress_bar_empty_texture" : "textures/ui/empty_progress_bar",
      "$progress_bar_filled_texture" : "textures/ui/filled_progress_bar",
      "anchor_from" : "center",
      "anchor_to" : "center",
      "controls" : [
         {
            "empty_progress_bar@fpsBattle.empty_progress_bar" : {}
         },
         {
            "filled_progress_bar@fpsBattle.filled_progress_bar" : {}
         }
      ],
      "layer" : 8,
      "offset" : [ 0, 0 ],
      "size" : [ 100, 10 ],
      "type" : "panel",
      "visible" : true
   },
   "empty_progress_bar" : {
      "is_new_nine_slice" : "$is_new_nine_slice",
      "layer" : 1,
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$progress_bar_empty_texture",
      "type" : "image"
   },
   "filled_progress_bar" : {
      "clip_direction" : "$clip_direction",
      "clip_ratio" : "$clip_ratio",
      "is_new_nine_slice" : "$is_new_nine_slice",
      "layer" : 2,
      "nine_slice_buttom" : "$nine_slice_buttom",
      "nine_slice_left" : "$nine_slice_left",
      "nine_slice_right" : "$nine_slice_right",
      "nine_slice_top" : "$nine_slice_top",
      "texture" : "$progress_bar_filled_texture",
      "type" : "image"
   },
变量
 解释
$progress_bar_empty_texture 进度条背景图片
$progress_bar_filled_texture 进度条前景图片
$clip_direction 进度条加载方向，目前支持["left", "right", "up", "down", "center"]
grid_item_template 被当作生成网格单元的控件模板
$is_new_nine_slice 设置为true标记该图片开启九宫格显示的功能,从Json结构里可以看出两张图片的九宫设置用的是同一个
$nine_slice_bottom 切片距离下边的距离，默认值为0
$nine_slice_left 切片距离左边的距离，默认值为0
$nine_slice_right 切片距离右边的距离，默认值为0
$nine_slice_top 切片距离上边的距离，默认值为0
$nineslice_size 设置原版九宫属性，相比于旧版九宫属性更符合像素风格。当设置了旧版九宫属性时优先旧版属性。该值支持数组和单个数字，数组代表[left,top,right,down]九宫属性，单个数值代表上下左右均采用该数值作为九宫属性，当四个方向的数值均为0时表示不开启原版九宫

下图为UI编辑器中进度条控件的属性编辑面板。

控件表现

进度条属性

变量
 解释
使用贴图 填充对应$progress_bar_filled_texture字段，空白对应$progress_bar_empty_texture,将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
图片适配 普通表示不开启九宫，选中旧版九宫则is_new_nine_slice置true，开启旧版九宫设置，选中原版九宫则开启原版九宫。

# SwitchToggle

开关控件，用于两个状态之间的切换

"switch_toggle0@common_toggles.switch_toggle_collection" : {
      "$default_texture" : "textures/ui/toggle_off",
      "$hover_texture" : "textures/ui/toggle_on",
      "$pressed_no_hover_texture" : "textures/ui/toggle_on_hover",
      "$pressed_texture" : "textures/ui/toggle_off_hover",
      "$toggle_name" : "#fpsBattle.toggle_name",
      "$toggle_state_binding_name" : "#fpsBattle.toggle_state",
      "anchor_from" : "center",
      "anchor_to" : "center",
      "bindings" : [
         {
            "binding_collection_name" : "",
            "binding_condition" : "always_when_visible",
            "binding_type" : "collection_details"
         }
      ],
      "layer" : 6,
      "offset" : [ 0, 0 ],
      "size" : [ 100, 100 ],
      "type" : "panel",
      "visible" : true
   },
变量
 解释
$default_texture 开关默认图片
$hover_texture 开关鼠标悬浮状态图片
$pressed_texture 开关按下图片
$pressed_no_hover_texture 开关鼠标悬浮状态按下图片
$toggle_name 获取输入到的信息，监听了BF_ToggleChanged的函数,类似文本输入框
$toggle_state_binding_name 开关控件显示toggle_state中返回的内容，这与上面形成了一个双向绑定，类似文本输入框
  • 注1
class TestScreen(ScreenNode):
   def __init__(self, namespace, name, param):
      ScreenNode.__init__(self, namespace, name, param)
        self.currentToggleShow = True

    @ViewBinder.binding(ViewBinder.BF_ToggleChanged)
    def OnDemoToggleChangeCallback(self,args):
        self.currentToggleShow = args["state"]
        return ViewRequest.Refresh

   @ViewBinder.binding(ViewBinder.BF_BindBool)
    def ReturnToggleState(self):
        return self.currentToggleShow

下图为UI编辑器中开关控件的属性编辑面板。

控件表现

开关属性

变量
 解释
使用贴图 滑轨开对应$hover_texture字段，滑轨关对应$default_texture,滑轨开时按下对应$pressed_no_hover_texture字段，滑轨关时按下对应$pressed_texture,将资源管理窗口中的图片资源拖曳到该图片小窗内赋值，可以在上方的下拉选项栏中重新选回默认图片
绑定开关交互 对应$toggle_name字段
绑定开关内容 对应$toggle_state_binding_name字段

# Slider

滑动条控件，用于拖动设置进度或百分比。

"slider0@common.slider": {
      "$slider_tts_text_value": "#netease_tts_text_value",
      "$slider_name": "#UIDemoScreen.OnDemoSliderChange",
      "$slider_value_binding_name":"#UIDemoScreen.ReturnSliderValue",
      "$slider_steps_binding_name": "#UIDemoScreen.ReturnSliderStep",
      "$background_default_control": "common.slider_background",
      "$progress_default_control": "common.slider_progress",
      "$progress_default_clip_direction": "left",
      "$background_hover_control": "common.slider_background_hover",
      "$progress_hover_control": "common.slider_progress_hover",
      "$progress_hover_clip_direction": "left",
      "$slider_direction": "horizontal",
      "$slider_box_layout": "common.slider_button_layout",
      "$slider_box_hover_layout": "common.slider_button_hover_layout",
      "$slider_box_locked_layout": "common.slider_button_locked_layout",
      "$slider_box_indent_layout": "common.slider_button_indent_layout",
      "$slider_box_size": [ 10, 16 ],
      "size": [ 100, 10 ],
      "offset": [ 0, 0 ],
      "$slider_step_factory_control_ids": {
         "slider_step": "@common.slider_step",
         "slider_step_hover": "@common.slider_step_hover",
         "slider_step_progress": "@common.slider_step_progress",
         "slider_step_progress_hover": "@common.slider_step_progress_hover"
      },
   }
变量
 解释
$slider_tts_text_value 开发者无需关注，但为必填属性，建议值为 "#netease_tts_text_value"（只要是以"#"开头的字符串值即可）
$slider_name 获取滑动条的信息，监听了BF_SliderChanged的函数OnDemoSliderChange，会在滑动条值改变时调到该函数，可参考下面的注1
$slider_value_binding_name 滑动条显示ReturnSliderValue中返回的值，这与上面形成了一个双向绑定，该值必须是float类型，可参考下面的注1
$slider_steps_binding_name 滑动条总步长，由ReturnSliderStep函数中返回的值进行设置。当设置大于1时该滑动条为固定格类型，类似设置面板中能见度设置，滑动范围为0-总步长；当设置小于等于1时该滑动条为百分比类型，类似设置面板中音量设置，滑动范围为0-1。
$background_default_control 滑动条背景默认情况下显示的控件，须为image
$progress_default_control 滑动条前景默认情况下显示的控件，会根据当前进度进行裁剪，须为image
$progress_default_clip_direction 滑动条前景默认情况下被裁剪方向, 可填"left", "right", "up", "down", "center"
$background_hover_control 滑动条背景在鼠标悬浮及按下情况下显示的控件，须为image
$progress_hover_control 滑动条前景在鼠标悬浮及按下情况下显示的控件，会根据当前进度进行裁剪，须为image
$progress_hover_clip_direction 滑动条前景在鼠标悬浮及按下情况下被裁剪方向, 可填"left", "right", "up", "down", "center"
$slider_direction 滑动条方向，可填"horizontal","vertical"和"none"，默认为"horizontal"。注意当滑动条方向改变时不会自动改变滑动条前景默认情况和悬浮及按下情况下被裁减的方向，如有需要请修改$progress_default_clip_direction和$progress_hover_clip_direction属性
$slider_box_layout 滑动格默认情况下显示的控件
$slider_box_hover_layout 滑动格鼠标悬浮情况下显示的控件
$slider_box_locked_layout 滑动格鼠标不可用情况下显示的控件
$slider_box_indent_layout 滑动格按下情况下显示的控件
$slider_box_size 滑动格大小
$slider_step_factory_control_ids 当滑动条为固定格类型滑动条时，滑动条会生成等距的分隔线来标明单步滑动的位置。而这一系列的分割线就是由$slider_step_factory_control_ids属性内的各个控件控制的。
slider_step 背景分隔线默认情况下显示的控件
slider_step_hover 背景分隔线鼠标悬浮情况下显示的控件
slider_step_progress 前景分隔线默认情况下显示的控件
slider_step_progress_hover 前景分隔线鼠标悬浮情况下显示的控件
  • 注1
class UIDemoScreen(ScreenNode):
   def __init__(self, namespace, name, param):
      ScreenNode.__init__(self, namespace, name, param)
        self.sliderPercentValue = 0.5  # 百分比值
        # self.sliderAbsValue = 5.0 # 固定值

    @ViewBinder.binding(ViewBinder.BF_SliderChanged | ViewBinder.BF_SliderFinished)
	def OnDemoSliderChange(self, value, isFinish, _unused):
		self.sliderPercentValue = value   # 百分比类型滑动条保存值
		# self.sliderAbsValue = value   # 固定格类型滑动条保存值
		return ViewRequest.Refresh

	@ViewBinder.binding(ViewBinder.BF_BindFloat)
	def ReturnSliderValue(self):
		return self.sliderPercentValue   # 百分比类型滑动条返回值
		# return self.sliderAbsValue  # 固定格类型滑动条返回值

	@ViewBinder.binding(ViewBinder.BF_BindInt)
	def ReturnSliderStep(self):
		return 1  # 百分比类型滑动条
      # return 10  # 固定格类型滑动条

下图为Slider在游戏中的控件表现

滑动控件

# SelectionWheel

该控件表现为一个轮盘选择UI，为了开发方便，可继承common_selection_wheels命名空间下的base_selection_wheel控件，Demo中表现如下。

轮盘控件-1

该控件结构稍微复杂，本质上是一堆控件的组合，直接看json不够直观。总体是分为两部分，一部分控件是不管鼠标怎么移动，都不影响那部分控件的可见性（visible属性），比如这些ItemRenderer以及中间的Label。

轮盘控件-2

而另一部分控件根据鼠标不同的位置，确定显示哪个控件，比如这个轮盘本身，本质上是一堆带不同选中效果的图片控件。

轮盘控件-3

Demo中显示的轮盘控件是一个圆环形状，这是因为计算鼠标位置映射到哪个控件的时候是按照鼠标落在圆环的哪个扇区决定的，这是比较精确的显示，但实际上是可以用相似的形状去贴近这个圆环的，比如如果圆环切分的不够多，均分成6个，就可以用下面的形状去近似。

这是轮盘控件近似的映射区域。

轮盘控件-4

这是轮盘控件实际的映射区域。

轮盘控件-5

了解了这个控件结构后，制作自己的轮盘控件需要确定的就是弄清楚鼠标移到哪个区域对应哪一个图片。实际上轮盘的映射规则并不明显，这里提供一个python函数，计算出 index == 0 的区域在极坐标系中的角度范围，下图是极坐标系示意图。

极坐标

index == 0 的区域在极坐标系中的坐标范围计算

# 获取第一个item的角度范围
def getFirstItemRange(itemNum):
	perItemSize = 360 / itemNum
	offset = 180 - perItemSize / 2
	rangeStart = -(0 - offset)
	rangeEnd = -(perItemSize - offset)
	print(rangeStart, rangeEnd)
	return rangeStart, perItemSize

为了方便开发者更快地确定不同数量叶片的情况，UIDemoMod 中有3-10个叶片的图片示例（外直径400，内直径200，路径为 "UIDemoMod/uidemoResourcePack/textures/ui/SelectionWheel/samples"），后续UI编辑器中将会集成对应的工具生成这些图片。

轮盘控件-7

值得注意的是，生成的图片中，有一张图片是需要作为这个轮盘的默认状态（也就是鼠标还未移到控件上的时候控件显示的状态），这张图片所对应的控件，就是轮盘的默认状态（也叫默认索引）。

有了上面的理解，json中的属性就比较清晰，我们以下面的json为例说明。

{
   "namespace": "custom_wheel_namespace",
   "wheel_state" : {
      "type" : "image"
   },
   "custom_selection_wheel_content":{
      "type": "panel",
      "controls": [
         {
            "state_default@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_default"
            }
         },
         {
            "state_0@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_0"
            }
         },
         {
            "state_1@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_1"
            }
         },
         {
            "state_2@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_2"
            }
         },
         {
            "state_3@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_3"
            }
         },
         {
            "state_4@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_4"
            }
         },
         {
            "state_5@custom_wheel_namespace.wheel_state": {
               "texture" : "textures/ui/circle/custom_wheel_selection_5"
            }
         }
      ]
   },
   "custom_selection_wheel@common_selection_wheels.base_selection_wheel" : {
      "inner_radius" : 0.35,
      "outer_radius" : 1.0,
      "size" : [ 200, 200 ],
      "slice_count" : 6,
      "initial_button_slice": -1,
      "$content": "custom_wheel_namespace.custom_selection_wheel_content",
      "state_controls" : [
         "state_default",
         "state_0",
         "state_1",
         "state_2",
         "state_3",
         "state_4",
         "state_5"
      ]
   }
}
属性
 解释
slice_count 轮盘切片的数量，如上图显示，这个轮盘有6个选择，所以将圆环平均切成了6份
outer_radius 轮盘的外直径系数，该值是一个比例值，默认为1.0，不建议修改该值。 该比例值是用来计算轮盘响应的外直径的有多大，轮盘的外直径 = outer_radius * min(width, height)，其中 width，height分别轮盘控件的宽高（控件size属性值）
inner_radius 轮盘的内直径系数，默认为0.0。
state_controls 上文所说的那一部分跟随鼠标位置变化的控件的名称， 这些控件必须是轮盘的子控件（不一定是直接子控件，可以是孙子或者更往下的子控件），在轮盘中，每个状态控件都有一个索引 index，默认状态控件的 index = -1，其他状态的index范围为 [0, slice_count - 1] ，需要注意的是，第一个控件必须是作为默认状态控件。
initial_button_slice 轮盘刚创建出来时所处的索引，默认值为-1
变量
 解释
$content 轮盘的内容控件，本质是一个控件变量，请将所有子控件都声明到该控件中

对于上面所出现的三种轮盘，UIDemo 中都涵盖了。

  • 注1

目前轮盘控件在SDK中支持的回调仅有两个：hover的回调（通过SetHoverCallback接口设置回调）以及SetTouchUpCallback接口设置回调），这些事件是在SelectionWheel控件的区域内发出（注意这个区域并不是可见的圆环区域，而是方形的区域，如下图所示）。

hover事件的触发本质上是与鼠标悬浮相关，在PC模式中，当鼠标从控件方形区域外移动到方形区域内时，会触发一次hover事件，从方形区域内移到方形区域外也会触发一次hover事件，当选中轮盘并且轮盘的选中索引发生了改变（index值改变）也会触发一次hover事件。 而在PE模式下，鼠标是模拟出来的，鼠标的悬浮是通过按着鼠标模拟点进行拖动或者点击某个位置来模拟的，因此hover事件触发逻辑其实和PC模式是一致的。

鼠标按下后弹起的事件则无论是PC还是PE都是一致的，是在控件方形区域内检测到鼠标按下后弹起都会触发（无论index是否改变了）。

轮盘控件-8

  • 注2

推荐轮盘所在的Screen用PushScreen的方式创建，因为PushScreen加载的UI是会对该UI中存在的控件中的贴图资源进行强制加载（如果这个贴图从未显示过的话），考虑到轮盘的贴图资源比较多（6切片的轮盘如果用CreateUI的方式创建轮盘，并且这些轮盘贴图从未显示过，那么选择轮盘的时候就会产生闪烁现象，原因就是第一次显示的贴图资源会动态加载，而动态加载是需要一定时间的。如果想彻底解决这类加载问题，详见 贴图预加载 。

轮盘控件-9

  • 注3

如果希望用手柄对轮盘进行控制，需要在轮盘所在的Screen上声明属性 "gamepad_cursor_deflection_mode" 为 true，具体可见下方的类似json代码

   "main" : {
      "controls" : [],
      "type" : "screen",
      "gamepad_cursor_deflection_mode": true
   },

# NeteaseComboBox

网易版单选下拉框，可以在给定的选项中进行选择。

"comboBoxPanel@combo_box.comboBoxPanel" : {
               "$content_size":[ "100.0%+0.0px", 100 ],
               "$item_size":[ "100.0%+0.0px", "10.0%x+0.0px" ],
               "$title_label":"combo_box.titleLabel",
               "$content_label":"combo_box.label",
               "$title_down_image":"combo_box.dropdownImage",
               "$title_up_image":"combo_box.dropupImage",
               "$default_title_texture" : "textures/ui/button_borderless_light",
               "$hover_title_texture" : "textures/ui/button_borderless_lighthover",
               "$pressed_title_texture" : "textures/ui/button_borderless_lightpressed",
               "$title_nineslice_size|default" : [ 0.0, 0.0, 0.0, 0.0 ],
               "$default_item_texture" : "textures/ui/button_borderless_light",
               "$hover_item_texture" : "textures/ui/button_borderless_lighthover",
               "$pressed_item_texture" : "textures/ui/button_borderless_lightpressed",
               "$item_nineslice_size|default" : [ 0.0, 0.0, 0.0, 0.0 ],
               "$scroll_background_texture" : "textures/ui/ScrollRail",
               "alpha" : 1.0,
               "anchor_from" : "center",
               "anchor_to" : "center",
               "clip_offset" : [ 0, 0 ],
               "clips_children" : false,
               "enabled" : true,
               "layer" : 0,
               "max_size" : [ 0, 0 ],
               "min_size" : [ 0, 0 ],
               "offset" : [ 0.0, 0.0 ],
               "priority" : 0,
               "propagate_alpha" : false,
               "size" : [ 120, 20 ],
               "type" : "panel",
               "visible" : true
            }
变量
 解释
$content_size 下拉框整个弹出框的大小，默认值为[ "100.0%+0.0px", 100 ]
$item_size 下拉框单个下拉项相对于整个弹出框的大小，默认值为[ "100.0%+0.0px", "10.0%x+0.0px" ]
$title_label 下拉框标题文本控件引用，默认值为"combo_box.titleLabel"
$content_label 下拉框单个下拉项文本控件引用，默认值为"combo_box.label"。
$title_down_image 下拉框未展开弹出框时标题右侧小图标控件引用，默认值为"combo_box.dropdownImage"
$title_up_image 下拉框展开弹出框时标题右侧小图标控件引用，默认值为"combo_box.dropupImage"
$default_title_texture 下拉框标题默认状态图片路径，默认值为"textures/ui/button_borderless_light"
$hover_title_texture 下拉框标题悬浮状态图片路径，默认值为"textures/ui/button_borderless_lighthover"
$pressed_title_texture 下拉框标题按下状态图片路径，默认值为"textures/ui/button_borderless_lightpressed"
$default_item_texture 下拉框单个下拉项默认状态图片路径，默认值为"textures/ui/button_borderless_light"
$hover_item_texture 下拉框单个下拉项悬浮状态图片路径，默认值为"textures/ui/button_borderless_lighthover"
$pressed_item_texture 下拉框单个下拉项按下状态图片路径，默认值为"textures/ui/button_borderless_lightpressed"
$title_nineslice_size 下拉框标题图片九宫切图，默认值为[ 0.0, 0.0, 0.0, 0.0 ]
$item_nineslice_size 下拉框单个下拉项图片九宫切图，默认值为[ 0.0, 0.0, 0.0, 0.0 ]
$scroll_background_texture 下拉框弹出框背景图片，默认值为"textures/ui/ScrollRail"

向该下拉框添加内容、注册选中回调等操作均需要调用UIAPI，详情请参考 NeteaseComboBoxUIControl

下图为网易版单选下拉框在游戏中的控件表现

网易版下拉框

UI编辑器暂时不支持编辑

# MiniMap

该控件可以在UI上画小地图，需要继承mini_map命名空间下的mini_map_wrapper控件。

其中官方封装了地图界面基类 MiniMapBaseScreen 供开发者扩展。

"mainPanel@mini_map.mini_map_wrapper" : {
    "anchor_from" : "top_right",
    "anchor_to" : "top_right",
    "layer" : 1,
    "offset" : [ -10.0, 10.0 ],
    "$enable_live_update": false,
    "$live_update_interval": 5,
    "$use_default_face_icon": true,
    "$face_icon_size": [4,4],
    "$face_icon_bg_color": "white",
    "$highest_y": 0
    // 如果希望小地图能够被裁剪，请继承后修改controls如下:
    "controls":[
      {
         "mini_map_bg@mini_map.mini_map_bg": {}
      },
      {
         "netease_mini_map@mini_map.netease_mini_map": {
            "allow_clipping":true,
            "enable_scissor_test" : true
         }
      },
      {
         "icon@mini_map.icon": {}
      },
      {
         "head_lbl@mini_map.head_label": {}
      },
      {
         "text_lbl@mini_map.text_label": {}
      }
    ]
}

相关字段说明：

变量
 解释
$enable_live_update 是否开启方块变化更新到小地图上（简称“热更”）
$live_update_interval “热更”的时间间隔，单位秒（s），不建议间隔太小，更新太频繁在低端机器可能有性能问题
$use_default_face_icon 本地玩家是否使用默认的脸部作为标记icon
$face_icon_size 脸部icon的大小，默认为[4,4]
$face_icon_bg_color 标记icon底部背景颜色，默认为白色
$highest_y 绘制的高度最大值，默认当前区块的最大值，当该值为-1时，表示最大高度值为玩家当前位置所在的高度
enable_scissor_test 超出父控件区域后是否裁剪，默认为false, enable_scissor_test (opens new window)

# 继承控件

继承控件允许开发者选择并继承目标控件，继承成功后该控件拥有目标控件的所有属性，并可以重写其中任何一个属性的数据。

# 继承写法简述

在界面json文件所有的编写技巧中，最为好用和灵活的功能当属继承写法。当界面中有一个需求，需要将若干个相同的控件按序排列，除了可以通过复制粘贴出若干个控件副本外，继承模板控件并只修改我们所需要修改的属性，其他的属性依然沿用模板控件的数据才是最便捷，也是最漂亮的写法。下面我们从一个简单的例子入手熟悉继承的写法，从例子中我们可以快速熟悉继承技巧。

{
   "main" : {
      "absorbs_input" : true,
      "always_accepts_input" : false,
      "controls" : [
         {
            "label0@myInherit.label0" : {}
         },
         {
            "inheritor0@myInherit.label0" : {
               "offset" : [ 10.0, 0.0 ]
            }
         },
         {
            "inheritor1@myInherit.label0" : {
               "offset" : [ 20.0, 0.0 ]
            }
         }
      ],
      "force_render_below" : false,
      "is_showing_menu" : true,
      "render_game_behind" : true,
      "render_only_when_topmost" : true,
      "should_steal_mouse" : false,
      "type" : "screen"
   },
   "label0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "color" : [ 1, 1, 1 ],
      "font_scale_factor" : 1.0,
      "font_size" : "normal",
      "font_type" : "smooth",
      "layer" : 0,
      "offset" : [ 0, 0 ],
      "shadow" : false,
      "size" : [ 100, 100 ],
      "text" : "Hello World!",
      "text_alignment" : "center",
      "type" : "label",
      "visible" : true
   },
   "namespace" : "myInherit"
}

该段json描述了在main画布中创建了一个文本控件label0，并使继承控件inherit0和inherit1均继承了label0控件，并重写了offset属性，在场景中就得到了三个文本控件，这三个文本控件除了在场景中的位置因为重写而不同外，其他的属性一模一样。但是要注意的是，可以被继承的控件必须写在json文件的最外层，和main处在同一层级，即一个命名空间下有且仅有一个该名称的控件，满足该条件的控件才可以被继承。

# UI编辑器中的继承

新版的UI编辑器对继承提供了更可视化的方法，请参考继承和自定义控件。

# Python编写说明

# 必要的属性

import mod.client.extraClientApi as clientApi
ViewBinder = clientApi.GetViewBinderCls()
ViewRequest = clientApi.GetViewViewRequestCls()
ScreenNode = clientApi.GetScreenNodeCls()
变量 解释
extraClientApi 我们开发的Client端Api接口文件
ViewBinder 用于绑定回调函数的类型和响应的方法
ViewRequest 用于返回绑定函数的返回值
ScreenNode UI的基类，用于继承基类的方法和UI管理

# UI界面初始化

class TestScreen(ScreenNode):
	def __init__(self, namespace, name, param):
		ScreenNode.__init__(self, namespace, name, param)

ScreenNode是我们的UI节点基类，必须继承。

# Bind Type
class ViewBinder(object):
	ButtonFilter = 0x10000000
	BF_ButtonClickUp	=	0 | ButtonFilter
	BF_ButtonClickDown	=	1 | ButtonFilter
	BF_ButtonClick		= 	2 | ButtonFilter
	BF_ButtonClickCancel= 	3
	BF_InteractButtonClick = 4
	BindFilter = 0x01000000
	BF_BindBool		= 5 | BindFilter
	BF_BindInt		= 6 | BindFilter
	BF_BindFloat	= 7 | BindFilter
	BF_BindString	= 8 | BindFilter
	BF_BindGridSize = 9 | BindFilter
	BF_BindColor	= 10 | BindFilter
	EditFilter = 0x00100000
	BF_EditChanged	= 11 | EditFilter
	BF_EditFinished	= 12 | EditFilter
    ToggleFilter = 0x00010000
	BF_ToggleChanged = 13 | ToggleFilter
# Return Type
class ViewRequest(object):
	Nothing = 0
	Refresh = 1 << 0
	PointerHeldEventsRequest = 1 << 1
	PointerHeldEventsCancel = 1 << 2
	Exit = 1 << 3

# UI绑定和返回

UI的绑定分为binding单个绑定和binding_collection集合绑定，适合集合容器。

绑定类型 绑定方式 解释
BF_ButtonClickUp binding 绑定按钮的Up事件
BF_ButtonClickDown binding 绑定按钮的Down事件
BF_ButtonClick binding 同时绑定Up和Down事件
BF_ButtonClickCancel binding 绑定按钮的Cancel事件（按钮down其他up）
BF_InteractButtonClick binding 绑定游戏原生的按钮点击事件
BF_BindBool binding | binding_collection 绑定Bool变量
BF_BindInt binding | binding_collection 绑定Int变量
BF_BindFloat binding | binding_collection 绑定Float变量
BF_BindString binding | binding_collection 绑定String变量
BF_BindGridSize binding 绑定GridSize变量
BF_BindColor binding | binding_collection 绑定颜色变量
BF_EditChanged binding 绑定输入框输入改变事件
BF_EditFinished binding 绑定输入框输入完成事件
BF_ToggleChanged binding 开关状态改变事件

binding(bind_flag, binding_name = None)

bind_flag为上文中绑定类型，binding_name为绑定名称。

binding_name为脚本绑定变量，binding_name_override为引擎变量，json格式如下

      "bindings" : [
         {
            "binding_condition" : "always",
            "binding_name" : "#scoreboard_grid.item_count",
            "binding_name_override" : "#StackGridItemsCount"
         }
      ]

对应的Python代码如下

	@ViewBinder.binding(ViewBinder.BF_BindInt, "#scoreboard_grid.item_count")
	def OnStarkGridResize(self):
		return len(self.scoreBoardList)

binding_collection(bind_flag, collection_name, binding_name = None)

bind_flag为上文中的绑定类型，collection_name为集合名称，binding_name为绑定的变量名称。

集合的json如下：

"collection_name" : "scoreboard_stackgrid"

在集合的子控件中，binding_collection_name为集合名，binding_condition为绑定条件，binding_name为绑定名称，binding_type为collection绑定，property_bag设置他的初始值，text为它的绑定值。

   "label_score_board" : {
      "bindings" : [
         {
            "binding_collection_name" : "scoreboard_stackgrid",
            "binding_condition" : "always",
            "binding_name" : "#label_score_board.text",
            "binding_type" : "collection"
         }
      ],
      "offset" : [ "0%+0 px", "0%+0px" ],
      "property_bag" : {
         "#label_score_board.text" : "666666666666"
      },
      "text" : "#label_score_board.text",
      "text_alignment" : "left",
      "type" : "label",
      "visible" : true
   },

对应的Python代码如下，其中index表示在集合中的哪一元素。

	@ViewBinder.binding_collection(ViewBinder.BF_BindString, "scoreboard_stackgrid", "#label_score_board.text")
	def OnRefreshScoreBoardLabel(self, index):
		return self.scoreBoardList[index] if len(self.scoreBoardList) > index else ""

# 接口调用说明

# 参数命名说明

@Mod.Binding(name = myModName, version = myModVersion)

参数 类型 解释
myModName str Mod名称
myModVersion str Mod版本

假设设置Mod名称为"myModName"，示例：

    @Mod.Binding(name = "myModName", version = "0.1")
    class MyModClass(object):
        def __init__(self):
            pass

# 界面创建流程及生命周期

界面在 UiInitFinished 事件发送之后就可以开始创建

创建UI的第一步是UI的注册，通过调用 RegisterUI 接口，将想开启UI的相关数据进行注册。同一UI只需要注册一次即可

注册完成之后就可以在需要的时候实例化UI，可使用的接口有 CreateUI 和 PushScreen 两种。使用 CreateUI 生成的界面都生成在操作UI下，不同的生成参数UI层级不同，而使用 PushScreen 生成的界面以堆栈管理的方式生成，该界面生成时上一个 PushScreen 生成的界面就会被隐藏。值得注意的是，MC原生界面（比如暂停界面，背包界面等）也是类似 PushScreen 的方式加载进来，并以堆栈管理。

在UI创建完成之后，可以调用 GetUI 接口拿到UI对应的ScreenNode实例。 如果想获取MC原生界面的实例，则需要监听原生界面Push进来的事件 PushScreenEvent ，然后在事件回调中调用接口 GetTopPushedUI 。

每个ScreenNode都有生命周期函数，生命周期函数会被自动在以下情况下调用，重写函数可以完成一些逻辑。

函数 作用
Create UI创建成功时调用
OnActive UI重新回到栈顶时调用
OnDeactive 栈顶UI有其他UI入栈时调用
Destroy UI销毁时调用

最后，当UI需要销毁时，可以调用ScreenNode实例的 SetRemove 接口，此外使用 PushScreen 接口创建的界面还可以使用 PopScreen 接口进行销毁。

# 手柄交互

（1）使用 PushScreen生成出的界面，调出手柄光标，有两步一是需要将底层Screen继承自common.base_screen，二是将screen的"gamepad_cursor" 属性设置为 true，如下格式

{
   "main@common.base_screen" : {
       ....
       "gamepad_cursor" : true
   },
   "namespace" : "Test"
}

（2）使用 CreateUI生成出的界面，只支持手柄与创建UI时isHud参数设置为0的Screen中的按钮进行交互。

（3）使用 PushScreen生成出具有轮盘控件的UI时，需要将底层screen的"gamepad_cursor_deflection_mode" 属性设置true，否则将无法选中轮盘格子

（4）GamepadModDemo展示了两种UI创建如何与手柄交互，以及一个基础的扳机使用方法。

# UIDemoMod介绍

为了让开发者更好的了解各个UI控件的使用方法以及控件在mod界面中的应用，我们开发了一个简单的UIDemoMod，开发者可以在官网下载到它。该Demo包含了文本、文本输入框、滚动列表、网格、进度条、按钮、图片、开关、纸娃娃、道具渲染控件的操作与逻辑演示。下图为UIDemoMod菜单界面。

UIDemo菜单

例如我们想了解一下文本控件是如何使用的，点击“文本控件演示”按钮进入演示界面，如下图。

UIDemo菜单

由于功能相关以及方便演示，我们将文本和文本输入框控件做在一个界面中共同演示。控件的演示界面中有待演示的UI控件、操作方法和返回菜单界面按钮。如操作方法描述的，我们在文本输入框中输入文本，上方的文本控件会根据文本输入框输入的内容发生对应的变化，逻辑可以在UIDemoMod的脚本代码中查到，如下图。

UIDemo菜单

还想了解其他控件的用法，就下一个UIDemo看看吧！

# 富文本控件介绍

富文本控件提供了一个支持文本、图片、按钮、超链接、序列帧的复合文本控件，富文本控件接受按一定规则组成的字符串，除去常规文本外，定制化文本及非文本控件用html的标签写法隔开（如<button></button>）,中间填写json格式数据。开发者可以在UI中引用该控件，并将符合解析规则的字符串传入解析接口，富文本控件会根据传入的字符串顺序排列生成富文本。以下详细介绍用法。

# 富文本支持定制化文本及非文本控件及写法

# 换行控件

2.6新增换行控件<br>，可在非标签的内容、定制化文本控件<label>的“text”变量，按钮控件<button>的“button_label”变量中使用。

  • 非标签内的换行与常规换行类似，但是需要下一行有内容才会出现换行效果，所以在文本的首位两端使用<br>换行控件是没有任何效果的
  • 定制化文本控件<label>的“text”变量，按钮控件<button>的“button_label”变量中使用<br>控件，只是对内部的内容进行换行，无法影响到外部的内容

使用方法如下所示

// 定制化文本控件
<label>
{"text" : "玩<br>家一", 
 "font" : "smooth", 
 "scale": 3, 
 "color": [1,0,0,1]}
</label>

// 在非标签的内容
Dear player, <br>welcome to Minecraft, <br>where you can build your own world

// 按钮控件
// 注意：如果按钮控件空间不足以显示该字符串，多余部分将以"..."显示
<button>
{"button_label": "1<br>2<br>3", 
 "press_texture" : "textures/ui/btn_pressed",
 "hover_texture" : "textures/ui/btn_hover",
 "default_texture" : "textures/ui/btn_light_default","x":50, "y":100}
</button>

例子及效果：

<label>{"text" : "玩<br>家一", "font" : "smooth", "scale": 3, "color": [1,0,0,1]}</label><br><button>{"button_label": "1<br>2<br>3", "press_texture" : "textures/ui/btn_pressed","hover_texture" : "textures/ui/btn_hover","default_texture" : "textures/ui/btn_light_default","x":50, "y":100}</button>:恭喜！<br>击杀了<link>{"text" : "末影人", "format_code":"§2"}</link>

rich_txt_br

# 定制化文本控件

在字符串中嵌入<label>label_data</label>样式文本会被解析成定制文本，与常规文本不同的是定制化文本可以独立设置文字的字体、大小、颜色等，丰富富文本的文本样式。label_data为特殊化数据，以下所列属性为必须属性，text为文本，font为字体，默认值为unicode，scale为字体缩放倍率，默认值为1.0，color为字体颜色，默认值为[1,1,1,1]。需要注意的是如果文本中存在中文字符则字体会被强制设置为unicode，此外如果字体缩放倍率过大该段文本将不会被显示。

   label_data：{
      "text" : "玩家一", 
      "font" : "smooth", 
      "scale": 3, 
      "color": [1,0,0,1]
      }

# 图片控件

在字符串中嵌入<image>image_data</image>样式文本会被解析成图片，image_data为特殊化数据，以下所列属性为必须属性，texture为资源路径，x为图片宽度，y为图片高度

   image_data：{
      "texture":"texture/ui/laugh",
      "x":30,
      "y":30
   }

# 按钮

在字符串中嵌入<button>button_data</button>样式会被解析成按钮，button_data为特殊化数据，开发者可以在其中添加符合json格式的自定义数据，在点击富文本中对应按钮时会将button_data通过回调函数整个返回，以下属性为必须属性，press_texture为按钮按下贴图，hover_texture为按钮鼠标悬浮贴图，default_texture为默认状态下按钮贴图，button_label为按钮上的问题，x为按钮宽度，y为按钮高度

   button_data:{
      "press_texture": "",
      "hover_texture": "",
      "default_texture": "",
      "button_label": "",
      "x":20,
      "y":20
   }

# 超链接

在字符串中嵌入<link>link_data</link>样式会被解析成超链接，外观和普通文本无异但可以被点击，link_data为特殊化数据，开发者可以在其中添加符合json格式的自定义数据，在点击富文本中对应超链接时会将link_data通过回调函数整个返回，以下属性为必须属性，text表示显示文本，format_code表示该段显示文本的样式代码，注意，基岩版的文本控件不支持下划线和删除线。

   link_data:{
      "text":"末影人",
      "format_code":"§2"
      }

# 序列帧动画

在字符串中嵌入<sfx>sfx_data</sfx>样式文本会被解析成图片，sfx_data为特殊化数据，以下所列属性为必须属性，texture为资源路径，x为显示图片宽度，y为显示图片高度，uv_x为截取图片宽度，uv_y为截取图片高度，frame_count表示该序列帧的总帧数，fps为每秒执行帧数。

   sfx_data:{
      "texture": "textures/ui/eating_apple",
      "x":30,
      "y":30,
      "uv_x": 64,
      "uv_y": 64,
      "frame_count": 36,
      "fps": 10
   }

# 富文本成品范例

# 文本

'[玩家]<label>{"text" : "玩家一", "font" : "smooth", "scale": 3, "color": [1,0,0,1]}</label><button>{"press_texture" : "textures/ui/btn_pressed","hover_texture" : "textures/ui/btn_hover","default_texture" : "textures/ui/btn_light_default","x":20, "y":20}</button>:恭喜！<image>{"texture":"textures/ui/skin/ty_yuanshenghuli_0_0", "x":30, "y":30}</image>击杀了<link>{"text" : "末影人", "format_code":"§2"}</link><sfx>{"texture": "textures/ui/eating_apple","x":30, "y":30,"uv_x": 64,"uv_y": 64,"frame_count": 36,"fps": 10}</sfx>'

# 效果

富文本效果

# 如何使用富文本

# UI文件编写

若需要使用富文本，开发者只需要继承rich_text命名空间下的RichTextPanel控件，它是一个panel控件，也是单个富文本控件的根节点，该panel的宽度决定了富文本宽度。我们开放了若干引用属性可供设置。

  • $rich_panel_bg

    开发者可以设置富文本的背景图片

  • $rich_panel_nineslice_size

    开发者可以设置背景图片的九宫切图,值为0.01代表开启微软版本的九宫切图，且上下左右为切图像素为0.01，等价于[0.01,0.01,0.01,0.01]。

  • $rich_panel_font_size

    开发者可以设置富文本的文本字体大小，可设置选项为small, normal, large其中一个，默认值为normal

  • $rich_panel_font_scale_factor

    开发者可以设置富文本的文本字体缩放倍率，和$rich_panel_font_size一起影响富文本字体的最终大小，默认值为1.0

  • $rich_panel_color

    开发者可以设置富文本的文本字体颜色，默认值为[1,1,1]，白色

   "main" : {
      "absorbs_input" : true,
      "always_accepts_input" : false,
      "controls" : [
         {
            "RichTextPanel@RichText.RichTextPanel" : {}
         }
      ],
      "force_render_below" : false,
      "is_showing_menu" : true,
      "render_game_behind" : true,
      "render_only_when_topmost" : true,
      "should_steal_mouse" : false,
      "type" : "screen"
   },
   "RichTextPanel@rich_text.RichTextPanel" : {
      "$rich_panel_bg": "textures/ui/effect_background",
      "$rich_panel_nineslice_size": 0.01,
      "$rich_panel_font_size" : "large",
      "$rich_panel_font_scale_factor" : 2.0,
      "$rich_panel_color" : [1,1,1]
   },

# python脚本编写

在需要创建富文本时，调用UIAPI GetRichTextItem，将富文本控件路径作为参数传入，就能返回得倒一个RichTextItem实例，就完成了富文本的初始化。

富文本提供了三个回调注册接口和一个设置文本接口。

# registerLinkItemClickCallback

注册点击超链接回调函数，参数为一个函数引用。超链接点击触发时会返回开发者给超链接设置的数据，以及当前点击屏幕的坐标值touchX和touchY

# registerButtonItemClickCallback

注册点击按钮回调函数，参数为一个函数引用。按钮点击触发时会返回开发者给按钮设置的数据，以及当前点击屏幕的坐标值touchX和touchY

# registerRichTextFinishCallback

注册富文本创建完毕回调函数，由于富文本构成较为复杂，无法在一帧之内生成完毕，因此生成需要一点点时间，等富文本创建完毕后会调用该回调函数。

# readRichText

创建富文本入口，接受一个符合格式的字符串，将其转变为富文本显示出来。

以下是示例

   def CreateRichText(self):
      self.richTextPath = "/RichTextPanel"
      self.richTextItem = self.GetRichTextItem(self.richTextPath)
      self.richTextItem.registerLinkItemClickCallback(self.OnLinkItemClickCallback)
      self.richTextItem.registerButtonItemClickCallback(self.OnButtonItemClickCallback)
      self.richTextItem.registerRichTextFinishCallback(self.OnRichTextCreateFinishCallback)
      self.richTextItem.readRichText('[玩家]<label>{"text" : "玩家一", "font" : "smooth", "scale": 3, "color": [1,0,0,1]}</label><button>{"press_texture" : "textures/ui/btn_pressed","hover_texture" : "textures/ui/btn_hover","default_texture" : "textures/ui/btn_light_default","x":20, "y":20}</button>:恭喜！<image>{"texture":"textures/ui/skin/ty_yuanshenghuli_0_0", "x":30, "y":30}</image>击杀了<link>{"text" : "末影人", "format_code":"§2"}</link><sfx>{"texture": "textures/ui/eating_apple","x":30, "y":30,"uv_x": 64,"uv_y": 64,"frame_count": 36,"fps": 10}</sfx>')

   def OnButtonItemClickCallback(self, data, touchX, touchY):
      print("---OnButtonItemClickCallback---", data, touchX, touchY)

   def OnLinkItemClickCallback(self, data, touchX, touchY):
      print("---OnLinkItemClickCallback---", data, touchX, touchY)

   def OnRichTextCreateFinishCallback(self):
      print("---OnRichTextCreateFinishCallback---")
# 使用事项
  • 富文本是python实现的一个复合控件，在生成富文本后会有部分数据缓存在RichTextItem实例中，因此不支持使用clone接口复制已创建完成的富文本，但是clone没有调用过readRichText的富文本是可行的。
  • 我们在内部会缓存路径与RichTextItem实例的映射，使用GetRichTextItem接口，传入相同路径返回的RichTextItem实例也会是相同的。

入门

分钟

← UI API →

文件命名说明

JSON编写说明

命名空间

Main Screen

特殊情况下的根节点路径变化

控件介绍

screen

通用属性

Label

Image

Image Button

Panel

InputPanel

StackPanel

TextEditBox

PaperDoll

NeteasePaperDoll

ItemRenderer

ScrollView

Grid

ProgressBar

SwitchToggle

Slider

SelectionWheel

NeteaseComboBox

MiniMap

继承控件

Python编写说明

必要的属性

UI界面初始化

UI绑定和返回

接口调用说明

参数命名说明

界面创建流程及生命周期

手柄交互

UIDemoMod介绍

富文本控件介绍

富文本支持定制化文本及非文本控件及写法

富文本成品范例

如何使用富文本