# data-structure-algorithms-visualizer

**Repository Path**: CaiSre/dsa-visualizer

## Basic Information

- **Project Name**: data-structure-algorithms-visualizer
- **Description**: 数据结构算法可视化
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# DSA Visualizer

**数据结构与算法可视化**

以 SVG 动画交互式演示 21 种常见数据结构与算法

[![Nuxt](https://img.shields.io/badge/Nuxt_4-00DC82?logo=nuxtdotjs&logoColor=white)](https://nuxt.com/)
[![Vue 3](https://img.shields.io/badge/Vue_3.5-4FC08D?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript_strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS_4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
[![Vitest](https://img.shields.io/badge/Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev/)
[![License](https://img.shields.io/badge/License-Apache_2.0-0078D4)](./LICENSE)

[快速开始](#-快速开始) · [算法目录](#-算法目录) · [常用命令](#-常用命令) · [项目结构](#-项目结构) · [架构设计](#-架构设计) · [许可证](#-许可证)

</div>

---

## 📖 简介

DSA Visualizer 是一个纯前端 Web 应用，以 **SVG 动画 + 交互**方式演示常见数据结构与算法：
支持逐步播放、单步回退、速度调节与自定义输入，配合伪代码同步高亮与复杂度展示，
适合课堂教学与自学演示。

- **零后端**：无需后端服务、数据库或用户系统，`nuxt generate` 静态产物可部署至静态托管
- **可验证**：算法与可视化分离，纯函数步骤生成器、播放器、动画状态及输入解析均有独立测试

## ✨ 特性

- **21 个算法演示** —— 覆盖排序、查找、线性结构、树、图、哈希表六大类，大小顶堆分别提供入口
- **响应式学习工作台** —— 桌面常驻分类侧栏与宽屏参考栏，窄屏使用抽屉和单列布局，画布及代码支持局部滚动
- **搜索与分类筛选** —— 首页和侧栏匹配名称、英文 ID、描述及标签；首页支持分类交集筛选，并通过 URL 保存搜索和分类，刷新后恢复
- **步骤级播放器** —— 播放 / 暂停 / 单步前进 / 单步回退 / 重置 / 拖动进度；支持 0.5x、1x、1.5x、2x、4x，步骤与树过渡按倍速等比例调整
- **代码与说明页签** —— 伪代码同步高亮且仅滚动代码容器；算法说明展示复杂度、稳定性、标签和知识点，切页签不重置演示
- **排序过程动画** —— 柱状图显示数组值与稳定下标，交换步骤展示元素双向移动
- **树结构动画** —— 演示 BST 插入、查找、删除与中序遍历、AVL 旋转、大小顶堆插入与取顶；节点和连线逐帧同步，支持增删淡入淡出及连续切步
- **自定义输入** —— 编辑数组、查找目标、图边列表与权重、线性结构及哈希表操作序列；提供格式提示、校验错误和随机示例，树演示可换一组数据
- **编辑草稿保留** —— 数据或操作编辑区可折叠，折叠及切换参考页签不会丢失草稿；非法线性操作不替换当前演示
- **浅深双主题** —— 基于 daisyUI，默认浅色，支持手动切换、本地保存偏好及首屏主题初始化
- **键盘与焦点支持** —— `空格` 播放/暂停，`←` `→` 单步，`Home` / `End` 跳至首/末步；输入控件和参考阅读区保留原生按键行为，移动抽屉支持 Escape 和焦点返回
- **基础无障碍** —— 可见输入标签、关联错误提示、键盘焦点、步骤 `aria-live` 播报，尊重 `prefers-reduced-motion` 减少动态效果设置
- **图与哈希交互** —— 图节点支持拖拽并同步更新连线；图可选择起点和方向，哈希表可调整容量并观察冲突处理
- **旧地址兼容** —— `/algorithm/heap` 保留为大顶堆兼容地址，支持静态页面直接访问，目录不重复展示

### 线性结构自定义操作

在线性结构演示页中，每行输入一条操作，点击“应用操作”生成播放步骤；也可以使用“随机示例”。
单次最多 30 条，参数必须是安全范围内的整数。

- 栈：`push 10`、`pop`、`peek`
- 队列：`enqueue 10`、`dequeue`、`peek`
- 链表：`insertHead 10`、`insertTail 20`、`remove 10`、`search 20`

## 🧮 算法目录

| 分类 | 算法 | 时间复杂度 | 空间复杂度 |
| :---: | :--- | :---: | :---: |
| 排序 | [冒泡排序](https://baike.baidu.com/item/冒泡排序) | O(n²) | O(1) |
| 排序 | [选择排序](https://baike.baidu.com/item/选择排序) | O(n²) | O(1) |
| 排序 | [插入排序](https://baike.baidu.com/item/插入排序) | O(n²) | O(1) |
| 排序 | [快速排序](https://baike.baidu.com/item/快速排序) | O(n log n) | O(log n) |
| 排序 | [归并排序](https://baike.baidu.com/item/归并排序) | O(n log n) | O(n) |
| 排序 | [堆排序](https://baike.baidu.com/item/堆排序) | O(n log n) | O(1) |
| 查找 | [线性查找](https://baike.baidu.com/item/顺序查找) | O(n) | O(1) |
| 查找 | [二分查找](https://baike.baidu.com/item/二分查找) | O(log n) | O(1) |
| 线性结构 | [栈](https://baike.baidu.com/item/栈) | O(1) | O(n) |
| 线性结构 | [队列](https://baike.baidu.com/item/队列) | O(1) | O(n) |
| 线性结构 | [链表](https://baike.baidu.com/item/链表) | O(n) | O(n) |
| 树 | [二叉搜索树](https://baike.baidu.com/item/二叉排序树) | O(log n) | O(n) |
| 树 | [AVL 树](https://baike.baidu.com/item/AVL树) | O(log n) | O(n) |
| 树 | [大顶堆](https://baike.baidu.com/item/大顶堆) | O(log n) | O(n) |
| 树 | [小顶堆](https://baike.baidu.com/item/小顶堆) | O(log n) | O(n) |
| 图 | [广度优先搜索](https://baike.baidu.com/item/广度优先搜索) | O(V+E) | O(V) |
| 图 | [深度优先搜索](https://baike.baidu.com/item/深度优先搜索) | O(V+E) | O(V) |
| 图 | [Dijkstra 最短路径](https://baike.baidu.com/item/迪杰斯特拉算法) | O((V+E) log V) | O(V) |
| 图 | [拓扑排序](https://baike.baidu.com/item/拓扑排序) | O(V+E) | O(V) |
| 哈希表 | [链地址法](https://baike.baidu.com/item/散列表) | O(1) | O(n) |
| 哈希表 | [开放寻址（线性探测）](https://baike.baidu.com/item/散列表) | O(1) | O(n) |

> 名称链接指向百度百科相关词条；哈希表两种冲突处理方式参考“散列表”词条。复杂度沿用演示目录的概览标注，并非所有输入和操作的最坏情况保证：快速排序、普通 BST 和哈希表均可能退化。
>
> 为便于观察，数组最多 20 个值，线性结构最多 30 条操作，图最多 10 个节点 / 20 条边，哈希表最多 24 次操作；树使用 7 个不同值生成随机示例，不提供手动操作编辑。

## 🚀 快速开始

**环境要求**：Node.js 版本满足 Nuxt 4.6 的约束 `^22.22.3 || ^24.15.0 || >=26.0.0`，并安装 pnpm。

```bash
# 克隆仓库
git clone https://gitee.com/CaiSre/dsa-visualizer.git
cd dsa-visualizer

# 安装依赖（统一使用 pnpm）
pnpm install

# 启动开发服务器（热更新）
pnpm dev
# → http://localhost:3000
```

> 项目统一使用 pnpm 管理依赖与脚本，请保留并使用仓库中的 `pnpm-lock.yaml`。

## 📦 常用命令

| 命令 | 说明 |
| :--- | :--- |
| `pnpm dev` | 开发服务器（热更新） |
| `pnpm build` | 生产构建 |
| `pnpm generate` | 静态生成，产物输出至 `.output/public` |
| `pnpm preview` | 本地预览构建产物 |
| `pnpm lint` | ESLint 检查 |
| `pnpm typecheck` | TypeScript 类型检查（strict） |
| `pnpm test` | 运行全部单元测试 |

## 🧪 测试

使用 Vitest、happy-dom 和 Vue Test Utils 验证算法步骤生成器、播放器、树动画状态、输入解析、
目录筛选与旧堆兼容。测试包括排序终态与元素守恒、空输入及首末步边界、播放中变速、
树旋转与增删、连续切步、减少动态效果、卸载清理，以及阅读区快捷键隔离。
另有步骤数与快照内存的性能回归测试；单测不替代真实浏览器的布局、触摸和动画验收。

```bash
pnpm test                                  # 全量运行
pnpm exec vitest run tests/sorting.test.ts # 运行单个文件
pnpm exec vitest run -t "二分查找"          # 按名称过滤用例
```

## 📁 项目结构

```
app/
├── pages/                        # 页面：index 目录页 + algorithm/[id] 详情页
├── layouts/                      # 布局
├── components/
│   ├── controls/                 # 播放控制条、输入面板（含线性结构操作编辑器）
│   └── views/                    # 可视化视图（ArrayBarView / TreeView / GraphView …）
├── composables/
│   ├── useAnimator.ts            # 步骤播放器状态机
│   └── useTreeAnimation.ts       # 树节点与连线的统一动画状态
├── algorithms/
│   ├── registry.ts               # 算法目录元数据（名称 / 复杂度 / 伪代码）
│   ├── array.ts                  # 数组 / 链表状态与步骤 recorder
│   ├── sorting/  search/         # 排序、查找步骤生成器
│   ├── linear/  tree/            # 线性结构、树步骤生成器
│   └── graph/  hash/             # 图、哈希表步骤生成器
├── utils/                        # 输入解析、目录筛选、快捷键边界与步骤样式
└── types/                        # AnimationStep 步骤协议、AlgorithmMeta
tests/                            # Vitest 单元测试
```

## 🏗️ 架构设计

核心原则是**算法与可视化分离**：

```
用户输入 ──▶ 算法步骤生成器（纯函数） ──▶ Step[] ──▶ useAnimator（播放器） ──▶ 视图组件（SVG 渲染）
```

- **算法层**：纯函数，只产出步骤序列（`generateSteps(input): Step[]`），不触碰 DOM 或组件状态，
  每一步携带操作后的不可变数据快照——因此可独立单元测试，回退与跳转天然可靠；
- **播放器层**：`useAnimator` 管理 `steps / currentIndex / isPlaying / speed`，
  提供 play / pause / 单步 / 重置 / seek 等操作，按速度推进并在末尾自动停止；
- **动画与视图层**：组件消费当前步骤的快照与高亮目标；`useTreeAnimation` 使用同一 RAF 推进树节点与连线，处理切步中断、增删和减少动态效果，不改变算法步骤协议。
- **工作台层**：`DemoShell` 统一画布、图例、步骤说明、控制条、数据编辑和参考页签；各演示容器持有自己的播放器，不创建全局共享播放状态。

## 🌐 构建与部署

```bash
pnpm generate
```

静态产物位于 `.output/public`，包含首页、21 个规范算法页面、旧 `/algorithm/heap` 兼容页面及兜底页面。
可部署至 Gitee Pages / GitHub Pages / Vercel / Netlify / Nginx 等静态托管，无需运行后端服务。
预渲染页面支持直接访问和刷新；发布时应使用整个 `.output/public`，而非仅复制首页。

## 🤝 参与贡献

欢迎提交 Issue 与 Pull Request。

1. Fork 本仓库并创建特性分支：`git checkout -b feature/your-feature`
2. 提交前请通过本地检查：`pnpm lint && pnpm typecheck && pnpm test && pnpm build`
3. 提交 Pull Request 并描述变更动机与验证结果

## 📄 许可证

本项目采用 [Apache License 2.0](./LICENSE) 开源。

---

## 🤖 开发说明

本项目由 [CodeArts](https://www.huaweicloud.com/product/codearts.html)、[Claude Code](https://claude.com/claude-code)、[Codex](https://openai.com/codex/) 及多个大模型工具联合设计开发。