# 📚 数据结构可视化学习中心 · 使用指南

> 一个在浏览器里"看见"C 程序如何操作内存的互动学习工具。
> 无需安装任何软件，打开网址即可使用。

**在线访问**：https://ds-viz4.pages.dev （国内直连）
备用地址：https://ds-viz-six.vercel.app

---

## 一、快速上手（30 秒）

1. 打开网址，**注册一个账号**（用户名 + 密码，数据只存在你自己的浏览器里）
2. 登录后进入**学习中心**，点击 **「🔗 线性表」** 卡片
3. 进入调试器后，点顶部绿色按钮 **「▶ 开始运行」**

你会看到：左边代码逐行高亮执行，右边栈内存、堆内存、图形视图同步变化。

---

## 二、三种身份用法

### 👀 我想看演示（零基础推荐）

从顶部下拉框选一个内置程序：

| 程序 | 演示内容 | 运行结果 |
|------|---------|---------|
| 单链表(头插法建表+遍历) | for 循环头插建 3 节点 | 输出 `30 20 10` |
| 单链表(尾插法建表+遍历) | tail 指针尾插，顺序不变 | 输出 `10 20 30` |
| 单链表(查找元素) | while+计数器找值为 20 的节点 | 输出 `找到 20, 位置 2` |
| 顺序表(插入+删除) | 数组存取与 length 增减 | 遍历后删除末尾元素 |

然后按 **「▶ 开始运行」** 看动画，或按 **「单步 ⤵」** 一行一行观察。

### ✍️ 我想写自己的代码

1. 点 **「＋ 新建 ▾」→「✍ 空白代码」**
2. 在编辑器里写 C 代码（右侧有帮助面板列出支持的语法）
3. 编辑区下方会**实时显示语法检查结果**（绿色 ✓ / 红色 ✗+原因）
4. 点 **「▶ 运行此代码」** 立即执行；点 **「💾 保存到我的程序」** 可命名收藏
5. 已保存的程序在下拉框「我的程序」分组里，随时再次运行

支持的语法：变量声明（`Node *p` / `int i`）、`malloc`/`free`、成员赋值（`p->data = 10`）、for/while/if-else 循环嵌套、printf、注释。

### 🗂️ 我想管理我的代码

在程序下拉框上**点击鼠标右键**，弹出管理菜单：

- ▶ 运行此程序
- ✍ 编辑代码（重新打开编辑器修改）
- ✏ 重命名
- 🗑 删除（需确认）

内置的 4 个教学程序不可删除，你自己的随便整理。

---

## 三、界面导览

```
┌──────────────┬─────────────┬──────────────┐
│  📄 代码区    │ 🧱 栈 Stack │ 👁️ 具象化视图 │
│  (逐行高亮)   │ 变量框       │  (浮动弹窗)   │
│              ├─────────────┤              │
│  ──可拖动──   │ 🗑️ 堆 Heap  │              │
│  📤 程序输出  │ malloc块     │              │
└──────────────┴─────────────┴──────────────┘
```

- **代码区**：当前执行行蓝色高亮；循环会真实回跳到循环头再判断
- **栈 Stack**：局部变量和指针。指针值显示为 `NULL` 或 `0x1020` 这样的地址
- **堆 Heap**：每次 `malloc` 凭空出现一个带地址的节点块；紫色箭头画出指针指向
- **具象化视图（浮窗）**：点顶栏「👁️ 具象化视图」打开。链表画成一串方框（左=数据，右=地址），箭头落在哪个框就指向哪个框。**整个窗口可以按住标题栏拖到屏幕任意位置**

### 所有边界都能拖动

| 拖动条 | 作用 |
|--------|------|
| 代码区右缘 ↔ 栈区 | 调整代码区宽度 |
| 栈区 ↔ 堆区之间 | 调整栈/堆宽度 |
| 堆区 ↔ 具象化入口 | 堆区加宽（推荐拖大）|
| 代码区下方横条 | 调整代码/输出高度 |

悬停在分隔条上会亮蓝色提示可拖。

---

## 四、控制按钮与快捷键

| 按钮/按键 | 功能 |
|-----------|------|
| ▶ 开始运行 | 自动播放（速度由滑块控制，左慢右快）|
| 单步 ⤵ | 执行一行就停，适合仔细观察 |
| 重置 ⟲ | 清空状态回到第一行 |
| `空格` | 播放 / 暂停 |
| `F10` 或 `S` | 单步 |
| `R` | 重置 |
| `Esc` | 关闭浮窗 / 编辑器 / 右键菜单 |

运行结束后播放按钮变成 **「↻ 重新运行」**，一键重看。

🎬 **演示模式**：一键放大全部字号，教室投屏必备。

---

## 五、学习建议

1. **先看头插法**：注意第 15-16 行——新节点的 next 先牵住旧链表，head 再回头指向新节点，顺序反了链就断了
2. **对比尾插法**：多了一个 tail 指针永远盯着队尾，还有关键的 `p = head`（遍历前回到链表头）
3. **试着自己写**：比如写一个"删除值为 X 的节点"，写错也没关系，看内存怎么乱掉本身就是学习
4. **观察堆区**：顺序表程序的堆区是空的！因为数组在栈上连续排列——这就是两种结构的本质区别

---

## 六、常见问题

**Q：我保存的代码别人能看到吗？**
看不到。每个账号的数据存在各自的浏览器里（localStorage），互不相通。

**Q：换电脑/清浏览器数据后代码还在吗？**
不在。数据是本地存储的，建议重要代码复制一份文本保存。

**Q：手机能用吗？**
可以。窄屏下自动切换为上下堆叠布局，所有拖动条支持手指触控。

**Q：支持哪些 C 语法？**
够教学用的子集：声明、赋值、malloc/free、指针运算、数组、for/while/if、printf。不支持函数定义、递归、结构体自定义等（编辑器会给出中文提示）。

**Q：页面打不开怎么办？**
试试备用地址，或让同学把两个 html 文件发给你，双击本地打开效果完全一样。

---

## 七、隐私与安全

- 密码经 PBKDF2（10 万次迭代）加盐哈希后存储，**服务器和页面作者都无法得知你的原密码**
- 全程无网络请求、无追踪、无广告
- 详细安全设计见仓库中的 [SECURITY.md](SECURITY.md)

---

*本项目纯前端实现，源码公开：[GitHub](https://github.com/zjc-bot/ds-viz) · [Gitee](https://gitee.com/wojiubuxinglenitamade/ds-viz)*