如有任何问题，敬请指出。

上拉页面即可看到 Dock 组件#

组件概述#

Dock 组件的添加解决三个主要问题：

阅读时无法搜索或切换页面
中小屏幕下”回到顶部”按钮的缺失
更有质感的博客

主要功能#

自动显隐: 向下滚动(超过 150 像素)时自动显示，向上滚动或返回顶部时隐藏。
快速导航：提供首页、存档和关于页面的快速访问按钮
返回顶部：一键平滑滚动至页面顶部
底部搜索：一个类似导航栏搜索的组件

文件结构#

1
src/components/dock/
2
├── Dock.svelte
3
└── DockSearch.svelte

集成步骤#

1. 创建文件#

在项目的 src/components/ 目录下创建一个名为 dock 的文件夹(可选)，并添加以下两个文件：

Dock.svelte - Dock 组件组件主体，包括UI显示与滚动处理

下面是 Dock.svelte 的完整代码。

1
<script lang="ts">
75 collapsed lines
2
  import Icon from "@iconify/svelte";
3
  import { url } from "@utils/url-utils.ts";
4
  import { onMount } from "svelte";
5
  import DockSearch from "./DockSearch.svelte";
6

7
  let props = $props();
8

9
// Configurable options - can be customized based on site needs
10
const config = {
11
  scrollThreshold: 150, // Show dock after scrolling this many pixels
12
  homePath: "/",
13
  archivePath: "/archive/",
14
  aboutPath: "/about/",
15
};
16

17
let showDock = $state(false);
18
let scrollTimer: ReturnType<typeof setTimeout> | null = null;
19

20
onMount(() => {
21
  handleScroll();
22

23
  window.addEventListener("scroll", handleScroll, { passive: true });
24

25
  return () => {
26
    window.removeEventListener("scroll", handleScroll);
27
    if (scrollTimer) {
28
      clearTimeout(scrollTimer);
29
    }
30
  };
31
});
32

33
function handleScroll() {
34
  if (scrollTimer) {
35
    clearTimeout(scrollTimer);
36
  }
37

38
  scrollTimer = setTimeout(() => {
39
    const currentScrollY = window.scrollY;
40
    // Dock displayed when the currentScrollY > scrollThreshold
41
    showDock = currentScrollY > config.scrollThreshold;
42
    scrollTimer = null;
43
  }, 16);
44
}
45

46
function navigateHome(event: Event) {
47
  event.preventDefault();
48
  if (window.swup) {
49
    window.swup.navigate(url(config.homePath));
50
  }
51
}
52

53
// Return to Top
54
function scrollToTop(e: Event) {
55
  e.stopPropagation();
56
  window.scrollTo({
57
    top: 0,
58
    behavior: "smooth",
59
  });
60
}
61

62
// Navigate to Archive
63
function navigateToArchive(event: Event) {
64
  event.preventDefault();
65
  if (window.swup) {
66
    window.swup.navigate(url(config.archivePath));
67
  }
68
}
69

70
// Navigate to About
71
function navigateToAbout(event: Event) {
72
  event.preventDefault();
73
  if (window.swup) {
74
    window.swup.navigate(url(config.aboutPath));
75
  }
76
}
77
</script>
78

79
<!-- Dock -->
80
<div
73 collapsed lines
81
  id="dock"
82
  role="toolbar"
83
  tabindex="0"
84
  class="fixed left-1/2 z-50 transition-all duration-300 ease-out"
85
  class:bottom-6={showDock}
86
  class:-bottom-14={!showDock}
87
  class:opacity-100={showDock}
88
  class:h-18={showDock}
89
  class:scale-100={showDock}
90
>
91
  <!-- Backdrop Blur -->
92
  <div
93
    class="absolute inset-0 bg-white/60 dark:bg-neutral-500/60 backdrop-blur-xs rounded-full shadow-lg border border-black/10 dark:border-white/20"
94
  ></div>
95

96
  <!-- Buttons Container -->
97
  <div
98
    class="relative flex items-center justify-center h-full px-4 will-change-transform"
99
  >
100
    <!-- Search Button -->
101
    <DockSearch />
102

103
    <!-- Home Button -->
104
    <a
105
      href={url(config.homePath)}
106
      class="btn-plain scale-animation rounded-3xl w-11 h-11 active:scale-90"
107
      aria-label="Home Page"
108
      onclick={navigateHome}
109
    >
110
      <Icon
111
        icon="material-symbols:home-outline-rounded"
112
        class="text-[1.5rem]"
113
      />
114
    </a>
115

116
    <!-- Return to Top Button -->
117
    <button
118
      class="btn-dock-primary items-center justify-center mx-1"
119
      onclick={scrollToTop}
120
      aria-label="Return to Top"
121
    >
122
      <Icon
123
        icon="material-symbols:keyboard-arrow-up-rounded"
124
        class="text-[1.5rem]"
125
      />
126
    </button>
127

128
    <!-- Archive Button -->
129
    <a
130
      href={url(config.archivePath)}
131
      class="btn-plain scale-animation rounded-3xl w-11 h-11 active:scale-90"
132
      aria-label="Archive Page"
133
      onclick={navigateToArchive}
134
    >
135
      <Icon
136
        icon="material-symbols:inventory-2-outline-rounded"
137
        class="text-[1.5rem]"
138
      />
139
    </a>
140

141
    <!-- About Button -->
142
    <a
143
      href={url(config.aboutPath)}
144
      class="btn-plain scale-animation rounded-3xl w-11 h-11 active:scale-90"
145
      aria-label="About Page"
146
      onclick={navigateToAbout}
147
    >
148
      <Icon
149
        icon="material-symbols:info-outline-rounded"
150
        class="text-[1.5rem]"
151
      />
152
    </a>
153
  </div>
154
</div>
155

156
<style>
25 collapsed lines
157
  /* Dock Container Style */
158
  #dock {
159
    transform: translateX(-50%);
160
  }
161

162
  /* Dock Main Button (Return to Top) Style */
163
  .btn-dock-primary {
164
    width: 3rem;
165
    height: 3rem;
166
    border-radius: 50%;
167
    display: flex;
168
    align-items: center;
169
    justify-content: center;
170
    background-color: var(--primary);
171
    color: white;
172
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
173
    transition-property: all;
174
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
175
    transition-duration: 200ms;
176
  }
177

178
  .btn-dock-primary:hover {
179
    opacity: 0.8;
180
    transform: scale(1.05);
181
  }
182
</style>

参考: Github | Dock.svelte

DockSearch.svelte - Dock 的搜索功能组件

下面是 DockSearch.svelte 的完整代码。

1
<script lang="ts">
211 collapsed lines
2
import I18nKey from "@i18n/i18nKey";
3
import { i18n } from "@i18n/translation";
4
import Icon from "@iconify/svelte";
5
import { url } from "@utils/url-utils.ts";
6
import { onMount } from "svelte";
7
import type { SearchResult } from "@/global";
8

9
let keyword = "";
10
let result: SearchResult[] = [];
11
let isSearching = false;
12
let pagefindLoaded = false;
13
let initialized = false;
14
let isVisible = false;
15
let searchPanelElement: HTMLDivElement;
16
let searchInputElement: HTMLInputElement;
17

18
// Mock data for development environment - customize as needed
19
const fakeResult: SearchResult[] = [
20
{
21
        url: url("/posts/nggyu/"),
22
        meta: {
23
                title: "Never Gonna Give You Up",
24
        },
25
        excerpt:
26
                "Because the search cannot work in the <mark>dev</mark> environment.",
27
},
28
{
29
        url: url("/"),
30
        meta: {
31
                title: "If You Want to Test the Search",
32
        },
33
        excerpt: "Try running <mark>npm build && npm preview</mark> instead.",
34
},
35
];
36

37
function toggleVisibility(): void {
38
isVisible = !isVisible;
39
if (isVisible) {
40
        setTimeout(() => {
41
                if (searchInputElement) searchInputElement.focus();
42
        }, 10);
43
} else {
44
        resetSearch();
45
}
46
}
47

48
function hide(): void {
49
isVisible = false;
50
resetSearch();
51
}
52

53
function resetSearch(): void {
54
result = [];
55
keyword = "";
56
}
57

58
function navigateToResult(event: Event, itemUrl: string): void {
59
event.preventDefault();
60
hide(); // Hide search panel
61
if (window.swup) {
62
        window.swup.navigate(itemUrl);
63
} else {
64
        window.location.href = itemUrl;
65
}
66
}
67

68
function handleClickOutside(event: Event): void {
69
const target = event.target as HTMLElement;
70
if (
71
        !searchPanelElement?.contains(target) &&
72
        !target?.closest("#dock-search-button")
73
) {
74
        hide();
75
}
76
}
77

78
async function search(): Promise<void> {
79
if (!keyword) {
80
        result = [];
81
        return;
82
}
83

84
if (!initialized) return;
85

86
isSearching = true;
87

88
try {
89
        if (import.meta.env.PROD && pagefindLoaded && window.pagefind) {
90
                const response = await window.pagefind.search(keyword);
91
                result = await Promise.all(response.results.map((item) => item.data()));
92
        } else if (import.meta.env.DEV) {
93
                result = fakeResult;
94
        } else {
95
                result = [];
96
                console.error("Pagefind is not available in production environment.");
97
        }
98
} catch (error) {
99
        console.error("Search error:", error);
100
        result = [];
101
} finally {
102
        isSearching = false;
103
}
104
}
105

106
$: hasResults = result.length > 0;
107

108
$: panelWidth = (() => {
109
// When not searching
110
if (!keyword?.trim()) return "30rem";
111

112
// When search results are available
113
if (hasResults) {
114
        // Calculate the estimated width of the longest heading
115
        const maxLength = Math.max(
116
                ...result.map(
117
                        (item) =>
118
                                (item?.meta?.title?.length || 0) * 1.2 +
119
                                (item?.excerpt?.length || 0) * 0.3,
120
                ),
121
        );
122

123
        // Calculate the width based on the content length
124
        const minWidth = 35; // rem
125
        const maxWidth = 55; // rem
126
        const calculatedWidth = Math.min(
127
                Math.max(minWidth, maxLength / 10),
128
                maxWidth,
129
        );
130
        return `${calculatedWidth}rem`;
131
}
132

133
// When searching or no results found
134
return "35rem";
135
})();
136

137
// Optimize performance using throttling
138
let lastPanelWidth = "";
139
let updateTimeout: ReturnType<typeof setTimeout>;
140
let searchTimeout: ReturnType<typeof setTimeout>;
141

142
function updatePanelWidth(width: string) {
143
if (width !== lastPanelWidth) {
144
        if (updateTimeout) clearTimeout(updateTimeout);
145
        updateTimeout = setTimeout(() => {
146
                if (typeof document !== "undefined") {
147
                        document.documentElement.style.setProperty(
148
                                "--search-panel-width",
149
                                width,
150
                        );
151
                        lastPanelWidth = width;
152
                }
153
        }, 50); // 50ms throttling
154
}
155
}
156

157
$: updatePanelWidth(panelWidth);
158

159
// Lifecycle Management
160
onMount(() => {
161
document.addEventListener("click", handleClickOutside);
162

163
const initializeSearch = (): void => {
164
        initialized = true;
165
        pagefindLoaded =
166
                typeof window !== "undefined" &&
167
                !!window.pagefind &&
168
                typeof window.pagefind.search === "function";
169
        console.log("Pagefind status on init:", pagefindLoaded);
170
        if (keyword) search();
171
};
172

173
if (import.meta.env.DEV) {
174
        console.log(
175
                "Pagefind is not available in development mode. Using mock data.",
176
        );
177
        initializeSearch();
178
} else {
179
        document.addEventListener("pagefindready", () => {
180
                console.log("Pagefind ready event received.");
181
                initializeSearch();
182
        });
183
        document.addEventListener("pagefindloaderror", () => {
184
                console.warn(
185
                        "Pagefind load error event received. Search functionality will be limited.",
186
                );
187
                initializeSearch();
188
        });
189

190
        // Fallback in case events are not caught or pagefind is already loaded
191
        setTimeout(() => {
192
                if (!initialized) {
193
                        console.log("Fallback: Initializing search after timeout.");
194
                        initializeSearch();
195
                }
196
        }, 2000);
197
}
198

199
return () => {
200
        document.removeEventListener("click", handleClickOutside);
201
        if (updateTimeout) clearTimeout(updateTimeout);
202
        if (searchTimeout) clearTimeout(searchTimeout);
203
};
204
});
205

206
// Responsive Search with throttling
207
$: if (initialized && keyword) {
208
if (searchTimeout) clearTimeout(searchTimeout);
209
searchTimeout = setTimeout(async () => {
210
        await search();
211
}, 300); // 300ms throttling
212
}
213
</script>
214

215
<button
6 collapsed lines
216
id="dock-search-button"
217
class="btn-plain scale-animation rounded-3xl w-11 h-11 active:scale-90"
218
on:click|stopPropagation={toggleVisibility}
219
aria-label="Search"
220
>
221
<Icon icon="material-symbols:search" class="text-[1.5rem]" />
222
</button>
223

224
<div
76 collapsed lines
225
class="fixed transition-all duration-300 ease-in-out"
226
class:opacity-0={!isVisible}
227
class:opacity-100={isVisible}
228
class:pointer-events-none={!isVisible}
229
class:-z-10={!isVisible}
230
class:z-50={isVisible}
231
style="bottom: 6rem; left: 50%; transform: translateX(-50%); width: calc(100% - 0rem); max-width: var(--search-panel-width, 30rem);"
232
>
233
<div
234
bind:this={searchPanelElement}
235
id="dock-search-panel"
236
class="rounded-3xl shadow-xl p-1 max-h-[70vh] overflow-y-auto border border-black/5 dark:border-white/5 bg-white/80 dark:bg-neutral-500/80 backdrop-blur-xs"
237
class:scale-95={!isVisible}
238
class:scale-100={isVisible}
239
>
240
<!-- Search Result Panel -->
241
{#if hasResults}
242
<div class="max-h-[50vh] overflow-y-auto mb-2">
243
{#each result as item}
244
        <div
245
        role="button"
246
        tabindex="0"
247
        class="transition first-of-type:mt-1 group block rounded-2xl text-lg px-3 py-2 hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] cursor-pointer"
248
        on:click={(e) => navigateToResult(e, item.url)}
249
        on:keydown={(e) => {
250
        if (e.key === 'Enter' || e.key === ' ') {
251
        e.preventDefault();
252
        navigateToResult(e, item.url);
253
        }
254
        }}
255
        >
256
        <div class="transition text-90 inline-flex font-bold group-hover:text-[var(--primary)]">
257
        {item.meta.title}
258
        <Icon
259
        icon="fa6-solid:chevron-right"
260
        class="transition text-[0.75rem] translate-x-1 my-auto text-[var(--primary)]"
261
        />
262
        </div>
263
        <div class="transition text-sm text-50">
264
        {#if import.meta.env.PROD}
265
        {@html item.excerpt}
266
        {:else}
267
        {item.excerpt}
268
        {/if}
269
        </div>
270
        </div>
271
{/each}
272
</div>
273
{:else if keyword && !isSearching}
274
<div class="py-4 text-center text-50 mb-2">No results found</div>
275
{/if}
276

277
<!-- Search Panel -->
278
<div class="relative flex items-center h-11 rounded-3xl bg-black/[0.04] hover:bg-black/[0.06] focus-within:bg-black/[0.06] dark:bg-white/5 dark:hover:bg-white/10 dark:focus-within:bg-white/10">
279
<Icon
280
icon="material-symbols:search"
281
class="absolute text-[1.25rem] pointer-events-none ml-3 text-black/30 dark:text-white/30"
282
/>
283
<input
284
id="dock-search-input"
285
bind:this={searchInputElement}
286
placeholder={i18n(I18nKey.search)}
287
bind:value={keyword}
288
class="pl-10 pr-8 py-2 text-sm bg-transparent outline-0 w-full h-full rounded-3xl"
289
/>
290
{#if keyword}
291
<button
292
        on:click|stopPropagation={resetSearch}
293
        class="absolute right-2 top-1/2 transform -translate-y-1/2 text-black/30 dark:text-white/30 hover:text-black/50 dark:hover:text-white/50"
294
        aria-label="Clear search"
295
>
296
        <Icon icon="material-symbols:close" class="text-[1rem]" />
297
</button>
298
{/if}
299
</div>
300
</div>
301
</div>
302

303
<style>
18 collapsed lines
304
/* Hide the scrollbar but retain functionality */
305
#dock-search-panel::-webkit-scrollbar {
306
width: 6px;
307
}
308

309
#dock-search-panel::-webkit-scrollbar-track {
310
background: transparent;
311
}
312

313
#dock-search-panel::-webkit-scrollbar-thumb {
314
background: rgba(0, 0, 0, 0.2);
315
border-radius: 3px;
316
}
317

318
#dock-search-panel {
319
transition: width 0.3s ease-in-out, transform 0.3s ease-in-out;
320
max-width: var(--search-panel-width, 30rem);
321
}
322
</style>

参考: Github | DockSearch.svelte
这是可选的，假如你不需要 Dock 的搜索功能

2. 导入到 Layout#

将 Dock 组件导入并添加到 Layout 文件（src/layouts/Layout.astro）：
在 </body> 前添加 <Dock client:only="svelte" />
NOTE
使用 client:only="svelte" 避免水合问题

// ...
import ConfigCarrier from "@components/ConfigCarrier.astro";
import Dock from "@components/dock/Dock.svelte";
// ...
<!DOCTYPE html>
<html lang={siteLang} class="...">
<body class="...">
// ...
<ConfigCarrier></ConfigCarrier>
<slot />
// 添加Dock组件,同时避免水合问题
<Dock client:only="svelte" />

<!-- increase ... -->
<div id="page-height-extend"></div>
</body>
</html>

参考: Github | Layout.astro

个性化设置#

配置选项#

Dock 组件包含一个配置对象，可根据网站的结构和个人偏好进行修改：

7
// Configurable options...
8
const config = {
9
  scrollThreshold: 150, //pixels
10
  homePath: "/",
11
  archivePath: "/archive/",
12
  aboutPath: "/about/",
13
};

节流优化(已整合)#

为了减少功耗，可以在 Dock.svelte 中添加节流机制，限制滚动事件处理频率：

// ...
function handleScroll() {
  if (scrollTimer) {
    clearTimeout(scrollTimer);
  }

  scrollTimer = setTimeout(() => {
    const currentScrollY = window.scrollY;
    // Dock displayed when the currentScrollY > scrollThreshold
    showDock = currentScrollY > config.scrollThreshold;
    scrollTimer = null;
  }, 16);
}
// ...

样式问题？#

我在项目中自定义了一些全局样式。如果最终呈现与我的示例不同，请检查样式定义。