# web-tools

**Repository Path**: RishChen/web-tools

## Basic Information

- **Project Name**: web-tools
- **Description**: 网页版工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Tools

一个基于 React + TypeScript + Vite 构建的前端工具门户项目。

当前版本已经从默认 Vite 模板改造成带有顶部横栏导航的工具站首页：
- 首页使用卡片式布局展示工具列表
- 点击卡片进入对应工具的二级菜单页
- 页面采用深色玻璃拟态风格
- 工具数据由统一配置驱动，便于后续继续扩展真实功能

## 项目预览

当前信息架构：
- `/`：首页，展示 hero 区、工具总览、推荐入口
- `/tools/:toolId`：工具菜单页，展示单个工具的简介和菜单入口
- `*`：兜底空状态页

当前内置的是示例工具工作区，包括：
- JSON 工坊
- 文本实验室
- 时间工作台
- 编码转换站
- 正则工位
- 色彩配方室

这些工具页目前主要承担“入口层”职责，用于建立清晰的导航与页面结构；后续可以在每个菜单项下继续补齐真实功能。

## 技术栈

- React 19
- TypeScript 5
- Vite 7
- React Router DOM
- ESLint
- 自定义 CSS 设计系统（基于 `src/index.css` + `src/App.css`）

## 启动与构建

安装依赖：

```bash
npm install
```

启动开发环境：

```bash
npm run dev
```

代码检查：

```bash
npm run lint
```

生产构建：

```bash
npm run build
```

本地预览构建结果：

```bash
npm run preview
```

## 环境变量

项目支持通过环境变量 `ICP_NUM` 和 `ICP_LINK` 动态注入网页底部的 ICP 备案号与跳转地址，`npm run dev` 与 `npm run build` 均会生效。

未提供 `ICP_NUM` 时，页面底部会继续显示默认占位文案 `备案号待补充`；未提供 `ICP_LINK` 时，会默认跳转到 `https://beian.miit.gov.cn/`。

推荐在项目根目录创建 `.env.local`：

```bash
ICP_NUM=京ICP备12345678号-1
ICP_LINK=https://beian.miit.gov.cn/
```

也可以在命令执行前临时注入环境变量。

PowerShell：

```powershell
$env:ICP_NUM='京ICP备12345678号-1'; $env:ICP_LINK='https://beian.miit.gov.cn/'; npm run dev
$env:ICP_NUM='京ICP备12345678号-1'; $env:ICP_LINK='https://beian.miit.gov.cn/'; npm run build
```

说明：
- `vite.config.ts` 已放开 `ICP_` 前缀环境变量注入
- 页面底部 ICP 展示值与跳转地址统一由 `src/data/siteMeta.ts` 读取

## 目录说明

```text
src/
  App.tsx                 应用路由壳层与顶部导航
  main.tsx                应用入口，挂载 BrowserRouter
  index.css               全局设计 token 与基础样式
  App.css                 页面布局、卡片、导航、响应式样式
  data/
    toolCatalog.ts        工具目录配置源
  pages/
    HomePage.tsx          首页
    ToolPage.tsx          工具菜单页
    NotFoundPage.tsx      兜底页
```

## 开发约定

### 1. 工具数据优先走配置驱动

工具名称、简介、路径、标签和二级菜单项统一维护在 `src/data/toolCatalog.ts`。

如果要新增一个工具，优先补充这份配置，而不是把内容分散写到多个页面组件里。首页卡片、顶部导航和工具菜单页都会自动复用这份数据。

### 2. 当前阶段优先维护入口层结构

当前项目重点是：
- 顶部横栏导航
- 首页工具卡片总览
- 工具菜单页跳转链路

如果后续要做真实工具功能，建议从现有 `ToolPage` 的菜单结构继续向下扩展，而不是推翻当前首页与导航体系。

### 3. 样式以现有设计系统为主

当前样式主要由 `src/index.css` 和 `src/App.css` 管理，已经形成统一的：
- 色彩变量
- 卡片容器
- 圆角与阴影
- section 标题结构
- 响应式断点

做视觉调整时，优先复用现有 token 和样式模式，避免引入第二套不一致的页面风格。

## 后续可扩展方向

你可以继续在这个项目上扩展：
- 为某个工具菜单项补充真实功能页面
- 增加搜索、分类筛选、收藏入口
- 让工具菜单页下钻到三级功能页
- 补充 README 截图、部署说明和产品介绍
- 将示例工具替换为真实业务工具集合

## 校验状态

最近一次已确认通过：
- `npm run lint`
- `npm run build`