# SoftBox

**Repository Path**: Destiny_cc/SoftBox

## Basic Information

- **Project Name**: SoftBox
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SoftBox

发现最好的开源免费软件 —— 一个纯前端的开源软件目录站。

## 功能特性

- 🔍 关键词搜索（名称 / 描述 / 标签）+ 10 类分类筛选
- ↕️ 多种排序：热度 / 评分 / 下载量 / 更新时间
- ⭐ 收藏（`localStorage` 持久化）+ Toast 反馈
- 🌓 深 / 浅色主题切换并记忆
- 💡 软件详情弹窗，**URL 可分享**（`#/software/:id`，支持浏览器前进 / 后退）
- ♿ 可访问性：弹窗 ESC 关闭、Tab 焦点陷阱、背景滚动锁定、`aria` 标注
- 📱 响应式布局 + 滚动渐入 + 骨架屏
- 📑 前端分页「加载更多」
- 🔗 导航锚点平滑滚动

## 技术栈

- React 18
- Vite 5
- Tailwind CSS v4（`@tailwindcss/vite`，CSS-first 配置，无 `tailwind.config.js`）
- 纯前端、无后端、无状态管理库、无路由库（自实现轻量 hash 路由）

## 快速开始

```bash
# 安装依赖
npm install

# 开发模式（默认 http://localhost:5173）
npm run dev

# 生产构建
npm run build

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

> 说明：本项目为纯静态前端，数据硬编码在 `src/data.js`，无需任何后端或接口即可运行。
> 在某些受限环境中，Vite 首次启动可能因清理 `.vite` 缓存失败而报错；可手动 `mv node_modules/.vite node_modules/.vite.bak` 后重试。

## 目录结构

```
softbox/
├── index.html              # 入口 HTML（含 SEO / Open Graph 元数据）
├── src/
│   ├── main.jsx            # 应用入口
│   ├── App.jsx             # 主容器：搜索 / 筛选 / 排序 / 分页 / 路由 / 详情
│   ├── data.js             # 全部静态数据（分类、平台、许可证、软件列表、热门、更新、统计）
│   ├── index.css           # Tailwind v4 主题变量 + 深色模式 + 动画
│   ├── components/
│   │   ├── Header.jsx          # 顶栏（搜索、主题切换、导航锚点）
│   │   ├── Hero.jsx            # 首屏（搜索框、统计数字）
│   │   ├── CategoryBar.jsx     # 分类筛选条
│   │   ├── SoftwareCard.jsx    # 软件卡片
│   │   ├── SoftwareDetail.jsx  # 软件详情弹窗（可访问性增强）
│   │   ├── TrendingSidebar.jsx # 热门排行榜
│   │   ├── RecentUpdates.jsx   # 最新更新（图标复用 softwareList）
│   │   ├── StarRating.jsx      # 星级评分（抽离复用）
│   │   ├── AnimatedCard.jsx    # 滚动渐入卡片
│   │   ├── SkeletonLoader.jsx  # 骨架屏
│   │   ├── BackToTop.jsx       # 回到顶部
│   │   └── Toast.jsx           # 轻提示
│   ├── hooks/
│   │   └── useTheme.js         # 深/浅色主题（系统偏好 + localStorage）
│   └── utils/
│       └── format.js           # 下载量格式化（抽离复用）
└── public/                  # 静态资源
```

## 数据结构

所有数据位于 `src/data.js`：

- `categories`：10 个分类（全部 / 系统工具 / 开发工具 / 设计创意 / 影音娱乐 / 办公效率 / 安全隐私 / 网络工具 / 浏览器 / 操作系统）
- `platforms`：6 个平台（Windows / macOS / Linux / Android / iOS / Web）
- `licenses`：4 种许可证（免费 / 开源 / 免费增值 / 专有），用于卡片标签配色
- `softwareList`：软件数组，**页面所有统计数字（如「已收录 X 款」）均由该数组长度动态计算**
- `trendingList` / `recentUpdates`：热门榜与最新更新（侧栏展示）
- `stats`：展示用统计（部分徽标文案）

新增一款软件只需在 `softwareList` 追加一个对象（字段参考现有条目）。

## 路由说明（可分享详情）

未引入路由库，采用零依赖的 hash 路由：

- 打开详情：`history.pushState` 写入 `#/software/:id`
- 关闭详情：清除 hash 回到无参 URL
- 监听 `hashchange`：支持浏览器前进 / 后退、直接打开分享链接自动恢复弹窗

## 可访问性

- 详情弹窗：`role="dialog"` + `aria-modal`，ESC 关闭，Tab 焦点陷阱，打开时锁定背景滚动并自动聚焦
- 分类按钮：`aria-label` + `aria-pressed`
- 主题切换按钮：`aria-label`

## 已知问题

- `npm run lint` 因 `eslint.config.js` 中 `reactHooks.configs.flat.recommended` 在已安装插件版本中导出为 `undefined` 而无法运行，属项目原有配置缺陷，待修复。
- 数据为静态硬编码，热门榜 / 最新更新为固定展示，未与软件列表自动联动。