orgchart 6.0.0 → 7.0.0

package/.github/workflows/publish.yml

@@ -15,18 +15,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Authenticate with npm
-        run: npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build and test
+        run: npm run build
+
+      - name: Publish package
+        run: npm publish --access public --provenance
         env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        
-      - run: npm ci
-      
-      # 3. 直接运行 npm publish，无需任何令牌
-      - run: npm publish --access public --provenance 
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,4 +1,4 @@
-![OrgChart](http://dabeng.github.io/OrgChart/img/heading.png)
+![OrgChart](http://dabeng.github.io/OrgChart/img/cover.png)
 
 # [简体文档](https://github.com/dabeng/OrgChart/blob/master/README.zh-cn.md), [繁體文档](https://github.com/dabeng/OrgChart/blob/master/README.zh-tw.md)
 
@@ -55,6 +55,10 @@ FYI, [How to use jQuery Orchart in React](https://stackblitz.com/edit/vitejs-vit
 ## [Demos based on nested table](https://codepen.io/collection/AWxGVb/) (obsolete)
 
 ### online demos
+- [I want to render 10,000 nodes within 500 milliseconds](https://dabeng.github.io/OrgChart/10000-nodes.html)
+
+![10000-nodes](http://dabeng.github.io/OrgChart/img/10000-nodes.png)
+
 - [using ul datasource](https://dabeng.github.io/OrgChart/ul-datasource.html)(this feature comes from [Tobyee's good idea :blush:](https://github.com/dabeng/OrgChart/issues/1))
 
 - [using local datasource](https://dabeng.github.io/OrgChart/local-datasource.html)
@@ -79,7 +83,7 @@ FYI, [How to use jQuery Orchart in React](https://stackblitz.com/edit/vitejs-vit
 
 ![ondemand-loading-data](http://dabeng.github.io/OrgChart/img/ondemand-loading-data.gif)
 
-**Note:** users use should set the relationship property of datasource by themselves. All of these staff are used to generate the correct expanding/collapsing arrows for nodes.
+**Note:** the library manages expand/collapse controls only for loaded nodes. The demo creates separate request buttons and handles loading through application code; no relationship metadata or loading callback option is required.
 
 - [I wanna customize the structure of node](https://dabeng.github.io/OrgChart/option-createNode.html)
 
@@ -129,7 +133,7 @@ This feature is inspired by the issues([Aligning Children Vertical](https://gith
 
 From now on, users never have to worry about how to align a huge of nodes in one screen of browser. The option "verticalLevel" allows users to align child nodes vertically from the given level.
 
-**Note**: currently, this option is incompatible with many other options or methods, like direction, drag&drop, addChildren(), removeNodes(), getHierarchy() and so on. These conflicts will be solved one by one in the later versions.
+When combined with `compact`, `verticalLevel` determines the layout from its configured level onward. Direction, depth limits and drag/drop continue to use the actual node hierarchy.
 
 - [I want to collapse some nodes by default](https://dabeng.github.io/OrgChart/default-collapsed.html)
 
@@ -169,6 +173,10 @@ You need the solution based on new datasource structure with **levelOffset data
 
 **compact data property** is designed for your use case. Once node data includes a "compact" prop with truthy value, itself and its descendant nodes will be arranged with compact mode.
 
+Compact layouts support `draggable`, `visibleLevel`, direction, pan, zoom and minimap together. Use `compact: true` to compact every branch, or a callback to select dense branches. `drag` is an alias for `draggable`; when both are supplied, `draggable` takes precedence. Compact drag/drop and node editing may rebuild the chart, so reacquire rendered node elements afterward.
+
+Grouped family sources use the configured `nodeId` for every member and the same one-based depth as JSON and UL sources. Compact family children are arranged as household grids. Drag/drop and editing modify the selected member and its descendants, not its surrounding household; family mutations may rebuild rendered nodes. `getHierarchy()` preserves grouped family arrays, and related-node queries include all members with the same chart parent.
+
 - [ I want to visualize genealogy/pedigree/family tree information](https://dabeng.github.io/OrgChart/family-tree.html)
 
 ![family-tree](http://dabeng.github.io/OrgChart/img/family-tree.png)
@@ -249,27 +257,24 @@ var oc = new OrgChart({
   // which will be used as className attribute of node.
   'nodeTitle': 'name', // This property is used to retrieve “title” value in datasource
   'nodeContent': 'title',// This property is used to retrieve "content" value in datasource
-  'relationship': relationshipValue, // Note: when you activate ondemand loading nodes feature,
-  // you should use json datsource (local or remote) and set this property.
-  // This property implies that whether this node has parent, siblings, children.
-  // relationshipValue is a string composed of three "0/1" identifier.
-  // First character stands for wether current node has parent node;
-  // Scond character stands for wether current node has siblings nodes;
-  // Third character stands for wether current node has children node.
   '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 // feel free to append any useful properties
 };
 ```
 
+Node relations are derived from the current loaded structure. Expand/collapse and compact-layout controls are created when a node is hovered, focused, or selected by touch, and removed when interaction ends. A control involved in loading is retained until loading finishes. Keyboard users can focus a node and activate its controls with Enter or Space.
+
+The `createNode` callback runs without prebuilt interaction controls; customize icons through `icons` rather than querying initial arrow elements. For on-demand loading, create application-owned request buttons through `createNode` and handle requests with event delegation. Keep their behavior selectors separate from built-in controls, then insert loaded nodes with `addAncestors()`, `addChildren()`, or `addDescendants()`. `getNodeState()` describes loaded relations, not data that may exist on a server. The former relationship field and relation-preprocessing method are no longer supported.
+
 ### Data Props
 <table>
   <thead>
@@ -307,10 +312,10 @@ var oc = new OrgChart({
   <tbody>
     <tr>
       <td>data</td>
-      <td>json or HTMLUListElement</td>
+      <td>object / array / HTMLUListElement</td>
       <td>yes</td>
       <td></td>
-      <td>datasource used to build out structure of orgchart. It can be a json object or an HTML ul element.</td>
+      <td>Datasource: a JSON tree object, grouped family-tree arrays, or an HTML ul element. UL data is normalized internally so later option changes retain edits.</td>
     </tr>
     <tr>
       <td>pan</td>
@@ -326,19 +331,26 @@ var oc = new OrgChart({
       <td>false</td>
       <td>Users could zoomin/zoomout the orgchart by mouse wheel if they enable this option.</td>
     </tr>
+    <tr>
+      <td>minimap</td>
+      <td>boolean</td>
+      <td>no</td>
+      <td>false</td>
+      <td>Displays an overview navigator. Drag its viewport to move the chart, or use the wheel over the minimap to zoom. Minimap wheel zoom remains available when zoom is false.</td>
+    </tr>
     <tr>
       <td>zoominLimit</td>
       <td>number</td>
       <td>no</td>
       <td>7</td>
-      <td>Users are allowed to set a zoom-in limit.</td>
+      <td>Inclusive maximum scale. Zoom steps are clamped to this bound. Limits must be finite, positive, and ordered.</td>
     </tr>
     <tr>
       <td>zoomoutLimit</td>
       <td>number</td>
       <td>no</td>
       <td>0.5</td>
-      <td>Users are allowed to set a zoom-out limit.</td>
+      <td>Inclusive minimum scale. It must not exceed zoominLimit. Invalid limits throw a RangeError before the chart is replaced.</td>
     </tr>
     <tr>
       <td>direction</td>
@@ -363,10 +375,10 @@ var oc = new OrgChart({
     </tr>
     <tr>
       <td>visibleLevel</td>
-      <td>positive integer</td>
+      <td>nonnegative integer or boolean</td>
       <td>no</td>
       <td>999</td>
-      <td>It indicates the level that at the very beginning orgchart is expanded to.</td>
+      <td>It indicates the initially expanded depth. true uses the default depth (999); false shows the first level; 0 hides all initial nodes. Deeper branches can be expanded later.</td>
     </tr>
     <tr>
       <td>nodeTitle</td>
@@ -375,13 +387,6 @@ var oc = new OrgChart({
       <td>"name"</td>
       <td>It sets one property of datasource as text content of title section of orgchart node. In fact, users can create a simple orghcart with only nodeTitle option.</td>
     </tr>
-    <tr>
-      <td>parentNodeSymbol</td>
-      <td>string</td>
-      <td>no</td>
-      <td>"oci-menu"</td>
-      <td>Using your own icon to imply that the node has child nodes.</td>
-    </tr>
     <tr>
       <td>nodeContent</td>
       <td>string</td>
@@ -428,7 +433,7 @@ var oc = new OrgChart({
       <td>exportFilename</td>
       <td>string</td>
       <td>no</td>
-      <td>"Orgchart"</td>
+      <td>"OrgChart"</td>
       <td>It's filename when you export current orgchart as a picture.</td>
     </tr>
     <tr>
@@ -438,6 +443,13 @@ var oc = new OrgChart({
       <td>"png"</td>
       <td>Available values are png and pdf.</td>
     </tr>
+    <tr>
+      <td>exportScale</td>
+      <td>number</td>
+      <td>no</td>
+      <td>2</td>
+      <td>Canvas resolution multiplier for PNG and PDF exports; PDF pages retain the chart's logical dimensions. Nonpositive values fall back to 1.</td>
+    </tr>
     <tr>
       <td>chartClass</td>
       <td>string</td>
@@ -471,7 +483,7 @@ var oc = new OrgChart({
       <td>json</td>
       <td>no</td>
       <td></td>
-      <td>Users can use this option to plug Font Awesome icons back in.
+      <td>Users can use this option to plug Font Awesome icons back in. Partial icon objects are merged with the defaults by field. Set icons.parentNode to customize the parent-node symbol.
         <pre>
           <code>
 'icons': {
@@ -490,10 +502,10 @@ var oc = new OrgChart({
     </tr>
     <tr>
       <td>compact</td>
-      <td>function</td>
+      <td>boolean or function</td>
       <td>no</td>
       <td></td>
-      <td>This callback is used to determine current node is wether rendered with compact mode. The node's data is passed in as a parameter. <b>Note:</b>The option "compact" has a higher priority than data prop "compact".</td>
+      <td>true compacts every branch; a callback receiving node data selects additional compact branches. Explicit compact data properties are preserved. Vertical/hybrid layout takes precedence at nodes where it applies.</td>
     </tr>
   </tbody>
 </table>
@@ -511,14 +523,14 @@ The public API is: `init`, `setOptions`, `attachMinimap`, `detachMinimap`, `upda
 | Call | Parameters | Return value and behavior |
 | --- | --- | --- |
 | `oc.init(options)` | Partial options object; use `data` to replace the data source. | Rebuilds the chart and returns `oc`. |
-| `oc.setOptions(options)`<br>`oc.setOptions(name, value)` | Object containing `data`, `pan`, `zoom`, or `minimap`; or one of the supported names with a boolean value. | Rebuilds for `data`; toggles pan, zoom, or minimap otherwise; returns `oc`. |
+| `oc.setOptions(options)`<br>`oc.setOptions(name, value)` | Partial options object, or an option name and value. | Applies navigation/export settings in place; rebuilds for data, layout or node-rendering settings; returns `oc`. |
 | `oc.attachMinimap()`<br>`oc.detachMinimap()`<br>`oc.updateMinimap(forceRefresh)` | `forceRefresh` is optional; `true` redraws preview nodes. | Creates, removes, or refreshes the minimap. Prefer `setOptions('minimap', value)` for normal enablement. |
 | `oc.addAncestors(data, parentId)` | Ancestor data and the id of the ancestor node that receives the existing root. | Inserts ancestor hierarchy; no return value. |
 | `oc.addDescendants(data, parent)` | Array of descendant data and a rendered parent `.node`. | Appends descendant hierarchy; no return value. |
 | `oc.addParent(currentRoot, data)` | Rendered root `.node` and its new parent data. | Wraps the current root with a parent; no return value. |
 | `oc.addSiblings(node, data)`<br>`oc.addChildren(node, data)` | Rendered `.node` and an array of sibling or child data. | Adds rendered nodes; no return value. |
 | `oc.removeNodes(node)` | Rendered `.node` to remove. | Removes the node and its descendants; no return value. |
-| `oc.getHierarchy(includeNodeData)` | Optional boolean, default `false`. | Returns the hierarchy object; returns an error string when the chart or required node ids are unavailable. |
+| `oc.getHierarchy(includeNodeData)` | Optional boolean, default `false`. | Returns a hierarchy object for tree sources or grouped arrays for family sources; returns an error string when the chart or required node ids are unavailable. |
 | `oc.getNodeState(node, relation)` | Rendered `.node`; `relation` is `parent`, `children`, or `siblings`. | Returns `{ exist, visible }`. |
 | `oc.getParent(node)` | Rendered `.node`. | Returns its parent `.node`, or `null`. |
 | `oc.getChildren(node)`<br>`oc.getSiblings(node)` | Rendered `.node`. | Returns an array of direct child or sibling `.node` elements. |
@@ -533,7 +545,7 @@ The public API is: `init`, `setOptions`, `attachMinimap`, `detachMinimap`, `upda
 It's the useful way when users want to re-initialize or refresh orgchart based on new options or reload new data.
 
 #### setOptions(options) / setOptions(name, value)
-Updates `pan`, `zoom`, or `minimap` without rebuilding the chart. Pass an options object, or a supported option name and boolean value. Passing an object containing `data` rebuilds the chart.
+Updates `pan`, `zoom`, `minimap`, zoom limits and export scale/filename/extension without rebuilding the chart. Other options rebuild the chart. Pass a partial options object, or an option name and value. Changes are retained by later `init()` calls; icon defaults are merged field by field. Reacquire node elements after a rebuild.
 
 #### attachMinimap() / detachMinimap()
 Creates or removes the minimap overlay for the current chart. Usually use `setOptions('minimap', true|false)` so the option state and overlay stay synchronized.

package/README.zh-cn.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-tw.md), [English](https://github.com/dabeng/OrgChart/blob/master/README.md)
 
@@ -52,6 +52,10 @@ $ npm install orgchart
 ## [基于嵌套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)
@@ -114,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'`。
@@ -152,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)
@@ -233,28 +243,25 @@ var oc = new OrgChart({
   // 来检索数据源，然后渲染默认结构样式的节点的上半部分
   '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>
@@ -269,10 +276,10 @@ var oc = new OrgChart({
   <tbody>
     <tr>
       <td>data</td>
-      <td>json / HTMLUListElement</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>
@@ -288,19 +295,26 @@ var oc = new OrgChart({
       <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>
@@ -325,10 +339,10 @@ var oc = new OrgChart({
     </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>
@@ -337,13 +351,6 @@ var oc = new OrgChart({
       <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>
@@ -390,7 +397,7 @@ var oc = new OrgChart({
       <td>exportFilename</td>
       <td>string</td>
       <td>否</td>
-      <td>"Orgchart"</td>
+      <td>"OrgChart"</td>
       <td>导出文件的文件名。</td>
     </tr>
     <tr>
@@ -400,6 +407,13 @@ var oc = new OrgChart({
       <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>
@@ -428,6 +442,35 @@ var oc = new OrgChart({
       <td></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>
 
@@ -444,14 +487,14 @@ const oc = new OrgChart({ chartContainer: '#chartContainerId', data: datasource
 | 调用 | 参数 | 返回值与调用行为 |
 | --- | --- | --- |
 | `oc.init(options)` | 部分选项对象；传入 `data` 可替换数据源。 | 重新构建图表并返回 `oc`。 |
-| `oc.setOptions(options)`<br>`oc.setOptions(name, value)` | 包含 `data`、`pan`、`zoom` 或 `minimap` 的对象；或受支持的选项名称及布尔值。 | `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.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` 元素数组。 |
@@ -466,7 +509,7 @@ const oc = new OrgChart({ chartContainer: '#chartContainerId', data: datasource
 当你想基于新的options或数据源刷新组织结构图时，这个方法就派上用场了。
 
 #### setOptions(options) / setOptions(name, value)
-无需重新构建图表即可更新 `pan`、`zoom` 或 `minimap`。可传入选项对象，或传入支持的选项名称和布尔值；传入包含 `data` 的对象时会重新构建图表。
+无需重新构建图表即可更新 `pan`、`zoom`、`minimap`、缩放上下限，以及导出的分辨率倍数、文件名和扩展名。其他选项会重建图表。可传入部分选项对象，或选项名称及对应值。后续 `init()` 调用会保留这些变更，图标默认值逐字段合并。重建后应重新查询节点元素。
 
 #### attachMinimap() / detachMinimap()
 创建或移除当前图表的小地图覆盖层。通常应使用 `setOptions('minimap', true|false)`，以保证选项状态和覆盖层保持同步。