mxgraph的API文檔：查看原文

Overview

This JavaScript library is divided into 8 packages. The top-level mxClient class includes (or dynamically imports) everything else. The current version is stored in mxClient.VERSION.

The editor package provides the classes required to implement a diagram editor. The main class in this package is mxEditor.

The view and model packages implement the graph component, represented by mxGraph. It refers to a mxGraphModel which contains mxCells and caches the state of the cells in a mxGraphView. The cells are painted using a mxCellRenderer based on the appearance defined in mxStylesheet. Undo history is implemented in mxUndoManager. To display an icon on the graph, mxCellOverlay may be used. Validation rules are defined with mxMultiplicity.

The handler, layout and shape packages contain event listeners, layout algorithms and shapes, respectively. The graph event listeners include mxRubberband for rubberband selection, mxTooltipHandler for tooltips and mxGraphHandler for basic cell modifications. mxCompactTreeLayout implements a tree layout algorithm, and the shape package provides various shapes, which are subclasses of mxShape.

The util package provides utility classes including mxClipboard for copy-paste, <mxDatatransfer> for drag-and-drop, mxConstants for keys and values of stylesheets, mxEvent and mxUtils for cross-browser event-handling and general purpose functions, mxResourcesfor internationalization and mxLog for console output.

The io package implements a generic mxObjectCodec for turning JavaScript objects into XML. The main class is mxCodec. mxCodecRegistry is the global registry for custom codecs.

Events

There are three different types of events, namely native DOM events, mxEventObjects which are fired in an mxEventSource, and mxMouseEvents which are fired in mxGraph.

Some helper methods for handling native events are provided in mxEvent. It also takes care of resolving cycles between DOM nodes and JavaScript event handlers, which can lead to memory leaks in IE6.

Most custom events in mxGraph are implemented using mxEventSource. Its listeners are functions that take a sender and mxEventObject. Additionally, the mxGraph class fires special mxMouseEvents which are handled using mouse listeners, which are objects that provide a mousedown, mousemove and mouseup method.

Events in mxEventSource are fired using mxEventSource.fireEvent. Listeners are added and removed using mxEventSource.addListener and mxEventSource.removeListener. mxMouseEvents in mxGraph are fired using mxGraph.fireMouseEvent. Listeners are added and removed using mxGraph.addMouseListener and mxGraph.removeMouseListener, respectively.

Key bindings

The following key bindings are defined for mouse events in the client across all browsers and platforms:

Control-Drag: Duplicates (clones) selected cells
Shift-Rightlick: Shows the context menu
Alt-Click: Forces rubberband (aka. marquee)
Control-Select: Toggles the selection state
Shift-Drag: Constrains the offset to one direction
Shift-Control-Drag: Panning (also Shift-Rightdrag)

Configuration

The following global variables may be defined before the client is loaded to specify its language or base path, respectively.

mxBasePath: Specifies the path in mxClient.basePath.
mxImageBasePath: Specifies the path in mxClient.imageBasePath.
mxLanguage: Specifies the language for resources in mxClient.language.
mxDefaultLanguage: Specifies the default language in mxClient.defaultLanguage.
mxLoadResources: Specifies if any resources should be loaded. Default is true.
mxLoadStylesheets: Specifies if any stylesheets should be loaded. Default is true.

Reserved Words

The mx prefix is used for all classes and objects in mxGraph. The mx prefix can be seen as the global namespace for all JavaScript code in mxGraph. The following fieldnames should not be used in objects.

mxObjectId: If the object is used with mxObjectIdentity
as: If the object is a field of another object
id: If the object is an idref in a codec
mxListenerList: Added to DOM nodes when used with mxEvent
window._mxDynamicCode: Temporarily used to load code in Safari and Chrome (see mxClient.include).
_mxJavaScriptExpression: Global variable that is temporarily used to evaluate code in Safari, Opera, Firefox 3 and IE (see mxUtils.eval).

Files

The library contains these relative filenames. All filenames are relative to mxClient.basePath.

Built-in Images

All images are loaded from the mxClient.imageBasePath, which you can change to reflect your environment. The image variables can also be changed individually.

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

The basename of the warning image (images/warning without extension) used in mxGraph.setCellWarning is defined in mxGraph.warningImage.

Resources

The mxEditor and mxGraph classes add the following resources to mxResources at class loading time:

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

By default, the library ships with English and German resource files.

Images

Recommendations for using images. Use GIF images (256 color palette) in HTML elements (such as the toolbar and context menu), and PNG images (24 bit) for all images which appear inside the graph component.

For PNG images inside HTML elements, Internet Explorer will ignore any transparency information.
For GIF images inside the graph, Firefox on the Mac will display strange colors. Furthermore, only the first image for animated GIFs is displayed on the Mac.

For faster image rendering during application runtime, images can be prefetched using the following code:

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

Deployment

The client is added to the page using the following script tag inside the head of a document:

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

The deployment version of the mxClient.js file contains all required code in a single file. For deployment, the complete javascript/src directory is required.

Source Code

If you are a source code customer and you wish to develop using the full source code, the commented source code is shipped in the javascript/devel/source.zip file. It contains one file for each class in mxGraph. To use the source code the source.zip file must be uncompressed and the mxClient.js URL in the HTML page must be changed to reference the uncompressed mxClient.js from the source.zip file.

Compression

When using Apache2 with mod_deflate, you can use the following directive in src/js/.htaccess to speedup the loading of the JavaScript sources:

SetOutputFilter DEFLATE

Classes

There are two types of “classes” in mxGraph: classes and singletons (where only one instance exists). Singletons are mapped to global objects where the variable name equals the classname. For example mxConstants is an object with all the constants defined as object fields. Normal classes are mapped to a constructor function and a prototype which defines the instance fields and methods. For example, mxEditor is a function and mxEditor.prototype is the prototype for the object that the mxEditor function creates. The mx prefix is a convention that is used for all classes in the mxGraph package to avoid conflicts with other objects in the global namespace.

Subclassing

For subclassing, the superclass must provide a constructor that is either parameterless or handles an invocation with no arguments. Furthermore, the special constructor field must be redefined after extending the prototype. For example, the superclass of mxEditor is mxEventSource. This is represented in JavaScript by first “inheriting” all fields and methods from the superclass by assigning the prototype to an instance of the superclass, eg. mxEditor.prototype = new mxEventSource() and redefining the constructor field using mxEditor.prototype.constructor = mxEditor. The latter rule is applied so that the type of an object can be retrieved via the name of its constructor using mxUtils.getFunctionName(obj.constructor).

Constructor

For subclassing in mxGraph, the same scheme should be applied. For example, for subclassing the mxGraph class, first a constructor must be defined for the new class. The constructor calls the super constructor with any arguments that it may have using the call function on the mxGraph function object, passing along explitely each argument:

function MyGraph(container)
{
  mxGraph.call(this, container);
}

The prototype of MyGraph inherits from mxGraph as follows. As usual, the constructor is redefined after extending the superclass:

MyGraph.prototype = new mxGraph();
MyGraph.prototype.constructor = MyGraph;

You may want to define the codec associated for the class after the above code. This code will be executed at class loading time and makes sure the same codec is used to encode instances of mxGraph and MyGraph.

var codec = mxCodecRegistry.getCodec(mxGraph);
codec.template = new MyGraph();
mxCodecRegistry.register(codec);

Functions

In the prototype for MyGraph, functions of mxGraph can then be extended as follows.

MyGraph.prototype.isCellSelectable = function(cell)
{
  var selectable = mxGraph.prototype.isSelectable.apply(this, arguments);

  var geo = this.model.getGeometry(cell);
  return selectable && (geo == null || !geo.relative);
}

The supercall in the first line is optional. It is done using the apply function on the isSelectable function object of the mxGraph prototype, using the special this and arguments variables as parameters. Calls to the superclass function are only possible if the function is not replaced in the superclass as follows, which is another way of subclassing in JavaScript.

mxGraph.prototype.isCellSelectable = function(cell)
{
  var geo = this.model.getGeometry(cell);
  return selectable &&
      (geo == null ||
      !geo.relative);
}

The above scheme is useful if a function definition needs to be replaced completely.

In order to add new functions and fields to the subclass, the following code is used. The example below adds a new function to return the XML representation of the graph model:

MyGraph.prototype.getXml = function()
{
  var enc = new mxCodec();
  return enc.encode(this.getModel());
}

Variables

Likewise, a new field is declared and defined as follows.

MyGraph.prototype.myField = 'Hello, World!';

Note that the value assigned to myField is created only once, that is, all instances of MyGraph share the same value. If you require instance-specific values, then the field must be defined in the constructor instead.

function MyGraph(container)
{
  mxGraph.call(this, container);

  this.myField = new Array();
}

Finally, a new instance of MyGraph is created using the following code, where container is a DOM node that acts as a container for the graph view:

var graph = new MyGraph(container);

翻譯：

概述

這個JavaScript庫分爲8個包。頂級mxClient類包括(或動態導入)所有其他內容。當前版本存儲在mxClient.VERSION中。

編輯器包提供了實現圖表編輯器所需的類。這個包中的主類是mxEditor。

視圖和模型包實現由mxGraph表示的圖形組件。它引用一個包含mxgraphcell的mxGraphModel，並在mxGraphView中緩存單元格的狀態。單元格是使用mxCellRenderer根據mxStylesheet中定義的外觀繪製的。撤銷歷史記錄是在mxUndoManager中實現的。要在圖形上顯示圖標，可以使用mxCellOverlay。驗證規則是用mxMultiplicity定義的。

處理程序、佈局和形狀包分別包含事件監聽器、佈局算法和形狀。圖形事件監聽器包括用於rubberband選擇的mxRubberband、用於工具提示的mxTooltipHandler和用於基本單元格修改的mxGraphHandler。mxCompactTreeLayout實現了一個樹佈局算法，shape包提供了各種形狀，它們是mxShape的子類。

util包提供了實用工具類，包括用於複製粘貼的mxClipboard、用於拖放的、用於樣式表的鍵和值的mxConstants、用於跨瀏覽器事件處理和通用功能的mxEvent和mxUtils、用於國際化的mxResources和用於控制檯輸出的mxLog。

io包實現了一個通用的mxObjectCodec，用於將JavaScript對象轉換爲XML。主要的類是mxCodec。mxCodecRegistry是用於自定義編解碼器的全局註冊表。

事件

有三種不同類型的事件，即原生DOM事件、在mxEventSource中觸發的mxEventObjects和在mxGraph中觸發的mxMouseEvents。

mxEvent中提供了一些用於處理本機事件的輔助方法。它還負責解析DOM節點和JavaScript事件處理程序之間的循環，這可能導致IE6中的內存泄漏。

mxGraph中的大多數自定義事件都是使用mxEventSource實現的。它的監聽器是接收sender和mxEventObject的函數。另外，mxGraph類觸發特殊的mxMouseEvents，這些事件使用鼠標監聽器來處理，這些監聽器是提供mousedown、mousemove和mouseup方法的對象。

使用mxEventSource. fireevent觸發mxEventSource中的事件。使用mxEventSource添加和刪除偵聽器。addListener mxEventSource.removeListener。mxGraph中的mxmouseevent是使用mxGraph. firemouseevent觸發的。使用mxGraph添加和刪除偵聽器。addMouseListener mxGraph。分別removeMouseListener。

鍵綁定

以下鍵綁定是爲跨所有瀏覽器和平臺的客戶端鼠標事件定義的:

control -拖動:複製(克隆)選定的單元格
Shift-Rightlick:顯示上下文菜單
Alt-Click:力量橡膠帶(又名。選框)
Control-Select:切換選擇狀態
shift -拖動:限制一個方向的偏移量
shift - control -拖動:平移(也可以是Shift-Rightdrag)

配置

在加載客戶端之前，可以分別定義以下全局變量來指定其語言或基本路徑。

mxBasePath:指定mxClient.basePath中的路徑。
mxImageBasePath:指定mxClient.imageBasePath中的路徑。
mxLanguage:指定mxClient.language中的資源的語言。
mxDefaultLanguage:指定mxClient.defaultLanguage中的默認語言。
mxLoadResources:指定是否加載任何資源。默認是正確的。
mxloadstylesheet:指定是否加載任何樣式表。默認是正確的。

保留字

mx前綴用於mxGraph中的所有類和對象。mx前綴可以看作是mxGraph中所有JavaScript代碼的全局名稱空間。下列字段名不應在對象中使用。

mxObjectId:如果對象與mxObjectIdentity一起使用
as:如果對象是另一個對象的字段
id:如果對象是編解碼器中的idref
mxListenerList:與mxEvent一起使用時添加到DOM節點
window._mxDynamicCode:臨時用於在Safari和Chrome中加載代碼(參見mxClient.include)。
_mxJavaScriptExpression:全局變量，用於臨時計算Safari、Opera、Firefox 3和IE中的代碼(參見mxUtils.eval)。

文件

庫包含這些相對的文件名。所有文件名都與mxClient.basePath相關。

內置的圖像

所有圖像都是從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中定義。

資源

mxEditor和mxGraph類在類加載時向mxResources添加以下資源:

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

默認情況下，庫附帶英語和德語資源文件。

圖片

使用圖像的建議。在HTML元素(如工具欄和上下文菜單)中使用GIF圖像(256色調色板)，對於圖形組件中出現的所有圖像使用PNG圖像(24位)。

對於HTML元素中的PNG圖像，Internet Explorer將忽略任何透明信息。
對於圖形內部的GIF圖像，Mac上的Firefox將顯示奇怪的顏色。此外，Mac上只顯示第一個動態gif圖像。

爲了在應用程序運行時更快的圖像渲染，可以使用以下代碼預取圖像:

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

部署

客戶端被添加到頁面使用以下腳本標籤內的一個文件的頭部:

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

js文件的部署版本在一個文件中包含了所有需要的代碼。對於部署，需要完整的javascript/src目錄。

源代碼

如果您是源代碼客戶，並且希望使用完整的源代碼進行開發，那麼所註釋的源代碼將包含在javascript/devel/source.zip文件中。它爲mxGraph中的每個類包含一個文件。要使用源代碼，必須解壓source.zip文件，並且必須更改HTML頁面中的mxClient.js URL，以從source.zip文件引用未壓縮的mxClient.js。

壓縮

在mod_deflate中使用Apache2時，可以在src/js/中使用以下指令。htaccess加速加載JavaScript源代碼:

SetOutputFilter DEFLATE

類

在mxGraph中有兩種類型的“類”:類和單例(其中只有一個實例存在)。單例對象被映射到全局對象，其中變量名等於類名。例如，mxConstants是一個對象，所有的常量都定義爲對象字段。普通類映射到構造函數和定義實例字段和方法的原型。例如，mxEditor是一個函數和mxEditor。prototype是mxEditor函數創建的對象的原型。mx前綴是一種約定，用於mxGraph包中的所有類，以避免與全局名稱空間中的其他對象發生衝突。

子類化

對於子類化，超類必須提供無參數或處理無參數調用的構造函數。此外，特殊構造函數字段必須在擴展原型之後重新定義。例如，mxEditor的超類是mxEventSource。這在JavaScript中表示爲，首先通過將原型分配給超類的一個實例來“繼承”來自超類的所有字段和方法，例如。mxEditor。prototype = new mxEventSource()，並使用mxedit .prototype重新定義構造函數字段。構造函數= mxEditor。後者應用規則,這樣類型的一個對象可以通過它的名字檢索的年代構造函數使用mxUtils.getFunctionName (obj.constructor)。

構造函數

對於mxGraph中的子類化，應該採用相同的方案。例如，爲了子類化mxGraph類，首先必須爲新類定義一個構造函數。構造函數使用mxGraph函數對象上的調用函數調用具有任何參數的超級構造函數，並明確地傳遞每個參數:

function MyGraph(container)
{
  mxGraph.call(this, container);
}

MyGraph的原型從mxGraph繼承如下。通常，構造函數在擴展超類後被重新定義:

MyGraph.prototype = new mxGraph();
MyGraph.prototype.constructor = MyGraph;

您可能希望在上述代碼之後定義與類相關的編解碼器。此代碼將在類裝入時執行，並確保使用相同的編解碼器對mxGraph和MyGraph的實例進行編碼。

var codec = mxCodecRegistry.getCodec(mxGraph);
codec.template = new MyGraph();
mxCodecRegistry.register(codec);

功能

在MyGraph的原型中，mxGraph的功能可以擴展如下。

MyGraph.prototype.isCellSelectable = function(cell)
{
  var selectable = mxGraph.prototype.isSelectable.apply(this, arguments);

  var geo = this.model.getGeometry(cell);
  return selectable && (geo == null || !geo.relative);
}

第一行中的超調用是可選的。它是使用mxGraph原型的isSelectable函數對象上的apply函數完成的，使用特殊的this和arguments變量作爲參數。調用超類函數是唯一可能的,如果不是取代超類如下,這是另一種子類化JavaScript。

mxGraph.prototype.isCellSelectable = function(cell)
{
  var geo = this.model.getGeometry(cell);
  return selectable &&
      (geo == null ||
      !geo.relative);
}

如果需要完全替換一個函數定義，那麼上面的方案是有用的。

爲了向子類添加新函數和字段，使用了以下代碼。下面的示例添加了一個新函數來返回圖模型的XML表示:

MyGraph.prototype.getXml = function()
{
  var enc = new mxCodec();
  return enc.encode(this.getModel());
}

變量

同樣，新字段的聲明和定義如下。

MyGraph.prototype.myField = 'Hello, World!';

注意，分配給myField的值只創建一次，也就是說，MyGraph的所有實例共享相同的值。如果需要實例特定的值，則必須在構造函數中定義字段。

function MyGraph(container)
{
  mxGraph.call(this, container);

  this.myField = new Array();
}

最後，使用以下代碼創建一個新的MyGraph實例，其中container是一個充當graph視圖容器的DOM節點:

var graph = new MyGraph(container);