开发选择城市组件

运行效果

选择城市组件，绑定数据列，运行时点击该组件，弹出城市列表，选择某个城市，将城市名称写入数据列

设计思路

组件使用只读的输入框实现

1 组件属性

• 组件提供2个自定义属性：绑定数据列和提示信息
• 组件提供动态绑定属性：动态隐藏、动态样式、动态禁用

2 组件样式

组件提供基本、文字、边距、边框、定位、圆角、阴影等样式

3 组件事件、方法

组件不提供事件和方法

4 设计时界面

组件文件结构

• 自定义的组件在UI2/comp目录下
• 一个组件包可以包括多个组件
• 一个组件包括设计时文件、编译时文件和运行时文件

开发过程

开发一个组件包city，组件包中包括一个组件selectCity

1 开启组件开发功能

切换到高级页面，点击“开启组件开发”

2 新建组件包

切换到页面设计区，点击“组件包管理”右侧的“新建组件包”按钮

输入组件包名称city，选择组件包类型为小程序，输入组件版本1.1，单击确定按钮新建组件包

3 新建组件

点击组件包city右侧的“新建组件”按钮

组件类型选择数据绑定组件，组件名称输入selectCity，组件标签输入选择城市，命名空间输入city，单击确定按钮新建组件

组件创建后，自动切换到“comp/city-小程序”端，在这里可以进行页面、数据和服务的可视化设计，也可以编辑编译时文件和运行时文件。手动切换到“comp/city-设计时”端，可以编辑设计时文件。也可以切换到“代码”页面，编辑设计时文件、编译时文件和运行时文件

4 组件的基础配置

首先配置组件的图标、模板、属性、Tag标签，然后在组件面板中显示组件

4.1 添加组件图标

编辑组件的设计时文件时，切换到“comp/city-设计时”端

点击designer/img目录右侧的文件上传按钮

上传一个图片文件

打开组件描述文件，在element标签中添加 icon="city.jpg"

4.2 添加组件属性

在组件描述文件中设置组件的全部属性，在组件的设计时JS文件定义显示的属性

4.2.1 设置全部的属性

在properties标签中定义组件的全部属性

添加通用属性，包括id和显示名称属性

<include path="$UI/wxsys/comps/designerCommon/commonConfig.xml#//common-properties/group[@name='common']/*"/>

添加绑定数据列属性

<property name="bind:ref" text="绑定数据列" editor-ref="dataRef" data-type="string" required="true"/>

添加提示信息属性

<property name="placeholder" text="提示信息" data-type="string" />

添加动态绑定属性，包括动态隐藏、动态样式、动态禁用

<include path="$UI/wxsys/comps/designerCommon/commonConfig.xml#//common-properties/group[@name='bind']/*"/>

设置后如下图所示

4.2.2 设置显示的属性

打开组件设计时JS文件，设置显示的属性

引用commonProp.js文件

var CommonProp = require("$UI/wxsys/comps/designerCommon/js/commonProp");

设置显示的属性

properties : [{name:"label",text:"显示名称"},"bind:ref","placeholder",CommonProp.bind_input()]

设置后如下图所示

4.3 配置组件模板

• template中的代码是在页面添加组件后，加在w文件中的代码
• 在模板中定义组件的结构，设置有默认值的属性:placeholder="请选择城市"
• 组件在w文件中是city:selectCity标签，用于设计器的显示，编译后会变成input标签，添加disabled="true"设置禁用

设置后如下图所示

4.4 设置组件的Tag标签

组件在w文件中是city:selectCity标签，编译为input标签，打开编译文件将return "selectCity"; 改为 return "input";

设置后如下图所示

4.5 处理数据绑定

数据绑定组件需要继承自BindComponent类，将extends WxComponent 修改为 extends BindComponent

增加处理绑定数据列的方法

public void processRef(Element bound, String ref){
    bound.addAttribute("value", " + ref + ");
}

设置后如下图所示

4.6 在组件面板中显示新建的组件

修改组件描述文件后，需要点击“更新配置文件”

更新后，切换到应用小程序端，在组件面板中显示出新建的组件

5 组件的功能实现

切换到comp/city-小程序端，添加组件中的数据和页面

5.1 添加组件的数据

城市数据由组件提供，因此需要添加组件中的数据。切换到数据设计区，添加动态数据集：字母

添加列：字母

添加动态数据集：城市

添加列：首字母、城市

添加数据集后，需要重启制作台才能添加数据

切换到高级页面，点击立即重启

重启后，添加或导入数据

5.2 添加组件的页面

运行时，点击组件弹出城市列表，城市列表即是组件中的页面。切换到页面设计区，先添加页面分组，再添加页面。

点击添加分组按钮，添加页面分组

在名称中输入cityDialog，单击确定按钮添加cityDialog分组

点击cityDialog分组右侧的新建页面按钮

在页面名称中输入cityList

开发方式同普通页面的开发，不支持直接预览。需要通过在普通页面中添加组件，通过组件的功能打开组件的页面，进行预览

cityList页面开发步骤如下：

1. 添加字母数据集，设置按字母排序，分页大小设置为-1
2. 添加城市数据集，修改id为cityData，设置按首字母和城市排序，分页大小设置为-1
3. 添加动态列表，绑定字母数据集
4. 在字母动态列表中，添加文本，动态文本设置为“动态列表当前行.字母”，是否可见为block，文字颜色为#999999，上下内边距5px，左内边距10px，下边框1px，颜色为#cccccc
5. 在字母动态列表中，添加动态列表，绑定城市数据集，过滤条件设置为“动态列表1当前行.首字母等于动态列表当前行.字母”

6. 在城市动态列表中，添加文本，动态文本设置为“动态列表1当前行.城市”，是否可见为block，文字大小为18px，上下内边距10px，左外边距20px，下边框1px，颜色为#cccccc。写点击事件，将选择的城市名称返回，代码如下

    onText1Tap(event){
        //关闭页面，返回城市名称
        wx.navigateBack({
            params: {
                city: this.comp("cityData").getValue("city")
            }
        });
    }
   

5.3 添加组件内事件

切换到代码页面，打开运行时JS文件，添加showCityList方法

打开编译文件，在doExecute方法中，添加点击事件，调用showCityList方法

addEventHandler(bound, "bindtap", "showCityList", bound.attributeValue("id"), wxContext);

设置后如下图所示

5.4 打开页面

在运行时JS文件的showCityList方法中，写代码打开cityList页面，并设置页面关闭后的回调事件，在回调事件中获取返回值，写入绑定数据列，代码如下

showCityList(event){
     wx.navigateTo({
        url: "$UI/comp/city/cityDialog/cityList.w",
        onClose: (evt) => {
            if (evt.data.city){
                this.doChange({value: evt.data.city});
            }
        }
    });        
}

打开某个w文件，需要系统先编译这个w文件。给w文件所在目录增加标志文件module.js，系统扫描到该标志文件后，会编译这个目录下的所有w文件。做法如下：

• 在cityDialog目录下新建module.js文件，文件内容为export default {};
• 在运行时JS文件中引用module.js文件，代码为import "../../cityDialog/module";

设置后如下图所示

5.5 调试组件

1. 切换到应用的小程序端
2. 切换到数据设计区
3. 添加出差申请数据集，添加目的地列
4. 切换到页面设计区
5. 添加出差申请页面
6. 在页面上添加出差申请数据集，设置自动模式为自动新增
7. 再添加选择城市组件，绑定数据集设置为出差申请.目的地
8. 保存、预览

如果需要修改组件中的文件，参考文档最下方的说明，使修改生效

6 组件的扩展功能实现

经过上面的步骤，选择城市组件基本开发完成。下面介绍几个扩展功能

1. 允许用户修改城市列表页面的样式
2. 组件的绑定数据列无数据时，只读时的处理
3. 城市列表页面增加字母导航
4. 组件在设计器中的显示样式
5. 提供更多的修改样式
6. 修改组件分类

6.1 用户修改组件页面

对于组件中的页面，可以开放出来，以便用户修改，开放后页面会显示在用户的应用中，开放后的页面继承自组件中的页面，用户修改的是继承后的页面，不是组件中的页面

切换到代码页面，打开设计时JS文件，配置页面信息。开放页面的组件必须继承自BizDesignComp类

引用bizDesignComp.js文件

var BizDesignComp = require("$UI/system/components/designerCommon/comp/bizDesignComp");

将ViewComponent改为BizDesignComp

添加页面信息

    files: {
            "cityDialog": {
                "label": '城市对话框',
                 "cityList.w": {
                     "label": '城市列表',
                     "type": 'file'
                 },
                 "cityList.js": {
                     "label": '城市列表',
                     "type": 'file'
                 }
             }
    },
    compPath : "$UI/comp/city",
    isWX: true,

设置后如下图所示

切换到页面设计区，点击刷新按钮，显示出继承的页面

6.2 获取组件属性值

从组件中继承的页面，不在UI2/comp目录下，在应用所在的端下，例如：UI2/mobile。在打开页面时需要指定页面的完整路径。

如果组件声明appPath属性，系统会自动填充appPath属性为端的目录。

切换到comp/city-设计时，打开组件描述文件，添加appPath属性，用于获取端的目录。该属性不需要显示，因此不需要在设计时JS文件中添加该属性

<property name="appPath" text="应用路径" extendType="URL" />

注意：修改组件描述文件，需要点击组件包右侧的更新配置文件按钮，使修改生效

设置后如下图所示

在编译文件的doExecute方法中，获取appPath属性的值，写入props，在运行时JS文件中通过props.appPath访问

String appPath = bound.attributeValue("appPath");
if(null==appPath) appPath = "";
props.put("appPath", appPath);

如果修改后不生效，可删除server/dclasses目录下的class文件，再刺激编译

设置后如下图所示

在运行时JS文件的constructor方法中，从props参数中获取appPath属性的值

this.appPath = props.appPath;

设置后如下图所示

6.3 显示继承的页面

用appPath和组件中的页面的路径，拼接成继承后的页面路径，打开运行时JS文件，修改showCityList方法，将组件中的页面路径换成继承后的页面路径

即将$UI/comp/city/cityDialog/cityList.w改为this.appPath + "/cityDialog/cityList.w

showCityList方法，代码如下

showCityList(event){
    wx.navigateTo({
        url: this.appPath + "/cityDialog/cityList.w",
        onClose: (evt) => {
            if(evt.data.city){
                this.doChange({value: evt.data.city});
            }
        }
    });        
}

切换到应用端，预览，此时打开的城市列表页面是继承的页面

6.4 无数据时、只读时的处理

当数据集里面没有数据，或者组件绑定的列为只读时，点击组件，不弹出城市列表页面

bindComponent类提供isReadonly方法，当数据集里面没有数据，或者列为只读时，isReadonly方法返回true

打开运行时JS文件，在showCityList方法中，增加如下代码，当isReadonly方法返回true时return，代码如下

if(this.isReadonly()) return;

showCityList方法，完整代码如下

showCityList(event){
    if(this.isReadonly()) return;
    wx.navigateTo({
        url: this.appPath + "/cityDialog/cityList.w",
        onClose: (event) => {
            if(event.data.city){
                this.doChange({value: event.data.city});
            }
        }
    });        
}

6.5 字母导航

城市列表中城市很多，增加字母导航便于快速定位城市

切换到comp/city-小程序端，进入数据设计区

添加静态数据集：页面数据

添加列：当前字母

添加一个空行

切换到页面设计区，打开cityList.w页面，页面实现滚动需要使用滚动视图组件

1. 在页面中添加上中下布局组件，删除面板头部和面板底部，保留面板内容
2. 在面板内容中添加滚动视图，设置纵向滚动为true，高度为100%
3. 将原来添加的动态列表拖拽到滚动视图中
4. 在面板内容中添加视图，设置宽为30px，高为500px，文字大小为12px，文字居中，颜色为#666666，定位方式为固定定位，距离顶部为0，距离右边为0
5. 在视图中添加动态列表，绑定数据集选择字母
6. 在动态列表中添加文本，动态文本选择动态列表2当前行.字母
7. 在页面中添加静态数据集：页面数据
8. 选择新添加的动态列表，点击事件选择赋值，目标列选择“页面数据.当前字母”，值输入"list"+动态列表2当前行.主键，如下图所示
9. 选中滚动视图组件，设置动态滚至指定元素为“页面数据.当前字母”
10. 选中动态列表（即id为list的动态列表)，设置动态标识为"list"+动态列表当前行.主键

滚动设置说明

• 滚动视图组件可以根据id将页面滚动到某个元素
• 如果字母动态列表中A的id为lista，B的id为listb，设置滚动视图的滚至指定元素为lista，会滚动到字母A，设置为listb，会滚动到字母B

切换到应用端，查看运行效果

6.6 设计器中的组件样式

组件添加到页面后，没有绑定数据列时，没有宽高，不能选中组件

在designer/css文件夹下，新建文件city.css，添加下面的代码

.d-wx-city[d_selectable='true']{
    min-height:22px;
    min-width:16px;
    outline:1px dotted #ddd;
    display: inline-block;
}

设置后如下图所示

打开设计时JS文件，引用city.css文件，给组件增加样式

引用city.css文件

require("css!./css/city.css").load();

在init方法中给组件增加样式

this.$domNode.addClass("d-wx-city");

设置后如下图所示

其中this.$domNode.attr("d_canaddchild", "false");表示不能向组件中添加组件

点击页面设计区中的刷新按钮，查看效果

未绑定数据列时，如图所示

绑定数据列时，如图所示

6.7 组件可修改样式

在设计时JS文件中，设置组件可修改样式，包括基本、文字、边距、边框、定位、圆角、阴影等样式

引用commonStyle.js文件

var CommonStyle = require("$UI/wxsys/comps/designerCommon/js/commonStyle");

给组件增加样式配置

styleConfig : function(designer) {
    return CommonStyle.styleConfig(designer).concat([designer.getCommonStyleItem('border-radius'),designer.getCommonStyleItem('box-shadow')]);
}        

设置后如下图所示

设计器效果如下图所示

6.8 修改组件分类

在组件包的components目录下的city.components.xml文件中设置组件分类，将“市场组件”改为其它分类名称即可

切换到组件设计端，点击更新配置文件按钮，再切换到应用端，可以看到分类已经变化

7 导出组件包

切换到组件设计端，点击city组件包右侧的导出按钮，导出city.zip文件

组件中的字母和城市数据需要带在组件包中，因此选中这两个数据，点击导出组件包

8 上传市场并审核

进入控制台，打开我的市场功能，点击上传组件按钮，再点击上传按钮，输入组件包信息，上传组件包文件，点击提交审核按钮

控制台管理员system进入控制台，打开模板组件中的组件管理功能，点击审核中或更新审核中，显示出提交待审核的组件，点击审核按钮，再点击通过按钮

打开应用，添加市场组件，可以看到选择城市组件

至此，选择城市组件开发完毕

文件修改后，如何生效