1275 lines
27 KiB
Markdown
1275 lines
27 KiB
Markdown
# Polaris 分类页设计文档
|
||
|
||
> 关联文档：
|
||
> [Polaris 项目说明文档](./Polaris%20项目说明文档.md) —— 项目定位、技术选型、数据结构、开发阶段
|
||
> [Polaris 首页设计文档](./Polaris%20首页设计文档.md) —— 首页布局与搜索交互
|
||
|
||
## 0. 当前实现状态（2026-10-14 校对）
|
||
|
||
本章为现状说明。第 1–23 章保留立项时的历史设计意图；其中浅色玻璃样式、白色大面板容器和数据示例均为历史方案，视觉细节以本章与 `src/app/globals.css` 为准。
|
||
|
||
- **路由**：`/categories/[categoryId]` 已实现，8 个分类全部静态预生成，未知分类返回 404。
|
||
- **布局**：左侧边栏与首页一致（桌面固定悬浮；≤767px 变为顶部横栏，折叠按钮隐藏、导航横向滚动）。主内容区**不再是一整块白色玻璃面板**——面板容器透明，使背景素材保持清晰，玻璃只压在承载文字的元素上：标题与描述带轻边框和文字投影，「全部工具」列表放在一层薄纱视口（rgba(5, 14, 29, 0.18)、圆角 20px）内，工具卡片为深色玻璃。
|
||
- **滚动**：桌面端页面高度固定为 `100svh`，工具列表在内部视口滚动（`overscroll-behavior: contain`、可聚焦）；视口过矮（`max-height` 断点）或移动端回退为整页滚动。
|
||
- **网格现状**：工具网格基础为两列；≥1280px 升为三列，≤999px 降为单列，即 1000–1279px 保持两列。手机顶部横栏与单列已完成；平板/中等窗口的两列已实现，与历史计划（768px–1279px 两列）的差异仅剩 768px–999px 区间当前同为单列。
|
||
- **视觉**：深色玻璃主题，tokens 与首页共用（见[首页设计文档](./Polaris%20首页设计文档.md)第 0 章）；背景素材可整体替换，背景层显示与遮罩样式由现有 CSS 管理，素材类型/路径/画面不作为设计规范。
|
||
- **数据现状**：全站 8 个分类共 51 条链接；本文以「开发工具」为例的数据（15 条）为立项期示意，当前该分类实际 12 条。
|
||
|
||
## 1. 页面定位
|
||
|
||
Polaris 的分类页用于展示某一类导航资源，例如：
|
||
|
||
```text
|
||
开发工具
|
||
AI 工具
|
||
设计资源
|
||
学习资料
|
||
效率工具
|
||
娱乐媒体
|
||
生活服务
|
||
```
|
||
|
||
分类页不是后台管理页，也不是资源管理面板，而是首页的延伸页面。
|
||
|
||
它的核心目标是：
|
||
|
||
1. 清晰展示当前分类下的所有链接；
|
||
2. 保持和首页一致的轻玻璃视觉风格；
|
||
3. 让用户可以快速浏览并打开目标网站；
|
||
4. 不引入过多管理、筛选、编辑类元素；
|
||
5. 保持页面干净、安静、克制。
|
||
|
||
分类页应给人的感觉是：
|
||
|
||
> 我进入了某一类个人收藏资源，可以直接浏览和访问，而不是进入了一个复杂的管理系统。
|
||
|
||
---
|
||
|
||
## 2. 页面示例
|
||
|
||
本文档以 **开发工具页** 为例进行说明。
|
||
|
||
页面标题：
|
||
|
||
```text
|
||
开发工具
|
||
```
|
||
|
||
页面描述：
|
||
|
||
```text
|
||
高效的开发工具和资源集合，提升你的开发体验和效率。
|
||
```
|
||
|
||
展示内容示例：
|
||
|
||
```text
|
||
GitHub
|
||
GitLab
|
||
Bitbucket
|
||
VS Code
|
||
JetBrains
|
||
GoLand
|
||
Postman
|
||
Docker
|
||
Kubernetes
|
||
Vercel
|
||
Netlify
|
||
Render
|
||
npm
|
||
pnpm
|
||
Figma
|
||
```
|
||
|
||
其他分类页面复用相同结构，只需要替换分类名称、描述和链接数据。
|
||
|
||
> 2026-10-14 说明：本节与第 12 节的链接清单、数量均为立项期示意数据，不代表当前 `src/data/` 内容。
|
||
|
||
---
|
||
|
||
## 3. 与首页的关系
|
||
|
||
首页负责最高频入口：
|
||
|
||
```text
|
||
时间 / 日期
|
||
全局搜索框
|
||
常用链接
|
||
左侧分类导航
|
||
```
|
||
|
||
分类页负责分类浏览：
|
||
|
||
```text
|
||
分类标题
|
||
分类说明
|
||
链接数量
|
||
该分类下的网站卡片
|
||
```
|
||
|
||
首页有全局搜索框，分类页默认不展示搜索框。
|
||
|
||
这样可以避免功能重复，也能让分类页更像一个干净的资源浏览页面。
|
||
|
||
---
|
||
|
||
## 4. 分类页不保留搜索框
|
||
|
||
当前分类页不展示顶部搜索框。
|
||
|
||
原因：
|
||
|
||
1. 首页已经存在全局搜索框；
|
||
2. 分类页主要任务是浏览当前分类资源；
|
||
3. 再放搜索框会让页面变得像后台或资源管理器；
|
||
4. 搜索框会削弱分类标题和内容列表的视觉层级；
|
||
5. 用户可能困惑搜索范围是全站、当前分类，还是外部搜索引擎。
|
||
|
||
因此分类页第一版只保留内容展示，不放搜索框。
|
||
|
||
如果未来某个分类链接数量非常多，例如超过 30 个，可以考虑增加一个轻量的分类内筛选输入框，但它不应该是首页那种大搜索框，也不应该支持 Google、Bing、GitHub 等外部搜索。
|
||
|
||
未来可选方案：
|
||
|
||
```text
|
||
仅当前分类内筛选
|
||
小尺寸输入框
|
||
弱视觉权重
|
||
不放在第一视觉中心
|
||
```
|
||
|
||
当前阶段不实现。
|
||
|
||
---
|
||
|
||
## 5. 页面整体布局
|
||
|
||
分类页整体仍采用左右结构：
|
||
|
||
```text
|
||
┌──────────────────┬────────────────────────────────────────────┐
|
||
│ 左侧边栏 │ 分类内容区域 │
|
||
│ │ │
|
||
│ Logo + 折叠按钮 │ 分类标题 │
|
||
│ 首页 │ 分类描述 │
|
||
│ AI 工具 │ │
|
||
│ 开发工具 │ 全部工具 共 15 个 │
|
||
│ 设计资源 │ │
|
||
│ 学习资料 │ 工具卡片网格 │
|
||
│ 效率工具 │ │
|
||
│ 娱乐媒体 │ │
|
||
│ 生活服务 │ │
|
||
└──────────────────┴────────────────────────────────────────────┘
|
||
```
|
||
|
||
布局原则：
|
||
|
||
1. 左侧边栏保持和首页一致；
|
||
2. 主内容区域使用玻璃面板承载；
|
||
3. 页面顶部展示分类标题和说明；
|
||
4. 内容区展示链接卡片；
|
||
5. 不展示搜索框；
|
||
6. 不展示排列切换；
|
||
7. 不展示编辑按钮；
|
||
8. 不展示设置按钮。
|
||
|
||
---
|
||
|
||
## 6. 左侧边栏
|
||
|
||
### 6.1 边栏内容
|
||
|
||
左侧边栏和首页保持一致。
|
||
|
||
展开状态下包含：
|
||
|
||
```text
|
||
Logo
|
||
折叠按钮
|
||
首页
|
||
AI 工具
|
||
开发工具
|
||
设计资源
|
||
学习资料
|
||
效率工具
|
||
娱乐媒体
|
||
生活服务
|
||
```
|
||
|
||
开发工具页中，左侧边栏的 **开发工具** 项处于选中状态。
|
||
|
||
---
|
||
|
||
### 6.2 选中态
|
||
|
||
开发工具项选中时，使用浅蓝紫色玻璃背景。
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
background: rgba(99, 102, 241, 0.1);
|
||
color: #2563eb;
|
||
```
|
||
|
||
> 2026-10-14 实现状态：上方浅蓝紫数值为历史方案。当前选中态为 `--primary-soft`（rgba(147, 190, 255, 0.15)）底色 + `--primary-hover` 文字色 + 一圈淡色内描边，圆角 16px 不变。
|
||
|
||
图标和文字同时高亮。
|
||
|
||
选中项圆角：
|
||
|
||
```css
|
||
border-radius: 16px;
|
||
```
|
||
|
||
选中态不要使用高饱和、大面积实色块，否则会破坏轻玻璃风格。
|
||
|
||
---
|
||
|
||
### 6.3 折叠按钮
|
||
|
||
折叠按钮仍然放在侧边栏顶部右侧，与 Logo 同一行。
|
||
|
||
示意：
|
||
|
||
```text
|
||
┌──────────────────────┐
|
||
│ Logo ≪ │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
不使用侧边栏中间悬浮折叠按钮。
|
||
|
||
按钮样式应低调：
|
||
|
||
```css
|
||
width: 32px;
|
||
height: 32px;
|
||
border-radius: 10px;
|
||
background: transparent;
|
||
color: #334155;
|
||
```
|
||
|
||
Hover 状态：
|
||
|
||
```css
|
||
background: rgba(15, 23, 42, 0.06);
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 主内容容器
|
||
|
||
### 7.1 容器定位
|
||
|
||
分类页主内容区域使用一个大的玻璃面板承载内容。
|
||
|
||
该面板与首页视觉风格一致，但内容密度略高。
|
||
|
||
推荐布局：
|
||
|
||
```text
|
||
┌────────────────────────────────────────────┐
|
||
│ │
|
||
│ 开发工具 │
|
||
│ 高效的开发工具和资源集合，提升你的开发体验... │
|
||
│ │
|
||
│ 全部工具 共 15 个 │
|
||
│ │
|
||
│ 工具卡片网格 │
|
||
│ │
|
||
└────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
### 7.2 容器样式
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
background: rgba(255, 255, 255, 0.56);
|
||
backdrop-filter: blur(24px);
|
||
border: 1px solid rgba(255, 255, 255, 0.48);
|
||
border-radius: 24px;
|
||
box-shadow: 0 24px 80px rgba(15, 23, 42, 0.1);
|
||
```
|
||
|
||
> 2026-10-14 实现状态：上方白色玻璃面板为历史方案。当前面板容器已透明化（见第 0 章）：`GlassPanel` 结构保留，但边框、背景、阴影与 backdrop-filter 均被覆盖为透明或无，背景素材直接可见。
|
||
|
||
容器与页面边距：
|
||
|
||
```css
|
||
margin: 24px 30px 24px 0;
|
||
```
|
||
|
||
如果左侧边栏悬浮在页面内，主容器左侧应与边栏保持间距：
|
||
|
||
```css
|
||
gap: 24px;
|
||
```
|
||
|
||
---
|
||
|
||
### 7.3 容器内部间距
|
||
|
||
推荐内边距：
|
||
|
||
```css
|
||
padding: 56px 64px;
|
||
```
|
||
|
||
小屏幕可降低为：
|
||
|
||
```css
|
||
padding: 32px 24px;
|
||
```
|
||
|
||
内容区域不应贴边，玻璃面板内部需要足够留白。
|
||
|
||
---
|
||
|
||
## 8. 分类标题区域
|
||
|
||
### 8.1 标题
|
||
|
||
开发工具页标题为：
|
||
|
||
```text
|
||
开发工具
|
||
```
|
||
|
||
标题是页面主视觉之一，但不需要像首页时间那样巨大。
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
font-size: 40px;
|
||
font-weight: 700;
|
||
color: #0f172a;
|
||
letter-spacing: -0.02em;
|
||
```
|
||
|
||
大屏幕可使用：
|
||
|
||
```css
|
||
font-size: 44px;
|
||
```
|
||
|
||
---
|
||
|
||
### 8.2 描述
|
||
|
||
标题下方展示分类描述。
|
||
|
||
示例：
|
||
|
||
```text
|
||
高效的开发工具和资源集合，提升你的开发体验和效率。
|
||
```
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
font-size: 16px;
|
||
line-height: 1.7;
|
||
color: #64748b;
|
||
margin-top: 12px;
|
||
```
|
||
|
||
描述文字应简洁，不要写太长。
|
||
|
||
不同分类可使用类似描述：
|
||
|
||
```text
|
||
AI 工具：精选常用 AI 工具与服务，辅助创作、开发和效率提升。
|
||
设计资源：常用设计工具、素材与灵感资源集合。
|
||
学习资料：整理常用学习平台、文档、课程和知识资源。
|
||
效率工具：提升日常工作流效率的工具入口。
|
||
娱乐媒体：常用影音、社区和内容平台。
|
||
生活服务：日常生活、服务查询和实用网站入口。
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 分组标题区域
|
||
|
||
分类描述下方展示内容分组标题。
|
||
|
||
开发工具页第一版只需要一个分组：
|
||
|
||
```text
|
||
全部工具
|
||
```
|
||
|
||
旁边展示数量：
|
||
|
||
```text
|
||
共 15 个
|
||
```
|
||
|
||
示意：
|
||
|
||
```text
|
||
全部工具 共 15 个
|
||
```
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
.section-title {
|
||
font-size: 18px;
|
||
font-weight: 700;
|
||
color: #0f172a;
|
||
}
|
||
|
||
.section-count {
|
||
font-size: 14px;
|
||
color: #94a3b8;
|
||
background: rgba(255, 255, 255, 0.42);
|
||
border-radius: 999px;
|
||
padding: 4px 10px;
|
||
}
|
||
```
|
||
|
||
分组标题和工具卡片网格之间保持间距：
|
||
|
||
```css
|
||
margin-top: 36px;
|
||
margin-bottom: 20px;
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 工具卡片网格
|
||
|
||
### 10.1 网格布局
|
||
|
||
开发工具页推荐使用三列网格。
|
||
|
||
桌面端：
|
||
|
||
```text
|
||
三列网格
|
||
每行 3 个
|
||
共 5 行
|
||
```
|
||
|
||
示意：
|
||
|
||
```text
|
||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||
│ GitHub │ │ GitLab │ │ Bitbucket│
|
||
└──────────┘ └──────────┘ └──────────┘
|
||
|
||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||
│ VS Code │ │ JetBrains│ │ GoLand │
|
||
└──────────┘ └──────────┘ └──────────┘
|
||
|
||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||
│ Postman │ │ Docker │ │Kubernetes│
|
||
└──────────┘ └──────────┘ └──────────┘
|
||
```
|
||
|
||
推荐 CSS：
|
||
|
||
```css
|
||
display: grid;
|
||
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||
gap: 20px 24px;
|
||
```
|
||
|
||
---
|
||
|
||
### 10.2 响应式网格
|
||
|
||
不同屏幕下的网格建议：
|
||
|
||
```text
|
||
大屏幕（>= 1280px）：3 列
|
||
中等屏幕（768px - 1279px）：2 列
|
||
```
|
||
|
||
推荐实现：
|
||
|
||
```css
|
||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||
|
||
@media (min-width: 1280px) {
|
||
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||
}
|
||
```
|
||
|
||
> 历史说明：立项时移动端单列为后续阶段工作。当前状态（2026-10-14）：两列为基础布局，≥1280px 升为三列，≤999px（含手机及 768px–999px 窗口）降为单列；历史计划的「768px–1279px 两列」已基本实现，仅 768px–999px 区间为单列。
|
||
|
||
---
|
||
|
||
## 11. 工具卡片设计
|
||
|
||
### 11.1 卡片内容
|
||
|
||
每个工具卡片展示：
|
||
|
||
```text
|
||
工具图标
|
||
工具名称
|
||
简短描述
|
||
外链图标
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
GitHub
|
||
全球最大的代码托管平台
|
||
```
|
||
|
||
不展示：
|
||
|
||
```text
|
||
编辑按钮
|
||
删除按钮
|
||
拖拽按钮
|
||
访问统计
|
||
创建时间
|
||
更新时间
|
||
域名副标题
|
||
复杂标签
|
||
```
|
||
|
||
外链图标可以保留，因为它表达“点击后打开外部网站”，但要足够轻，不要像编辑按钮。
|
||
|
||
---
|
||
|
||
### 11.2 卡片结构
|
||
|
||
推荐结构：
|
||
|
||
```text
|
||
┌────────────────────────────────────┐
|
||
│ 图标 GitHub ↗ │
|
||
│ 全球最大的代码托管平台 │
|
||
└────────────────────────────────────┘
|
||
```
|
||
|
||
图标左侧对齐。
|
||
|
||
文字区域位于图标右侧。
|
||
|
||
外链图标位于右上角。
|
||
|
||
---
|
||
|
||
### 11.3 卡片尺寸
|
||
|
||
推荐桌面端尺寸：
|
||
|
||
```css
|
||
height: 96px;
|
||
min-width: 0;
|
||
```
|
||
|
||
卡片不需要太高，避免页面显得笨重。
|
||
|
||
推荐内边距：
|
||
|
||
```css
|
||
padding: 24px 28px;
|
||
```
|
||
|
||
---
|
||
|
||
### 11.4 卡片样式
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
background: rgba(255, 255, 255, 0.58);
|
||
backdrop-filter: blur(20px);
|
||
border: 1px solid rgba(255, 255, 255, 0.52);
|
||
border-radius: 18px;
|
||
box-shadow: 0 14px 40px rgba(15, 23, 42, 0.08);
|
||
```
|
||
|
||
> 2026-10-14 实现状态：上方浅色样式为历史方案。当前工具卡为深色玻璃 rgba(12, 24, 42, 0.65) + blur(10px)，高 82px、圆角 18px，hover 提亮为 rgba(25, 43, 65, 0.84) 并轻微上浮。
|
||
|
||
Hover 状态：
|
||
|
||
```css
|
||
transform: translateY(-2px);
|
||
background: rgba(255, 255, 255, 0.74);
|
||
box-shadow: 0 18px 50px rgba(15, 23, 42, 0.12);
|
||
border-color: rgba(255, 255, 255, 0.72);
|
||
```
|
||
|
||
过渡：
|
||
|
||
```css
|
||
transition:
|
||
transform 180ms ease,
|
||
background 180ms ease,
|
||
box-shadow 180ms ease,
|
||
border-color 180ms ease;
|
||
```
|
||
|
||
---
|
||
|
||
### 11.5 图标尺寸
|
||
|
||
工具图标推荐尺寸：
|
||
|
||
```css
|
||
width: 40px;
|
||
height: 40px;
|
||
```
|
||
|
||
对于复杂图标，可使用：
|
||
|
||
```css
|
||
width: 44px;
|
||
height: 44px;
|
||
```
|
||
|
||
图标区域应统一对齐，不同来源图标大小要视觉统一。
|
||
|
||
图标来源遵循统一图标方案（见[项目说明文档](./Polaris%20项目说明文档.md)）：
|
||
|
||
```text
|
||
自定义图标 → Simple Icons / 本地图标库 → favicon 自动抓取 → 文字占位兜底
|
||
```
|
||
|
||
推荐包裹容器：
|
||
|
||
```css
|
||
.icon-wrapper {
|
||
width: 44px;
|
||
height: 44px;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
flex-shrink: 0;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 11.6 文字样式
|
||
|
||
工具名称：
|
||
|
||
```css
|
||
font-size: 17px;
|
||
font-weight: 700;
|
||
color: #0f172a;
|
||
```
|
||
|
||
工具描述：
|
||
|
||
```css
|
||
font-size: 14px;
|
||
line-height: 1.5;
|
||
color: #64748b;
|
||
margin-top: 4px;
|
||
```
|
||
|
||
描述建议控制在 8 到 16 个中文字之间。
|
||
|
||
示例：
|
||
|
||
```text
|
||
全球最大的代码托管平台
|
||
一体化 DevOps 平台
|
||
代码托管和协作开发
|
||
强大的代码编辑器
|
||
智能开发工具套件
|
||
Go 语言 IDE
|
||
API 开发和测试工具
|
||
容器化平台
|
||
容器编排平台
|
||
前端部署与托管平台
|
||
现代化的开发平台
|
||
云应用托管平台
|
||
JavaScript 包管理器
|
||
快速的包管理器
|
||
界面设计协作工具
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 开发工具页数据示例
|
||
|
||
> 2026-10-14 说明：本节数据为立项期示例（15 条），不代表当前 `src/data/`；当前全站 8 类 51 条链接，开发工具分类 12 条。字段结构与现行 `NavLink` 类型一致，仍可作为格式参考。
|
||
|
||
### 12.1 分类数据
|
||
|
||
```json
|
||
{
|
||
"id": "dev",
|
||
"title": "开发工具",
|
||
"description": "高效的开发工具和资源集合，提升你的开发体验和效率。",
|
||
"icon": "code",
|
||
"sort": 20
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 12.2 链接数据
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "github",
|
||
"title": "GitHub",
|
||
"description": "全球最大的代码托管平台",
|
||
"url": "https://github.com",
|
||
"icon": "si:github",
|
||
"categoryId": "dev",
|
||
"pinned": true,
|
||
"pinnedSort": 10,
|
||
"keywords": ["代码", "仓库", "开源", "git"],
|
||
"sort": 10
|
||
},
|
||
{
|
||
"id": "gitlab",
|
||
"title": "GitLab",
|
||
"description": "一体化 DevOps 平台",
|
||
"url": "https://gitlab.com",
|
||
"icon": "si:gitlab",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["代码", "仓库", "devops", "ci", "cd"],
|
||
"sort": 20
|
||
},
|
||
{
|
||
"id": "bitbucket",
|
||
"title": "Bitbucket",
|
||
"description": "代码托管和协作开发",
|
||
"url": "https://bitbucket.org",
|
||
"icon": "si:bitbucket",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["代码", "仓库", "git"],
|
||
"sort": 30
|
||
},
|
||
{
|
||
"id": "vscode",
|
||
"title": "VS Code",
|
||
"description": "强大的代码编辑器",
|
||
"url": "https://code.visualstudio.com",
|
||
"icon": "si:vscode",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["编辑器", "ide", "代码"],
|
||
"sort": 40
|
||
},
|
||
{
|
||
"id": "jetbrains",
|
||
"title": "JetBrains",
|
||
"description": "智能开发工具套件",
|
||
"url": "https://www.jetbrains.com",
|
||
"icon": "si:jetbrains",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["ide", "开发工具", "编辑器"],
|
||
"sort": 50
|
||
},
|
||
{
|
||
"id": "goland",
|
||
"title": "GoLand",
|
||
"description": "Go 语言 IDE",
|
||
"url": "https://www.jetbrains.com/go/",
|
||
"icon": "si:goland",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["go", "golang", "ide"],
|
||
"sort": 60
|
||
},
|
||
{
|
||
"id": "postman",
|
||
"title": "Postman",
|
||
"description": "API 开发和测试工具",
|
||
"url": "https://www.postman.com",
|
||
"icon": "si:postman",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["api", "接口", "测试"],
|
||
"sort": 70
|
||
},
|
||
{
|
||
"id": "docker",
|
||
"title": "Docker",
|
||
"description": "容器化平台",
|
||
"url": "https://www.docker.com",
|
||
"icon": "si:docker",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["容器", "部署", "镜像"],
|
||
"sort": 80
|
||
},
|
||
{
|
||
"id": "kubernetes",
|
||
"title": "Kubernetes",
|
||
"description": "容器编排平台",
|
||
"url": "https://kubernetes.io",
|
||
"icon": "si:kubernetes",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["k8s", "容器", "编排", "云原生"],
|
||
"sort": 90
|
||
},
|
||
{
|
||
"id": "vercel",
|
||
"title": "Vercel",
|
||
"description": "前端部署与托管平台",
|
||
"url": "https://vercel.com",
|
||
"icon": "si:vercel",
|
||
"categoryId": "dev",
|
||
"pinned": true,
|
||
"pinnedSort": 70,
|
||
"keywords": ["部署", "前端", "托管"],
|
||
"sort": 100
|
||
},
|
||
{
|
||
"id": "netlify",
|
||
"title": "Netlify",
|
||
"description": "现代化的开发平台",
|
||
"url": "https://www.netlify.com",
|
||
"icon": "si:netlify",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["部署", "前端", "托管"],
|
||
"sort": 110
|
||
},
|
||
{
|
||
"id": "render",
|
||
"title": "Render",
|
||
"description": "云应用托管平台",
|
||
"url": "https://render.com",
|
||
"icon": "si:render",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["部署", "后端", "托管", "云服务"],
|
||
"sort": 120
|
||
},
|
||
{
|
||
"id": "npm",
|
||
"title": "npm",
|
||
"description": "JavaScript 包管理器",
|
||
"url": "https://www.npmjs.com",
|
||
"icon": "si:npm",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["javascript", "node", "包管理"],
|
||
"sort": 130
|
||
},
|
||
{
|
||
"id": "pnpm",
|
||
"title": "pnpm",
|
||
"description": "快速的包管理器",
|
||
"url": "https://pnpm.io",
|
||
"icon": "si:pnpm",
|
||
"categoryId": "dev",
|
||
"pinned": false,
|
||
"keywords": ["javascript", "node", "包管理"],
|
||
"sort": 140
|
||
},
|
||
{
|
||
"id": "figma",
|
||
"title": "Figma",
|
||
"description": "界面设计协作工具",
|
||
"url": "https://www.figma.com",
|
||
"icon": "si:figma",
|
||
"categoryId": "dev",
|
||
"pinned": true,
|
||
"pinnedSort": 50,
|
||
"keywords": ["设计", "ui", "协作"],
|
||
"sort": 150
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 13. 交互行为
|
||
|
||
### 13.1 点击卡片
|
||
|
||
点击工具卡片后，在新标签页打开对应链接。
|
||
|
||
推荐行为：
|
||
|
||
```ts
|
||
window.open(url, "_blank", "noopener,noreferrer")
|
||
```
|
||
|
||
---
|
||
|
||
### 13.2 外链图标
|
||
|
||
每个卡片右上角可以保留一个轻量外链图标。
|
||
|
||
作用：
|
||
|
||
```text
|
||
提示该卡片会打开外部网站
|
||
```
|
||
|
||
外链图标不代表编辑，不是更多操作。
|
||
|
||
推荐样式：
|
||
|
||
```css
|
||
width: 16px;
|
||
height: 16px;
|
||
color: #64748b;
|
||
opacity: 0.75;
|
||
```
|
||
|
||
Hover 时：
|
||
|
||
```css
|
||
color: #2563eb;
|
||
opacity: 1;
|
||
```
|
||
|
||
---
|
||
|
||
### 13.3 卡片 hover
|
||
|
||
Hover 时只做轻微反馈：
|
||
|
||
```text
|
||
轻微上浮
|
||
背景更亮
|
||
阴影稍增强
|
||
外链图标高亮
|
||
```
|
||
|
||
不要使用夸张动画。
|
||
|
||
---
|
||
|
||
### 13.4 快捷键
|
||
|
||
分类页不注册任何快捷键。
|
||
|
||
`Ctrl K`（macOS 为 ⌘K）仅在首页生效；用户需要搜索时，通过侧边栏「首页」回到首页。
|
||
|
||
---
|
||
|
||
## 14. 响应式设计
|
||
|
||
### 14.1 桌面端
|
||
|
||
桌面端布局：
|
||
|
||
```text
|
||
左侧边栏固定
|
||
右侧主内容玻璃面板
|
||
工具卡片三列网格
|
||
```
|
||
|
||
推荐断点：
|
||
|
||
```text
|
||
>= 1280px：三列
|
||
768px - 1279px：两列
|
||
```
|
||
|
||
当前实现（2026-10-14）：两列为基础布局，≥1280px 三列、≤999px 单列；历史计划的「768px–1279px 两列」已基本实现，仅其中 768px–999px 区间当前为单列（见第 0 章）。
|
||
|
||
---
|
||
|
||
### 14.2 平板与移动端
|
||
|
||
> 2026-10-14 实现状态：移动端适配已完成——≤767px 时侧边栏变为**常驻顶部横栏**（Logo + 横向滚动导航，非抽屉），工具卡片单列，短屏与移动端回退整页滚动；平板方向的「边栏宽度略小（220px）」与「工具卡片两列」已实现（两列覆盖 1000px–1279px，768px–999px 区间为单列），下列历史方向中的「抽屉式边栏」未采用。
|
||
|
||
立项时（仅适配桌面端）的参考方向：
|
||
|
||
```text
|
||
平板端：边栏宽度略小（200px - 220px），工具卡片两列
|
||
移动端：顶部 Logo + 菜单按钮（抽屉式边栏），单列工具卡片，
|
||
主容器改为更轻的背景层（padding: 20px 16px; 卡片高度 84px）
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 空状态设计
|
||
|
||
如果某个分类暂无链接，显示空状态。
|
||
|
||
示例：
|
||
|
||
```text
|
||
暂无工具
|
||
这个分类下还没有添加链接。
|
||
```
|
||
|
||
空状态不展示新增按钮。
|
||
|
||
原因：
|
||
|
||
1. 首页和分类页不承担管理功能；
|
||
2. 新增能力未来放在独立管理页；
|
||
3. 保持当前页面纯浏览定位。
|
||
|
||
空状态样式：
|
||
|
||
```css
|
||
height: 280px;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
color: #64748b;
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 加载状态设计
|
||
|
||
第一版数据来自本地数据配置，通常不需要明显 loading。
|
||
|
||
后续接入 Go 后端后，可以增加加载状态。
|
||
|
||
推荐加载方式：
|
||
|
||
```text
|
||
骨架屏
|
||
轻微渐入
|
||
不使用大面积转圈 loading
|
||
```
|
||
|
||
工具卡片骨架：
|
||
|
||
```css
|
||
height: 96px;
|
||
border-radius: 18px;
|
||
background: rgba(255, 255, 255, 0.36);
|
||
```
|
||
|
||
---
|
||
|
||
## 17. 错误状态设计
|
||
|
||
如果后续从后端加载失败，显示轻量错误提示。
|
||
|
||
示例：
|
||
|
||
```text
|
||
资源加载失败
|
||
请稍后重试。
|
||
```
|
||
|
||
错误状态不要占据过多视觉空间。
|
||
|
||
可以提供一个轻量重试按钮，但不要设计得像后台系统。
|
||
|
||
---
|
||
|
||
## 18. 视觉一致性要求
|
||
|
||
分类页必须和首页保持一致：
|
||
|
||
```text
|
||
相同背景
|
||
相同侧边栏
|
||
相同玻璃材质
|
||
相同圆角系统
|
||
相同阴影系统
|
||
相同字体系统
|
||
相同主色系统
|
||
相同导航选中态
|
||
```
|
||
|
||
分类页相比首页的区别：
|
||
|
||
```text
|
||
首页强调时间、搜索、常用链接
|
||
分类页强调标题、描述、链接集合
|
||
```
|
||
|
||
---
|
||
|
||
## 19. 不建议出现的元素
|
||
|
||
分类页第一版不建议出现：
|
||
|
||
```text
|
||
顶部搜索框
|
||
排列方式切换
|
||
表格视图
|
||
编辑按钮
|
||
删除按钮
|
||
拖拽排序
|
||
新增按钮
|
||
管理入口
|
||
筛选器
|
||
复杂标签
|
||
访问统计
|
||
最近访问时间
|
||
用户头像
|
||
登录状态
|
||
```
|
||
|
||
这些内容会让页面从“个人导航浏览页”变成“后台管理页”。
|
||
|
||
后续如果需要管理功能，应放入独立管理页面或隐藏入口。
|
||
|
||
---
|
||
|
||
## 20. 推荐组件拆分
|
||
|
||
前端组件可以拆分为：
|
||
|
||
```text
|
||
CategoryPage
|
||
CategoryHeader
|
||
CategorySectionHeader
|
||
ToolGrid
|
||
ToolCard
|
||
Sidebar
|
||
MainLayout
|
||
```
|
||
|
||
目录示例：
|
||
|
||
```text
|
||
src/
|
||
app/
|
||
categories/
|
||
[categoryId]/
|
||
page.tsx
|
||
|
||
components/
|
||
layout/
|
||
Sidebar.tsx
|
||
MainLayout.tsx
|
||
|
||
category/
|
||
CategoryHeader.tsx
|
||
CategorySectionHeader.tsx
|
||
ToolGrid.tsx
|
||
ToolCard.tsx
|
||
|
||
services/
|
||
categories.ts
|
||
links.ts
|
||
|
||
types/
|
||
navigation.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 21. TypeScript 类型建议
|
||
|
||
```ts
|
||
export type Category = {
|
||
id: string
|
||
title: string
|
||
description: string
|
||
icon: string
|
||
sort: number
|
||
}
|
||
|
||
export type NavLink = {
|
||
id: string
|
||
title: string
|
||
description: string
|
||
url: string
|
||
icon?: string
|
||
categoryId: string
|
||
pinned: boolean
|
||
pinnedSort?: number
|
||
keywords: string[]
|
||
sort: number
|
||
}
|
||
```
|
||
|
||
分类页获取数据时：
|
||
|
||
```ts
|
||
type CategoryPageData = {
|
||
category: Category
|
||
links: NavLink[]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 22. 分类页开发优先级
|
||
|
||
### 第一阶段
|
||
|
||
完成静态展示：
|
||
|
||
```text
|
||
分类页路由
|
||
分类标题
|
||
分类描述
|
||
全部工具数量
|
||
工具卡片网格
|
||
空分类展示空状态
|
||
左侧导航选中态
|
||
点击卡片跳转
|
||
```
|
||
|
||
---
|
||
|
||
### 第二阶段
|
||
|
||
完善响应式（后续阶段）：
|
||
|
||
```text
|
||
平板两列
|
||
移动端一列
|
||
侧边栏移动端适配
|
||
```
|
||
|
||
> 2026-10-14 实现状态：「平板两列」（1000px–1279px 区间，768px–999px 除外）、「移动端一列」与「侧边栏移动端适配」已完成（见第 0 章）。
|
||
|
||
---
|
||
|
||
### 第三阶段
|
||
|
||
完善状态：
|
||
|
||
```text
|
||
空状态
|
||
加载状态
|
||
错误状态
|
||
卡片 hover
|
||
外链图标 hover
|
||
```
|
||
|
||
---
|
||
|
||
### 第四阶段
|
||
|
||
接入后端：
|
||
|
||
```text
|
||
从 Go API 获取分类
|
||
从 Go API 获取链接
|
||
支持按 categoryId 查询
|
||
支持服务层切换数据源
|
||
```
|
||
|
||
---
|
||
|
||
## 23. 开发工具页最终目标
|
||
|
||
开发工具页最终应呈现为：
|
||
|
||
> 一个安静、清爽、玻璃感的开发资源集合页。用户进入页面后，可以快速知道当前分类是什么，并直接浏览和打开开发相关工具。页面没有搜索框、没有排列切换、没有编辑管理按钮，整体保持和 Polaris 首页一致的个人起始页气质。
|
||
|
||
核心原则：
|
||
|
||
```text
|
||
分类页负责浏览
|
||
首页负责搜索
|
||
侧边栏负责导航
|
||
管理功能不进入主视觉
|
||
视觉风格保持轻玻璃和极简
|
||
```
|