# page-stack

**Repository Path**: renyk/page-stack

## Basic Information

- **Project Name**: page-stack
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PageStack — 页面导航管理系统

纯前端页面导航管理工具，支持页面收藏、分类管理、搜索过滤、数据持久化及暗色主题。

## 功能说明

### 页面管理
- **添加页面** — 填写标题、URL、描述，选择所属分类；支持 `http://` / `https://` 协议校验
- **编辑页面** — 鼠标悬停卡片显示编辑按钮，可修改全部字段
- **删除页面** — 提供确认弹窗，防止误删
- **页面跳转** — 点击卡片在新标签页打开对应网址
- **页面排序** — 支持上移/下移调整页面在分类内的排列顺序
- **视图切换** — 网格视图（带描述文字）和列表视图（紧凑排列）

### 分类管理
- **自定义分类** — 创建/编辑/删除分类，支持选择颜色和图标（12 种 Lucide 图标 + 8 种预设颜色）
- **分类筛选** — 侧边栏点选分类过滤页面，支持"全部页面"视图
- **页面计数** — 每个分类旁显示所含页面数量

### 搜索
- 实时关键字搜索，匹配标题和描述字段

### 主题
- 亮色 / 暗色主题一键切换
- 刷新页面保持主题状态，无闪烁
- 未手动设置时自动跟随系统偏好

### 数据存储（三层策略）

| 层级 | 方式 | 特点 |
|------|------|------|
| 自动保存 | `localStorage` | 无需任何配置，开箱即用；浏览器清除缓存会丢失 |
| 手动导出 | 导出/导入 JSON 文件 | 点击侧边栏按钮，适合数据迁移或备份 |
| 本地文件 | File System Access API | 选择本地 JSON 文件后自动读写，数据存于磁盘，不受浏览器缓存影响 |

> **注意**：使用 File System Access API 存储时，刷新页面后可能需要点击"重新连接"以恢复文件写入权限（浏览器安全策略要求）。

### 页面图标
- 自动请求目标网站 `/favicon.ico` 作为页面图标
- 获取失败时显示标题首字母头像（颜色由域名哈希决定，同域名同颜色）
- 模块级缓存，切换分类不会重新请求

---

## 技术栈

| 技术 | 用途 |
|------|------|
| React 18 + TypeScript | 前端框架，类型安全 |
| Vite 6 | 构建工具，开发服务器 |
| Tailwind CSS 3 + tailwindcss-animate | 原子化 CSS，动画 |
| Lucide React | 图标库 |
| CVA + clsx + tailwind-merge | 组件变体管理，className 合并 |
| File System Access API | 本地文件持久化 |
| IndexedDB | 缓存文件句柄 |

---

## 项目结构

```
page-stack/
├── index.html                     # HTML 入口（含主题预加载脚本）
├── package.json
├── vite.config.ts                 # Vite 配置，@ 路径别名
├── tsconfig.json / tsconfig.app.json
├── tailwind.config.ts             # 暗色模式、自定义颜色、动画
├── postcss.config.js
└── src/
    ├── main.tsx                   # React 入口
    ├── App.tsx                    # 主组件，状态编排
    ├── index.css                  # 全局样式，CSS 变量（亮/暗主题）
    ├── vite-env.d.ts
    ├── types/
    │   └── index.ts               # 类型定义 & 常量
    ├── lib/
    │   ├── store.ts               # 状态管理（useReducer + localStorage）
    │   ├── fileStorage.ts         # File System Access API 存储
    │   ├── theme.ts               # 主题管理
    │   └── utils.ts               # cn() 工具函数
    └── components/
        ├── Header.tsx             # 顶栏（搜索、视图切换、主题切换、添加）
        ├── Sidebar.tsx            # 侧边栏（分类导航、文件存储、导入导出）
        ├── PageGrid.tsx           # 页面网格/列表渲染
        ├── PageCard.tsx           # 页面卡片
        ├── Favicon.tsx            # 网站图标（含首字母回退）
        ├── EmptyState.tsx         # 空状态占位
        ├── PageDialog.tsx         # 添加/编辑页面弹窗
        ├── CategoryDialog.tsx     # 添加/编辑分类弹窗
        ├── DeleteConfirm.tsx      # 删除确认弹窗
        └── ui/
            ├── button.tsx
            ├── input.tsx
            ├── dialog.tsx
            ├── badge.tsx
            └── toast.tsx
```

---

## 开发

```bash
# 安装依赖
npm install

# 启动开发服务器（默认 http://localhost:5173）
npm run dev

# 类型检查 + 构建（输出到 dist/）
npm run build

# 预览构建产物
npm run preview
```

---

## 部署

### 静态文件部署

构建产物在 `dist/` 目录，可直接部署到任意静态文件服务器。

### Nginx 部署

```nginx
server {
    listen       80;
    server_name  your-domain.com;

    root   /path/to/pagestack/dist;
    index  index.html;

    # SPA 路由支持：所有路径回退到 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长期缓存（Vite 构建自动添加哈希）
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 开启 gzip 压缩
    gzip            on;
    gzip_types      text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
    gzip_min_length 1000;
}
```

### 关键说明
- `try_files $uri $uri/ /index.html` 确保 SPA 路由正常工作，直接访问子路径不会 404
- Vite 构建产物中的 `/assets/` 文件已包含内容哈希，可放心开启长期缓存
- 如果部署在子路径（如 `/pagestack/`），需在 `vite.config.ts` 中设置 `base: '/pagestack/'`，并在 Nginx 中对应调整 `location` 配置

---

## 浏览器兼容性

- **File System Access API**（本地文件存储）仅 Chromium 内核浏览器支持（Chrome / Edge / Opera）
- 不支持的浏览器自动降级为 `localStorage` 存储 + 手动导入导出
- 其余功能（页面管理、分类、主题、搜索）在所有现代浏览器中可用