控件基础

控件是具有用户界面的，在场景中，我们通过控件Widget来实现不同形式的场景交互。

我们 SDK 内置了如下一些基础控件：

导航罗盘 CompassWidget
导航Cube CubeViewWidget
操作引导 GuideWidget

滚轮特效 MouseScrollingEffectWidget
鼠标提示窗 MousePromptWidget
底部状态栏 StatusBarWidget
时间面板 ClockPanelWidget

主题切换 ThemeWidget

弹窗 popup
场景目录 BuildingTreeWidget
UI组件 UIDisplayWidget
右键菜单 ContextMenu
工具栏 ToolbarWidget

注：除此之外，我们也在开发新的控件，实时更新控件。

1. 安装控件

在场景中安装控件的两种方法：

初始化场景之时，直接添加控件
初始化场景之后，初始化并添加控件

注：除此之外，有些控件的安装不使用以上两种方式，后面会单独介绍其安装使用。

1.1 初始化场景之时，直接添加控件

new ubm.Scene('app', {
  ...
  ui:{
    widgets:[
      {
        //id 唯一标识符
        id:'home',
        // name 控件名称
        name: 'HomeWidget',
        //position 控件位置信息 top-right | top-left | bottom-right | bottom-left | manual  
        position: 'top-right',
      }
    ]
  }
  ...
})

注： position 属性中的 manual，是有些控件是有自己内置的固定位置，不需要自己设置位置，可以不设置 position 属性，也可以将其设置为 manual 。

1.2 初始化场景之后，初始化并添加控件

初始化控件

// 以导航器控件为例，传入的参数 scene 为当前的场景初始化之后的实例。
const instanceWidget = new ubm.CubeViewWidget(scene)

注：控件在实例化的时候，一些控件是需要传递必要的参数的，具体的控件需要具体分析。

动态添加控件：通过场景实例的 UI 属性使用add()方法来动态添加控件

//add方法的第二个参数为位置参数，表示所添加控件在场景中的位置。
scene.ui.add(instanceWidget, 'top-right')

2. 卸载控件

需要获取到控件实例instanceWidget，再通过场景实例的 UI 属性使用remove()方法来卸载控件。

scene.ui.remove(instanceWidget)

注：在使用动态添加add()或移除remove() 控件的时候，要在 scene.when() 函数的回调中使用，意为待 scene 场景实例加载完成后才添加控件。

界面控件

控件列表

在我们 SDK 中有众多控件，每个控件都有不同的功能与交互。