WelcomeToast 欢迎弹窗组件实现教程

一、功能介绍

WelcomeToast 是一个轻量级的欢迎弹窗组件，当访客第一次打开页面时，右下角会弹出一个欢迎卡片，支持 IP 地理位置的个性化问候，5 秒后自动消失。

功能特点

✅ 首次访问弹出：使用 sessionStorage 去重，每个会话只弹一次
✅ IP 地理位置问候：自动获取访客位置，显示个性化问候
✅ 自动消失：5 秒后自动关闭，不打扰用户
✅ 手动关闭：支持点击关闭按钮提前关闭
✅ 响应式设计：适配桌面端和移动端
✅ 深色模式支持：自动切换主题样式
✅ Swup 兼容：完美适配 SPA 客户端路由

二、效果演示

场景	效果
桌面端	固定在右下角，显示欢迎卡片
移动端	固定在底部居中，宽度 90%
深色模式	自动切换深色主题
首次访问	显示 IP 地理位置问候
重复访问	不再弹出（会话内）

三、涉及的文件

整个组件涉及两个文件：

文件	路径
组件本身	`src/components/WelcomeToast.astro`
在布局中引用	`src/layouts/MainGridLayout.astro`

四、组件实现原理

组件特点

组件的 frontmatter 是空的，没有任何服务端逻辑。所有事情都在浏览器端的 <script> 和 <style> 里完成。

页面结构

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

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

五、关键函数说明

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

1. 会话标识

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

2. createWelcomeToast()

创建 Toast 的 DOM 结构，插入到页面上。

3. closeWelcomeToast()

关掉 Toast：先滑出去，500ms 后把节点从 DOM 里移掉。

4. fetchLocation()

请求一个免费的 IP API，拿到访客的位置信息。

5. showWelcomeToast()

整个弹出流程的”导演”：创建 → 滑入 → 拿位置 → 5秒后自动关闭。

6. initWelcome()

入口函数：判断是不是第一次访问，是的话才弹。

六、完整代码

组件文件

1
---
2
// 空的 frontmatter，所有逻辑都在浏览器端
3
---
4

5
<script is:inline>
6
  const VISIT_SESSION_KEY = 'blog_visit_flag';
7
  let hasShownToast = false;
8

9
  function createWelcomeToast() {
10
    const toast = document.createElement('div');
11
    toast.id = 'welcome-toast';
12
    toast.className = 'welcome-toast';
13
    toast.innerHTML = `
14
      <div class="welcome-toast-card">
15
        <div class="welcome-toast-emoji">👋</div>
16
        <div class="welcome-toast-content">
17
          <div class="welcome-toast-greeting">正在加载...</div>
18
          <div class="welcome-toast-subtitle">欢迎来到我的博客</div>
19
        </div>
20
        <button class="welcome-toast-close" onclick="closeWelcomeToast()">×</button>
21
      </div>
22
    `;
23
    document.body.appendChild(toast);
24
    return toast;
25
  }
26

27
  function closeWelcomeToast() {
28
    const toast = document.getElementById('welcome-toast');
29
    if (toast) {
30
      toast.classList.remove('show');
31
      toast.classList.add('hide');
32
      setTimeout(() => toast.remove(), 500);
33
    }
34
  }
35

36
  async function fetchLocation() {
37
    try {
38
      const response = await fetch('https://ipapi.co/json/');
39
      const data = await response.json();
40
      return {
41
        city: data.city,
42
        region: data.region,
43
        country: data.country_name
44
      };
45
    } catch (error) {
46
      console.error('获取位置信息失败:', error);
47
      return null;
48
    }
49
  }
50

51
  async function showWelcomeToast() {
52
    if (hasShownToast) return;
53
    hasShownToast = true;
54

55
    const toast = createWelcomeToast();
56
    setTimeout(() => toast.classList.add('show'), 100);
57

58
    const location = await fetchLocation();
59
    const greeting = toast.querySelector('.welcome-toast-greeting');
60

61
    if (location) {
62
      greeting.textContent = `你好，来自${location.city || location.region || location.country}的朋友！`;
63
    } else {
64
      greeting.textContent = '你好，欢迎访问！';
65
    }
66

67
    setTimeout(closeWelcomeToast, 5000);
68
  }
69

70
  function initWelcome() {
71
    if (sessionStorage.getItem(VISIT_SESSION_KEY)) return;
72
    sessionStorage.setItem(VISIT_SESSION_KEY, '1');
73
    showWelcomeToast();
74
  }
75

76
  // 兼容 Swup 的 SPA 导航
77
  if (document.readyState === 'loading') {
78
    document.addEventListener('DOMContentLoaded', initWelcome);
79
    document.addEventListener('astro:page-load', initWelcome);
80
  } else {
81
    initWelcome();
82
  }
83

84
  // 挂载到 window 上供内联 onclick 调用
85
  window.closeWelcomeToast = closeWelcomeToast;
86
</script>
87

88
<style>
89
  .welcome-toast {
90
    position: fixed;
91
    bottom: 1rem;
92
    right: 1rem;
93
    z-index: 50;
94
    transform: translateX(120%);
95
    transition: transform 0.5s ease-out;
96
  }
97

98
  .welcome-toast.show {
99
    transform: translateX(0);
100
  }
101

102
  .welcome-toast.hide {
103
    transform: translateX(120%);
104
  }
105

106
  .welcome-toast-card {
107
    background: var(--card-bg, #fff);
108
    border: 1px solid var(--line-divider, rgba(0, 0, 0, 0.1));
109
    border-radius: 12px;
110
    padding: 1rem 1.25rem;
111
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
112
    display: flex;
113
    align-items: center;
114
    gap: 0.75rem;
115
    min-width: 280px;
116
    max-width: 360px;
117
  }
118

119
  .welcome-toast-emoji {
120
    font-size: 1.5rem;
121
    flex-shrink: 0;
122
  }
123

124
  .welcome-toast-content {
125
    flex: 1;
126
    min-width: 0;
127
  }
128

129
  .welcome-toast-greeting {
130
    font-size: 0.875rem;
131
    font-weight: 600;
132
    color: var(--text-primary, #1f2937);
133
    line-height: 1.4;
134
  }
135

136
  .welcome-toast-subtitle {
137
    font-size: 0.75rem;
138
    color: var(--text-secondary, #6b7280);
139
    margin-top: 0.25rem;
140
  }
141

142
  .welcome-toast-close {
143
    background: none;
144
    border: none;
145
    font-size: 1.25rem;
146
    color: var(--text-secondary, #6b7280);
147
    cursor: pointer;
148
    padding: 0.25rem;
149
    line-height: 1;
150
    flex-shrink: 0;
151
    transition: color 0.2s;
152
  }
153

154
  .welcome-toast-close:hover {
155
    color: var(--text-primary, #1f2937);
156
  }
157

158
  /* 深色模式 */
159
  :root.dark .welcome-toast-card {
160
    background: var(--card-bg, #1f2937);
161
    border-color: var(--line-divider, rgba(255, 255, 255, 0.1));
162
  }
163

164
  :root.dark .welcome-toast-greeting {
165
    color: var(--text-primary, #f9fafb);
166
  }
167

168
  :root.dark .welcome-toast-subtitle {
169
    color: var(--text-secondary, #9ca3af);
170
  }
171

172
  :root.dark .welcome-toast-close {
173
    color: var(--text-secondary, #9ca3af);
174
  }
175

176
  :root.dark .welcome-toast-close:hover {
177
    color: var(--text-primary, #f9fafb);
178
  }
179

180
  /* 移动端适配 */
181
  @media (max-width: 640px) {
182
    .welcome-toast {
183
      bottom: 1rem;
184
      left: 50%;
185
      right: auto;
186
      transform: translateX(-50%) translateY(120%);
187
    }
188

189
    .welcome-toast.show {
190
      transform: translateX(-50%) translateY(0);
191
    }
192

193
    .welcome-toast.hide {
194
      transform: translateX(-50%) translateY(120%);
195
    }
196

197
    .welcome-toast-card {
198
      width: 90vw;
199
      max-width: none;
200
    }
201
  }
202
</style>

七、在布局中使用

导入组件

打开 src/layouts/MainGridLayout.astro，在文件顶部添加导入：

1
---
2
import WelcomeToast from "@components/WelcomeToast.astro";
3
// ... 其他导入
4
---

使用组件

在 <main id="swup-container"> 里面、<slot /> 后面添加：

1
<main id="swup-container" class="transition-main">
2
  <div id="content-wrapper">
3
    <slot></slot>
4
  </div>
5
  <WelcomeToast />
6
</main>

布局层级关系

1
Layout.astro
2
└── MainGridLayout.astro
3
    ├── Navbar（导航栏）
4
    ├── Wallpaper（背景壁纸）
5
    ├── <main id="swup-container">      ← Swup 的容器，导航时会替换这里面的内容
6
    │   ├── <slot>                       ← 每个页面的具体内容
7
    │   └── <WelcomeToast />             ← 放在内容后面
8
    ├── Footer（页脚）
9
    └── FloatingControls（浮动控制按钮）

八、注意事项

1. 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
}

2. 内联 onclick 兼容

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

1
(window as any).closeWelcomeToast = closeWelcomeToast;

3. 会话去重

靠 sessionStorage 去重：每次 Swup 导航都会重建组件，但因为有 blog_visit_flag 标记，所以不会重复弹出。

4. 无 HTML 输出

构建时没有 HTML 输出：组件只有 <script> 和 <style>，不产生静态 HTML，全靠 JS 在浏览器里创建。

5. 无 Props 依赖

没传任何 props：组件完全是自包含的，不需要从外面传参数。

九、常见问题

Q1: 弹窗不显示？

可能原因：

浏览器禁用了 sessionStorage
IP API 请求失败
页面加载时序问题

解决方案：

检查浏览器设置，确保 sessionStorage 可用
检查网络连接，确保能访问 IP API
检查控制台是否有错误信息

Q2: 地理位置显示不准确？

可能原因：

IP API 返回的数据不准确
访客使用了 VPN 或代理

解决方案： 这是正常现象，IP 定位本身就有一定误差，可以显示更宽泛的地区信息。

Q3: 每次刷新都显示？

可能原因：

sessionStorage 被清空
浏览器隐私模式

解决方案： 这是正常行为，sessionStorage 在关闭浏览器后会清空。如果需要更持久的去重，可以使用 localStorage。

Q4: 如何修改样式？

解决方案： 修改组件中的 <style> 部分即可，主要样式包括：

1
.welcome-toast {
2
  /* 容器样式 */
3
}
4

5
.welcome-toast-card {
6
  /* 卡片样式 */
7
}
8

9
.welcome-toast-greeting {
10
  /* 问候语文本样式 */
11
}

Q5: 如何禁用此功能？

解决方案： 在 MainGridLayout.astro 中注释掉组件导入和使用：

1
{/* import WelcomeToast from "@components/WelcomeToast.astro"; */}
2

3
<main id="swup-container" class="transition-main">
4
  <div id="content-wrapper">
5
    <slot></slot>
6
  </div>
7
  {/* <WelcomeToast /> */}
8
</main>

十、总结

WelcomeToast 是一个轻量级的欢迎弹窗组件，主要特点：

特点	说明
首次访问弹出	使用 sessionStorage 去重
IP 地理位置问候	自动获取访客位置
自动消失	5 秒后自动关闭
手动关闭	支持点击关闭按钮
响应式设计	适配桌面端和移动端
深色模式支持	自动切换主题样式
Swup 兼容	完美适配 SPA 客户端路由

实现原理：

组件是纯客户端渲染，不输出静态 HTML
使用 sessionStorage 做会话级别的去重
通过 IP API 获取访客地理位置
支持 Swup 的 astro:page-load 事件

放在 Firefly 主题的 MainGridLayout 里，和 Swup 的 SPA 导航机制配合得很好。🎉

音乐

音乐

一、功能介绍

功能特点

二、效果演示

三、涉及的文件

四、组件实现原理

组件特点

页面结构

五、关键函数说明

1. 会话标识

2. createWelcomeToast()

3. closeWelcomeToast()

4. fetchLocation()

5. showWelcomeToast()

6. initWelcome()

六、完整代码

组件文件

七、在布局中使用

导入组件

使用组件

布局层级关系

八、注意事项

1. SPA 导航适配

2. 内联 onclick 兼容

3. 会话去重

4. 无 HTML 输出

5. 无 Props 依赖

九、常见问题

Q1: 弹窗不显示？

Q2: 地理位置显示不准确？

Q3: 每次刷新都显示？

Q4: 如何修改样式？

Q5: 如何禁用此功能？

十、总结

支持与分享

评论区

音乐

文章目录