7.2 KiB
7.2 KiB
规划 · 未登录首页 v1.4(方案 A 首屏 + 热门公开仓库)
状态:仅规划,未动任何代码(2026-11-05) 目标实例:
https://git.qyhhh.top(Gitea 1.21.11) 铁律不变:只走custom/覆盖、先preview/后线上、蓝白配色、禁止绿色、大量留白。
1. 已确认的决策
| # | 问题 | 决定 |
|---|---|---|
| 1 | 热门仓库放几个 | 单行 3 个(宽屏 3 列 × 1 行) |
| 2 | 排序 | 星标优先(同星数再按最近更新) |
| 3 | Fork / 镜像仓库 | 排除 |
| 4 | 数字条 | 待定,默认建议:删除(见 §6) |
| 5 | 终端 git clone 示例 |
占位地址 https://git.qyhhh.top/qq/repo.git |
参考效果图:dsh-image-gen/image-5f71a3ab.png(方案 A)、dsh-image-gen/image-c8208180.png(方案 B 的仓库区)。
2. 页面结构(自上而下)
| 区块 | 内容 | 备注 |
|---|---|---|
| 顶栏 | Gitea 原生顶栏 | 不动,沿用 qq-ui.css 毛玻璃 |
| ① 首屏 Hero(左右分栏) | 左 7/12:渐变大标题 {{AppName}}、口号「自己的代码,自己的地方。」、搜索框(提交到 /explore/repos)、主按钮「免费注册」/ 次按钮「登录」/ 文字链「浏览全部仓库 →」右 5/12:毛玻璃卡片,内含 SVG 提交分支图(蓝色节点 + 分叉线),右下叠终端小窗 $ git clone https://git.qyhhh.top/qq/repo.git + 复制按钮 |
方案 A |
| ② 热门公开仓库 | 标题「热门公开仓库」+ 右侧「查看全部 →」(/explore/repos?sort=moststars);3 张卡片单行 |
方案 B 的仓库区 |
| ③ 功能卡 | 沿用现有三卡(版本控制 / 议题与看板 / 数据自持),视觉降一级作为收尾 | 文案不变 |
| ④ 数字条 | 待定(§6) | — |
| 页脚 | 左站点信息 / 中语言切换 / 右 ICP 备案号 | 不动 |
整体限宽 1280px 居中,与登录后控制台一致。
3. 仓库卡片规格
┌────────────────────────────────────┐
│ (头像20px) owner/仓库名 │
│ 描述文字,最多两行,超出省略…… │
│ ● 语言 ★ 12 ⑂ 3 3 天前更新 │
└────────────────────────────────────┘
- 语言圆点:只用品牌蓝色阶(
#1D4ED8/#3B82F6/#60A5FA/#93C5FD按语言名哈希取色),不用 Gitea 原生语言色(含绿色)。 - hover:上浮 2px,描边变主色
#3B82F6(深色#38BDF8)。 - 深色模式:卡片底
#161B22,沿用qq-dark变量。 - 圆角 8px,字体 JetBrains Mono(数字/仓库名)。
4. 数据来源(关键技术点)
Gitea 1.21 的首页 handler 不给模板传仓库列表,因此改为前端调用官方公开 API:
GET /api/v1/repos/search?sort=stars&order=desc&limit=10&mode=source
- 匿名调用只返回公开仓库,不会泄露私有仓库。
- 取多一些(10 个)在前端二次过滤:去掉
fork === true、mirror === true、private === true、archived === true(归档是否排除可再议),按stars_count降序、同星按updated_at降序,截取前 3 个。 - 使用字段:
full_name、html_url、description、language、stars_count、forks_count、updated_at、owner.avatar_url。 - 状态处理:
- 加载中:3 张骨架卡占位(无闪烁时遵守
prefers-reduced-motion); - 结果为 0:整块隐藏,只留首屏「浏览全部仓库 →」;
- 接口失败 / 超时(5s):静默隐藏,不报错。
- 加载中:3 张骨架卡占位(无闪烁时遵守
- 前置条件:需实测匿名能访问该接口(
REQUIRE_SIGNIN_VIEW=false且 API 未禁用)。若不可用,退路是只放「查看全部仓库」入口,不做卡片。
5. 涉及文件
| 文件 | 改动 |
|---|---|
custom/templates/home.tmpl |
重写 Hero 为左右分栏;新增仓库区空容器 #qq-hot-repos + 3 张骨架卡;<script defer src="{{AssetUrlPrefix}}/js/qq-home.js?v=…"> 仅在首页引入 |
custom/public/assets/css/qq-pages.css |
新增 .qq-lp-split / .qq-lp-graph / .qq-lp-term / .qq-repo-card / .qq-skeleton 等样式,沿用 .qq-lp-* 前缀 |
custom/public/assets/js/qq-home.js(新增) |
拉 API → 过滤排序 → 渲染卡片;复制 clone 命令(navigator.clipboard,失败回退 execCommand);相对时间格式化 |
custom/public/assets/js/qq-fx.js |
光斑 / 打字机挂载点随新 Hero 结构调整(选择器更新) |
custom/public/assets/css/qq-fx.css |
如有 Hero 相关选择器同步调整 |
preview/index.html(+ preview/app.js) |
落地页段换成新版式,仓库区用本地假数据,不打线上 |
docs/TODO.md |
新增「阶段 8 · 首页 v1.4」条目与部署记录 |
不新增模板钩子以外的任何覆盖,不改 app.ini。
6. 关于「数字条」(待确认)
数字条指当前首页最底部那一排四格:
| 1.21.11 | MIT | MySQL | 1 台 |
|---|---|---|---|
| Gitea 版本 | 开源协议 | 独立数据库存储 | 服务器即可跑 |
对访客价值不高,且新版已有仓库区和功能卡,页面会偏长。三个选项:
- A. 删除(默认建议)
- B. 缩成首屏标题下一行小字:
Gitea 1.21.11 · MIT · 自托管 - C. 保持原样放在功能卡下面
未回复则按 A 执行。
7. 响应式与无障碍
| 断点 | 行为 |
|---|---|
| > 1024px | Hero 左右分栏;仓库 3 列 |
| 641–1024px | Hero 上下堆叠(分支图卡片在文字下方);仓库 3 列压缩 → 不足时 2 列 + 第三张换行 |
| ≤ 640px | 仓库 1 列;终端小窗缩为单行可横向滚动;分支图隐藏 |
prefers-reduced-motion:分支图静止、骨架不闪、关闭光斑。- 仓库卡片整卡为
<a>,有可见焦点环;复制按钮有aria-label和「已复制」反馈。
8. 执行步骤(待批准后进行)
- 接口验证:匿名
curl https://git.qyhhh.top/api/v1/repos/search?sort=stars&order=desc&limit=10&mode=source,确认可用并记录当前公开仓库数量。 - 离线预览:在
preview/做出新版,截图 日间 / 夜间 / 375px 移动端 交 QQ 确认。 - 接入模板:改
home.tmpl/qq-pages.css/ 新增qq-home.js;跑scripts/audit_colors.py确认无绿色;提交并打v1.4-rc1。 - 部署:
./scripts/deploy.sh预演 → QQ 批准 →./scripts/deploy.sh --yes(自动备份到/var/backups/)→ 线上实拍复核 → 打v1.4-live。 - 回滚预案:
./scripts/rollback.sh /var/backups/gitea-custom-<时间戳>.tar.gz。
9. 验收清单
- 未登录访问首页:首屏左右分栏,分支图 + 终端正常显示
- 复制按钮可复制
git clone https://git.qyhhh.top/qq/repo.git - 热门仓库显示 ≤3 个,按星标降序,无 fork / 镜像 / 私有仓库
- 无公开仓库或接口失败时整块隐藏,页面无报错
- 日间 / 夜间 / 跟随系统 三主题无绿色、无白边
- 375px 移动端无横向溢出
- 登录后首页仍为控制台,不受影响
- 页脚 ICP 备案号与语言切换正常