索引

• 概述
• 基础
• 原生组件
• 表单组件

概述

HT for Web提供了工具条组件类ht.widget.Toolbar，工具条上的元素可为原生的html元素， 也支持ht提供的如ht-form.js的表单插件中的组件，并内置提供了按钮、单选按钮、复选框等组件。

工具条支持水平pan的手抓图方式平移，当用户点击在原生或表单插件的组件时工具条不再进行交互控制， 当用户点击在内置组件时，如果后续有水平移动工具条会进行平移的手抓图效果操作，如果放手前没平移则 工具条会进行内置组件的点击操作，因此如果工具条元素较多需要平移功能时，建议尽量使用工具条内置组件， 一方面有助于更多空间可进行平移，另外内置组件占用内存资源也较少，有助于系统性能。

基础

通过toolbar = new ht.widget.Toolbar(items);初始化构建一个工具条对象，items参数为数组类型， 数组中的每个对象都会生成一个工具条元素(按钮、分隔条、原生html或表单插件组件)。

工具条主要可配置属性和函数如下：

• getItems()和setItems(items)获取和设置工具条元素数组
• itemGap属性通过getItemGap和setItemGap获取和设置元素之间的间距
• separatorColor属性通过getSeparatorColor和setSeparatorColor获取和设置分隔条颜色
• stickToRight属性通过isStickToRight和setStickToRight获取和设置工具条是否向右对齐排布，默认为false
• 通过addItem(item, index)可在指定index位置插入新元素，index为空代表插入到最后
• 通过removeItem(item)可删除指定元素
• 通过removeItemById(id)可删除指定编号id的元素，id值为item元素上的id属性定义
• 通过getItemById(id)可获取指定编号id的元素，id值为item元素上的id属性定义
• 通过重载drawItem(g, item, x, height)可自定义元素的绘制，函数返回该元素所占的宽度值
• 通过重载getLabelFont(item)可自定义文本字体
• 通过重载getLabelColor(item)可自定义文本颜色
• 通过重载getSelectBackground(item)可自定义选中背景颜色
• redraw()函数可用于item元素有所变化时进行刷新绘制
• enableToolTip()和disableToolTip()开启和关闭文字提示
• isDisabled()和setDisabled(true/false, iconURL)可获取和设置整个组件处于不可用状态
• getValue(id)根据id获取对应item元素值，简写函数为v(id)

• setValue(id, value)根据id设置对应item元素值，简写函数为v(id, value)

• 数组中的item元素格式说明：

  • separator字符串，表示分隔条
  • 对象类型
    • id 工具条元素的唯一标示，如果设置可通过getItemById获取
    • label 工具条元素的标签文字。
    • icon 工具条元素的图标。
    • toolTip 工具条元素的文字提示，注意需要结合Toolbar#enableToolTip()
    • type 工具条元素类型，check表示复选框，toggle表示开关按钮，radio表示单选按钮
    • selected 工具条元素是否被选中，值为true或false，对复选框、开关按钮和单选按钮有效
    • visible 工具条元素是否可见，默认值为true，设置为false则隐藏该元素
    • unfocusable 工具条元素是否不可获取焦点，默认鼠标滑过时会显示一个矩形边框，可设置为true关闭此效果
    • disabled 工具条元素是否被禁用，默认值为false
    • groupId 对工具条元素进行分组，同一个分组内的元素选中会自动出现互斥效果
    • element 可在该属性上直接设置元素html或表单组件元素
    • width 工具条元素宽度，常和element搭配使用，工具条内置组件无需设置该值
    • action 函数类型，工具条元素被点击时调用。

原生组件

内置的组件以及下节介绍的表单组件已经能满足大部分应用需求，但工具条依然允许用户放置原生的html组件， 例如元素的select下拉组件，或者用户已经封装好的html组件，对于所有组件工具条都会将其css的 position属性设置为absolute，box-sizing属性设置为border-box的方式进行绝对定位的布局。

采用native的元素组件在配置时，只需要在item的配置属性element上设置上html元素对象即可， 另外需注意item的action属性不会起作用，如果要监听组件的事件变化，用户需自行对html元素添加原生的监听事件。

表单组件

对于表单插件提供的组件也都可设置在item的element属性上， 并且工具条还支持用json直接描述自动构建element元素的机制。

如下代码将构建通过关键字属性slider，自动构建ht.widget.Slider组件，并将该组件自动存储到item的element属性上， ht内部先以不带参数的构造函数构造出组件对象，然后根据json上配置的属性信息查找是否有对应的set函数， 如果有对应的set函数则直接赋值到该对象，如果没找到对应函数则直接用将该属性名和值设置到对象上。

var toolbar = new ht.widget.Toolbar([
    {
        id: 'step',
        label: 'Step',
        unfocusable: true,
        slider: {
            width: 120,
            step: 5,
            min: 100,
            max: 200,
            value: 125,
            thickness: 1,
            onValueChanged: function(){
                toolbar.getItemById('step').label = this.getValue();
                toolbar.redraw();
            },
            onEndValueChanged: function(){
                toolbar.getItemById('step').label = 'Step';
                toolbar.redraw();
            }        
        }
    }
]);

以下代码为slider对象构建的过程：

slider = new ht.widget.Slider();
item.element = slider;
slider.setWidth(120);
slider.setStep(5);
slider.setMin(100);
slider.setMax(200);
slider.setValue(125);
slider.setThickness(1);
slider.onValueChanged = function(){
    toolbar.getItemById('step').label = this.getValue();
    toolbar.redraw();
};
slider.onEndValueChanged: function(){
    toolbar.getItemById('step').label = 'Step';
    toolbar.redraw();
};    

以下为ht目前支持的几个组件关键字映射关系：

• textField -> ht.widget.TextField
• textArea -> ht.widget.TextArea
• button -> ht.widget.Button
• checkBox -> ht.widget.CheckBox
• image -> ht.widget.Image
• comboBox -> ht.widget.ComboBox
• slider -> ht.widget.Slider

function createToolbar(){
    var toolbar = new ht.widget.Toolbar([
        {
            id: 'step',
            label: 'Step',
            unfocusable: true,
            slider: {
                width: 120,
                step: 5,
                min: 100,
                max: 200,
                value: 125,
                thickness: 1,
                onValueChanged: function(){
                    toolbar.getItemById('step').label = this.getValue();
                    toolbar.redraw();
                },
                onEndValueChanged: function(){
                    toolbar.getItemById('step').label = 'Step';
                    toolbar.redraw();
                }        
            }
        },
        {        
            id: 'nation',
            label: 'Nation',                        
            unfocusable: true,
            comboBox: {
                width: 120,
                value: 'Sweden',
                values: ['Spain', 'Sweden', 'Switzerland'],
                icons: ['images/spain.png', 'images/sweden.png', 'images/switzerland.png']
            }
        },
        {
            id: 'text',
            unfocusable: true,
            textField: {
                width: 120,
                color: 'red'        
            }
        },
        'separator', 
        {
            label: 'Get Information',
            action: function(){                            
                alert('Slider:' + toolbar.v('step') + '\n' +
                    'Nation:' + toolbar.v('nation') + '\n' +
                    'Name:' + toolbar.v('text')
                );
            }
        }
    ]);
    toolbar.v('text', 'Eric Lin');
    return toolbar;                
}