docs: zh guide

Author: phphe

docs/zh/v1/guide.md

@@ -22,7 +22,7 @@ yarn add he-tree-react
 
 此库支持两种结构的数据:
 
-- 扁平数据, 即一个一维数组. 类似与存储在数据库中的数据. 每项需要`id`, 父级 id, `null`代表没有父级. 扁平数据的顺序必须准确, 你需要在初始化数据时使用[`sortFlatData`](./api#sortflatdata)方法给数据排序.
+- 扁平数据, 即一个一维数组. 类似与存储在数据库中的数据. 每项需要`id`, 父级 id, `null`代表没有父级. 扁平数据的顺序必须跟树一样, 你可以在初始化数据时使用[`sortFlatData`](./api#sortflatdata)方法给数据排序.
   ```js
   [
     { id: 1, pid: null },
@@ -51,7 +51,7 @@ yarn add he-tree-react
 ## 没有组件
 
 此库没有导出组件,而是导出一个 hook `useHeTree`. 使用它返回的`renderHeTree`渲染树. 这样做的好处是除了`renderHeTree`,
-`useHeTree`还会返回一些内部状态和方法, 可以轻松的被使用.
+`useHeTree`还会返回一些内部状态和方法, 可以轻松的被获取.
 
 ```js
 import { useHeTree } from "he-tree-react";
@@ -64,7 +64,29 @@ export default function App() {
 }
 ```
 
-## 基础使用-平面数据
+## 选项
+
+`useHeTree`是主要使用的函数, 它的第一个参数是选项对象. 必须的选项有`data`, 必须两者中有一个的是`renderNode, renderNodeBox`. 其他重要选项是:
+
+- `dataType`, 表明数据类型. 可用值:
+  - `flat`, 默认. 扁平数据.
+  - `tree`, 树形数据.
+- `idKey, parentIdKey`, 默认值是`id`和`parent_id`. 使用扁平数据时需要. 虽然有默认值, 但还是建议写明更好.
+- `childrenKey`, 默认是`children`. 使用树形数据时需要. 虽然有默认值, 但还是建议写明更好.
+- `onChange`, 数据改变时调用的函数, 参数是新数据. 如果你的树不会改变则不需要.
+- `isFunctionReactive`, 布尔. 默认`false`. `useHeTree`选项中包含许多回调函数, 如`onChange, canDrop`. `isFunctionReactive`可用来控制是否监听这些回调函数的改变. 如果你的回调函数和`data`是同步改变的, 则不用启用此项. 否则你需要启用此项, 并且用 React 的`useCallback`或`useMemo`缓存你的所有回调函数以避免性能问题.
+
+[查看`useHeTree`的 API 文档以了解更多](api#usehetree).
+
+## 提示
+
+- `stat`, 单个节点的相关信息. 大部分回调函数的参数里有`stat`. [参考`Stat` API](api#stat).
+- `node`, 节点的数据. 通过`stat.node`可以获取节点数据.
+- `getStat`, 通过此函数可以获取`stat`, 唯一参数可以是`id, node, stat`. 此函数在`useHeTree`的返回对象中: `const {getStat} = useHeTree({...})`.
+- 下面的代码例子附带有运行效果. 这些例子可以直接复制使用. 注意其中的高亮行的代码.
+- 下面的代码例子使用`tsx`格式, 如果你需要`js`格式, 可以使用任意 ts js 在线转换器.
+
+## 基础使用-扁平数据
 
 <<< @/../src/pages/base_flat_data.tsx
 <DemoIframe url="/base_flat_data" />
@@ -73,3 +95,173 @@ export default function App() {
 
 <<< @/../src/pages/base_tree_data.tsx
 <DemoIframe url="/base_tree_data" />
+
+## 自定义拖拽触发元素
+
+给节点任意子元素添加`draggable`属性即可.
+
+<<< @/../src/pages/custom_drag_trigger_flat_data.tsx{14}
+<DemoIframe url="/custom_drag_trigger_flat_data" />
+
+## 节点 HTML 结构和样式
+
+节点 HTML 如下:
+
+```html
+<div
+  draggable="true"
+  data-key="1"
+  data-level="1"
+  data-node-box="true"
+  style="padding-left: 0px;"
+>
+  <div>Node</div>
+</div>
+```
+
+上面有两个 div. 使用`renderNode`选项控制内层 div 的渲染. 如: `renderNode: ({node}) => <div>{node.name}</div>`.
+
+外层节点被称为`nodeBox`, 不要修改它的`margin, padding-left, padding-right`, 不要给它的父元素设置`gap`. 如果你想控制`nodeBox`或拖拽占位节点的渲染, 可以使用`renderNodeBox`选项, 这将覆盖`renderNode`. 标准的`renderNodeBox`如下:
+
+```tsx{4-7,9}
+renderNodeBox: ({ stat, attrs, isPlaceholder }) => (
+  <div {...attrs}>
+    {isPlaceholder ? (
+      <div
+        className="he-tree-drag-placeholder"
+        style={{ minHeight: "20px", border: "1px dashed blue" }}
+      />
+    ) : (
+      <div>{/* node area */}</div>
+    )}
+  </div>
+);
+```
+
+第 4 到第 7 行是拖拽占位节点. 第 9 行是节点元素.
+
+## 自定义拖拽占位节点和 node box
+
+<<< @/../src/pages/customize_placeholder_and_node_box.tsx{13-19,23-39}
+<DemoIframe url="/customize_placeholder_and_node_box" />
+
+## 节点的展开与折叠
+
+- 使用选项`openIds`表明展开的节点.
+- 可通过`stat.open`获取该节点的`open`状态.
+- `useHeTree`返回的`allIds`包含所有节点的 id.
+- 此库导出了方法可以展开单个或多个节点的所有父级. 扁平数据: [`openParentsInFlatData`](api#openparentsinflatdata). 树形数据: [`openParentsInTreeData`](api#openparentsintreedata).
+
+<<< @/../src/pages/open_ids.tsx{1,9-16,22-24,29-32}
+<DemoIframe url="/open_ids" />
+此例子顶部 4 个按钮分别是: 展开全部, 折叠全部, 展开'Python'节点的所有父节点, 仅展开'Python'节点的所有父节点.
+
+## 节点的勾选
+
+- 使用选项`checkedIds`表明勾选的节点.
+- 可通过`stat.checked`获取该节点的`checked`状态.
+- 此库导出了方法可以获取单个或多个节点`checked`变动后的`checkedIds`. 扁平数据: [`updateCheckedInFlatData`](api#updatecheckedinflatdata). 树形数据: [`updateCheckedInTreeData](api#updatecheckedintreedata).
+  - 此方法对节点的`checked`的更新是级联的. 如果你不想级联更新, 使用你自己的逻辑替代.
+  - 此方法返回一个长度 2 的数组. 第一项是所有勾选的 id, 第二项是所有半选的 id. 如果不需要半选, 忽略第二项.
+  - 半选, 即同时有子节点被勾选或半选, 也有子节点未被勾选.
+
+<<< @/../src/pages/checked_ids.tsx{1,9-15,21-23,28-29}
+<DemoIframe url="/checked_ids" />
+
+## 控制是否可拖拽, 可放入
+
+使用以下选项控制:
+
+- [`canDrag`](api#candrag), 节点是否可拖拽.
+- [`canDrop`](api#candrop), 节点是否可放入.
+- [`canDropToRoot`](api#candroptoroot), 树根是否可放入.
+
+<<< @/../src/pages/draggable_droppable.tsx{16-18}
+<DemoIframe url="/draggable_droppable" />
+
+- 根节点不可放入.
+- `Technology`及子节点可以拖拽. `Science`及子节点不可以拖拽.
+- `Science`及子节点可以放入. `Technology`及子节点不可以放入.
+
+## 拖拽到节点上时打开节点
+
+使用以下选项控制:
+
+- [`dragOpen`](api#dragopen), 是否启用, 默认`false`.
+- [`dragOpenDelay`](api#dragopen), 延时, 默认 `600` 毫秒.
+- [`onDragOpen`](api#ondragopen), 打开节点时调用的函数.
+
+<<< @/../src/pages/dragopen.tsx
+<DemoIframe url="/dragopen" />
+
+## 更新数据
+
+由于 React 的不可变特性, 扁平数据和树形数据更新都很困难. 针对扁平数据, 此库提供了两个方法, 用以增加节点或删除节点. 如果你要进行更复杂的操作, 或者更新树形数据, 推荐你使用[`immer`](https://github.com/mweststrate/immer).
+::: code-group
+
+```sh [npm]
+npm install immer use-immer
+```
+
+```sh [pnpm]
+pnpm add immer use-immer
+```
+
+```sh [yarn]
+yarn add immer use-immer
+```
+
+:::
+
+## 使用内置方法更新扁平数据
+
+[`addToFlatData`](api#addtoflatdata): 增加节点. [`removeByIdInFlatData`](api#removebyidinflatdata): 删除节点.
+这两个方法都会改变原数据, 所以把原数据的复制传给它, 或者与`immer`一起使用.
+
+<<< @/../src/pages/update_data.tsx{3,12-22,33-34}
+<DemoIframe url="/update_data" />
+
+## 使用 immer 更新扁平数据
+
+注意, 这里使用了`useImmer`替代 React 的`useState`.
+
+<<< @/../src/pages/update_flat_data_with_immer.tsx{3,7,12,13-31,42-44}
+<DemoIframe url="/update_flat_data_with_immer" />
+
+## 使用 immer 更新树形数据
+
+注意, 这里使用了`useImmer`替代 React 的`useState`. `findTreeData`方法类似数组的`find`方法.
+
+<<< @/../src/pages/update_tree_data_with_immer.tsx{1,4,10-30,41-43}
+<DemoIframe url="/update_tree_data_with_immer" />
+
+## 从外部发起的拖拽
+
+相关选项:
+
+- [`onExternalDragOver`](api#onexternaldragover): 表明是否处理外部拖拽.
+- [`onExternalDrop`](api#onexternaldrop): 当外部拖拽放入树中时调用的回调函数.
+
+<<< @/../src/pages/external_drag.tsx{16-22,25}
+<DemoIframe url="/external_drag" />
+
+## 超大数据
+
+使用选项[`virtual`](api#virtual)启用虚拟列表功能. 记得给树设置可见区域高度.
+
+<<< @/../src/pages/virtual_list.tsx{23,30}
+<DemoIframe url="/virtual_list" />
+
+## 触摸 & 移动设备
+
+此库基于 HTML5 Drag and Drop API, 所以在支持 Drag and Drop API 的移动设备上能工作. 如果不支持, 可以尝试添加兼容 Drag and Drop API 的库.
+
+::: tip 注意
+触摸时, 用户需要触摸并等一会儿才能触发拖拽。
+:::
+
+## 其他
+
+- 选项 [`direction`](api#direction): 从右往左显示.
+- 选项 [`customDragImage`](api#customdragimage): 自定义 drag image.
+- 选项 [`rootId`](api#rootid): 使用扁平数据时, 顶级节点的父 id.

lib/HeTree.tsx

@@ -50,6 +50,7 @@ export const defaultProps = {
   dataType: 'flat' as 'tree' | 'flat',
   direction: 'ltr' as 'ltr' | 'rtl',
   rootId: null as Id | null,
+  virtual: false,
 }
 
 export interface HeTreeProps<T extends Record<string, any>> extends Partial<typeof defaultProps> {
@@ -648,7 +649,7 @@ export function useHeTree<T extends Record<string, any>>(
     }
     return (
       <div className={`he-tree ${options?.className || ''}`} style={options?.style} ref={rootRef} onDragOver={onDragOverRoot} onDrop={onDropToRoot} onDragEnd={onDragEndOnRoot}>
-        <VirtualList<Id> ref={virtualListRef} items={visibleIds} virtual={false} persistentIndices={persistentIndices}
+        <VirtualList<Id> ref={virtualListRef} items={visibleIds} virtual={props.virtual} persistentIndices={persistentIndices} style={{ height: '100%' }}
           renderItem={(id, index) => renderNodeBox({
             stat: getStat(id)!, attrs: attrsList[index], isPlaceholder: id === placeholderId
           })}

package.json

@@ -57,6 +57,7 @@
     "eslint": "^8.55.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-refresh": "^0.4.5",
+    "immer": "^10.0.3",
     "jsdom": "^24.0.0",
     "react-router-dom": "^6.22.2",
     "react-test-renderer": "^18.2.0",

pnpm-lock.yaml

@@ -21,6 +21,50 @@ export default function PageLayout(props: {}) {
       title: 'Base - Tree Data',
       path: '/base_tree_data',
     },
+    {
+      title: 'Custom Drag Trigger',
+      path: '/custom_drag_trigger_flat_data',
+    },
+    {
+      title: 'Open',
+      path: '/open_ids',
+    },
+    {
+      title: 'Checked',
+      path: '/checked_ids',
+    },
+    {
+      title: 'Update Data',
+      path: '/update_data',
+    },
+    {
+      title: 'Update Flat Data With Immer',
+      path: '/update_flat_data_with_immer',
+    },
+    {
+      title: 'Update Tree Data With Immer',
+      path: '/update_tree_data_with_immer',
+    },
+    {
+      title: 'Customize Placeholder and Node Box',
+      path: '/customize_placeholder_and_node_box',
+    },
+    {
+      title: 'Draggable & Droppable',
+      path: '/draggable_droppable'
+    },
+    {
+      title: 'Open Node when Drag over',
+      path: '/dragopen'
+    },
+    {
+      title: 'Drag and Drop to External',
+      path: '/external_drag'
+    },
+    {
+      title: 'Big Data with Virtual List',
+      path: '/virtual_list'
+    },
     {
       title: 'Home',
       path: '/',

src/PageLayout.tsx

@@ -11,7 +11,18 @@ import PageLayout from './PageLayout.tsx';
 const Pages = {
   home: lazy(() => import("./pages/index.tsx")),
   base_tree_data: lazy(() => import("./pages/base_tree_data.tsx")),
-  base_flat_data: lazy(() => import("./pages/base_flat_data.tsx"))
+  base_flat_data: lazy(() => import("./pages/base_flat_data.tsx")),
+  custom_drag_trigger_flat_data: lazy(() => import("./pages/custom_drag_trigger_flat_data.tsx")),
+  open_ids: lazy(() => import("./pages/open_ids.tsx")),
+  checked_ids: lazy(() => import("./pages/checked_ids.tsx")),
+  update_data: lazy(() => import("./pages/update_data.tsx")),
+  update_flat_data_with_immer: lazy(() => import("./pages/update_flat_data_with_immer.tsx")),
+  update_tree_data_with_immer: lazy(() => import("./pages/update_tree_data_with_immer.tsx")),
+  customize_placeholder_and_node_box: lazy(() => import("./pages/customize_placeholder_and_node_box.tsx")),
+  draggable_droppable: lazy(() => import("./pages/draggable_droppable.tsx")),
+  dragopen: lazy(() => import("./pages/dragopen.tsx")),
+  external_drag: lazy(() => import("./pages/external_drag.tsx")),
+  virtual_list: lazy(() => import("./pages/virtual_list.tsx")),
 }
 const router = createHashRouter([
   {
@@ -29,7 +40,51 @@ const router = createHashRouter([
       {
         path: "/base_flat_data",
         element: <Pages.base_flat_data />,
-      }
+      },
+      {
+        path: "/custom_drag_trigger_flat_data",
+        element: <Pages.custom_drag_trigger_flat_data />,
+      },
+      {
+        path: "/open_ids",
+        element: <Pages.open_ids />,
+      },
+      {
+        path: "/checked_ids",
+        element: <Pages.checked_ids />,
+      },
+      {
+        path: "/update_data",
+        element: <Pages.update_data />,
+      },
+      {
+        path: "/update_flat_data_with_immer",
+        element: <Pages.update_flat_data_with_immer />,
+      },
+      {
+        path: "/update_tree_data_with_immer",
+        element: <Pages.update_tree_data_with_immer />,
+      },
+      {
+        path: "/customize_placeholder_and_node_box",
+        element: <Pages.customize_placeholder_and_node_box />,
+      },
+      {
+        path: "/draggable_droppable",
+        element: <Pages.draggable_droppable />,
+      },
+      {
+        path: "/dragopen",
+        element: <Pages.dragopen />,
+      },
+      {
+        path: "/external_drag",
+        element: <Pages.external_drag />,
+      },
+      {
+        path: "/virtual_list",
+        element: <Pages.virtual_list />,
+      },
     ]
   },
 ]);