Skip to content

Commit 333a46a

Browse files
phphephphe
committed
docs: en
1 parent cda325c commit 333a46a

File tree

3 files changed

+610
-6
lines changed

3 files changed

+610
-6
lines changed

‎docs/v1/api.md

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# API
2+
3+
## Exported
4+
5+
The exported variables, methods, and Typescript types.
6+
7+
- [`useHeTree`](#usehetree): Main React hook. This library does not export components, you need to use the [`renderTree`](#rendertree) render tree returned by this function.
8+
- [`walkTreeData`](#walktreedata), [`walkTreeDataGenerator`](#walktreedatagenerator), [`findTreeData`](#findtreedata), [`filterTreeData`](#filtertreedata), [`openParentsInTreeData`](#openparentsintreedata), [`updateCheckedInTreeData`](#updatecheckedintreedata): Methods for processing and traversing tree data.
9+
- [`sortFlatData`](#sortflatdata), [`walkFlatData`](#walkflatdata), [`walkFlatDataGenerator`](#walkflatdatagenerator), [`convertIndexToTreeIndexInFlatData`](#convertindextotreeindexinflatdata), [`addToFlatData`](#addtoflatdata), [`removeByIdInFlatData`](#removebyidinflatdata), [`openParentsInFlatData`](#openparentsinflatdata), [`updateCheckedInFlatData`](#updatecheckedinflatdata): Methods for processing and traversing flat data.
10+
- [`walkParentsGenerator`](#walkparentsgenerator): To iterate over another special kind of data. This data is like `HTMLElement`, which contains a key pointing to the parent node like `parentElement`.
11+
- `defaultProps`: The default value of `useHeTree` options.
12+
13+
Typescript types:
14+
15+
- `Id`: node id, parent id. Type: `string | number`.
16+
- [`Stat`](#stat): Node information.
17+
- `HeTreeProps`: Options for `useHeTree`.
18+
19+
## useHeTree
20+
21+
```ts
22+
import { useHeTree } from "he-tree-react";
23+
const {/* return */} = useHeTree({/* options */}) // prettier-ignore
24+
```
25+
26+
The main function of this library. React hook. The arguments are as follows:
27+
28+
- options: Options, type is object. The following are some properties in options:
29+
30+
| Name | Type | Default | Description |
31+
| ---------------------------------------------- | ----------------------- | ----------- | :------------------------------------------------------------------------------------------------------------------- |
32+
| data<a id="data"/> | Array | | Data. Check [Data Types](guide#data-types). |
33+
| dataType<a id="datatype"/> | 'flat', 'tree' | 'flat' | Data Types |
34+
| idKey<a id="idkey"/> | string | 'id' | key of id 名. |
35+
| parentIdKey<a id="parentidkey"/> | string | 'parent_id' | key of the parent id. For flat data only. |
36+
| childrenKey<a id="childrenkey"/> | string | 'children' | key of children nodes. For tree data only. |
37+
| indent<a id="indent"/> | number | 20 | Node indentation, unit is px. |
38+
| dragOpen<a id="dragopen"/> | boolean | false | Whether to enable the function "Open node when dragging over node". |
39+
| dragOpenDelay<a id="dragopendelay"/> | number | 600 | The waiting time to open the node when dragging over the node. The unit is milliseconds. |
40+
| onDragOpen<a id="ondragopen"/> | `function(stat): void` | | The callback of "Open node when dragging over node". |
41+
| direction<a id="direction"/> | 'lrt', 'rtl' | 'ltr' | Display direction, ltr is displayed from left to right, rtl is the opposite. |
42+
| rootId<a id="rootid"/> | string, null | null | The parent id of a node that has not parent in flat data. |
43+
| virtual<a id="virtual"/> | boolean | false | Whether to enable virtualization. Used to improve performance when there is a lot of data. |
44+
| keepPlaceholder<a id="keepplaceholder"/> | boolean | false | Whether to retain placeholder when dragging out of the tree. It is recommended to enable this only on one tree page. |
45+
| openIds<a id="openids"/> | Array | | All open nodes' id. |
46+
| checkedIds<a id="checkedids"/> | Array | | All checked nodes' id. |
47+
| isFunctionReactive<a id="isfunctionreactive"/> | boolean | false | Whether to listen for change of the callback functions. [Reference](guide#isfunctionreactive) |
48+
49+
The remaining callback functions in options:
50+
| Name | Type | Description |
51+
| ------------------------- | ------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------|
52+
| renderNode<a id="rendernode"/> | `(stat)=> ReactNode` | Node render. |
53+
| renderNodeBox<a id="rendernodebox"/> | `({stat, attrs, isPlaceholder})=> ReactNode` | nodeBox's render. [Reference](guide#node_structure_style). |
54+
| onChange<a id="onchange"/>| `(newData)=>void`|Callback on data change|
55+
| canDrag<a id="candrag"/> | `(stat)=>boolean, null, undefined, void` | Whether a node draggable. Returning `null, undefined, void` means inheriting the parent node. |
56+
| canDrop<a id="candrop"/> | `(stat, index)=>boolean, null, undefined, void` | Whether a node droppable. Returning `null, undefined, void` means inheriting the parent node. The parameter `index` may be empty. If it is not empty, it indicates the position. |
57+
| customDragImage<a id="customdragimage"/> | `(event, stat)=> void` | Called `event.dataTransfer.setDragImage` to custom drag image. [Reference](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/setDragImage). |
58+
|onDragStart<a id="ondragstart"/>| `(event, stat)=> void` ||
59+
|onExternalDragOver<a id="onexternaldragover"/>|`(event)=>boolean`|Called when drag from external. Must return a Boolean value to indicate whether to handle this drag.|
60+
|onDragOver<a id="ondragover"/>| `(event, stat, isExternal)=> void` |`isExternal` indicates whether the drag is from outside.|
61+
|onDragEnd<a id="ondragend"/>|`(event, stat, isOutside)=>void`|Called on dragend and this drag is started in this tree. `stat` is the stat of the dragged node. `isOutside` indicates whether it ended outside the tree.|
62+
|onExternalDrop<a id="onexternaldrop"/>|`(event, parentStat, index)=>void`|Called when the external drag ends on this tree. parentStat is the stat of the target parent node, and when it is empty, it represents the root of the tree. Index is the target position, the index of the node among siblings.|
63+
64+
The return of `useHeTree` is an object, including some states and methods. **Note**, this object will change every time. Do not rely on this object, but you can rely on the properties of this object. The properties are as follows:
65+
| Name | Type | Description |
66+
| ------------------------- | ------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------|
67+
|renderHeTree<a id="renderhetree"/>|`(options?: { className?: string, style?: React.CSSProperties }): ReactNode`|Tree render. Options can be passed in `className` and `style` to control the style of the root element.|
68+
|getStat<a id="getstat"/>|`(idOrNodeOrStat)=>stat`|Get stat by id, or node data, or stat object.|
69+
|allIds<a id="allids"/>|Array|The ids of all nodes.|
70+
|rootIds<a id="rootids"/>|Array|The ids of all root nodes|
71+
|rootNodes<a id="rootnodes"/>|Array|All root nodes. In tree data, it is same with `options.data`.|
72+
|rootStats<a id="rootstats"/>|Array|All root nodes' stat.|
73+
|placeholder<a id="placeholder"/>|`{parentStat, index, level}`| Drag placeholder info. Null if it does not exist.|
74+
|draggingStat<a id="draggingstat"/>|`stat`|When a drag is initiated from this tree, the stat of the dragged node. Null if it does not exist.|
75+
|dragOverStat<a id="dragoverstat"/>|`stat`|Dragging over node's stat. May be null.|
76+
|visibleIds<a id="visibleids"/>|Array|All visible nodes' id.|
77+
|attrsList<a id="attrslist"/>|Array|All visible nodes' attrs.|
78+
|virtualListRef<a id="virtuallistref"/>|`ref`| `ref` of virtual list component, Check [virtual list](https://github.com/phphe/react-base-virtual-list).|
79+
80+
## walkTreeDataGenerator
81+
82+
The method of traversing tree data through `for of`. Executing `skipChildren()` in the loop will skip all child nodes of the node, and executing `exitWalk` will end the traversal.
83+
84+
```ts
85+
for (const [
86+
node,
87+
{ parent, parents, siblings, index, skipChildren, exitWalk },
88+
] of walkTreeDataGenerator(data, "children")) {
89+
// ...
90+
}
91+
```
92+
93+
## walkTreeData
94+
95+
The method to traverse tree data through the callback method. Executing `skipChildren()` in the callback method will skip all child nodes of the node, and executing `exitWalk` will end the traversal.
96+
97+
```ts
98+
walkTreeDataGenerator(
99+
data,
100+
(node, { parent, parents, siblings, index, skipChildren, exitWalk }) => {
101+
// ...
102+
},
103+
"children"
104+
);
105+
```
106+
107+
## findTreeData
108+
109+
Like `Array.prototype.find`. Returns the first node found. Executing `skipChildren()` in the callback method will skip all child nodes of the node, and executing `exitWalk` will end the traversal.
110+
111+
```ts
112+
let foundNode = findTreeData(
113+
data,
114+
(node, { parent, parents, siblings, index, skipChildren, exitWalk }) => {
115+
// return node.id === 1;
116+
},
117+
"children"
118+
);
119+
```
120+
121+
## filterTreeData
122+
123+
Like `Array.prototype.filter`. Returns all nodes found. Executing `skipChildren()` in the callback method will skip all child nodes of the node, and executing `exitWalk` will end the traversal.
124+
125+
```ts
126+
let nodes = filterTreeData(
127+
data,
128+
(node, { parent, parents, siblings, index, skipChildren, exitWalk }) => {
129+
// return node.id > 1;
130+
},
131+
"children"
132+
);
133+
```
134+
135+
## openParentsInTreeData
136+
137+
Open all parent nodes of a single or multiple nodes to make the node visible. [Reference](guide#node_open).
138+
139+
```
140+
(
141+
treeData,
142+
openIds: Id[],
143+
idOrIds: Id | Id[],
144+
options?: {idKey: string, childrenKey: string}
145+
): newOpenIds
146+
```
147+
148+
## updateCheckedInTreeData
149+
150+
Update the `checked` status of a single node or multiple nodes. This will update both their children and parents. [Reference](guide#node_checked).
151+
152+
```
153+
(
154+
treeData,
155+
checkedIds: Id[],
156+
idOrIds: Id | Id[],
157+
checked: boolean,
158+
options?: {idKey: string, childrenKey: string}
159+
): [newCheckedIds, newSemiCheckedIds]
160+
```
161+
162+
## sortFlatData
163+
164+
Sort the flat data according to the order of the nodes in the tree. Return the new sorted array. Your data should use it to ensure order after initialized.
165+
166+
```
167+
(
168+
flatData,
169+
options?: {idKey: string, parentIdKey: string}
170+
): sortedData
171+
```
172+
173+
## walkFlatDataGenerator
174+
175+
The method of traversing flat data through `for of`. Executing `skipChildren()` in the loop will skip all the child nodes of the node, and executing `exitWalk` will end the traversal. Make sure the order of your data is correct before using it.
176+
177+
Compared to walkTreeDataGenerator, it lacks `siblings`, but has `treeIndex, id, pid`. treeIndex is the index of the node in the tree.
178+
179+
```ts
180+
for (const [
181+
node,
182+
{ parent, parents, index, treeIndex, id, pid, skipChildren, exitWalk },
183+
] of walkFlatDataGenerator(flatData, {
184+
idKey: "id",
185+
parentIdKey: "parent_id",
186+
})) {
187+
// ...
188+
}
189+
```
190+
191+
## walkFlatData
192+
193+
The method of traversing flat data through the callback method. Executing `skipChildren()` in the callback method will skip all child nodes of the node, and executing `exitWalk` will end the traversal. Before using, make sure that the order of your data is correct.
194+
195+
```ts
196+
walkFlatData(
197+
flatData,
198+
(
199+
node,
200+
{ parent, parents, index, treeIndex, id, pid, skipChildren, exitWalk }
201+
) => {
202+
// ...
203+
},
204+
{
205+
idKey: "id",
206+
parentIdKey: "parent_id",
207+
}
208+
);
209+
```
210+
211+
## openParentsInFlatData
212+
213+
Open all parent nodes of a single or multiple nodes to make the node visible. Make sure your data is in the correct order before using it. [Reference](guide#node_open).
214+
215+
```
216+
(
217+
flatData,
218+
openIds: Id[],
219+
idOrIds: Id | Id[],
220+
options?: {
221+
idKey: "id",
222+
parentIdKey: "parent_id",
223+
}
224+
): newOpenIds
225+
```
226+
227+
## updateCheckedInFlatData
228+
229+
Update the `checked` status of a single node or multiple nodes. This will update both their children and parents. Make sure your data is in the correct order before using it. [Reference](guide#node_checked).
230+
231+
```
232+
(
233+
flatData,
234+
checkedIds: Id[],
235+
idOrIds: Id | Id[],
236+
checked: boolean,
237+
options?: {
238+
idKey: "id",
239+
parentIdKey: "parent_id",
240+
}
241+
): [newCheckedIds, newSemiCheckedIds]
242+
```
243+
244+
## convertIndexToTreeIndexInFlatData
245+
246+
Calculate the index of a node in the tree through its parent node id and its index in the sibling nodes.
247+
248+
```
249+
(
250+
flatData,
251+
parentId: Id | null,
252+
indexInSiblings: Id | null,
253+
options?: {
254+
idKey: "id",
255+
parentIdKey: "parent_id",
256+
}
257+
): treeIndex
258+
```
259+
260+
## addToFlatData
261+
262+
Add a node to the flat data. It will change the original data array. Therefore, it is recommended to pass in a copy of the original data, or use it together with `useImmer`. [Reference](guide#update_flat_data_with_inner_methods2)
263+
264+
```
265+
(
266+
flatData,
267+
newNode,
268+
index: Id | null,
269+
options?: {
270+
idKey: "id",
271+
parentIdKey: "parent_id",
272+
}
273+
):void
274+
```
275+
276+
## removeByIdInFlatData
277+
278+
Remove node by id from the flat data. It will change the original data array. Therefore, it is recommended to pass in a copy of the original data, or use it together with `useImmer`. [Reference](guide#update_flat_data_with_inner_methods2)
279+
280+
```
281+
(
282+
flatData,
283+
removeId: Id | null,
284+
options?: {
285+
idKey: "id",
286+
parentIdKey: "parent_id",
287+
}
288+
): removedData
289+
```
290+
291+
## walkParentsGenerator
292+
293+
A method to iterate over another special kind of data. This data is like `HTMLElement`, which contains keys pointing to the parent node like `parentElement`.
294+
295+
```
296+
(
297+
node,
298+
parentKeyOrGetter: string | ((node) => parent | undefined),
299+
options?: {
300+
withSelf: boolean;
301+
}
302+
): Generator
303+
```
304+
305+
`parentKeyOrGetter` can be a string or a method that returns the parent. `options.withSelf` indicates whether to include the node self. Returns [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator). Here is an example of traversing HTMLElement:
306+
307+
```ts
308+
let el = document.querySelector("div");
309+
for (const parent of walkParentsGenerator(el, "parentElement", {
310+
withSelf: true,
311+
})) {
312+
// ...
313+
}
314+
```
315+
316+
## Stat
317+
318+
`stat` contains information related to the node. Read-only. The properties are as follows:
319+
320+
| Name | Type | Description |
321+
| ------------ | ------------ | :------------------------------------ |
322+
| \_isStat | boolean | Indicates whether it is a stat object |
323+
| node | object | node data |
324+
| id | Id | id |
325+
| pid | Id, null | parent id |
326+
| parent | object, null | parent data |
327+
| parentStat | stat, null | parent stat |
328+
| childIds | Id[] | |
329+
| children | object[] | |
330+
| childStats | stat[] | stats of children |
331+
| siblingIds | Id[] | |
332+
| siblings | object[] | sibling nodes |
333+
| siblingStats | stat[] | stats of siblings |
334+
| index | number | node's index in siblings |
335+
| level | number | node's depth in tree. Start from 1 |
336+
| open | boolean | |
337+
| checked | boolean | |
338+
| draggable | boolean | |

0 commit comments

Comments
 (0)