mxClient JS 文档翻译

📅 4月24日 / 🎨 信息分享 / 👓 24


mxGraph 的 JavaScript 接口规格文档。

原文地址:https://jgraph.github.io/mxgraph/docs/js-api/files/index-txt.html

概述

此 JS 库分为 8 个包(package):

  1. Editor
  2. View
  3. Model
  4. Handler
  5. Layout
  6. Shape
  7. Util
  8. I/O

它们全部由 mxClient 类包含或动态引入,
当前版本号保存在常量 mxClient.VERSION 中。

Editor 提供了实现图编辑器功能所需的基类,其中最重要的是 mxEditor 类。

ViewModel 包实现图形组件(graph component), 由 mxGraph 表示。 它指的是 mxGraphModel, 其中包含 mxCells, 并将图元(cells)的状态缓存在 mxGraphView 中。
这些图元是根据 mxStylesheet 中定义的外观使用 mxCellRenderer 绘制的。
撤消历史记录在 mxUndoManager 中实现。
若要在图形上显示图标, 可以使用 mxCellOverlay
验证规则定义在 mxMultiplicity 中。

HandlerLayoutShape分别为事件监听器(event listener)、布局算法和形状。

事件监听器包括:

  • 用于橡皮带选择(rubberband selection)的 mxRubberband
  • 用于工具提示的 mxTooltipHandler
  • 用于基本图元修改的 mxGraphHandler

mxCompactTreeLayout 实现了树形布局算法。

Shape 包提供了各种形状,它们是 mxShape 的子类。

Util 包提供了各种实用程序类,包括:

  • 用于复制粘贴的 mxClipboard
  • 用于拖放的 mxDatatransfer
  • 用于键值样式表的 mxConstants
  • 用于跨浏览器事件的mxEvent
  • 用于通用处理功能的 mxUtils
  • 用于国际化的mxResources
  • 用于控制台输出的mxLog

I/O 包实现了一个通用的 mxObjectCodec,用于将JavaScript对象转换为XML。
主要类是 mxCodec
mxCodecRegistry 是自定义编解码器的全局注册表。

事件(Events)

有三种不同类型的事件,即:

  • 本地 DOM 事件
  • mxEventSource 中触发的 mxEventObjects
  • mxGraph 中触发的 mxMouseEvents

mxEvent 中提供了一些处理本地事件的辅助方法,它还负责解析 DOM 节点和 JavaScript 事件处理程序之间的循环,这可能导致IE6中的内存泄漏。

mxGraph 中的大多数 自定义事件 都是使用 mxEventSource 实现的,它的监听器是带有 sendermxEventObject 的函数。

另外,mxGraph 中触发特殊的 mxMouseEvents,它使用了鼠标事件监听器,包含了 mousedownmousemovemouseup 等方法。

mxEventSource 中的事件是使用 mxEventSource.fireEvent 触发的。
使用 mxEventSource.addListenermxEventSource.removeListener 添加和删除监听器。

mxGraph 中的 mxMouseEvents 是使用 mxGraph.fireMouseEvent 触发的。
分别使用 mxGraph.addMouseListenermxGraph.removeMouseListener 添加和删除监听器。

按键绑定(Key binding)

默认为鼠标事件定义了以下按键绑定:

  • Control-Drag:复制选定的图元
  • Shift-Rightlick:显示上下文菜单
  • Alt-Click:强制橡皮筋(也被称为 marquee)
  • Shift-Drag:切换选择状态
  • Shift-Drag:将偏移量限制为一个方向
  • Shift-Control-Drag:平移(同 Shift-Rightdrag)

配置(Configuration)

可以在加载客户端之前定义以下全局变量,以分别指定其语言或基本路径。

  • mxBasePath:指定 mxClient.basePath 中的路径。
  • mxImageBasePath:指定 mxClient.imageBasePath 中的路径。
  • mxLanguage:指定 mxClient.language 中资源的语言。
  • mxDefaultLanguage:指定 mxClient.defaultLanguage 中的默认语言。
  • mxLoadResources:指定是否应加载任何资源。 默认为true。
  • mxLoadStylesheets:指定是否应加载任何样式表。 默认为true。

保留字(Reserved Words)

mx 前缀用于 mxGraph 中的所有类和对象,可以看作全局命名空间。

不应在对象中使用以下字段名:

  • mxObjectId:如果该对象与mxObjectIdentity一起使用
  • as:如果对象是另一个对象的字段
  • id:如果对象是编解码器中的idref
  • mxListenerList:与mxEvent一起使用时添加到DOM节点
  • window._mxDynamicCode:暂时用于在Safari和Chrome中加载代码(请参阅mxClient.include)。
  • _mxJavaScriptExpression:临时用于评估 Safari,Opera,Firefox3 和 IE 中代码的全局变量(请参阅mxUtils.eval)。

文件(Files)

该库包含这些相对文件名。所有文件名都与mxClient.basePath相关。

内置图像(Built-in Images)

所有图像都是从 mxClient.imageBasePath 加载的,您可以更改它以适应您的环境。
图像变量也可以单独更改。

  • mxGraph.prototype.collapsedImage
  • mxGraph.prototype.expandedImage
  • mxGraph.prototype.warningImage
  • mxWindow.prototype.closeImage
  • mxWindow.prototype.minimizeImage
  • mxWindow.prototype.normalizeImage
  • mxWindow.prototype.maximizeImage
  • mxWindow.prototype.resizeImage
  • mxPopupMenu.prototype.submenuImage
  • mxUtils.errorImage
  • mxConstraintHandler.prototype.pointImage

mxGraph.setCellWarning 中使用的警告图像的基本名称(无扩展名的图像/警告)在 mxGraph.warningImage 中定义。

资源(Resources)

mxEditormxGraph 在加载时将以下资源添加到 mxResources

  • resources/editor*.properties
  • resources/graph*.properties

默认情况下,该库附带英语和德语资源文件。

图片(Images)

使用图像的建议:在 HTML 元素(例如工具栏和上下文菜单)中使用 GIF 图像(256色调色板),对于出现在图形组件内的所有图像使用 PNG 图像(24位)。

对于 HTML 元素内的 PNG 图像,IE 将忽略任何透明度信息。
对于图表中的 GIF 图像,Mac 上的 Firefox 将显示奇怪的颜色。
此外,Mac 上仅显示动画GIF的第一个图像。
为了在应用程序运行时期间更快地呈现图像,可以使用以下代码预取图像:

var image = new Image();
image.src = url_to_image;

部署(Deployment)

在页面中引入 mxClient.js 文件即可。

<script type="text/javascript" src="js/mxClient.js"></script>

源码

源代码在 javascript/devel/source.zip 文件中提供。

参考

(完)

留言(0)