刻度尺手册 - HT for Web

HT 刻度尺手册

索引

概述
示例一：为拓扑增加刻度尺
示例二：为通用组件增加刻度尺

概述

ht.widget.RulerFrame用于为HT组件(拓扑和树、表格等通用组件)及HTML元素(如div)提供刻度尺， RulerFrame可以在组件的上、右、下、左四条边上绘制刻度，刻度可根据用户的操作(缩放、滚动)自动调节。在正式使用API之前，您的页面里应该引入相关js：

<script src="ht.js"></script> <!--先引入ht.js-->
<script src="ht-rulerframe.js"></script>

RulerFrame提供的API如下：

defaultRulerConfig通过getDefaultRulerConfig()和setDefaultRulerConfig('newConfig')操作，总控所有刻度尺的属性
topRulerConfig通过getTopRulerConfig()和setTopRulerConfig('newConfig')操作，用于控制上刻度尺的属性
rightRulerConfig通过getRightRulerConfig()和setRightRulerConfig('newConfig')操作，用于控制右刻度尺的属性
bottomRulerConfig通过getBottomRulerConfig()和setBottomRulerConfig('newConfig')操作，用于控制下刻度尺的属性
leftRulerConfig通过getLeftRulerConfig()和setLeftRulerConfig('newConfig')操作，用于控制左刻度尺的属性
component表示要增加刻度尺的组件，通过getComponent()和setComponent(component)操作，可以是HT组件，也可以是HTML元素
addComponentPropertyChangeListener(component, handler)为component增加属性变化监听器，默认实现如下：
```
if (component && component.mp) component.mp(handler);
```
HTML元素没有提供mp接口，所以如果component为HTML元素，就需要重写此方法。另外需要注意，重写此方法后必须调用setComponent()，以便RulerFrame能正确监听到component的属性变化。换句话说，如果component为HTML元素，不能在RulerFrame的构造函数中传入component，而是应该先重写addComponentPropertyChangeListener再调用setComponent()
removeComponentPropertyChangeListener(component, handler)删除component上的属性变化监听器，如果重写了addComponentPropertyChangeListener，也要重写此方法删除监听器，以免造成内存泄露
getComponentViewRect(component)获得component的可视范围，默认实现如下：
```
if (component && component.getViewRect) return component.getViewRect();
```
HTML元素没有提供getViewRect接口，所以如果component为HTML元素，需要重写此方法
invalidateComponent(component)使component无效。默认实现如下：
```
if (component && component.iv) component.iv();
```
HTML元素没有提供iv接口，直接忽略此方法即可。对于特殊的HT组件(如TablePane)，内部封装了多个组件(TableHeader和TableView)，需要重写此方法，无效当前component及子component
validateComponent使component立即生效，同invalidateComponent一样，如果component内部封装了其它组件，需要重写此方法，使子component也生效
dispose()销毁此组件

setDefaultRulerConfig的参数为一个js对象，此对象提供所有刻度尺的默认配置，支持的属性如下：

size指定刻度尺的宽度，默认为20,
borderWidth指定刻度尺的边框宽度，默认为1,
borderStyle指定刻度尺的边框样式，支持css提供的所有边框样式，默认为solid
borderColor指定刻度尺的边框颜色，默认为#888
tickSpacingAdaptable是否自动调整刻度尺主刻度之间的间距，默认为true
minMajorTickSpacing 主刻度之间的最小间距，默认为10
defaultMajorTickSpacing指定刻度尺主刻度之间的间距，默认为50,
minPhysicalMajorTickSpacing指定刻度尺主刻度之间的最小屏幕像素，如果tickSpacingAdaptable为true并且主刻度之间的屏幕像素小于此属性指定的值，则自动扩大主刻度之间的间距;默认值为50
maxPhysicalMajorTickSpacing: 指定刻度尺主刻度之间的最大屏幕像素，如果tickSpacingAdaptable为true并且主刻度之间的屏幕像素大于此属性指定的值，则自动收缩主刻度之间的间距;默认值为100
majorTickTextFont指定主刻度文字的字体，默认为12px Arial
majorTickTextColor指定主刻度文字的颜色，默认为#666
majorTickColor指定主刻度标记的颜色，默认为#888
minorTickColor指定小刻度标记的颜色，默认为#ccc
background指定刻度尺背景色，默认为rgba(0,0,0,0)
guideVisible参考线是否可见，默认为false
guideColor指定参考线颜色，默认为rgb(0, 173, 239)
guideWidth指定参考线宽度，默认为2
guideTipVisible 指定参考线提示框是否可见,默认为false
guideTipBorderColor 指定参考线提示框边框颜色，默认为#666
guideTipTextColor 指定参考线提示框内的文本颜色，默认为#666
guideTipTextFont 指定参考线提示框内的文本字体，默认为12px Arial
guideTipBackground 指定参考线提示框的背景颜色，默认为#fff

每个刻度尺可配置的属性同defaultRulerConfig一致，但优先级高于默认配置。另外,单个刻度尺可配置visible属性，用于控制当前刻度尺是否可见，默认只显示左、上两个刻度尺。

如果只要修改某个属性，可通过下面代码实现：

rulerFrame.getLeftRulerConfig().size = 30;
rulerFrame.iv();

示例一：为拓扑增加刻度尺

var dataModel = new ht.DataModel(),
    graphView = new ht.graph.GraphView(dataModel),
    rulerFrame = new ht.widget.RulerFrame(graphView),
    view = rulerFrame.getView();
rulerFrame.getDefaultRulerConfig().guideVisible = true;
rulerFrame.getDefaultRulerConfig().guideTipVisible = true;
rulerFrame.getDefaultRulerConfig().guideTipBackground = "rgb(0, 173, 239)";
rulerFrame.getDefaultRulerConfig().guideTipTextColor = "white";

rulerFrame.getLeftRulerConfig().background = "yellow";
rulerFrame.getLeftRulerConfig().tickSpacingAdaptable = false;
rulerFrame.getLeftRulerConfig().defaultMajorTickSpacing = 100;
rulerFrame.getLeftRulerConfig().guideTipVisible = false;

rulerFrame.getTopRulerConfig().guideTipVisible = false;

rulerFrame.getRightRulerConfig().visible = true;

rulerFrame.getBottomRulerConfig().visible = true;

rulerFrame.iv();
//...
document.body.appendChild(view);

缩小拓扑可以发现左刻度尺的刻度挤在一起，因为我们将其tickSpacingAdaptable设为了false，主刻度之间的间距不会自动调整。

示例二：为通用组件增加刻度尺

rightRulerFrame.getLeftRulerConfig().visible = false;
rightRulerFrame.getRightRulerConfig().visible = true;
centerRulerFrame.getRightRulerConfig().visible = true;

leftRulerFrame.getView().style.position = "absolute";
rightRulerFrame.getView().style.position = "absolute";
centerRulerFrame.getView().style.position = "absolute";

/* TablePane的滚动由内部的TableView实现，所以需要重写此方法增加监听器*/
leftRulerFrame.addComponentPropertyChangeListener = function(component, handler){
    component.getTableView().mp(handler);
};
leftRulerFrame.removeComponentPropertyChangeListener = function(component, handler){
    component.getTableView().ump(handler);
};
/* 返回内部TableView的ViewRect*/
leftRulerFrame.getComponentViewRect = function(component) {
    return component.getTableView().getViewRect();
};
/* 使TablePane和内部的TableView无效*/
leftRulerFrame.invalidateComponent = function(component) {
    component.iv();
    component.getTableView().iv();
};
/* 使TablePane和内部的TableView生效*/
leftRulerFrame.validateComponent =  function(component) {
    component.validate();
    component.getTableView().validate();
};

/* HTML元素没有mp方法，为其scroll事件增加监听器*/
centerRulerFrame.addComponentPropertyChangeListener = function(component, handler){
    component.addEventListener("scroll", handler);
};
centerRulerFrame.removeComponentPropertyChangeListener = function(component, handler){
    component.removeEventListener("scroll", handler);
};
/* 返回HTML元素的可视区域*/
centerRulerFrame.getComponentViewRect = function(component) {
    return {x: component.scrollLeft, y: component.scrollTop, width: component.offsetWidth, height: component.offsetHeight};
};
//设置component
leftRulerFrame.setComponent(tablePane); 
centerRulerFrame.setComponent(scrollableDiv);

欢迎交流 service@hightopo.com