orgchart 5.0.0 → 7.0.0

package/README.zh-tw.md

@@ -1,4 +1,4 @@
-![OrgChart](http://dabeng.github.io/OrgChart/img/heading.svg)
+![OrgChart](http://dabeng.github.io/OrgChart/img/cover.png)
 
 # Read this in other languages: [简体中文](https://github.com/dabeng/OrgChart/blob/master/README.zh-cn.md), [English](https://github.com/dabeng/OrgChart/blob/master/README.md)
 
@@ -11,6 +11,9 @@
 ## 寫在前面的話
 感謝[wesnolte](https://github.com/wesnolte)的非常棒的作品-- [jOrgChart](https://github.com/wesnolte/jOrgChart)。用嵌套的table來構造樹狀結構，用td的border來構造節點間的連線，非常有創意。天然地降低了前端程序員在構造樹狀結構時的工作量和難度，要知道，利用D3.js中的腦圖去達到同樣效果，開發周期就會長好多。哪怕你對svg，canvas等高級的制圖API了然于胸，當你的樹狀結構圖激發出HR大姐的各種天馬行空的需求時，你會坦誠的承認svg或canvas這種重型武器拖累了你的快速解決一小戳敵人的能力。相比較而言，用單純的**HTML5 + CSS3**的解決方案就像是 **“小米 + 步槍”的輕步兵**，天然地降低了你在實現樹狀結構圖的難度，同時給予你更大的定制空間去面對基于這個結構圖衍生出的種種瑣碎需求。只要你的需求足夠多，基于這個樹狀結構圖，打造出一個完備的HR系統，也是可以期待的。實際上，網絡上很多OrgChart商業軟件就是圍繞著一個樹狀結構核心模型展開的業務邏輯實現。
 
+- 自 5.0 版本起，使用者可以建立家譜樹。
+- 自 6.0 版本起，OrgChart 元件已回歸原生實作，不再依賴 jQuery。
+
 ## 功能特性
 - 支持本地和遠程的數據源。
 - 用戶可以展開/折疊節點或子樹，方便地浏覽局部的結構圖。
@@ -40,13 +43,19 @@ $ bower install orgchart
 # From version 1.0.4 on, users can install orgchart with npm
 $ npm install orgchart
 ```
-`require('orgchart')`會把orgchart插件追加到jQuery對象上。orgchart模塊本身並不導出任何東西。
+在 CommonJS 環境中，`require('orgchart')`會直接導出 `OrgChart` 構造函數。
+
+可參考這個例子, [在React中使用jQuery Orchart](https://stackblitz.com/edit/vitejs-vite-hqv4nbdt)
 
 ## [gihtub pages實例集合](https://dabeng.github.io/OrgChart/)
 ## [基于嵌套ul的實例集合](https://codepen.io/collection/nWqvzY)
 ## [基于嵌套table的實例集合](https://codepen.io/collection/AWxGVb/) (過時)
 
 ### 天馬行空的需求
+- [我想在500毫秒內渲染10,000個節點](https://dabeng.github.io/OrgChart/10000-nodes.html)
+
+![10000-nodes](http://dabeng.github.io/OrgChart/img/10000-nodes.png)
+
 - [ul數據源](https://dabeng.github.io/OrgChart/ul-datasource.html)(感謝 [Tobyee的好點子:blush:](https://github.com/dabeng/OrgChart/issues/1))
 
 - [本地數據源](https://dabeng.github.io/OrgChart/local-datasource.html)
@@ -109,6 +118,8 @@ $ npm install orgchart
 
 這個特性的靈感來源于這兩個話題的討論--[Aligning Children Vertical](https://github.com/dabeng/OrgChart/issues/46), [Hybrid(horizontal + vertical) OrgChart](https://github.com/dabeng/OrgChart/issues/61)。感謝[mfahadi](https://github.com/mfahadi)和[Destructrix](https://github.com/Destructrix)建設性的討論:blush:尤其感謝[tedliang](https://github.com/tedliang)提供了非常棒的混合布局的解決方案。
 
+與 `compact` 同時設定時，`verticalLevel` 從指定層級開始決定版面配置。方向、層級限制和拖放仍按照實際的父子關係處理。
+
 - [我想在組織結構圖初始化時，就默認折疊掉若幹節點（不限時這些節點的子節點）](https://dabeng.github.io/OrgChart/default-collapsed.html)
 
 這個好辦。在數據源中，給父節點追加`'collapsed': true`，給子節點追加`'className': 'slide-up'`。
@@ -147,6 +158,10 @@ $ npm install orgchart
 
 **compact data property** 就派上用場了。在數據源的某個節點裏提供了"compact"屬性，並賦為真值，那麽它和它的子節點就會展示為壓縮模式。
 
+緊湊版面配置可以與 `draggable`、`visibleLevel`、方向、平移、縮放和小地圖同時使用。`compact: true` 會將所有分支設為緊湊版面配置，也可以透過回呼選擇子節點較多的分支。`drag` 是 `draggable` 的別名，同時提供兩者時以 `draggable` 為準。緊湊版面配置中的拖放和節點編輯可能重建圖表，操作後應重新取得已渲染的節點元素。
+
+家譜分組資料中的每個成員都使用設定的 `nodeId`，層級與 JSON、UL 資料一樣從第 1 層起算。緊湊家譜的子節點按家庭分組排列成網格。拖放和編輯只修改選取成員及其後代，不會誤移動整個家庭；家譜修改可能重建節點元素。`getHierarchy()` 會保留家譜分組陣列，關聯節點查詢包含同一圖表父級下的全部成員。
+
 - [我想構造族譜，家譜，宗譜的關系圖](https://dabeng.github.io/OrgChart/family-tree.html)
 
 ![family-tree](http://dabeng.github.io/OrgChart/img/family-tree.png)
@@ -156,32 +171,32 @@ $ npm install orgchart
 ```
 var datascource = [
   [
-    { 'id': '8', 'name': 'Lao Ye', 'title': 'Grandfather', 'gender': 'male' },
+    { 'id': '8', 'name': 'Lao Ye', 'title': 'Grandfather' },
     { 
-      'id': '1', 'name': 'Lao Lao', 'title': 'Grandmother', 'gender': 'female', 'outsider': true,
+      'id': '1', 'name': 'Lao Lao', 'title': 'Grandmother', 'outsider': true,
       'children': [
         [
-          { 'id': '2', 'name': 'Bo miao', 'title': 'Aunt', 'gender': 'female'}
+          { 'id': '2', 'name': 'Bo miao', 'title': 'Aunt' }
         ],
         [
-          { 'id': '3', 'name': 'Su Miao', 'title': 'Mother', 'gender': 'female',
+          { 'id': '3', 'name': 'Su Miao', 'title': 'Mother',
             'children': [
               [
               
-                { 'id': '12', 'name': 'Pang Pang', 'title': 'Wife', 'gender': 'female', 'outsider': true,
+                { 'id': '12', 'name': 'Pang Pang', 'title': 'Wife', 'outsider': true,
                   'children': [
-                    [{ 'id': '7', 'name': 'Dan Dan', 'title': 'Daughter', 'gender': 'female' }],
-                    [{ 'id': '6', 'name': 'Er Dan', 'title': 'Daughter', 'gender': 'female' }],
+                    [{ 'id': '7', 'name': 'Dan Dan', 'title': 'Daughter' }],
+                    [{ 'id': '6', 'name': 'Er Dan', 'title': 'Daughter' }],
                   ]
                 },
-                { 'id': '5', 'name': 'Hei Hei', 'title': 'Me', 'gender': 'male' },
+                { 'id': '5', 'name': 'Hei Hei', 'title': 'Me' },
               ]
             ]
           },
-          { 'id': '9', 'name': 'Tie Hua', 'title': 'Father', 'gender': 'male', 'outsider': true }
+          { 'id': '9', 'name': 'Tie Hua', 'title': 'Father', 'outsider': true }
         ],
         [
-          { 'id': '10', 'name': 'Hong miao', 'title': 'Aunt', 'gender': 'female'}
+          { 'id': '10', 'name': 'Hong miao', 'title': 'Aunt' }
         ]
       ]
     }
@@ -189,6 +204,16 @@ var datascource = [
 ];
 ```
 
+- [我想往族譜裏追加一些自定義的標識](https://dabeng.github.io/OrgChart/familytree-custom-properties.html)
+
+![familytree-custom-properties](http://dabeng.github.io/OrgChart/img/familytree-custom-properties.png)
+
+- [我想通過小地圖導航組織結構圖](https://dabeng.github.io/OrgChart/minimap.html)
+
+![minimap](http://dabeng.github.io/OrgChart/img/minimap.png)
+
+啓用 `minimap` 選項即可顯示概覽導航器。拖動其中的視口可以移動組織結構圖，在小地圖上滾動鼠標滾輪可以縮放。
+
 ### 本地運行orgchart
 
 - 必須安裝node.js v6+，因爲我們的單元測試是基于jsdom v11。
@@ -202,7 +227,10 @@ var datascource = [
 
 ### 實例化組織結構圖
 ```js
-var oc = $('#chartContainerId').orgchart(options);
+var oc = new OrgChart({
+  chartContainer: '#chartContainerId',
+  data: datasource
+});
 ```
 
 ### 數據源示例
@@ -215,28 +243,25 @@ var oc = $('#chartContainerId').orgchart(options);
   // 來檢索數據源，然後渲染默認結構樣式的節點的上半部分
   'nodeContent': 'title', // 可選屬性。插件會以該屬性的值爲屬性，
   // 來檢索數據源，然後渲染默認結構樣式的節點的下半部分
-  'relationship': relationshipValue, // 注意：當你激活按需載入節點特性時
-  // 你應該使用JSON數據源（不論本地或遠程）並設置本屬性
-  // 本屬性標識當前節點是否具有父節點，兄弟節點，子節點
-  // relationshipValue的值是由“0”或“1”組成的長度爲3的字符串
-  // 第1個字符代表當前節點是否具有父節點
-  // 第2個字符代表當前節點是否具有兄弟節點
-  // 第三個字符代表當前節點是否具有孩子節點
   'children': [ // The property stands for nested nodes.
-    { 'name': 'Bo Miao', 'title': 'department manager', 'relationship': '110' },
-    { 'name': 'Su Miao', 'title': 'department manager', 'relationship': '111',
+    { 'name': 'Bo Miao', 'title': 'department manager' },
+    { 'name': 'Su Miao', 'title': 'department manager',
       'children': [
-        { 'name': 'Tie Hua', 'title': 'senior engineer', 'relationship': '110' },
-        { 'name': 'Hei Hei', 'title': 'senior engineer', 'relationship': '110' }
+        { 'name': 'Tie Hua', 'title': 'senior engineer' },
+        { 'name': 'Hei Hei', 'title': 'senior engineer' }
       ]
     },
-    { 'name': 'Yu Jie', 'title': 'department manager', 'relationship': '110' }
+    { 'name': 'Yu Jie', 'title': 'department manager' }
   ],
   'otherPro': anyValue // 數據源中可以追加任意其他字段，只要你覺得
   // 在之後的渲染和操作組織結構圖時派得上用場
 };
 ```
 
+節點關係直接依據目前已載入的結構判斷。展開摺疊和緊湊佈局切換按鈕在節點懸浮、聚焦或觸控選取時才建立，互動結束後回收；參與載入的按鈕保留至載入完成。鍵盤使用者可以聚焦節點，再用 Enter 或空白鍵啟動按鈕。
+
+`createNode` 回呼執行時沒有預先建立的互動按鈕，請透過 `icons` 自訂圖示，不要查詢初始化時的箭頭元素。按需載入由 demo 或業務層透過 `createNode` 建立獨立請求按鈕，並使用事件委派處理請求；請求按鈕應使用與內建控制項不同的行為選擇器。載入後呼叫 `addAncestors()`、`addChildren()` 或 `addDescendants()` 加入實際節點，不需要關係中繼資料或新的載入回呼選項。`getNodeState()` 只描述已載入的關係，不推斷伺服器尚未載入的資料。舊的關係屬性和關係預處理方法不再支援。
+
 ### 選項
 <table>
   <thead>
@@ -251,10 +276,10 @@ var oc = $('#chartContainerId').orgchart(options);
   <tbody>
     <tr>
       <td>data</td>
-      <td>json / jquery object</td>
+      <td>object / array / HTMLUListElement</td>
       <td>是</td>
       <td></td>
-      <td>用于構造組織結構圖的數據源。它的值可以是JSON或能提供數據的ul元素。</td>
+      <td>資料來源可以是 JSON 樹狀物件、家譜分組陣列或 HTML ul 元素。UL 資料會在內部正規化，後續修改選項時仍會保留編輯結果。</td>
     </tr>
     <tr>
       <td>pan</td>
@@ -270,19 +295,26 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>false</td>
       <td>啓動本選項，用戶可以通過鼠標滾輪或觸摸板對組織結構圖進行縮放。</td>
     </tr>
+    <tr>
+      <td>minimap</td>
+      <td>boolean</td>
+      <td>否</td>
+      <td>false</td>
+      <td>顯示小地圖導覽。拖動視口框可移動圖表，在小地圖上使用滾輪可縮放；即使 zoom 為 false，小地圖自身的滾輪縮放仍然可用。</td>
+    </tr>
     <tr>
       <td>zoominLimit</td>
       <td>number</td>
       <td>否</td>
       <td>7</td>
-      <td>放大的上限值</td>
+      <td>包含邊界的最大縮放比例。縮放步長會限制到此邊界。上下限必須為有限正數，且下限不能大於上限。</td>
     </tr>
     <tr>
       <td>zoomoutLimit</td>
       <td>number</td>
       <td>否</td>
       <td>0.5</td>
-      <td>縮小的下限值</td>
+      <td>包含邊界的最小縮放比例，不能大於 zoominLimit。無效的上下限會在替換圖表前拋出 RangeError。</td>
     </tr>
     <tr>
       <td>direction</td>
@@ -307,10 +339,10 @@ var oc = $('#chartContainerId').orgchart(options);
     </tr>
     <tr>
       <td>visibleLevel</td>
-      <td>positive integer</td>
+      <td>非負整數或布林值</td>
       <td>否</td>
       <td>999</td>
-      <td>該選項爲用戶指定初始化組織結構圖時，可見的展開的層級是多少</td>
+      <td>指定初始展開深度。true 使用預設深度（999）；false 只顯示第一層；0 隱藏所有初始節點。更深的分支可以隨後展開。</td>
     </tr>
     <tr>
       <td>nodeTitle</td>
@@ -319,13 +351,6 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>"name"</td>
       <td>將默認節點結構中的標題部分關聯到數據源中的一個屬性</td>
     </tr>
-    <tr>
-      <td>parentNodeSymbol</td>
-      <td>string</td>
-      <td>否</td>
-      <td>"oci-leader"</td>
-      <td>爲所有父節點的icon標識指定CSS類名</td>
-    </tr>
     <tr>
       <td>nodeContent</td>
       <td>string</td>
@@ -352,7 +377,7 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>function</td>
       <td>否</td>
       <td></td>
-      <td>爲該選項提供的函數，會在默認節點結構創建完畢後調用。利用傳入的兩個參數--"$node"和"data"，可以幫助開發者定制或改動現有的節點結構。</td>
+      <td>爲該選項提供的函數，會在默認節點結構創建完畢後調用。利用傳入的兩個參數--"node"和"data"，可以幫助開發者定制或改動現有的節點結構。</td>
     </tr>
     <tr>
       <td>exportButton</td>
@@ -372,7 +397,7 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>exportFilename</td>
       <td>string</td>
       <td>否</td>
-      <td>"Orgchart"</td>
+      <td>"OrgChart"</td>
       <td>導出文件的文件名。</td>
     </tr>
     <tr>
@@ -382,6 +407,13 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>"png"</td>
       <td>導出文件的擴展名。</td>
     </tr>
+    <tr>
+      <td>exportScale</td>
+      <td>number</td>
+      <td>否</td>
+      <td>2</td>
+      <td>匯出畫布的解析度倍數，PNG 和 PDF 均適用；PDF 頁面保留圖表的邏輯尺寸。非正數會回退為 1。</td>
+    </tr>
     <tr>
       <td>chartClass</td>
       <td>string</td>
@@ -408,20 +440,83 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>function</td>
       <td>否</td>
       <td></td>
-      <td>組織結構圖初始化完成後，該選項指定的回調函數被觸發。該函數接受一個參數--"$chart", 即初始化後的組織結構圖jquery對象。</td>
+      <td>組織結構圖初始化完成後，該選項指定的回調函數被觸發。該函數接受一個參數--"chart", 即初始化後的組織結構圖元素。</td>
+    </tr>
+    <tr>
+      <td>icons</td>
+      <td>json</td>
+      <td>否</td>
+      <td></td>
+      <td>自訂圖示的 CSS 類別名稱。部分圖示物件會逐欄位與預設值合併，父節點圖示使用 icons.parentNode 設定。
+        <pre>
+          <code>
+'icons': {
+  'theme': 'fa-solid fa-sm',
+  'parentNode': 'fa-user-tie',
+  'expandToUp': 'fa-angles-up',
+  'collapseToDown': 'fa-angles-down',
+  'collapseToLeft': 'fa-angles-left',
+  'expandToRight': 'fa-angles-right',
+  'collapsed': 'fa-circle-plus',
+  'expanded': 'fa-circle-minus'
+}
+          </code>
+        </pre>
+      </td>
+    </tr>
+    <tr>
+      <td>compact</td>
+      <td>布林值或函式</td>
+      <td>否</td>
+      <td></td>
+      <td>true 會將所有分支設為緊湊版面配置；接收節點資料的回呼可選擇額外的緊湊分支。節點資料中明確設定的 compact 屬性會保留。在適用的節點上，垂直或混合版面配置優先。</td>
     </tr>
   </tbody>
 </table>
 
 ### 方法
-我們相信當你研究了[edit orgchart](http://dabeng.github.io/OrgChart/edit-orgchart/)這個Demo後，會基本掌握orgchart插件的所有方法。
+使用 `new OrgChart(options)` 建立實例。`chartContainer` 和 `chart` 屬性分別提供原生容器元素與已渲染的組織結構圖元素。
 
-#### var oc = $container.orgchart(options)
-在指定容器元素內嵌入一個組織結構圖。該方法接受的options參數的細節可以到上面的“選項”一節中查看。這裏的oc是OrgChart類的實例。
+```js
+const oc = new OrgChart({ chartContainer: '#chartContainerId', data: datasource });
+```
+
+公開 API 包括：`init`、`setOptions`、`attachMinimap`、`detachMinimap`、`updateMinimap`、`addAncestors`、`addDescendants`、`addParent`、`addSiblings`、`addChildren`、`removeNodes`、`getHierarchy`、`getNodeState`、`getParent`、`getChildren`、`getSiblings`、`getRelatedNodes`、`hideParent`、`showParent`、`hideChildren`、`showChildren`、`hideSiblings`、`showSiblings`、`setChartScale`、`export`、`exportPNG` 和 `exportPDF`。其中節點和圖表參數均為原生 `HTMLElement`。
+
+#### API 參考
+| 呼叫 | 參數 | 回傳值與呼叫行為 |
+| --- | --- | --- |
+| `oc.init(options)` | 部分選項物件；傳入 `data` 可替換資料來源。 | 重新建立圖表並回傳 `oc`。 |
+| `oc.setOptions(options)`<br>`oc.setOptions(name, value)` | 部分選項物件，或選項名稱及對應值。 | 原地更新導覽與匯出設定；資料、版面配置或節點渲染設定會重建圖表；回傳 `oc`。 |
+| `oc.attachMinimap()`<br>`oc.detachMinimap()`<br>`oc.updateMinimap(forceRefresh)` | `forceRefresh` 可選；傳入 `true` 會重繪節點預覽。 | 建立、移除或刷新小地圖。一般啟用應使用 `setOptions('minimap', value)`。 |
+| `oc.addAncestors(data, parentId)` | 祖先資料，以及接收原根節點的祖先節點 id。 | 插入祖先層級；無回傳值。 |
+| `oc.addDescendants(data, parent)` | 後代資料陣列和已渲染的父 `.node`。 | 附加後代層級；無回傳值。 |
+| `oc.addParent(currentRoot, data)` | 已渲染的根 `.node` 和新父節點資料。 | 用新父節點包裹目前根；無回傳值。 |
+| `oc.addSiblings(node, data)`<br>`oc.addChildren(node, data)` | 已渲染的 `.node` 和兄弟節點或子節點資料陣列。 | 增加渲染節點；無回傳值。 |
+| `oc.removeNodes(node)` | 要刪除的已渲染 `.node`。 | 刪除該節點及其後代；無回傳值。 |
+| `oc.getHierarchy(includeNodeData)` | 可選布林值，預設 `false`。 | 樹狀資料回傳層級物件，家譜資料回傳分組陣列；圖表或必要節點 id 不可用時回傳錯誤字串。 |
+| `oc.getNodeState(node, relation)` | 已渲染 `.node`；`relation` 為 `parent`、`children` 或 `siblings`。 | 回傳 `{ exist, visible }`。 |
+| `oc.getParent(node)` | 已渲染 `.node`。 | 回傳父 `.node`，不存在時回傳 `null`。 |
+| `oc.getChildren(node)`<br>`oc.getSiblings(node)` | 已渲染 `.node`。 | 回傳直接子節點或兄弟節點 `.node` 元素陣列。 |
+| `oc.getRelatedNodes(node, relation)` | 已渲染 `.node`；`relation` 為 `parent`、`children` 或 `siblings`。 | 通用關聯查詢；parent 回傳節點或 `null`，其他關係回傳陣列。 |
+| `oc.hideParent(node)` / `oc.showParent(node)`<br>`oc.hideChildren(node)` / `oc.showChildren(node)` | 已渲染 `.node`。 | 透過圖表過渡隱藏或顯示關聯分支；無回傳值。 |
+| `oc.hideSiblings(node, direction)`<br>`oc.showSiblings(node, direction)` | 已渲染 `.node`；可選 `direction` 為 `left` 或 `right`。 | 隱藏或顯示指定一側的兄弟節點；省略方向時處理全部兄弟節點；無回傳值。 |
+| `oc.setChartScale(chart, multiplier, zoomAnchor)` | 通常傳入 `oc.chart`；正數的相對縮放倍數；可選視口座標 `{ x, y }`。 | 在配置的縮放範圍內縮放，提供 `zoomAnchor` 時固定該點。 |
+| `oc.export(filename, extension)` | 可選檔案名稱和 `png` 或 `pdf` 副檔名。 | 按配置預設值開始匯出；無法匯出時回傳 `false`。 |
+| `oc.exportPNG(canvas, filename)`<br>`oc.exportPDF(canvas, filename, exportScale)` | 已準備的 canvas、檔案名稱；PDF 縮放預設 `1`。 | 將傳入 canvas 直接下載為 PNG 或 PDF；通常應呼叫 `export()`。 |
 
 #### init(newOptions)
 當你想基于新的options或數據源刷新組織結構圖時，這個方法就派上用場了。
 
+#### setOptions(options) / setOptions(name, value)
+無需重新建立圖表即可更新 `pan`、`zoom`、`minimap`、縮放上下限，以及匯出的解析度倍數、檔案名稱和副檔名。其他選項會重建圖表。可傳入部分選項物件，或選項名稱及對應值。後續 `init()` 呼叫會保留這些變更，圖示預設值逐欄位合併。重建後應重新取得節點元素。
+
+#### attachMinimap() / detachMinimap()
+建立或移除目前圖表的小地圖覆蓋層。通常應使用 `setOptions('minimap', true|false)`，以確保選項狀態和覆蓋層保持同步。
+
+#### updateMinimap(forceRefresh)
+在修改圖表變換或版面配置後重新計算小地圖視口。傳入 `true` 會重繪小地圖中的節點預覽。
+
 #### addAncestors(data, parentId)
 爲當前的組織結構圖增加祖先節點，可以不止壹個層級。
 <table>
@@ -452,7 +547,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tbody>
 </table>
 
-#### addDescendants(data, $parent)
+#### addDescendants(data, parent)
 爲指定的父節點增加後代節點。
 <table>
   <thead>
@@ -473,8 +568,8 @@ var oc = $('#chartContainerId').orgchart(options);
       <td>用于構造後代節點的數據源</td>
     </tr>
     <tr>
-      <td>$parent</td>
-      <td>jquery object</td>
+      <td>parent</td>
+      <td>HTMLElement</td>
       <td>yes</td>
       <td></td>
       <td>後代節點要追加到的父節點對象</td>
@@ -482,7 +577,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tbody>
 </table>
 
-#### addParent(data)
+#### addParent(currentRoot, data)
 爲當前的組織結構圖增加父節點。
 <table>
   <thead>
@@ -495,6 +590,13 @@ var oc = $('#chartContainerId').orgchart(options);
     </tr>
   </thead>
   <tbody>
+    <tr>
+      <td>currentRoot</td>
+      <td>HTMLElement</td>
+      <td>是</td>
+      <td></td>
+      <td>當前組織結構圖的根節點，新父節點會包裹這個根節點</td>
+    </tr>
     <tr>
       <td>data</td>
       <td>json object</td>
@@ -505,7 +607,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tbody>
 </table>
 
-#### addSiblings($node, data)
+#### addSiblings(node, data)
 爲指定的節點增加兄弟節點。
 <table>
   <thead>
@@ -519,8 +621,8 @@ var oc = $('#chartContainerId').orgchart(options);
   </thead>
   <tbody>
     <tr>
-      <td>$node</td>
-      <td>jquery object</td>
+      <td>node</td>
+      <td>HTMLElement</td>
       <td>是</td>
       <td></td>
       <td>基于該節點增加其兄弟節點</td>
@@ -535,7 +637,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tbody>
 </table>
 
-#### addChildren($node, data)
+#### addChildren(node, data)
 爲指定的節點增加孩子節點。
 <table>
   <thead>
@@ -549,8 +651,8 @@ var oc = $('#chartContainerId').orgchart(options);
   </thead>
   <tbody>
     <tr>
-      <td>$node</td>
-      <td>jquery object</td>
+      <td>node</td>
+      <td>HTMLElement</td>
       <td>是</td>
       <td></td>
       <td>基于該節點增加其孩子節點</td>
@@ -565,7 +667,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tbody>
 </table>
 
-#### removeNodes($node）
+#### removeNodes(node)
 刪除指定的節點及其後代節點。
 <table>
   <thead>
@@ -579,8 +681,8 @@ var oc = $('#chartContainerId').orgchart(options);
   </thead>
   <tbody>
     <tr>
-      <td>$node</td>
-      <td>jquery object</td>
+      <td>node</td>
+      <td>HTMLElement</td>
       <td>是</td>
       <td></td>
       <td>待刪除的節點。</td>
@@ -608,7 +710,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tr>
 </table>
 
-#### hideParent($node)
+#### hideParent(node)
 隱藏指定節點的父節點。當然其兄弟節點及祖先節點也一並隱藏了。
 <table>
   <tr>
@@ -619,15 +721,15 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>Yes</td>
     <td>None</td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
 </table>
 
-#### showParent($node)
+#### showParent(node)
 顯示指定節點的父節點。但不包括更上一層的祖先節點。
 
 <table>
@@ -639,15 +741,15 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
 </table>
 
-#### hideChildren($node)
+#### hideChildren(node)
 隱藏指定節點的孩子節點。當然這其中包含了所有的後代節點。
 
 <table>
@@ -659,15 +761,15 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
 </table>
 
-#### showChildren($node)
+#### showChildren(node)
 顯示指定節點的孩子節點。默認只顯示緊鄰的下一個層級，並不包括所有的後代節點。
 
 <table>
@@ -679,15 +781,15 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
 </table>
 
-#### hideSiblings($node, direction)
+#### hideSiblings(node, direction)
 隱藏指定節點的兄弟節點。
 
 <table>
@@ -699,11 +801,11 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
   <tr>
     <td>direction</td>
@@ -714,7 +816,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tr>
 </table>
 
-#### showSiblings($node, direction)
+#### showSiblings(node, direction)
 顯示指定節點的兄弟節點。
 
 <table>
@@ -726,11 +828,11 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>It's the desired JQuery Object to show its siblings nodes</td>
+    <td>指定節點元素。</td>
   </tr>
   <tr>
     <td>direction</td>
@@ -741,7 +843,7 @@ var oc = $('#chartContainerId').orgchart(options);
   </tr>
 </table>
 
-#### getNodeState($node, relation)
+#### getNodeState(node, relation)
 該方法幫你了解指定節點的相關節點的顯示狀況。
 
 <table>
@@ -753,11 +855,11 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
   <tr>
     <td>relation</td>
@@ -775,7 +877,7 @@ var oc = $('#chartContainerId').orgchart(options);
   "visible":true|false, // 標識相關節點當前是否可見
 }
 ```
-#### getRelatedNodes($node, relation)
+#### getRelatedNodes(node, relation)
 獲得指定節點的關聯節點。
 
 <table>
@@ -787,11 +889,11 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$node</td>
-    <td>JQuery Object</td>
+    <td>node</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td></td>
-    <td>指定節點的jquery對象。</td>
+    <td>指定節點元素。</td>
   </tr>
   <tr>
     <td>relation</td>
@@ -802,9 +904,20 @@ var oc = $('#chartContainerId').orgchart(options);
   </tr>
 </table>
 
-#### setChartScale($chart, newScale)
+#### getParent(node)
+回傳指定節點的父節點；如果不存在父節點，則回傳 `null`。
+
+#### getChildren(node)
+回傳指定節點的直接子節點陣列。回傳值中的每一項都是原生 `HTMLElement`。
+
+#### getSiblings(node)
+回傳指定節點的兄弟節點陣列。回傳值中的每一項都是原生 `HTMLElement`。
+
+#### setChartScale(chart, newScale, zoomAnchor)
 用這個方法可以幫你爲指定的組織結構圖設置新的scale系數。
 
+`zoomAnchor` 為可選參數，格式為視口座標 `{ x, y }`。提供該參數後，縮放時會固定該座標點。
+
 <table>
   <tr>
     <th>名稱</th>
@@ -814,8 +927,8 @@ var oc = $('#chartContainerId').orgchart(options);
     <th>描述</th>
   </tr>
   <tr>
-    <td>$chart</td>
-    <td>JQuery Object</td>
+    <td>chart</td>
+    <td>HTMLElement</td>
     <td>是</td>
     <td>None</td>
     <td>組織結構圖容器中的某一個圖。</td>
@@ -856,8 +969,22 @@ var oc = $('#chartContainerId').orgchart(options);
   </tr>
 </table>
 
+#### exportPNG(canvas, exportFilename)
+將準備好的 canvas 匯出為 PNG 下載。當應用程式自行提供 canvas 時可直接呼叫；大多數情境應使用 `export()`。
+
+#### exportPDF(canvas, exportFilename, exportScale)
+將準備好的 canvas 匯出為 PDF 下載。`exportScale` 是 canvas 的渲染縮放比例，用於保持 PDF 的邏輯尺寸；大多數情境應使用 `export()`。
+
 ### 事件
 
+OrgChart 會派發可冒泡的原生 `CustomEvent`。請使用 `addEventListener` 訂閱，事件參數位於 `event.detail`。
+
+```js
+oc.chart.addEventListener('nodedrop.orgchart', function (event) {
+  const { draggedNode, dragZone, dropZone } = event.detail;
+});
+```
+
 <table>
   <thead>
     <tr>
@@ -869,23 +996,28 @@ var oc = $('#chartContainerId').orgchart(options);
   <tbody>
     <tr>
       <td>nodedrop.orgchart</td>
-      <td>draggedNode, dragZone, dropZone</td>
-      <td>當你拖拽一個節點，然後在目前區域松放時，該事件被觸發。請參考實例 <a target="_blank" href="http://dabeng.github.io/OrgChart/drag-drop/">example drag & drop</a>。</td>
+      <td><code>event.detail</code>: draggedNode, dragZone, dropZone</td>
+      <td>在節點移動前於圖表元素上觸發。呼叫 <code>event.preventDefault()</code> 可取消本次拖放。</td>
+    </tr>
+    <tr>
+      <td>otherdropped.orgchart</td>
+      <td><code>event.detail</code>: draggedItem, dropZone</td>
+      <td>非 OrgChart 的可拖放項目被放到節點上時，於圖表元素上觸發。</td>
     </tr>
     <tr>
       <td>init.orgchart</td>
-      <td>chart</td>
-      <td>當組織結構圖初始化完成時，該事件觸發。在響應事件處理器中，你可以訪問到渲染出的任意節點。</td>
+      <td>無；<code>event.target</code> 為圖表元素</td>
+      <td>圖表渲染完成後觸發。</td>
     </tr>
     <tr>
       <td>show-[relation].orgchart</td>
       <td></td>
-      <td>在顯示指定節點的關聯節點時，觸發該事件。</td>
+      <td>關聯節點顯示時在該節點上觸發；<code>relation</code> 為 parent、children 或 siblings。</td>
     </tr>
     <tr>
       <td>hide-[relation].orgchart</td>
       <td></td>
-      <td>在隱藏指定節點的關聯節點時，觸發該事件。</td>
+      <td>關聯節點隱藏時在該節點上觸發；<code>relation</code> 為 parent、children 或 siblings。</td>
     </tr>
   </tbody>
 </table>
@@ -896,9 +1028,9 @@ var oc = $('#chartContainerId').orgchart(options);
 
 我們提供了一個CSS類"noncollapsable"，可以方便地完成這件事。
 ```js
-$('.orgchart').addClass('noncollapsable'); // 禁掉展開/折疊
+oc.chart.classList.add('noncollapsable'); // 禁掉展開/折疊
 
-$('.orgchart').removeClass('noncollapsable'); // 開啓展開/折疊
+oc.chart.classList.remove('noncollapsable'); // 開啓展開/折疊
 ```
 
 #### 爲啥根節點消失了，看不到了？