@hsu-react/ui 0.0.1

package/src/components/Tree/_utils/index.ts

@@ -0,0 +1,170 @@
+import { Key } from "react";
+import { TreeData } from "..";
+
+/**
+ * 获取节点的所有子节点 key
+ * @param children 子节点数组
+ * @returns 所有子节点的 key 数组
+ */
+export const getAllChildrenKeys = (children: TreeData[]): Key[] => {
+  const keys: Key[] = [];
+  const traverse = (nodes: TreeData[]) => {
+    for (const node of nodes) {
+      keys.push(node.key);
+      if (node.children?.length) {
+        traverse(node.children);
+      }
+    }
+  };
+  traverse(children);
+  return keys;
+};
+
+/**
+ * 在树中查找节点的所有父级节点 key
+ * @param targetKey 目标节点的 key
+ * @param treeData 树数据
+ * @param parentKeys 父级节点 key 数组（递归使用）
+ * @returns 所有父级节点的 key 数组，如果未找到则返回空数组
+ */
+export const getAllParentKeys = (
+  targetKey: Key,
+  treeData: TreeData[],
+  parentKeys: Key[] = []
+): Key[] => {
+  for (const node of treeData) {
+    if (node.key === targetKey) {
+      return parentKeys;
+    }
+    if (node.children?.length) {
+      const newParentKeys = [...parentKeys, node.key];
+      const found = getAllParentKeys(targetKey, node.children, newParentKeys);
+      // 如果找到了（返回的数组长度大于0或等于newParentKeys），说明在子树中找到了
+      if (found.length > 0) {
+        return found;
+      }
+    }
+  }
+  return [];
+};
+
+/**
+ * 根据 key 查找节点
+ * @param targetKey 目标节点的 key
+ * @param data 树数据
+ * @returns 找到的节点或 null
+ */
+export const findNodeByKey = (
+  targetKey: Key,
+  data: TreeData[]
+): TreeData | null => {
+  for (const node of data) {
+    if (node.key === targetKey) {
+      return node;
+    }
+    if (node.children) {
+      const found = findNodeByKey(targetKey, node.children);
+      if (found) return found;
+    }
+  }
+  return null;
+};
+
+/**
+ * 搜索过滤树数据
+ * @param searchKey 搜索关键词
+ * @param data 树数据
+ * @returns 过滤后的树数据
+ */
+export const filterTreeData = (
+  searchKey: string,
+  data: TreeData[]
+): TreeData[] => {
+  if (!searchKey.trim()) return data;
+
+  const result: TreeData[] = [];
+  const lowerSearchKey = searchKey.toLowerCase();
+
+  for (const item of data) {
+    const matchesTitle = item.title.toLowerCase().includes(lowerSearchKey);
+    const filteredChildren = item.children?.length
+      ? filterTreeData(searchKey, item.children)
+      : undefined;
+
+    if (matchesTitle || filteredChildren?.length) {
+      result.push({
+        ...item,
+        children: filteredChildren?.length ? filteredChildren : undefined,
+      });
+    }
+  }
+
+  return result;
+};
+
+/**
+ * 根据默认展开层级计算应该展开的节点 keys
+ * @param treeData 树数据
+ * @param level 展开层级（从 1 开始，1 表示第一层，2 表示第二层，以此类推）
+ * @returns 应该展开的节点 keys 数组
+ */
+export const getExpandedKeysByLevel = (
+  treeData: TreeData[],
+  level: number
+): Key[] => {
+  if (level < 1 || !treeData?.length) {
+    return [];
+  }
+
+  const expandedKeys: Key[] = [];
+
+  const traverse = (nodes: TreeData[], currentLevel: number) => {
+    for (const node of nodes) {
+      // 如果当前层级小于等于目标层级，则展开该节点
+      if (currentLevel <= level && node.children?.length) {
+        expandedKeys.push(node.key);
+        traverse(node.children, currentLevel + 1);
+      }
+    }
+  };
+
+  traverse(treeData, 1);
+
+  return expandedKeys;
+};
+
+/**
+ * 获取节点的完整路径（从根节点到当前节点）
+ * @param targetKey 目标节点的 key
+ * @param treeData 树数据
+ * @returns 节点路径数组，包含从根节点到目标节点的所有节点信息；如果未找到则返回 null
+ */
+export const getNodePath = (
+  targetKey: Key,
+  treeData: TreeData[]
+): TreeData[] | null => {
+  const findPath = (
+    nodes: TreeData[],
+    path: TreeData[] = []
+  ): TreeData[] | null => {
+    for (const node of nodes) {
+      const currentPath = [...path, node];
+      
+      // 找到目标节点
+      if (node.key === targetKey) {
+        return currentPath;
+      }
+      
+      // 在子节点中继续查找
+      if (node.children?.length) {
+        const found = findPath(node.children, currentPath);
+        if (found) {
+          return found;
+        }
+      }
+    }
+    return null;
+  };
+
+  return findPath(treeData);
+};

package/src/components/Tree/_utils/normalizeCheckedKeys.ts

@@ -0,0 +1,74 @@
+import { Key } from "react";
+import { TreeData, CheckedKeys } from "..";
+import { getAllChildrenKeys } from ".";
+
+/**
+ * 规范化 checkedKeys：检查父节点，如果子项未全选，将父节点设为半选
+ * @param checkedKeys 待规范化的 checkedKeys
+ * @param treeData 树数据
+ * @returns 规范化后的 checkedKeys
+ */
+export const normalizeCheckedKeys = (
+  checkedKeys: CheckedKeys | undefined,
+  treeData: TreeData[]
+): CheckedKeys | undefined => {
+  if (!checkedKeys || !treeData.length) {
+    return checkedKeys;
+  }
+
+  // 如果是数组格式，转换为对象格式
+  const checkedSet = new Set<Key>();
+  const halfCheckedSet = new Set<Key>();
+
+  if (Array.isArray(checkedKeys)) {
+    checkedKeys?.forEach((key) => checkedSet.add(key));
+  } else {
+    checkedKeys.checked?.forEach((key) => checkedSet.add(key));
+    (checkedKeys.halfChecked || [])?.forEach((key) => halfCheckedSet.add(key));
+  }
+
+  // 递归遍历所有节点，检查父节点状态
+  // 从最底层开始处理，确保父节点的状态基于子节点的正确状态
+  const processNode = (node: TreeData): void => {
+    // 先递归处理子节点（从最底层开始）
+    if (node.children?.length) {
+      for (const child of node.children) {
+        processNode(child);
+      }
+    }
+
+    // 然后处理当前节点（父节点）
+    // 如果节点在 checked 中，且有子节点
+    if (checkedSet.has(node.key) && node.children?.length) {
+      // 获取所有子节点的 key
+      const allChildrenKeys = getAllChildrenKeys(node.children);
+
+      // 检查所有子节点是否都被勾选
+      if (allChildrenKeys.length > 0) {
+        const allChildrenChecked = allChildrenKeys.every((childKey) =>
+          checkedSet.has(childKey)
+        );
+
+        if (!allChildrenChecked) {
+          // 如果子节点未全选，将父节点从 checked 中移除，添加到 halfChecked
+          checkedSet.delete(node.key);
+          halfCheckedSet.add(node.key);
+        } else {
+          // 如果所有子节点都被勾选，确保父节点不在 halfChecked 中
+          halfCheckedSet.delete(node.key);
+        }
+      }
+    }
+  };
+
+  // 遍历所有根节点
+  for (const node of treeData) {
+    processNode(node);
+  }
+
+  // 返回规范化后的 checkedKeys
+  return {
+    checked: Array.from(checkedSet),
+    halfChecked: Array.from(halfCheckedSet),
+  };
+};

package/src/components/Tree/index.md

@@ -0,0 +1,17 @@
+---
+nav: 组件
+group:
+  title: 数据展示
+  order: 4
+title: Tree 树形控件
+---
+
+# Tree 树形控件
+
+> `Tree` 组件。完整 API 见源码类型定义，下方为基础用法。
+
+## 引入
+
+```ts
+import { Tree } from "@hsu-react/ui";
+```

package/src/components/Tree/index.module.less

@@ -0,0 +1,142 @@
+.Tree {
+  --tree-indent-unit-width: 19px;
+  --tree-switcher-width: 8px;
+  --tree-switcher-gap: 4px;
+
+  display: flex;
+  flex-direction: column;
+  row-gap: 15px;
+
+  width: 100%;
+  height: 100%;
+  min-height: 0px !important;
+
+  background: var(--cf-surface);
+
+  border-radius: 8px;
+
+  .title_search {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    column-gap: 1.2em;
+
+    height: max-content;
+    min-height: max-content;
+
+    .title {
+      font-size: 16px;
+      font-weight: 500;
+      line-height: 24px;
+      word-break: keep-all;
+      white-space: nowrap;
+
+      cursor: pointer;
+    }
+
+    .search {
+      height: 32px;
+
+      .searchIcon {
+        font-size: 16px;
+      }
+    }
+
+    .buttonGroup {
+      display: flex;
+      align-items: center;
+      column-gap: 10px;
+    }
+  }
+
+  .treeContainer {
+    width: 100%;
+    height: 100%;
+
+    overflow-y: auto;
+    scrollbar-gutter: stable;
+
+    .ant-tree-treenode {
+      &:hover {
+        background: var(--cf-subtle);
+      }
+
+      &:has(> .ant-tree-node-selected) {
+        background-color: #e6f4ff;
+
+        .ant-tree-node-selected {
+          background-color: transparent;
+        }
+      }
+    }
+
+    .ant-tree-indent-unit {
+      width: var(--tree-indent-unit-width);
+    }
+
+    .ant-tree-switcher {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+
+      width: var(--tree-switcher-width);
+      margin-inline-start: var(--tree-switcher-gap);
+      margin-inline-end: var(--tree-switcher-gap);
+
+      &::before {
+        width: var(--tree-switcher-width);
+        height: 100%;
+      }
+
+      &:hover {
+        &::before {
+          background: transparent;
+        }
+      }
+    }
+
+    .ant-tree-node-content-wrapper {
+      display: inline-flex;
+      align-items: center;
+      column-gap: 4px;
+
+      flex: 1 1 auto;
+      min-width: 0px;
+
+      padding: 2px 0px;
+
+      .ant-tree-title {
+        display: inline-block;
+      }
+
+      &:hover {
+        background: transparent;
+      }
+
+      .ant-tree-iconEle {
+        display: inline-flex;
+        align-items: center;
+
+        width: max-content;
+      }
+    }
+  }
+
+  &.hideLeafExpand {
+    .ant-tree-switcher-noop {
+      display: none;
+    }
+  }
+
+  &.legacyHasSelectedNodeBackground {
+    .treeContainer {
+      .ant-tree-treenode.ant-tree-treenode-selected {
+        background-color: #e6f4ff;
+
+        .ant-tree-node-selected {
+          background-color: transparent;
+        }
+      }
+    }
+  }
+}

package/src/components/Tree/index.tsx

@@ -0,0 +1,308 @@
+import { Tree as AntdTree, TreeProps as AntdTreeProps } from "antd";
+import React, {
+  ReactNode,
+  useMemo,
+  CSSProperties,
+  useCallback,
+  Key,
+  useEffect,
+  useRef,
+} from "react";
+import { generateRandomStr } from "hsu-utils";
+import styles from "./index.module.less";
+import classNames from "classnames";
+import TitleSearchBar from "./_components/TitleSearchBar";
+import { useTreeSearch } from "./_hooks/useTreeSearch";
+import { useExpandedKeys, useCheckedKeys } from "./_hooks/useTreeState";
+import { useTreeCheck } from "./_hooks/useTreeCheck";
+import { useClearNodeTitle } from "./_hooks/useClearNodeTitle";
+import { InputProps } from "../Input";
+import { ButtonProps } from "../Button";
+import { getExpandedKeysByLevel, getNodePath } from "./_utils";
+import TextEllipsis from "../TextEllipsis";
+import usePermissions from "../../hooks/usePermissions";
+import { isLegacyHasSelectorBrowser } from "../../utils/cssSupports";
+
+export interface TreeData extends Record<string, unknown> {
+  title: string;
+  key: string | number;
+  value: string | number;
+  selectable?: boolean;
+  disabled?: boolean;
+  disableCheckbox?: boolean;
+  isLeaf?: boolean;
+  checkable?: boolean;
+  icon?: ReactNode;
+  children?: TreeData[];
+}
+
+export interface CheckedObject {
+  checked: React.Key[];
+  halfChecked: React.Key[];
+}
+
+export type CheckedKeys = React.Key[] | CheckedObject;
+
+export interface TreeProps extends Omit<
+  AntdTreeProps,
+  "treeData" | "loadData" | "loadedKeys" | "titleRender"
+> {
+  titleRender?: (data: TreeData) => ReactNode;
+  treeClassName?: string;
+  treeContainerClassName?: string;
+  titleClassName?: string;
+  title?: ReactNode;
+  search?: boolean;
+  treeData?: TreeData[];
+  onChange?: (checked: CheckedKeys) => void;
+  searchProps?: InputProps;
+  indent?: number;
+  switchWidth?: number;
+  switchGap?: number;
+  hideLeafExpand?: boolean;
+  buttonGroup?: ButtonProps[];
+  btnPosition?: "left" | "right";
+  /** 默认展开层级（从 1 开始，1 表示第一层，2 表示第二层，以此类推） */
+  defaultExpandLevel?: number;
+  hasPermi?: string[];
+  /** 节点被选中时的回调，返回选中节点的完整路径 */
+  onSelectPath?: (path: TreeData[] | null, selectedKeys: Key[]) => void;
+  /** 点击已选中的节点时是否允许取消选中，默认 true（允许取消选中） */
+  allowDeselect?: boolean;
+  titleSearchBarClassName?: string;
+}
+
+const Tree: React.FC<TreeProps> = (props) => {
+  const {
+    title,
+    titleRender,
+    treeClassName,
+    treeContainerClassName,
+    titleClassName,
+    className,
+    search,
+    treeData = [],
+    onChange,
+    onCheck,
+    onSelect,
+    searchProps,
+    indent,
+    switchWidth,
+    switchGap,
+    hideLeafExpand,
+    expandedKeys: expandedKeysProps,
+    defaultExpandedKeys,
+    defaultExpandLevel,
+    checkedKeys: checkedKeysProps,
+    selectedKeys: selectedKeysProps,
+    defaultSelectedKeys,
+    buttonGroup,
+    btnPosition = "right",
+    hasPermi,
+    onSelectPath,
+    allowDeselect = true,
+    titleSearchBarClassName,
+    ...treeConfig
+  } = props;
+  const { permitted } = usePermissions(hasPermi);
+  const legacyHasSelector = isLegacyHasSelectorBrowser();
+
+  // 生成唯一类名（用于样式隔离）
+  const cls = useMemo(() => generateRandomStr(10), []);
+  // 根据 defaultExpandLevel 计算默认展开的 keys
+  // 如果同时提供了 defaultExpandedKeys 和 defaultExpandLevel，优先使用 defaultExpandedKeys
+  const computedDefaultExpandedKeys = useMemo(() => {
+    if (defaultExpandedKeys !== undefined) {
+      return defaultExpandedKeys;
+    }
+    if (defaultExpandLevel !== undefined && defaultExpandLevel > 0) {
+      return getExpandedKeysByLevel(treeData, defaultExpandLevel);
+    }
+    return undefined;
+  }, [defaultExpandLevel, treeData, defaultExpandedKeys]);
+
+  // 管理展开状态
+  const [expandedKeys, setExpandedKeys] = useExpandedKeys(
+    expandedKeysProps,
+    computedDefaultExpandedKeys,
+  );
+
+  // 管理勾选状态（自动规范化：父级在 checked 中但子项未全选时，设为半选）
+  const [checkedKeys, setCheckedKeys] = useCheckedKeys(
+    checkedKeysProps,
+    treeData,
+  );
+
+  // 管理选中状态（用于支持 allowDeselect 功能）
+  const [internalSelectedKeys, setInternalSelectedKeys] = React.useState<Key[]>(
+    defaultSelectedKeys ?? [],
+  );
+
+  // 受控模式使用外部传入的 selectedKeys，非受控模式使用内部状态
+  const selectedKeys = selectedKeysProps ?? internalSelectedKeys;
+
+  // 处理搜索
+  const { searchKey, handleSearchChange, filteredTreeData } = useTreeSearch(
+    treeData,
+    setExpandedKeys,
+  );
+
+  // 处理勾选（使用 antd 默认逻辑）
+  const handleCheck = useTreeCheck(setCheckedKeys, onCheck, onChange);
+
+  // 清空节点 title 属性（防止悬浮显示）
+  useClearNodeTitle(filteredTreeData, cls);
+
+  // 样式对象（CSS 变量）
+  const style = useMemo<CSSProperties>(
+    () =>
+      ({
+        "--tree-indent-unit-width":
+          typeof indent === "number" ? `${indent}px` : undefined,
+        "--tree-switcher-width":
+          typeof switchWidth === "number" ? `${switchWidth}px` : undefined,
+        "--tree-switcher-gap":
+          typeof switchGap === "number" ? `${switchGap}px` : undefined,
+      }) as CSSProperties,
+    [indent, switchWidth, switchGap],
+  );
+
+  // 使用 ref 保存最新的 onSelectPath 回调和初始化标志，避免闭包陷阱
+  const onSelectPathRef = useRef(onSelectPath);
+  const isInitializedRef = useRef(false);
+
+  useEffect(() => {
+    onSelectPathRef.current = onSelectPath;
+  }, [onSelectPath]);
+
+  // 处理展开事件
+  const handleExpand = useCallback(
+    (
+      expandedKeys: Key[],
+      info: Parameters<NonNullable<AntdTreeProps["onExpand"]>>[1],
+    ) => {
+      setExpandedKeys(expandedKeys);
+      treeConfig.onExpand?.(expandedKeys, info);
+    },
+    [setExpandedKeys, treeConfig],
+  );
+
+  // 处理选中事件
+  const handleSelect = useCallback(
+    (
+      selectedKeys: Key[],
+      info: Parameters<NonNullable<AntdTreeProps["onSelect"]>>[1],
+    ) => {
+      let finalSelectedKeys = selectedKeys;
+
+      // 如果不允许取消选中，且点击的是已选中的节点（info.selected 为 false 表示要取消选中）
+      // 则阻止取消，保持该节点选中
+      if (!allowDeselect && !info.selected && info.node.key) {
+        finalSelectedKeys = [info.node.key];
+      }
+
+      // 非受控模式下，更新内部状态
+      if (selectedKeysProps === undefined) {
+        setInternalSelectedKeys(finalSelectedKeys);
+      }
+
+      onSelect?.(finalSelectedKeys, info);
+
+      if (!onSelectPathRef.current) return;
+
+      // 获取节点路径并调用回调
+      const path =
+        finalSelectedKeys.length > 0
+          ? getNodePath(finalSelectedKeys[0], treeData)
+          : null;
+      onSelectPathRef.current(path, finalSelectedKeys);
+    },
+    [onSelect, treeData, allowDeselect, selectedKeysProps],
+  );
+
+  // 处理初始传入的 selectedKeys 和 defaultSelectedKeys
+  useEffect(() => {
+    if (!onSelectPathRef.current || !treeData.length) return;
+
+    // 受控模式：使用 selectedKeysProps
+    if (selectedKeysProps !== undefined) {
+      if (selectedKeysProps.length > 0) {
+        const path = getNodePath(selectedKeysProps[0], treeData);
+        onSelectPathRef.current(path, selectedKeysProps);
+        isInitializedRef.current = true;
+      } else if (isInitializedRef.current) {
+        onSelectPathRef.current(null, selectedKeysProps);
+      }
+      return;
+    }
+
+    // 非受控模式：只在初始化时使用 defaultSelectedKeys
+    if (
+      !isInitializedRef.current &&
+      defaultSelectedKeys &&
+      defaultSelectedKeys.length > 0
+    ) {
+      const path = getNodePath(defaultSelectedKeys[0], treeData);
+      onSelectPathRef.current(path, defaultSelectedKeys);
+      isInitializedRef.current = true;
+    }
+  }, [defaultSelectedKeys, selectedKeysProps, treeData]);
+
+  if (!permitted) {
+    return null;
+  }
+
+  return (
+    <div
+      className={classNames(styles.Tree, className, {
+        [styles.hideLeafExpand]: hideLeafExpand,
+        [styles.legacyHasSelectedNodeBackground]: legacyHasSelector,
+      })}
+      style={style}
+    >
+      <TitleSearchBar
+        titleClassName={titleClassName}
+        title={title}
+        search={search}
+        searchValue={searchKey}
+        onSearchChange={handleSearchChange}
+        searchProps={searchProps}
+        buttonGroup={buttonGroup}
+        btnPosition={btnPosition}
+        className={titleSearchBarClassName}
+      />
+      <div className={classNames(styles.treeContainer, treeContainerClassName)}>
+        {filteredTreeData.length > 0 && (
+          <AntdTree
+            blockNode
+            titleRender={(node) => {
+              const data = node as unknown as TreeData;
+
+              if (titleRender) {
+                return titleRender(data);
+              }
+
+              return (
+                <TextEllipsis containerStyle={{ display: "inline-flex" }}>
+                  {data.title}
+                </TextEllipsis>
+              );
+            }}
+            {...treeConfig}
+            className={classNames(treeClassName, cls)}
+            treeData={filteredTreeData}
+            onCheck={handleCheck}
+            checkedKeys={checkedKeys}
+            {...(expandedKeys !== undefined && { expandedKeys })}
+            selectedKeys={selectedKeys}
+            onExpand={handleExpand}
+            onSelect={handleSelect}
+            checkStrictly={false}
+          />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default Tree;