# Hyflow 流程图框架开发文档

tags: gojs

## Get Start
> hyflow 基于 `gojs` 绘图框架, 能够迅速的绘制出基础流程图

### 安装
``` bash
npm i -S hyflow
```

### 使用

``` html
<div id="flow" style="width: 500px; height: 500px"></div>
```

``` javascript
import * as hyflow from 'hyflow'

const ele = document.getElementById('flow')
const flow = new hyflow.Flow(ele)

flow.setOption({
  nodeDataArray: [{
    category: 'normal',
    key: 1
  }, {
    category: 'normal',
    key: 2,
    loc: '200, 0'
  }],
  linkDataArray: [{
    key: 'link', from: 1, to: 2
  }]
})
```

---

## 配置项
### Flow
> 实例化 `hyflow` 时的全局配置

`const flow = new hyflow.Flow(ele [, options = Object])`

|参数名|类型|是否必选|描述|
|---|---|---|---|
|ele|HTMLDOM|true|容器对象|
|options|Object|false|其他全局配置项|

**options** 配置项:

|参数名|类型|是否必选|描述|
|---|---|---|---|
|editable|Boolean|false|是否开启编辑者模式, 默认 false|
|gridVisible|Boolean|false|是否打开网格工具, 默认 false|
|isPalette|Boolean|false|是否开启调色板模式, 如果开启需要先设置 `editable` 为 true, 默认为 false|
|layout|Object|false|是否使用树形布局模式, 共有5个配置项 <br> `show` *Boolean* 是否启用树形布局; <br> `angle` *Number* 布局方向, 可选 0 90 180 270 四个值; <br> `layerSpacing` *Number* 布局连线之间的距离; <br> `nodeSpacing` *Number* 节点之间的距离; <br> `alignment` *String* 排列布局, 可选 start end center, 默认 center|
|onLinkDrawn|Func|false|监听连接线完成绘制后的回调, 回调参数 (key, data, e)|
|onModelChangeAction|Func|false|监听画布中所有正在编辑的回调, 回调参数 (nodeDataArray, linkDataArray, diagram)|
|onModelChangeDone|Func|false|监听画布中所有完成的回调, 回调参数 (nodeDataArray, linkDataArray, diagram)|
|onSelectNodeChanged|Func|false|监听节点被选择或取消选择回调, 回调参数 (obj, data)|
|onSelectLinkChanged|Func|false|监听连接线被选择或取消选择回调, 回调参数 (obj, data)|
|onNodeClick|Func|false|监听节点的点击事件的回调, 回调参数 (obj, data)|
|onNodeMouseEnter|Func|false|监听鼠标进入节点的事件回调, 回调参数 (obj, data)|
|onNodeMouseLeave|Func|false|监听鼠标离开节点的事件回调, 回调参数 (obj, data)|

**flow属性:**

|属性|类型|描述|
|---|---|---|
|flow.diagram.**scale**|Number|获取或设置视图的缩放比例|
|flow.diagram.**minScale**|Number|获取或设置视图当前允许的最小缩放比例|
|flow.diagram.**maxScale**|Number|获取或设置视图当前允许的最大缩放比例|
|flow.diagram.**initialScale**|Number|获取或设置视图初始化时的缩放比例|
|---|---|---|---|
|flow.diagram.**allowZoom**|Boolean|获取或设置当前用户是否允许缩放画布|
|flow.diagram.**allowSelect**|Boolean|获取或设置当前用户是否允许选择画布内的元素|
|flow.diagram.**allowRotate**|Boolean|获取或设置当前用户是否允许旋转画布内的元素|
|flow.diagram.**allowResize**|Boolean|获取或设置当前用户是否允许设置画布内的元素的尺寸|
|flow.diagram.**allowMove**|Boolean|获取或设置当前用户是否允许移动画布内的元素|
|flow.diagram.**allowLink**|Boolean|获取或设置当前用户是否允许从一个节点向另一个节点绘制连接线|
|flow.diagram.**allowRelink**|Boolean|获取或设置当前用户是否允许重新连接一条已存在的连接线|
|flow.diagram.**allowHorizontalScroll**|Boolean|获取或设置当前用户是否允许水平滚动画布|
|flow.diagram.**allowVerticalScroll**|Boolean|获取或设置当前用户是否允许垂直滚动画布|
|flow.diagram.**allowDelete**|Boolean|获取或设置当前用户是否允许删除画布内的元素|
|flow.diagram.**allowCopy**|Boolean|获取或设置当前用户是否允许复制画布内的元素|
|flow.diagram.**allowClipboard**|Boolean|获取或设置当前用户是否允许剪切画布内的元素|
|flow.diagram.**allowUndo**|Boolean|获取或设置当前用户是否允许撤销或恢复画布操作|
|---|---|---|---|
|flow.diagram.**div.appendChild**(*HTMLDocument*)|Func|这是一个函数方法, 该方法允许在画布中添加一个 *HTMLDocument* 对象|
|flow.diagram.**div.removeChild**(*HTMLDocument*)|Func|这是一个函数方法, 该方法允许在画布中删除一个 *HTMLDocument* 对象|

---

### Nodes
节点分为普通节点, 和其他**富文本**节点

#### Group Node
> 集群节点, 该节点用于包装其他所有节点的集合

- **key** `Number || String` *必选*
节点的唯一标识符号, 在连接线中通过这个标识符来决定某两个节点之间的关系

- **category** `String` *必选*
该节点的类型, `Normal Node` 为 'group'

- **isSelected** `Boolean`
默认 *false*, 控制节点是否处于选中状态

- **zOrder** `Number`
默认 *0*, 表示节点的层级关系

- **figure** `String`
默认 *RoundedRectangle*, 表示节点的图形, [查看可选择图形](https://gojs.net/latest/samples/shapes.html)

- **fill / stroke** `String`
默认 *'#F2F4F5' / '#E6E9EB'*, 表示节点的填充和描边颜色

- **strokeWidth** `Number`
默认 *1*, 表示节点描边的宽度

- **strokeDashArray** `String`
默认 *'0 0'*, 定义节点的虚线描边

- **image** `Object`
定义背景图片
	- **show** `Boolean`
	默认 *false*, 是否显示背景图片
	
	- **width / height** `Number`
	默认 *100 / 100*, 背景图片的宽高
	
	- **src** `String`
	默认 *''*, 背景图片路径
	
	- **imageStretch** `String`
	默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式

- **title** `Object`
定义节点的标题
	- **isExpander** `Boolean`
	默认 *false*, 表示是否显示折叠集群的按钮
	
	- **alignment** `String`
	默认 *'center'*, 图标的布局模式, 可选参数 center left right top topLeft topRight bottom bottmLeft bottomRight 或者自定义 `0.5 0.5 0 0`

	- **width / height** `Number`
	默认 *80 / 30*, 表示标题的宽高

	- **fill / stroke** `String`
	默认 *'transparent'*, 表示标题的背景色和描边

	- **strokeWidth** `Number`
	默认 *1*, 表示标题的边宽

	- **figure** `String`
	默认 *Rectangle*, 表示标题的图形, [查看可选择图形](https://gojs.net/latest/samples/shapes.html)

	- **bgsrc** `String`
    默认 *''*, 背景图片的路径地址

    - **imageStretch** `String`
    默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式

    - **text** `String`
    默认 *'Text'*, 输入的文字

    - **font** `String`
    默认 *'Normal Normal 12px Helvetica'*, 参考[CSS Font 属性](http://www.w3school.com.cn/cssref/pr_font_font.asp)

    - **fontColor** `String`
    默认 *'#666'*, 文字的颜色

    - **fontBackground** `String`
    默认 *'transparent'*, 文字的背景颜色

---

#### Normal Node
- **key** `Number || String` *必选*
节点的唯一标识符号, 在连接线中通过这个标识符来决定某两个节点之间的关系

- **category** `String` *必选*
该节点的类型, `Normal Node` 为 'normal'

- **group** `Any`
所属集群节点的 `key`, 设置该属性后, 该节点会被纳入指定**集群节点**的子节点下

- **figure** `String`
默认 *RoundedRectangle*, 表示节点的图形, [查看可选择图形](https://gojs.net/latest/samples/shapes.html)

- **cursor** `String`
默认 *'pointer'*

- **isSelected** `Boolean`
默认 *false*, 控制节点是否处于选中状态

- **zOrder** `Number`
默认 *1*, 表示节点的层级关系

- **width / height** `Number`
默认 *100 / 60*, 表示节点的宽高

- **loc** `String`
默认 *'0, 0'*, 表示节点的偏移位置

- **angle** `Number`
默认 *0*, 表示节点的旋转角度

- **fill / stroke** `String`
默认 *'rgba(24, 144, 255, .32)' / 'rgba(24, 144, 255, 1)'*, 表示节点的填充和描边颜色

- **strokeWidth** `Number`
默认 *1*, 表示节点描边的宽度

- **strokeDashArray** `String`
默认 *'0 0'*, 定义节点的虚线描边

- **label** `Object`
定义节点文字的对象
    - **text** `String`
    默认 *'Text'*, 输入的文字

    - **font** `String`
    默认 *'Normal Normal 18px Helvetica'*, 参考[CSS Font 属性](http://www.w3school.com.cn/cssref/pr_font_font.asp)

    - **fontColor** `String`
    默认 *'#666'*, 文字的颜色

    - **fontBackground** `String`
    默认 *'transparent'*, 文字的背景颜色

- **image** `Object`
定义节点背景图片的对象
    - **src** `String`
    默认 *''*, 图片的路径地址

    - **imageStretch** `String`
    默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式

---

#### Icon Node
- **key** `Number || String` *必选*
节点的唯一标识符号, 在连接线中通过这个标识符来决定某两个节点之间的关系

- **category** `String` *必选*
该节点的类型, `Icon Node` 为 'icon'

- **group** `Any`
所属集群节点的 `key`, 设置该属性后, 该节点会被纳入指定**集群节点**的子节点下

- **cursor** `String`
默认 *'pointer'*

- **isSelected** `Boolean`
默认 *false*, 控制节点是否处于选中状态

- **zOrder** `Number`
默认 *1*, 表示节点的层级关系

- **width / height** `Number`
默认 *100 / 60*, 表示节点的宽高

- **loc** `String`
默认 *'0, 0'*, 表示节点的偏移位置

- **angle** `Number`
默认 *0*, 表示节点的旋转角度

- **icon** `Object`
定义图标的数据集
    - **alignment** `String`
    默认 *'center'*, 图标的布局模式, 可选参数 center left right top topLeft topRight bottom bottmLeft bottomRight 或者自定义 `0.5 0.5 0 0`

    - **width / height** `Number`
    默认 *60 / 60*, 图标的宽高

    - **isClipping** `Boolean`
    默认 *false*, 是否开启剪切模式

    - **figure** `String`
    默认 *'Rectangle'*, 剪切模式下的, 裁剪图片的图形形状

    - **bgsrc** `String`
    默认 *''*, 图片的路径地址

    - **imageStretch** `String`
    默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式

- **label** `Object`
定义底部文字标签的数据集
    - **alignment** `String`
    默认 *'bottom'*, 文本的布局模式, 可选参数 center left right top topLeft topRight bottom bottmLeft bottomRight 或者自定义 `0.5 0.5 0 0`

    - **width / height** `Number`
    默认 *60 / 60*, 文本的宽高

    - **fill / stroke** `String`
    默认 *'transparent' / 'transparent'*, 表示文本标签的填充和描边颜色

    - **strokeWidth** `Number`
    默认 *1*, 表示文本标签的描边的宽度

    - **strokeDashArray** `String`
	默认 *'0 0'*, 定义节点的虚线描边

    - **isClipping** `Boolean`
    默认 *false*, 是否开启剪切模式

    - **figure** `String`
    默认 *'Rectangle'*, 剪切模式下的, 裁剪图片的图形形状

    - **bgsrc** `String`
    默认 *''*, 图片的路径地址

    - **imageStretch** `String`
    默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式

    - **text** `String`
    默认 *'Text'*, 输入的文字

    - **font** `String`
    默认 *'Normal Normal 18px Helvetica'*, 参考[CSS Font 属性](http://www.w3school.com.cn/cssref/pr_font_font.asp)

    - **fontColor** `String`
    默认 *'#666'*, 文字的颜色

    - **fontBackground** `String`
    默认 *'transparent'*, 文字的背景颜色

- **subLabel** `Object`
副标题, 其属性与 *label* 属性完全一致, 只是多了一个 `show` 属性
	- **show** `Boolean`
	默认 *false*, 是否显示副标题

### Links
- **key** `String` *必选*
连接线的唯一标识符号

- **from / to** `String` * 必选*
取已定义的节点的 *key*, *from* 表示连接线从这个节点出发, *to* 表示到达的节点位置

- **isSelected** `Boolean`
默认 *false*, 控制连接线是否处于选中状态

- **corner** `Number`
默认 *0*, 表示连接线拐角处的弧度, 只有当连接线为直角模式时有效(routing: 'Orthogonal')

- **routing** `String`
默认 *'Orthogonal'*, 表示连接线的模式, 默认为直角模式, 可选 *Normal* 普通直线

- **cursor** `String`
默认 *'normal'*, 同 CSS 的 cursor 属性

- **stroke / strokeWidth / strokeDashArray** `String / Number / String`
默认 *'#BAC4CF' / 1 / '0 0'*, 分别表示连接线的 描边颜色 描边宽度 虚线

- **fromArrow** `Object`
定义线头的图标各类属性的对象
    - **show** `boolean`
    默认 *true*, 是否显示

    - **figure** `String`
    默认 *'Circle'*, 使用的图形, [查看可用的图形](https://gojs.net/latest/samples/arrowheads.html)

    - **scale** `Number`
    默认 *0.6*, 图形缩放的级别

    - **fill** `String`
    默认 *'#BAC4CF'*, 图形的填充色

- **toArrow** `Object`
定义线尾的图标各类属性的对象
    - **show** `boolean`
    默认 *true*, 是否显示

    - **figure** `String`
    默认 *'Standard'*, 使用的图形, [查看可用的图形](https://gojs.net/latest/samples/arrowheads.html)

    - **scale** `Number`
    默认 *1*, 图形缩放的级别

    - **fill** `String`
    默认 *'#BAC4CF'*, 图形的填充色

- **symbols** `Object`
定义线段中间的标签图形, 分为 start middle end, 三块, 其初始位置分别位于线段的 开始 中间 结束 位置, 这三个标签的属性配置默认项都相同, 下面以 start 为例:
    - **start** `Object`
        - **show** `Boolean`
        默认 *false*, 是否显示

        - **upright** `Boolean`
        默认 *false*, 标签是否围绕线段旋转

        - **segmentOffset** `String`
        默认 *'0 0'*, 标签相对自身初始位置的偏移量

        - **segmentIndex** `Number`
        标签位于线段的**段落位置**,
        当线段 `routing: Orthogonal` 时:
        1 表示起始点到第一个拐角的距离
        2 表示第一个拐角到第二个拐角的距离
        3 表示第三个拐角到终点的距离
        当线段 `routing: Normal` 时
        0 表示线头
        1 表示线头到线尾范围的连接线
        2 表示线尾

        - **segmentFraction** `Number`
        默认 *0.5*, 取 0 ~ 1 范围内的浮点值, 表示标签位于其段落位置百分比偏移

        - **figure** `String`
        默认 *'RoundedRectangle'*, 表示标签的图形类型

        - **width / height** `Number`
        默认 *50 / 30*, 表示标签的宽高

        - **fill / stroke** `String`
        默认 *'#FFF / #BAC4CF'*, 标签的填充色 与 描边色

        - **strokeWidth** `Number`
        默认 *1*, 表示标签描边的宽度

        - **strokeDashArray** `String`
        默认 *'0 0'*, 定义标签的虚线描边

        - **label** `Object`
        定义标签文字的对象
            - **text** `String`
            默认 *'Text'*, 输入的文字

            - **font** `String`
            默认 *'Normal Normal 18px Helvetica'*, 参考[CSS Font    属性](http://www.w3school.com.cn/cssref/pr_font_font.asp)

            - **fontColor** `String`
            默认 *'#666'*, 文字的颜色

            - **fontBackground** `String`
            默认 *'transparent'*, 文字的背景颜色

        - **image** `Object`
        定义标签背景图片的对象
            - **src** `String`
                默认 *''*, 图片的路径地址

            - **imageStretch** `String`
                默认 *'Fill'*, 图片的拉伸模式, 共有 Fill None Uniform UniformToFill 四种模式


---

## Api

### 设置视图
|名称|描述|
|---|---|
|hyflow.Flow.**resizingDiagram**({ width, height })|重新设置画板的宽高|
|hyflow.Flow.**toggleGrid**(visible)|动态切换显示网格线|
|hyflow.Flow.**clear**()|清空当前画布|

### 增删改查
|名称|描述|
|---|---|
|hyflow.Flow.**addNodeData**(category [, options])|向画布添加一个指定类型的节点|
|hyflow.Flow.**removeNodeData**(category [, options])|向画布删除一个指定的节点|
|hyflow.Flow.**addLinkData**(options)|向画布添加一条连接线|
|hyflow.Flow.**removeLinkData**(options)|向画布删除一条指定连接线|
|hyflow.Flow.**setDataProperty**(type, key, property, callback)|设置某一节点或连接线的属性|

### 集群
|名称|描述|
|---|---|
|hyflow.Flow.**addNodesForGroup**(groupKey, nodeKeys)|将指定的一个或多个节点添加到某一集群中|
|hyflow.Flow.**removeNodesFromGroup**(groupKey, nodeKeys)|从某一集群删除指定的一个或多个节点|
|hyflow.Flow.**gatherNodesGroup**(nodeKeys)|将指定的一个或多个节点组成集群|
|hyflow.Flow.**breakNodesGroup**(groupKey)|解散某个集群|

### 通用
|名称|描述|
|---|---|
|hyflow.Flow.**setOption**({ nodeDataArray, linkDataArray })|万能函数方法, 只需将符合规范的配置对象传入,即可完成图形绘制, 以及图形动态修改属性操作|
|hyflow.Flow.**dispatchJson**()|将当前画布的图形配置以 JSON 的格式发出, 该 JSON 可以直接导入 hyflow.Flow.setOption 中使用|