mxgraph 系列【2】：項目結構

1. 目錄說明

mxgraph 目錄結構以下：

• docs: mxgraph 說明文檔
• dotnet: 基於 .net 的編輯器後端實現，暫時無需關注
• etc/build: 這個目錄下只有一份 Gruntfile.js 文件，用於構建生成環境版本
• java: 基於 java 的編輯器後端實現，暫時無需關注
• javascript: mxgraph 核心代碼文件夾，其中 javascript/src 爲框架源碼；javascript/examples 爲示例代碼。

mxgraph 倉庫主要包含幾類類型的資源，最核心的是 javascript/src 目錄下的圖形引擎源碼；其次是 javascript/src/editor 目錄中基於圖形引擎實現的圖形編輯器；以外還有基於 .net、java 的後端示例；以及做爲學習資源的 docs 目錄下的文檔，和 javascript/examples 目錄下的示例代碼，下面逐一解釋。

2. 官方文檔

學習 mxgraph，能夠先從官方提供的文檔出發。mxgraph 倉庫中存在如下幾類文檔，對入門有比較大的幫助：

1. tutorial: 項目概覽文檔，概要說明 mxgraph 的做用、組件結構，並提供了一個簡單的入門示例，首次接觸項目時有較高的指導做用。
2. manual: 用戶手冊文檔，詳細說明了 mxgraph 的設計思路、開發動機、使用方法，以及 mxgraph 如何管理圖像的數據模型。前期建議略讀，寫幾個示例對框架有了基本的感性認知後能夠再回過頭來細讀。
3. examples: 項目示例索引文檔，詳細介紹了每個示例的用途，可用做參考學習。
4. api: API 手冊，提供了 mxgraph 下全部類、類方法、類屬性的使用說明，能夠在須要用到某些類時查詢。

建議的閱讀順序是，一細讀 tutorial，可以幫助創建對 mxgraph 的感性認知；二略讀 manual，瞭解 mxgraph 數據模型的管理方法；三細讀各個示例代碼，從示例中學習、領悟各種接口的用法；必要時能夠結合 api 文檔查閱各個接口的詳細信息。

以上各種文檔都可雙擊對應的 html 文件，在瀏覽器打開查閱。

提示：

mxgraph 官方文檔質量寫的簡直惜字如金，不少概念一筆帶過，沒有詳盡說明，加上社區對 mxgraph 的討論熱度很低，致使對於使用者而言，框架學習成本很高。這種情況下，筆者認爲最有效的學習方法只能是結合示例、API 文檔、源碼，三個維度互相對照學習。

3. 核心目錄結構

mxgraph 框架代碼存放於 javascript/src 目錄下，主要文件有：

mxgraph
└─── javascript
│   └─── src
│       └─── css
│       └─── images
│       └─── js
│            └─── editor
│            └─── handler
│            └─── io
│            └─── layout
│            └─── model
│            └─── shape
│            └─── util
│            └─── view
│            |    index.txt
│       └─── resources
│       │   index.html
│       │   mxClient.js
│       │   mxClient.min.js

• javascript/src/js: mxgraph 的 JS 代碼，基本上全部功能都是在這裏實現。
• javascript/src/css: mxgraph 組件的樣式實現，可暫時忽略。
• javascript/src/images: 圖表編輯器中須要用到的圖像資源，可忽略。
• javascript/src/resource: 圖形編輯器的多語言定義文件，可忽略。

mxgraph 的核心功能都定義在 javascript/src/js 目錄下，因此後續的學習主要都是集中在這部分代碼中。幾個子目錄的主要做用分別爲：

• model 子目錄是數據管理模型的實現，數據模型記錄着 mxgraph 實例的圖形結構及節點的詳細信息，並對外暴露一系列更新、刪除、插入接口，咱們使用 mxgraph 時會跟這部分接口常常打交道。關於數據模型的更多探索，將在後續補充。
• shape 定義了幾種主要的圖元類型，包括線、標籤、箭頭、多邊形、四邊形、泳道等。
• view 是框架對外交互的主要接口層，包含了圖形交互接口 mxGraph 類、樣式管理接口 mxStylesheet、圖元編輯器 mxCellEditor 等。
• handler 定義了框架中圖元的幾種常見的交互行爲邏輯，好比處理快捷鍵邏輯的 mxKeyHandler；處理鏈接線分片的 mxEdgeSegmentHandler；處理圖元高亮效果的 mxCellHighlight 等。
• layout 定義 mxgraph 所使用的佈局邏輯，包括堆疊佈局 mxStackLayout；泳道佈局 mxSwimlaneLayout；圓形佈局 mxCircleLayout。
• util 包含各類工具函數。
• io 定義了幾種應對不一樣時態的編解碼器，可用以實現 mxgraph 實例狀態的持久化。
• editor 短小精悍的編輯器實現，內置快捷鍵、彈出菜單、工具欄等功能支持。

此外， javascript/src/mxClient.js 是框架的入口文件，它一方面定義了一系列環境變量；一方面聲明框架的基礎依賴文件列表。 javascript/src/mxClient.min.js 是通過 etc/build/Gruntfile.js 執行鏈接、合併、壓縮操做後的版本，可用做生產環境庫文件。

提示：

mxgraph 倉庫包含兩類功能代碼，一是做爲底層的圖形引擎；二是做爲上層應用的圖形編輯器。源碼中 javascript/src/js/editor 是編輯器的實現代碼， javascript/src/css、javascript/src/images、javascript/src/resource 都是圖形編輯器的資源依賴，建議讀者暫時忽略這部分代碼，先集中精力學習圖形引擎的使用方法。

4. 示例代碼

mxgraph 官方提供的示例都在 javascript/examples 目錄下，合計有 88 個，能夠雙擊 javascript/index.html 打開示例索引文檔。雖然有如此多的示例代碼，但每個示例都沒有足夠的細節說明；官方也沒有提供一個由淺入深的學習流程，爲此我簡單總結了一份閱讀順序：

1. helloworld.html，雖然是很基礎的入門示例，但完整演示了 mxgraph 框架的使用流程。
2. 經過 shape.html 學習如何自定義圖元；經過 stencils.html 學習如何以 xml 格式定義圖元樣式。
3. 經過 events.html 學習如何監聽 mxgraph 實例對象的事件，完整的事件列表可參考 javascript/docs/jsapi/index.html 文檔。
4. 經過 layers.html 學習圖形分層的概念，分層功能有助於管理圖形元素，大多數圖形引擎都會有相似的功能設計。
5. 經過 groups.html 學習圖形元素的分組合並，分組功能能將複數的圖形在邏輯上合併爲 一個 元素，是另外一種維度的管理方法。
6. 經過 stylesheet.html 學習如何定義圖形樣式。
7. 經過 images.html 學習如何在 mxgraph 中嵌入自定義圖案。
8. 經過 markers.html 學習如何修改鏈接線的樣式。
9. 經過 labels.html、secondlabel.html 學習如何爲圖形添加說明文字；經過 indicators.html 學習如何爲父級圖元增長指示器；經過 htmllabel.html 學習若是以 label 形式嵌入 html 內容。
10. 經過 anchors.html、control.html 學習如何爲圖形組件添加交互功能。
11. 經過 graphlayout.html、autolayout.html、boundary.html 學習 mxgraph 的佈局功能；以後還可經過 hierarchicallayout.html、swimlanes.html 學習更復雜的佈局邏輯。
12. 經過 codec.html、jsondata.html 學習如何執行數據模型的編解碼功能，以及 fileio.html 學習如何實現圖形內容的持久化與還原。
13. 經過 dragsource.html、drop.html 學習如何實現圖形拖拽操做，以及 handles.html 學習更復雜的交互功能。

精度以上事例，結合 javascript/docs/jsapi/index.html 文檔相信讀者會對 mxgraph 有一個更高維度的認知。