项目中用到的各类安装包说明

Next.js +React项目

ksjs/use-url-state

* `@ahooksjs/use-url-state` 是一个 React 的自定义 Hook，用于管理 URL 中的查询参数（query parameters）状态。它可以让你轻松地将组件的状态与 URL 同步，从而实现状态持久化和分享功能。
* ### 核心功能：

1.  **状态与 URL 同步**：

    -   通过 Hook 管理状态时，状态的变化会自动更新到浏览器的 URL 中。
    -   反之，URL 的变化也会更新到组件的状态中。

1.  **支持多种数据类型**：

    -   自动解析和序列化常见的数据类型（如字符串、数字、布尔值、数组等）。

1.  **简化状态管理**：

    -   无需手动解析或更新 URL 参数，减少了操作 URL 的复杂性。

### 使用场景：

-   **状态持久化**：在页面刷新或分享链接时，状态可以通过 URL 保持一致。
-   **分享功能**：用户可以通过 URL 分享当前页面的状态。
-   **导航与回退**：支持浏览器的前进、后退操作，状态会随之更新。

import useUrlState from '@ahooksjs/use-url-state';

function Demo() {
  const [state, setState] = useUrlState({ count: 0, name: 'default' });

  return (
    <div>
      <p>Count: {state.count}</p>
      <p>Name: {state.name}</p>
      <button onClick={() => setState({ count: state.count + 1 })}>Increment</button>
      <button onClick={() => setState({ name: 'updated' })}>Update Name</button>
    </div>
  );
}

babel/runtime

* `@babel/runtime` 是一个辅助库，主要用于支持 Babel 转译后的代码运行时所需的工具函数和 polyfill。它的作用是减少重复代码、优化打包体积，并确保转译后的代码能够在目标环境中正常运行。
* ### 核心功能：

1. 提供运行时工具函数：

   • Babel 在转译代码时会用到一些工具函数（如 _extends、_asyncToGenerator 等），这些函数会被抽取到 @babel/runtime 中，而不是每次都嵌入到转译后的代码里。
   • 这样可以避免重复定义工具函数，从而减小打包体积。

2. 支持 ES6+ 特性：

   • 提供对 ES6+ 特性的 polyfill（如 Promise、Symbol 等），以确保代码在不支持这些特性的环境中也能正常运行。

3. 避免全局污染：

   • 与 @babel/polyfill 不同，@babel/runtime 不会污染全局作用域，而是以模块化的方式引入所需的 polyfill。

4. 与 Babel 插件配合：

   • 通常与 @babel/plugin-transform-runtime 一起使用，自动替换代码中的工具函数调用为 @babel/runtime 的模块导入。

使用场景：

• 减少重复代码：在多个文件中使用相同的工具函数时，避免每个文件都嵌入一份。
• 优化打包体积：通过模块化引入，减少冗余代码。
• 兼容性支持：为目标环境提供必要的 polyfill。

@dagrejs/dagre

@dagrejs/dagre 是一个用于图布局的 JavaScript 库，主要用于为有向图（Directed Graph）生成自动化的节点和边的布局。它可以帮助开发者根据图的结构自动计算节点的位置，从而生成美观的图形布局。

核心功能：

1. 自动图布局：

   • 根据输入的节点和边，自动计算每个节点的坐标位置，生成层次化或紧凑的图布局。
   • 支持有向图（DAG, Directed Acyclic Graph）的布局。

2. 支持多种布局算法：

   • 提供层次化布局（Hierarchical Layout），适合流程图、依赖图等场景。
   • 支持自定义边的方向、节点的大小等。

3. 灵活的配置：

   • 可以设置节点的大小、边的长度、对齐方式等参数，生成符合需求的布局。

4. 与图形库集成：

   • 通常与 D3.js、Cytoscape.js、React Flow 等图形库结合使用，用于渲染图形。

使用场景：

• 流程图：自动布局复杂的流程图。
• 依赖图：生成模块依赖关系图。
• 树状结构：绘制层次化的树状结构。
• 网络拓扑图：展示网络设备的连接关系。

import dagre from '@dagrejs/dagre';

// 创建一个有向图
const g = new dagre.graphlib.Graph();

// 设置图的全局属性
g.setGraph({
  rankdir: 'LR', // 布局方向：从左到右（默认是从上到下）
  nodesep: 50,   // 节点之间的水平间距
  ranksep: 100,  // 层级之间的垂直间距
});

// 设置默认的边属性
g.setDefaultEdgeLabel(() => ({}));

// 添加节点
g.setNode('A', { label: 'Node A', width: 100, height: 50 });
g.setNode('B', { label: 'Node B', width: 100, height: 50 });
g.setNode('C', { label: 'Node C', width: 100, height: 50 });

// 添加边
g.setEdge('A', 'B');
g.setEdge('B', 'C');

// 运行布局算法
dagre.layout(g);

// 输出每个节点的坐标
g.nodes().forEach(node => {
  console.log(node, g.node(node));
});

// 输出边的路径
g.edges().forEach(edge => {
  console.log(edge, g.edge(edge));
});

输出结果：

• 每个节点的坐标位置（x 和 y）。
• 每条边的路径信息（起点和终点的坐标）。

依赖关系：

• @dagrejs/dagre 是 dagre 的现代化版本，支持更好的模块化和 TypeScript 类型定义。
• 通常与图形渲染库（如 D3.js、React Flow）结合使用，负责布局计算，而渲染由其他库完成。

总结：

@dagrejs/dagre 是一个强大的图布局工具，适合需要自动化布局的场景。它专注于计算图的布局，而不负责图形的渲染，非常适合与其他图形库配合使用。

@dnd-kit/core

@dnd-kit/core 是一个现代化的拖拽和放置（Drag and Drop, DnD）库，专为 React 应用设计，提供了灵活且高性能的拖拽功能。它是 dnd-kit 的核心模块，提供了基础的拖拽逻辑和事件处理。

核心功能：

1. 拖拽和放置的核心逻辑：

   • 提供拖拽的检测、拖拽目标的管理、拖拽事件的处理等功能。
   • 支持复杂的拖拽场景，如嵌套拖拽、动态拖拽目标等。

2. 高性能：

   • 使用现代浏览器 API（如 Pointer Events 和 MutationObserver），性能优于传统的 HTML5 DnD API。

3. 完全可控：

   • 提供了对拖拽行为的完全控制，允许开发者自定义拖拽的触发条件、约束、动画等。

4. 无 UI 限制：

   • 不强制使用特定的 UI 库或组件，开发者可以自由选择如何渲染拖拽元素。

5. 事件驱动：

   • 提供了丰富的事件回调（如 onDragStart、onDragOver、onDragEnd），方便开发者监听和处理拖拽行为。

使用场景：

• 列表排序：实现拖拽排序功能，如任务管理工具中的任务列表。
• 拖拽上传：支持文件或元素的拖拽上传。
• 复杂布局：支持拖拽调整布局或嵌套拖拽。
• 游戏开发：实现拖拽交互的游戏场景。

import React from 'react';
import { DndContext } from '@dnd-kit/core';

function App() {
  const handleDragStart = (event) => {
    console.log('Drag started:', event);
  };

  const handleDragEnd = (event) => {
    console.log('Drag ended:', event);
  };

  return (
    <DndContext onDragStart={handleDragStart} onDragEnd={handleDragEnd}>
      <Draggable />
      <Droppable />
    </DndContext>
  );
}

function Draggable() {
  return <div draggable>Drag me</div>;
}

function Droppable() {
  return <div>Drop here</div>;
}

依赖关系：

• @dnd-kit/core 是 dnd-kit 的核心模块，通常与其他模块（如 @dnd-kit/sortable、@dnd-kit/utilities）结合使用，以实现更高级的功能。

优势：

• 现代化：基于现代浏览器 API，性能和兼容性更好。
• 灵活性：允许开发者完全控制拖拽行为。
• 模块化：可以根据需求选择性地引入其他功能模块。

@floating-ui/react

@floating-ui/react 是一个用于构建高效、灵活的浮动用户界面（如工具提示、弹出框、下拉菜单等）的库。它是 Floating UI 的 React 集成版本，提供了强大的定位和动态调整功能。

核心功能：

1. 精准定位：

   • 提供强大的定位算法，确保浮动元素（如弹出框）能够准确地显示在目标元素附近。
   • 支持多种定位策略（如 top, bottom, left, right 等）。

2. 动态调整：

   • 自动检测屏幕边界，避免浮动元素超出可视区域（防止溢出）。
   • 支持动态调整位置和大小，确保浮动元素始终可见。

3. 高性能：

   • 使用现代浏览器 API（如 ResizeObserver 和 IntersectionObserver）优化性能。
   • 轻量级且模块化，适合现代前端框架。

4. React 集成：

   • 提供 React Hook 和组件，方便在 React 应用中快速集成。

5. 可扩展性：

   • 支持插件机制，允许开发者自定义行为（如偏移、翻转、缩放等）。

使用场景：

• 工具提示（Tooltip） ：在目标元素上方或周围显示提示信息。
• 弹出框（Popover） ：构建复杂的弹出式交互组件。
• 下拉菜单（Dropdown） ：实现动态定位的下拉菜单。
• 上下文菜单（Context Menu） ：右键菜单的动态定位。

import React, { useState, useRef } from 'react';
import { useFloating, offset, flip, shift } from '@floating-ui/react';

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const buttonRef = useRef(null);
  const { x, y, reference, floating, strategy } = useFloating({
    middleware: [offset(8), flip(), shift()],
    placement: 'bottom',
  });

  return (
    <div>
      <button
        ref={reference}
        onClick={() => setIsOpen((prev) => !prev)}
      >
        Toggle Popover
      </button>
      {isOpen && (
        <div
          ref={floating}
          style={{
            position: strategy,
            top: y ?? 0,
            left: x ?? 0,
          }}
        >
          This is a popover!
        </div>
      )}
    </div>
  );
}

export default App;

输出效果：

• 点击按钮后，弹出框会显示在按钮下方。
• 如果屏幕空间不足，弹出框会自动翻转到其他位置。

依赖关系：

• Floating UI 核心库：@floating-ui/core 提供了底层定位逻辑。
• React 集成：@floating-ui/react 封装了核心功能，提供 React Hook 和组件。

优势：

• 轻量级：相比其他类似库（如 Popper.js），更小巧且性能更优。
• 灵活性：支持多种定位策略和动态调整。
• 现代化：基于现代浏览器 API，兼容性和性能更好。