公共组件与插件
src/components/存放跨页面复用的 UI 组件,src/composables/存放可复用逻辑,src/plugins/存放需要安装到 router / app 上的插件。
组件一览
| 组件 | 作用 | 使用位置 |
|---|---|---|
AppLayout.vue | 全局布局:顶栏、侧边栏 / 顶部菜单、语言切换、用户菜单、通知中心、路由视图 | App.vue |
AppSkeleton.vue | 骨架屏占位(cards / list 两种布局,shimmer 动画) | Dashboard、Proxies、Nodes、Download、About、ServiceProvider |
NodeMap.vue | 节点分布地图(纯 SVG 世界陆地轮廓 + 中国省界,无瓦片服务依赖) | Nodes.vue |
AnnouncementModal.vue | 系统公告弹窗(仅登录用户,24 小时内不重复展示同一公告) | AppLayout.vue |
AdBanner.vue | 广告横幅(多广告自动轮播,悬停暂停) | Dashboard.vue |
CnRedirectModal.vue | 国内用户提示:检测到中国大陆 IP 时建议切换到 cn.console.hayfrp.com | App.vue |
OfflineIndicator.vue | PWA 离线提示弹窗(监听 online / offline) | App.vue |
SeoHead.vue | 动态写入 SEO 标签:title、meta description/keywords、Open Graph、canonical | App.vue |
DevWatermark.vue | 开发环境水印(import.meta.env.DEV 为 false 时整段被 tree-shake) | App.vue |
AppLayout.vue
布局核心,包含:
- 顶栏:Logo(点击回首页)、语言选择器、主题切换、通知中心、用户头像与下拉菜单;未登录时显示「登录 / 注册」
- 菜单:
menuPosition为left时渲染侧边栏,top时渲染顶部菜单;移动端(< 768px)强制顶部菜单(汉堡按钮展开) - 侧边栏显隐:
route.meta.hideSidebar为true时不渲染侧边栏与滚动容器 - 用户菜单:用户设置(
/settings)、个性化(/customize)、服务商控制台(/sp)、兑换码(/user type=redemption)、退出登录 - 头像:优先使用绑定的 QQ 号头像
https://q.qlogo.cn/headimg_dl?dst_uin=<qid>&spec=100 - 未登录兜底:
watch(route)中若route.meta.requiresAuth && !csrf,router.replace到/login?redirect=...
NodeMap.vue
后端不下发经纬度,节点位置来自名称中的地区(如「中国-平顶山-花枫服务器」):
utils/nodeGeo.ts的resolveNodeLocation(name)分词匹配:先城市(地级行政区中心点 + 境外常用城市),再退化到国家 / 地区中心点- 投影到内嵌的世界陆地轮廓(
data/worldCountries.json,Natural Earth 110m,坐标压缩到 0.1°) - 中国视野额外叠加省界(
data/chinaProvinces.json) - 地名坐标表:
data/nodeLocations.json
为什么不用地图瓦片
全部用 SVG 绘制,不依赖任何在线瓦片服务,国内外网络环境都能直接显示;同时避免第三方地图的鉴权与合规问题。
AppSkeleton.vue
vue
<AppSkeleton v-if="loading" variant="list" :rows="6" />
<div v-else>...真实内容...</div>| Props | 类型 | 默认值 | 说明 |
|---|---|---|---|
variant | 'cards' | 'list' | 'cards' | 卡片网格 / 表格行 |
items | number | 4 | 骨架块数量 |
rows | number | 3 | 每张卡片内的文本行数(仅 cards) |
animated | boolean | true | 是否显示 shimmer 动画 |
全局弹窗与提示
| 组件 | localStorage 键 | 行为 |
|---|---|---|
AnnouncementModal | hayfrp_announcement_dismissed | 记录已关闭的公告标识与时间,24 小时内不再弹出 |
CnRedirectModal | hayfrp_cn_redirect_never(旧版 hayfrp_cn_redirect_rejected) | 「不再显示」后长期不再提示;HayFrpCnRedirect({ resetRemembered: true }) 可在控制台重置 |
OfflineIndicator | — | 断网弹窗,window.testOffline() 可手动触发调试 |
AnnouncementModal与ServiceProvider的公告渲染都会先经DOMPurify清洗 HTML,避免 XSS。
composables
useNotification
见 状态管理与本地存储 的「浏览器通知」一节。隧道状态通知由 Proxies.vue 在轮询检测到上下线变化时调用 notifyProxyStatus()。
plugins
progressPlugin
src/plugins/progressPlugin.ts 为 vue-router 提供顶部加载进度条:
| 选项 | 默认值 | 说明 |
|---|---|---|
minimum | 0.08 | 初始进度 |
trickleSpeed | 180 ms | 自动增长间隔 |
- 在
main.ts中通过progressPlugin(router)安装 - 动态创建
#route-progress/#route-progress-barDOM,无需引入额外依赖 - 进度增长分档递减(
<0.3每次 +0.12,<0.6+0.06,其余 +0.02),最高到 0.92 afterEach/onError收尾到 100% 后 240ms 归零
utils
| 工具 | 作用 |
|---|---|
utils/token.ts | Token 读写、过期判断、兼容旧格式(详见 路由守卫 的「登录态与 Token 存储」) |
utils/redirect.ts | Open Redirect 防护与带 csrf 的重定向 URL 构造 |
utils/nodeGeo.ts | 节点名称 → 经纬度解析(城市级 / 国家地区级) |
静态数据
| 文件 | 内容 |
|---|---|
data/worldCountries.json | 世界国界轮廓(Natural Earth 110m,压缩坐标) |
data/chinaProvinces.json | 中国省界(DataV 边界 RDP 简化) |
data/nodeLocations.json | 中国地级行政区 + 境外城市 / 国家坐标 |
data/developmentTimeline.json | 关于页「开发时间线」数据(基于 Git 提交记录整理) |