页面上长什么样#

组件本身不输出任何 HTML，所有 DOM 都是 JS 动态生成的。结构大概是这样：

1
#welcome-toast（固定在右下角，z-50）
2
└── 一个卡片 div（白色背景、圆角、阴影）
3
    ├── 👋 表情
4
    ├── 文字区
5
    │   ├── 问候语（一开始显示"正在加载..."，后面会变成具体地址）
6
    │   └── 副标题"欢迎来到我的博客"
7
    └── 关闭按钮（一个 ×）

几个关键函数#

整个逻辑不复杂，就是 5 个函数各管各的事：

1
// 用 sessionStorage 做会话标识，防止重复弹出
2
const VISIT_SESSION_KEY = 'blog_visit_flag';
3
let hasShownToast = false;
4

5
// 创建 Toast 的 DOM 结构，插入到页面上
6
function createWelcomeToast()
7

8
// 关掉 Toast：先滑出去，500ms 后把节点从 DOM 里移掉
9
function closeWelcomeToast()
10

11
// 请求一个免费的 IP API，拿到访客的位置信息
12
async function fetchLocation()
13

14
// 整个弹出流程的"导演"：创建 → 滑入 → 拿位置 → 5秒后自动关闭
15
async function showWelcomeToast()
16

17
// 入口函数：判断是不是第一次访问，是的话才弹
18
function initWelcome()

执行顺序#

说白了就是这么个流程：

怎么适配 SPA 导航的#

这里有个坑：Firefly 用了 Swup 做客户端路由，页面切换的时候不会走完整的 DOMContentLoaded。所以组件同时绑了两个事件：

1
if (document.readyState === 'loading') {
2
    document.addEventListener('DOMContentLoaded', initWelcome);
3
    document.addEventListener('astro:page-load', initWelcome);  // Swup 专用
4
} else {
5
    initWelcome();
6
}

另外关闭按钮用的是内联 onclick，所以函数得挂到 window 上才能调用：

1
(window as any).closeWelcomeToast = closeWelcomeToast;

样式部分#

• 桌面端：固定在右下角（fixed bottom-4 right-4 z-50），用 CSS transition 做滑入滑出动画，500ms ease-out。
• 移动端（640px 以下）：改到屏幕底部居中，宽度 90%，不会遮挡太多内容。
• 深色模式：用 Tailwind 的 dark: 变体自动切换背景色、边框色和文字色。

几个值得注意的点#

• 没传任何 props：组件完全是自包含的，不需要从外面传参数。
• 靠 sessionStorage 去重：每次 Swup 导航都会重建组件，但因为有 blog_visit_flag 标记，所以不会重复弹出。
• 兼容 Swup 的 astro 事件：客户端路由切换后也能正常触发。
• 构建时没有 HTML 输出：组件只有 <script> 和 <style>，不产生静态 HTML，全靠 JS 在浏览器里创建。