@shencom/utils-tree/README.md

树形数据结构相关工具方法

# @shencom/utils-tree

> 树形数据结构相关工具方法

## Install

```sh
pnpm add @shencom/utils

# or

pnpm add @shencom/utils-tree
```

## Basic Usage

```ts
import { TreeFindNode, TreeToArray } from '@shencom/utils';
// import { TreeFindNode, TreeToArray } from '@shencom/utils-tree';
```

## Methods

**TreeToArray**

- 说明: 转数组
- 类型: `(tree: T, options?: TreeToArrayOptions): AnyToArray<T>`
- 参数:
  - `tree` - 数据
  - `options` - 配置属性
  - `options.children` - 子节点映射字段，默认: `children`
  - `options.keepChildren` - 是否保留完整子节点数据，默认: `false`
- 示例:
  ```ts
  TreeToArray(tree);
  TreeToArray(tree, { children: 'child' });
  TreeToArray(tree, { children: 'child', keepChildren: true });
  ```

**TreeFindNode**

- 说明: 查找树形数据中的某个节点
- 类型: `(tree: T, id: string, maps?: Omit<TreeNodeOptions, 'pid'>): Flatten<T> | null`
- 参数:
  - `tree` - 数据
  - `id` - 节点 id
  - `maps` - 配置属性
  - `maps.id` - 节点 id 映射字段，默认: `id`
  - `maps.children` - 子节点映射字段，默认: `children`
- 示例:

  ```ts
  TreeFindNode(tree, '1');
  TreeFindNode(tree, '1', { id: 'id', children: 'child' });
  ```

**TreeFindParentNodes**

- 说明: 查找树形数据中的某个节点的所有父节点，返回数据中包含自身
- 类型: `(tree: T, id: string, maps?: TreeNodeOptions, keepChildren?: boolean): AnyToArray<T>`
- 参数:
  - `tree` - 数据
  - `id` - 节点 id
  - `maps` - 配置属性
  - `maps.id` - 节点 id 映射字段，默认: `id`
  - `maps.children` - 子节点映射字段，默认: `children`
  - `maps.pid` - 父节点 id 映射字段，默认: `pid`
  - `keepChildren` - 是否保留完整子节点数据，默认: `false`
- 示例:
  ```ts
  TreeFindParentNodes(tree, '1');
  TreeFindParentNodes(tree, '1', { id: 'id', children: 'child', pid: 'pid' });
  TreeFindParentNodes(tree, '1', { id: 'id', children: 'child', pid: 'pid' }, true);
  ```

**TreeFindParentByKey**

- 说明: 通过树形数据中的某个 key 的值，查找所有的父级节点，返回数据中包含自身
- 类型: `(tree: T, props: ParentByKeyProps, keepChildren?: boolean): AnyToArray<T>`
- 参数:
  - `tree` - 数据
  - `props` - 配置属性
  - `props.key` - 要查找的 key
  - `props.value` - 要查找的 key 的值
  - `props.id` - 节点 id 映射字段，默认: `id`
  - `props.children` - 子节点映射字段，默认: `children`
  - `props.pid` - 父节点 id 映射字段，默认: `pid`
  - `keepChildren` - 是否保留完整子节点数据，默认: `false`
- 示例:
  ```ts
  TreeFindParentByKey(tree, { key: 'name', value: '1' });
  TreeFindParentByKey(tree, { key: 'name', value: '1', id: 'id', pid: 'pid', children: 'child' });
  TreeFindParentByKey(
    tree,
    { key: 'name', value: '1', id: 'id', pid: 'pid', children: 'child' },
    true,
  );
  ```

**TreeFindParentIds**

- 说明: 查找树形数据中的某个节点的所有父节点 id，返回数据中包含自身
- 类型: `(tree: TreeType, id: string, maps?: TreeNodeOptions): string[]`
- 参数:
  - `tree` - 数据
  - `id` - 节点 id
  - `maps` - 配置属性
  - `maps.id` - 节点 id 映射字段，默认: `id`
  - `maps.children` - 子节点映射字段，默认: `children`
  - `maps.pid` - 父节点 id 映射字段，默认: `pid`
- 示例:
  ```ts
  TreeFindParentIds(tree, '1');
  TreeFindParentIds(tree, '1', { id: 'id', children: 'child', pid: 'pid' });
  ```

**TreeMap**

- 说明: 处理树形结构每一项的数据
- 类型: `(tree: T, handler: TreeCallbackfn<Flatten<T>>, maps?: Pick<TreeNodeOptions, 'children'>): T`
- 参数:
  - `tree` - 数据
  - `handler` - 处理函数
  - `maps` - 配置属性
  - `maps.children` - 子节点映射字段，默认: `children`
- 示例:
  ```ts
  TreeMap(tree, (node) => ({ ...node, title: node.name }));
  TreeMap(tree, (node) => ({ ...node, title: node.name }), { children: 'child' });
  ```

**TreeForEach**

- 说明: 遍历树形结构每一项的数据
- 类型: `(tree: T, handler: (node: T) => void, maps?: Pick<TreeNodeOptions, 'children'>): void`
- 参数:
  - `tree` - 数据
  - `handler` - 处理函数
  - `maps` - 配置属性
  - `maps.children` - 子节点映射字段，默认: `children`
- 示例:
  ```ts
  TreeForEach(tree, (node) => {
    // ...
  });
  TreeForEach(
    tree,
    (node) => {
      // ..
    },
    { children: 'child' },
  );
  ```

**TreeMapOption**

- 说明: 对树形结构中每一项的进行映射
- 类型: `(tree: T, maps: Record<string, string>, childKey?: string) => AnyToArray<T>`
- 参数:
  - `tree` - 数据
  - `maps` - 映射关系
  - `childKey` - 子节点字段，默认: `children`
- 示例:
  ```ts
  TreeMapOption(tree, { id: 'ID' });
  TreeMapOption(tree, { id: 'ID' }, 'child');
  ```

**TreeFilter**

- 说明: 过滤树形结构中的每一项的数据
- 类型: `(tree: T, condition: (node: Flatten<T>) => boolean, maps?: Pick<TreeNodeOptions, 'children'>): T | T[] | null`
- 参数:
  - `tree` - 数据
  - `condition` - 判断函数
  - `maps` - 配置属性
  - `maps.children` - 子节点映射字段，默认: `children`
- 示例:
  ```ts
  TreeFilter(tree, (node) => node.active);
  TreeFilter(tree, (node) => node.active, { children: 'child' });
  ```

**TreeFilterChildEmpty**

- 说明: 将子节点列表为空数组处理成 null
- 类型: `(tree: T, maps?: Pick<TreeNodeOptions, 'children'>): T`
- 参数:
  - `tree` - 数据
  - `maps` - 配置属性
  - `maps.children` - 子节点映射字段，默认: `children`
- 示例:
  ```ts
  TreeFilterChildEmpty(tree);
  TreeFilterChildEmpty(tree, { children: 'child' });
  ```