Skip to content

Commit 3a81e47

Browse files
CC11001100CC11001100
committed
docs: 美化README和项目文档，添加详细说明和贡献指南
1 parent d4165df commit 3a81e47

File tree

4 files changed

+321
-53
lines changed

4 files changed

+321
-53
lines changed

‎CONTRIBUTING.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# 贡献指南
2+
3+
感谢您考虑为二叉树中序遍历可视化项目做出贡献！以下是参与本项目开发的指南。
4+
5+
## 如何贡献
6+
7+
贡献的方式有很多，不仅限于代码：
8+
9+
- 报告 Bug
10+
- 提交功能需求
11+
- 改进文档
12+
- 优化代码实现
13+
- 修复已知问题
14+
- 添加测试用例
15+
16+
## 开发流程
17+
18+
1. Fork 本仓库
19+
2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
20+
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
21+
4. 推送到分支 (`git push origin feature/amazing-feature`)
22+
5. 提交 Pull Request
23+
24+
## 提交规范
25+
26+
提交信息应遵循以下格式：
27+
28+
```
29+
<类型>: <描述>
30+
31+
[可选的详细描述]
32+
33+
[可选的关闭问题引用，例如: Closes #123]
34+
```
35+
36+
类型可以是：
37+
38+
- `feat`: 新功能
39+
- `fix`: 修复bug
40+
- `docs`: 文档变更
41+
- `style`: 代码风格变更（如格式化）
42+
- `refactor`: 代码重构
43+
- `perf`: 性能优化
44+
- `test`: 添加测试
45+
- `chore`: 构建过程或辅助工具变动
46+
47+
## 代码规范
48+
49+
- 遵循项目的代码风格和格式
50+
- 所有代码必须通过TypeScript编译
51+
- 添加适当的注释
52+
- 确保改动不会引入新的警告或错误
53+
54+
## 可视化组件开发规范
55+
56+
开发树可视化相关组件时，请确保：
57+
58+
1. 遵循[二叉树可视化规则](docs/二叉树可视化规则.md)文档中的指导
59+
2. 测试不同种类的树结构，包括：
60+
- 平衡和不平衡的树
61+
- 深度不同的树结构
62+
- 各种边缘情况（如空树、只有单个节点等）
63+
3. 确保节点不会重叠或布局错乱
64+
4. 保持响应式布局，适配不同屏幕尺寸
65+
66+
## 问题报告
67+
68+
提交问题时，请包含以下信息：
69+
70+
- 清晰的问题描述
71+
- 复现步骤
72+
- 预期行为与实际行为
73+
- 屏幕截图（如适用）
74+
- 浏览器和操作系统信息
75+
76+
## 拉取请求检查清单
77+
78+
- 更新文档（如适用）
79+
- 添加必要的测试
80+
- 确保所有测试通过
81+
- 保持代码简洁，遵循项目的代码风格
82+
- 在PR描述中描述您的更改
83+
84+
感谢您的贡献！

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2023 fuck-algorithm
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 215 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,216 @@
1-
# React + TypeScript + Vite
2-
3-
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
4-
5-
Currently, two official plugins are available:
6-
7-
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
8-
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
9-
10-
## Expanding the ESLint configuration
11-
12-
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
13-
14-
```js
15-
export default tseslint.config({
16-
extends: [
17-
// Remove ...tseslint.configs.recommended and replace with this
18-
...tseslint.configs.recommendedTypeChecked,
19-
// Alternatively, use this for stricter rules
20-
...tseslint.configs.strictTypeChecked,
21-
// Optionally, add this for stylistic rules
22-
...tseslint.configs.stylisticTypeChecked,
23-
],
24-
languageOptions: {
25-
// other options...
26-
parserOptions: {
27-
project: ['./tsconfig.node.json', './tsconfig.app.json'],
28-
tsconfigRootDir: import.meta.dirname,
29-
},
30-
},
31-
})
32-
```
33-
34-
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
35-
36-
```js
37-
// eslint.config.js
38-
import reactX from 'eslint-plugin-react-x'
39-
import reactDom from 'eslint-plugin-react-dom'
40-
41-
export default tseslint.config({
42-
plugins: {
43-
// Add the react-x and react-dom plugins
44-
'react-x': reactX,
45-
'react-dom': reactDom,
46-
},
47-
rules: {
48-
// other rules...
49-
// Enable its recommended typescript rules
50-
...reactX.configs['recommended-typescript'].rules,
51-
...reactDom.configs.recommended.rules,
52-
},
53-
})
1+
# 二叉树中序遍历可视化
2+
3+
<div align="center">
4+
5+
![GitHub license](https://img.shields.io/github/license/fuck-algorithm/leetcode-94-binary-tree-inorder-traversal)
6+
![GitHub stars](https://img.shields.io/github/stars/fuck-algorithm/leetcode-94-binary-tree-inorder-traversal)
7+
![GitHub forks](https://img.shields.io/github/forks/fuck-algorithm/leetcode-94-binary-tree-inorder-traversal)
8+
![GitHub issues](https://img.shields.io/github/issues/fuck-algorithm/leetcode-94-binary-tree-inorder-traversal)
9+
10+
</div>
11+
12+
<p align="center">
13+
<img src="assets/images/tree-demo.png" alt="二叉树中序遍历演示" width="800" />
14+
</p>
15+
16+
## 📖 项目简介
17+
18+
这是一个交互式的二叉树中序遍历可视化工具，帮助学习者理解二叉树中序遍历算法的实现原理和执行过程。本项目实现了 [LeetCode 94. 二叉树的中序遍历](https://leetcode.cn/problems/binary-tree-inorder-traversal/) 问题的可视化解答。
19+
20+
通过动态展示二叉树的遍历过程，包括节点访问顺序、栈的变化和结果数组的构建，学习者能够直观地理解"左-根-右"的中序遍历模式。
21+
22+
## ✨ 核心特性
23+
24+
- 🌲 **直观的树结构可视化**：使用D3.js渲染二叉树，清晰展示节点关系
25+
- 🔄 **递归和迭代双实现**：提供递归和迭代两种方式的中序遍历实现
26+
- 📊 **详细步骤追踪**：记录并展示遍历过程中的每个细节步骤
27+
- 📚 **栈状态可视化**：直观展示遍历过程中栈的变化情况
28+
- 🎮 **交互式控制**：支持单步执行、自动播放、速度调节等控制功能
29+
- 🎯 **节点高亮**：高亮显示当前访问的节点、已访问节点和栈中节点
30+
- 🎲 **随机树生成**：一键生成随机二叉树进行学习和测试
31+
- 📱 **响应式设计**：适配不同屏幕大小，提供良好的移动设备体验
32+
33+
## 🚀 在线体验
34+
35+
访问 [https://fuck-algorithm.github.io/leetcode-94-binary-tree-inorder-traversal/](https://fuck-algorithm.github.io/leetcode-94-binary-tree-inorder-traversal/) 即可在线体验本项目。
36+
37+
## 📦 本地安装与运行
38+
39+
### 前置条件
40+
41+
- Node.js 16.0.0 或更高版本
42+
- npm 7.0.0 或更高版本
43+
44+
### 安装步骤
45+
46+
1. 克隆仓库
47+
48+
```bash
49+
git clone https://github.com/fuck-algorithm/leetcode-94-binary-tree-inorder-traversal.git
50+
cd leetcode-94-binary-tree-inorder-traversal
51+
```
52+
53+
2. 安装依赖
54+
55+
```bash
56+
npm install
57+
```
58+
59+
3. 启动开发服务器
60+
61+
```bash
62+
npm run dev
63+
```
64+
65+
4. 打开浏览器访问 `http://localhost:5173`
66+
67+
### 构建项目
68+
69+
```bash
70+
npm run build
71+
```
72+
73+
## 🔍 使用指南
74+
75+
1. **树的输入**：
76+
- 直接输入数组形式的树结构，如 `[1,null,2,3]`
77+
- 点击"生成随机树"按钮创建随机结构
78+
- 使用示例按钮选择预设的树结构
79+
80+
2. **遍历算法选择**：
81+
- 选择"递归"或"迭代"方法实现中序遍历
82+
83+
3. **控制遍历过程**：
84+
- 使用底部控制栏的按钮控制遍历过程
85+
- 支持"上一步"、"下一步"、"自动播放"等操作
86+
- 使用滑块调节自动播放速度
87+
- 支持键盘快捷键（← → 空格 R）控制
88+
89+
4. **观察结果**：
90+
- 树可视化区域：显示当前节点访问状态
91+
- 栈可视化区域：展示栈的变化
92+
- 结果区域：显示遍历结果数组
93+
94+
## 🛠️ 技术实现
95+
96+
本项目采用了以下技术和库：
97+
98+
- **前端框架**：React 18 + TypeScript
99+
- **构建工具**：Vite
100+
- **可视化库**：D3.js
101+
- **状态管理**：React Hooks
102+
- **样式处理**：CSS Module
103+
- **自动部署**：GitHub Actions
104+
105+
### 核心算法实现
106+
107+
<details>
108+
<summary>点击展开查看递归实现</summary>
109+
110+
```typescript
111+
export function inorderTraversalRecursive(root: TreeNode | null): number[] {
112+
const result: number[] = [];
113+
114+
function inorder(node: TreeNode | null) {
115+
if (!node) return;
116+
117+
// 左子树
118+
inorder(node.left);
119+
120+
// 根节点
121+
result.push(node.val);
122+
123+
// 右子树
124+
inorder(node.right);
125+
}
126+
127+
inorder(root);
128+
return result;
129+
}
54130
```
131+
</details>
132+
133+
<details>
134+
<summary>点击展开查看迭代实现</summary>
135+
136+
```typescript
137+
export function inorderTraversalIterative(root: TreeNode | null): number[] {
138+
const result: number[] = [];
139+
const stack: TreeNode[] = [];
140+
let current = root;
141+
142+
while (current || stack.length) {
143+
// 一直遍历到最左边的节点
144+
while (current) {
145+
stack.push(current);
146+
current = current.left;
147+
}
148+
149+
// 处理当前节点
150+
current = stack.pop()!;
151+
result.push(current.val);
152+
153+
// 处理右子树
154+
current = current.right;
155+
}
156+
157+
return result;
158+
}
159+
```
160+
</details>
161+
162+
## 📚 项目结构
163+
164+
```
165+
src/
166+
├── algorithms/ # 算法实现
167+
│ └── inorderTraversal.ts
168+
├── components/ # 界面组件
169+
│ ├── BinaryTreeInorderTraversal.tsx
170+
│ ├── StackVisualization.tsx
171+
│ ├── TreeInputExamples.tsx
172+
│ └── TreeVisualization.tsx
173+
├── types/ # 类型定义
174+
│ └── TreeNode.ts
175+
├── utils/ # 工具函数
176+
│ └── tree/
177+
│ ├── treeAnalysis.ts
178+
│ ├── treeLayout.ts
179+
│ ├── treeOptimization.ts
180+
│ ├── treeRenderer.ts
181+
│ ├── treeScaling.ts
182+
│ └── treeTypes.ts
183+
├── App.tsx
184+
└── main.tsx
185+
```
186+
187+
## 📌 项目规范
188+
189+
项目遵循以下规范确保代码质量和可维护性：
190+
191+
- 模块化设计，清晰的职责分离
192+
- TypeScript 类型安全
193+
- 组件库设计模式
194+
- 算法实现与UI展示分离
195+
- 详细注释和文档
196+
- 统一的代码风格
197+
198+
更多细节请参考 [docs/二叉树可视化规则.md](docs/二叉树可视化规则.md)。
199+
200+
## 🤝 贡献
201+
202+
欢迎贡献代码、报告问题或提出改进建议！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与贡献。
203+
204+
## 📄 许可证
205+
206+
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
207+
208+
## 📧 联系方式
209+
210+
如有问题或建议，请通过 GitHub Issues 联系我们。
211+
212+
---
213+
214+
<div align="center">
215+
<sub>Built with ❤️ by fuck-algorithm team</sub>
216+
</div>

‎assets/images/tree-demo.png‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)