林业地理信息数据管理之六（下）
- Web AppBuilder构建应用程序
（陈家 安徽省林业调查规划院）
本章我们继续介绍Web AppBuilder的微件定制开发，上一章说了微件里面文件的修改，本章的主要内容是地图操作等。
（六）访问地图
Web AppBuilder for ArcGis是一种以地图为中心的应用，它在baseWidget类里定义了访问地图的属性，我们可以通过这些属性访问地图。微件的地图属性是从基础javascript的ArcGis API中的esri.Map派生的一种类型，主要配置都在“config.json”这个文件中。你可以通过这个访问所有的地图，编写代码和通常的ArcGis JavaScript应用程序方法相同。
当微件实例化的时候，地图就会被传递到这个微件中，这时，我们可以通过“postCreate”或者“startup”这两个方法访问地图属性。
首先，修改“widget.html”文件，加入需要显示地图的ID：
其次，在“widget.js”文件内，在“startup”方法中加上js代码访问地图：
（七）和应用程序容器通讯
如果一个微件是Dojo Dijit微件的话，当这个微件实例化的时候，它会完成一个Dijit微件的生命周期，例如constructor、postCreate、startup。
下面介绍一下常用的回调函数：
* onOpen 当微件实例化的时候，这个函数会在startup后调用，每次微件打开的时候会调用这个函数；
* onMaximize 当微件最大化的时候调用该函数，这个方法对于控制板内的微件无效；
* onMinimize 当微件最小化的时候调用该函数，这个方法对于控制板内的微件无效；
* onClose 当微件关闭的时候调用；
* onSignIn 当用户登录上门户的时候调用；
* onSignOut 当用户登出门户的时候调用；
* onPositionChange 当微件的位置发生变化的时候调用，用户改变页面布局的时候，可能会导致微件位置发生变化；
* resize 当窗口改变大小的时候调用；
* onNormalize 当微件正常化的时候调用；
* onActive 当微件处于活动状态调用，只要用户点击微件，这个微件就处于活动状态；
* onDeActive
当微件处于不活动状态调用，当用户点击一个微件，其它微件则处于不活动状态；
* setPosition
当屏幕上的微件在打开之前调用，在默认状态下，这个微件会被放置在指定的位置；
* getPanel 返回微件的控制板，如果是板式外的微件，则返回空值。
（八）微件的属性
微件的属性主要包括以下这些：
* id 由应用程序容器自动产生或者在config.json手工进行配置微件的id；
* icon 该微件的图标；
* config 该微件的配置对象；
* map 二维微件的关联地图；
* sceneView 三维微件的关联场景；
* appConfig 应用程序主配置文件（config.json）的位置；
* folderUrl 微件存放目录的地址；
* state 微件当前的状态，活动、打开或者关闭等；
* windowState 微件的当前窗体状态，正常、最大化或者最小化；
* position 微件的位置，这对于屏幕上的微件尤为重要。
（九）制作响应敏捷的微件
jimu.js文件不仅支持响应敏捷的图形布局，并且可以提供相应的功能给开发者开发微件。
有两种方法可以实现这个目标，即CSS和Dijit layout，我们可以在Web AppBuilder安装目录下的client\jimu.js\css中找到jimu.css文件，它可以迅速的设置页面的格式、显示效果等：
* jimu-r-row 一行布局；
* col-1-2 宽度为父控件的一半；
* col-1-3 宽度为父控件的三分之一；
* col-2-3 宽度为父控件的三分之二；
* col-1-4 宽度为父控件的四分之一；
* col-3-4 宽度为父控件的四分之三；
Dijit布局可以在jimu.js\dijit目录中找到有一个TileLayoutContainer文件，用于描述页面布局情况：
（十）微件之间的通讯
baseWidget类支持在两个微件之间读取或者发送数据。在baseWidget类的构造器中，有publishData、dataFetched和noData事件，同样的，baseWidget类也提供了publishData和fetchData方法。
如果想让微件发布数据，可以调用publishData方法；
如果想让微件接受从另外一个微件发送的数据，可以调用fetchData方法；
同时改写onReceiveData和onNoData方法读取数据；
所有发布的数据都被存放在名为DataManager的数据存储里，一个微件可以在被加载之前就接收发布的数据。举个例子，微件B想读取微件A发送的数据，在微件B被加载之前，从微件A发布的数据已经存储在DataManager中了。当微件B被加载的时候，它会调用fetchData方法读取DataManager中的数据。在微件B被加载之后，它将接收所有从微件A发送的数据。在某些情况下，在发送信息给这个微件之前，我们可能已经使用this.openWidget这个方法来打开它。那么两种情况的工作流如下：
关于微件通讯的例子，大家可以看看Web AppBuilder安装目录下“client\stemapp\widgets\samplewidgets”的“WidgetCommunication”。
（十一）Dojo dijit
微件是一个Dojo的UI框架，源自baseWidget的UI框架，它可以快速开发WEB应用程序。为了实现程序目的，不要在baseWidget里面混入_WidgetInTemplateMixin。
（十二）让微件在成为可配置
如果一个微件是可以配置的，那么这个微件的行为就可以通过编辑config.json进行控制。为了更好的用户体验，微件应该提供配置界面。
微件应该遵循以下规则：
1、建立名为setting的文件夹，用于存放与设置相关的文件；
2、在上述文件夹里创建setting.js文件，用于存放配置逻辑。这个类应该从baseWidgetSetting中继承而来，里面存放着控制微件配置数据的属性值。
3、这个类需要改写两个方法，一个是getConfig，用于返回用户输入的参数；另一个是setConfig，用于使用默认参数初始化微件的设置页面；
4、创建“setting.html”文件，用于管理配置的用户界面。
5、创建“string.js”文件，在“setting\nls”文件夹中，用于存放国际化文件；
6、创建“style.css”，在“setting\css”文件夹中，用于存放配置界面的样式文件。
完成以上的修改后，我们就可以在浏览器中访问定制好的微件了。
（十三）让微件向下兼容
每一个微件的配置都会存放在应用程序中，当微件产生新的功能时，我们需要去修改配置格式。想让微件向下兼容以前的配置，我们有两种方法可以实现：自动检查配置格式或者使用版本管理器去升级旧的格式文件，强烈建议使用后一种方法。
1、代码比较简单，那么只需要处理最后一次格式；
2、如果很容易监测到的变化，只需要将其放入版本管理器；
3、首先BaseVersionManger类将通过以下操作被继承：
（1）在“manifest.json”里加入使用版本管理的属性值：
（2）创建一个新文件名为“VersionManger.js”里面内容为：
当从BaseVersionManager中继承的时候，需要注意以下事项：
*因为BaseVersionManager在浏览器和Node.js中运行，Dojo类不导入Node.js的话，那么Dojo类将不会被使用；
* 将所有的版本放入属性值中；
* 对于升级后的功能来说，输入的是旧的配置，输出是新的配置文件。
（十四）建立控制微件
控制微件是一种在微件池中可以控制其它微件的微件，在下面文件夹的“widgets”目录中可以找到“HeaderController”这个示例微件：
控制微件通常都是主题的一部分，除了需要添加以下操作外，创建控制微件的方法和其它微件是一样的。
1、添加“jimu\PoolControllerMinxin”类，这个类提供了以下方法：
（1）getWidgetConfigs，返回微件池中所有微件的配置；
（2）getGroupConfigs，返回微件池中所有群组微件的配置；
（3）getAllConfigs，返回微件池中所有微件（分组或者未分组）的配置；
（4）getConfigById，获得配置部分的id。
2、在构建环境中，这个类还会提供以下方法：
（1）getOpenedIds，返回打开微件和群组的所有id；
（2）setOpenedIds，使用定义的参数打开微件和群组。
3、在微件池中创建控制菜单。
当我们在主题中选择“折叠式主题”后，窗口上方的就是控制微件：
（十五）微件生命周期
每一个Web AppBuilder for ArcGis微件都被应用程序框架管理着，并且有自己的生命周期。当应用程序加载或者点击按钮的时候，一个或者多个微件加载和打开。对于屏幕上的微件，布局管理器促使微件管理器异步的加载微件。在微件被加载之后，布局管理器就会调用微件的setPosition方法，将其放入DOM树上，置于正确的位置，并且允许微件管理器打开它。下面的图表描述了这个方法如何在微件的生命周期里运行：
setPosition方法被调用，将微件放在DOM树上，并置于正确的位置，仅仅应用于板式外微件，对于板式内微件，位置需要依靠控制板决定。
每个微件都有两个属性用于保存微件状态：state和windowState。state属性代表着微件的活动状态：活动的、被打开和已关闭。windowState属性代表微件的窗口状态：正常、最大化和最小化。下面的图表反应了这些状态的切换：
（十六）在微件中加入帮助
要为自己定制的微件链接上帮助文档，首先需要将帮助文件的html格式准备好，然后按照如下步骤操作：
1、将定制好的微件拷贝到微件的存放位置，一般来说都是Web AppBuilder安装目录下的“client\stemapp\widgets”里；
2、将准备好的帮助文档拷贝到微件目录中的“\docs”里；
3、打开“client\builder”目录中的widgetHelp.json文件，在“dev”属性域中加入微件名称和对应帮助文档的属性值；
4、运行服务，在浏览器里输入地址“https://gis.linye.cn:3344/webappbuilder/help/帮助文档的文件名加扩展名”，看看是否能够打开；
5、在Web AppBuilder里，建立应用程序并添加定制的微件；
6、打开微件设置界面，单击“Learn more about the widget”，帮助文档就会显示出来。
（十七）微件中调用地图工具
地图工具是一段代码可以去操作一个或者一组地理要素。Web AppBuilder for ArcGis提供了一些能够直接放在地图上的地图工具，比如缩放、导出和属性表。另外我们可以通过baseFeatureAction来定制地图工具，以下的步骤演示了如何在Demo微件里建立地图工具：
1、建立地图工具类：
（1）浏览Web AppBuilder安装目录的“client\stemapp\widgets\samplewidgets”；
（2）在上述目录的Demo微件目录中，建立一个新的文本文件命名ShowVertexFeatureAction.js；
（3）将以下代码复制粘贴到上述文件中去：
2、声明地图工具
在“manifest.json”文件里加上featureActions属性：
3、标签地图工具
打开“demo\nls”文件夹里的“string.js”文件，加上以下内容：
4、地图工具的图标
与图标相关联的是地图工具的两种状态：正常状态和鼠标悬停状态，所以需要两个图标来支持：
（1）将需要的图标文件拷贝到“demo\images”文件夹里，分别命名为ShowVertex_default.png和ShowVertex_hover.png；
（2）修改地图工具类中的iconFormat属性，使之能够支持图标格式。
5、显示计数
（1）打开“Widget.js”文件，添加以下代码：
（2）打开“Widget.html”文件，添加如下代码：
6、使用地图工具
以选择工具为例，当选中某个要素后，点击省略符号，就可以查看能够进行的地图工具。
这里最重要的方法是 FeatureActionManager.js API的“getSupportAcitons()”方法。
（十八）微件的数据源设置
以Web AppBuilder建立的应用程序是以地图为中心的，这意味着所有微件都有地图参数，并且能够从地图读取数据。在2.5版本的时候，一个关于数据源的新概念被引入，即能够被微件所使用的新型数据。有两种方法产生这种数据源：配置额外的数据源或者从微件中产生它。产生的数据源将被保存在应用程序的配置文件中，所有微件都可以使用它。
这种数据源是微件之间相互通讯的好办法，在示例微件中有两个例子来演示这个数据源概念：samplewidgets\DataSourceProvider和samplewidgets\DataSourceConsumer。效果如下：
（十九）单元测试
大家都知道，代码编写完成后需要进行测试，如果每次都放在web进行测试会很麻烦，因此这部分会介绍Web AppBuilder建立和运行单元测试。微件和应用是基于AMD进行编写的，因为这样，下面介绍的是以支持dojo的Intern为测试框架。
1、首先需要下载nodejs，https://nodejs.org/en/download/，根据自己的需要下载相应的版本，然后安装；
2、然后下载Intern 4.2.0，https://github.com/theintern/intern，下载后解压到相应的目录；
3、进入该目录，输入“npm install intern -gf”安装intern；
4、安装完成后， “C:\Users\Jia Chen\AppData\Roaming\npm\node_modules\intern”就是工程位置，添加如下代码到package.json文件：
“scripts”:{
“test”:”intern”,
…
然后在工程目录下运行npm test，就可以启动测试了。
6、如果想测试微件或者应用程序，请按照ArcGis官网上的介绍按步骤操作，就可以测试了。
关于Web AppBuilder for ArcGis我们就介绍到这里了，在ArcGis官网中有很多微件的示例代码，大家有兴趣可以去看看，在今后支持会越来越丰富的，这是一个发展趋势，会将我们Web应用系统开发的门槛和难度降得很低。在以后的章节中，我会介绍微件开发的一些技巧和方法。
（如需转载，请注明出处）