> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 浮动按钮与欢迎弹窗

> 适用版本 ≥ 2.0.0 ｜ 后台路径：主题设置 → 布局设置 → 浮动导航按钮 / 欢迎弹窗

右下角的快捷按钮，以及访客首次进入时的问候卡片。两者默认都存在，但可以按需关掉或替换。

## 配置项

### 浮动导航按钮

| 选项    | 默认值 | 说明                                  |
| ----- | --- | ----------------------------------- |
| 回到顶部  | 开启  | 滚动后显示回到顶部按钮                         |
| 回到首页  | 开启  | 一键回到站点首页                            |
| 跳转评论  | 开启  | 滚动到当前页评论区                           |
| 目录按钮  | 开启  | 页面没有可见目录时显示，点击呼出目录弹窗，主要面向移动端与平板     |
| 自定义按钮 | 空   | 显示在默认按钮上方。每条填写按钮名称、图标（Iconify）、跳转链接 |

### 欢迎弹窗

| 选项     | 默认值                         | 说明                                |
| ------ | --------------------------- | --------------------------------- |
| 启用     | 关闭                          | 访客进入站点时显示，关闭后本次会话不再弹出             |
| 弹窗位置   | 右下角                         | 左上 / 右上 / 左下 / 右下；移动端固定底部居中       |
| 欢迎标题   | 欢迎来到我的博客！                   | 弹窗标题                              |
| 欢迎语模板  | 来自 \{location} 的小伙伴，很高兴遇见你！ | 正文，`{location}` 会替换为 IP 定位结果      |
| 定位失败文案 | 未知星球                        | 未配置 Key 或定位失败时替换 `{location}` 的文字 |

## 推荐配法

**极简**：只保留「回到顶部」，关闭其余按钮。移动端阅读长文时仍可用目录按钮，如果文章页本身有目录，可一并关闭。

**多功能导航**：回到顶部 + 回到首页 + 目录 + 两个自定义按钮（例如「关于我」「打赏」），自定义按钮放在默认按钮上方，形成一条竖向快捷栏。

**增加亲和力**：开启欢迎弹窗，正文写成「来自 \{location} 的小伙伴，很高兴遇见你！」，定位失败文案填「未知星球」，语气轻松且不会暴露精确位置。

## 注意事项

- **目录按钮是条件显示的**：只有当前页面没有可见目录（两栏的悬浮目录、三栏的侧栏目录都不存在）时才出现，避免与已有目录重复
- 自定义按钮的图标使用 Iconify 名称（如 `ri:heart-line`），留空图标只显示文字；名称与链接为必填
- 欢迎弹窗的 IP 定位**复用天气小组件的腾讯位置服务 Key**，没配 Key 时统一显示定位失败文案
- 关闭弹窗后本次会话内不再出现（写入会话存储），换浏览器或清缓存后会再次出现
- 移动端弹窗固定底部居中，位置设置只影响桌面端
- 自定义按钮数量不宜过多，纵向排列超过 5 个会挤占可视区域