Fuwari 主题背景图功能教程

本教程将介绍如何为 Fuwari 主题添加背景图功能，包括高斯模糊效果和用户可调节的模糊程度。

功能特性#

✨ 全屏背景图显示
🎨 高斯模糊效果
🎚️ 用户可调节模糊程度（0-50px）
🧊 半透明卡片效果
💾 设置自动保存到本地存储

配置步骤#

1. 配置背景图#

打开 src/config.ts 文件，找到 siteConfig 对象，添加或修改 background 配置：

1
export const siteConfig: SiteConfig = {
2
  // ... 其他配置
3

4
  background: {
5
    enable: true,              // 是否启用背景图
6
    src: "/homeground.webg",   // 背景图片路径
7
    blur: 10,                  // 默认模糊程度（像素）
8
  },
9

10
  // ... 其他配置
11
};

参数说明：

enable: 布尔值，控制是否显示背景图
src: 图片路径，以 / 开头表示相对于 /public 目录，否则相对于 /src 目录
blur: 数字，默认模糊程度，范围建议 0-50

2. 添加背景图片#

将你的背景图片放到 /public 目录下（如果路径以 / 开头）或 /src 目录下。建议使用高分辨率的图片以获得最佳效果。

推荐图片规格：

分辨率：至少 1920x1080
格式：WebP（推荐）、JPG、PNG
大小：建议小于 2MB

3. 自定义模糊度#

用户可以在网页上通过导航栏的模糊图标调节背景模糊度：

点击导航栏右侧的模糊图标
使用滑块调节模糊程度（0-50px）
设置会自动保存，刷新页面后保持

样式自定义#

如果需要调整半透明效果，可以修改 src/styles/variables.styl 文件：

1
define({
2
  // 卡片背景透明度（85% 不透明）
3
  --card-bg-transparent: oklch(1 0 0 / 0.85) oklch(0.23 0.015 var(--hue) / 0.85)
4

5
  // 导航栏背景透明度（80% 不透明）
6
  --navbar-bg: oklch(1 0 0 / 0.8) oklch(0.23 0.015 var(--hue) / 0.8)
7
})

修改 0.85 和 0.8 可以调整透明度（0-1 之间，越小越透明）。

禁用背景图#

如果不想要背景图效果，只需在配置中设置 enable: false：

1
background: {
2
  enable: false,
3
  src: "/homeground.webg",
4
  blur: 10,
5
},

效果展示#

启用背景图后，整个网站将拥有：

固定在底层的全屏背景图
可调节的高斯模糊效果
半透明的卡片和导航栏
保持良好的文字可读性

代码实现#

如果你想从零开始实现这个功能，或者了解具体的技术细节，请按照以下步骤操作：

步骤 1: 定义配置类型#

首先在 src/types/config.ts 中添加背景图配置的类型定义：

1
export type SiteConfig = {
2
  // ... 其他配置
3

4
  background: {
5
    enable: boolean;
6
    src: string;
7
    blur?: number;
8
  };
9

10
  // ... 其他配置
11
};

步骤 2: 添加配置项#

在 src/config.ts 中添加背景图配置：

1
export const siteConfig: SiteConfig = {
2
  // ... 其他配置
3

4
  background: {
5
    enable: true,
6
    src: "/homeground.webg",
7
    blur: 10,
8
  },
9

10
  // ... 其他配置
11
};

步骤 3: 实现设置存储和读取#

在 src/utils/setting-utils.ts 中添加模糊度的存储和读取函数：

1
// 获取默认模糊度
2
export function getDefaultBlur(): number {
3
  const fallback = "10";
4
  const configCarrier = document.getElementById("config-carrier");
5
  return Number.parseInt(configCarrier?.dataset.blur || fallback);
6
}
7

8
// 获取存储的模糊度
9
export function getBlur(): number {
10
  const stored = localStorage.getItem("blur");
11
  return stored ? Number.parseInt(stored) : getDefaultBlur();
12
}
13

14
// 设置模糊度
15
export function setBlur(blur: number): void {
16
  localStorage.setItem("blur", String(blur));
17
  const r = document.querySelector(":root") as HTMLElement;
18
  if (!r) {
19
    return;
20
  }
21
  r.style.setProperty("--bg-blur", String(blur) + "px");
22
}

步骤 4: 创建模糊设置组件#

创建 src/components/widget/BlurSettings.svelte 文件：

1
<script lang="ts">
2
import I18nKey from "@i18n/i18nKey";
3
import { i18n } from "@i18n/translation";
4
import Icon from "@iconify/svelte";
5
import { getDefaultBlur, getBlur, setBlur } from "@utils/setting-utils";
6

7
let blur = getBlur();
8
const defaultBlur = getDefaultBlur();
9

10
function resetBlur() {
11
  blur = getDefaultBlur();
12
}
13

14
$: if (blur || blur === 0) {
15
  setBlur(blur);
16
}
17
</script>
18

19
<div id="blur-setting" class="float-panel float-panel-closed absolute transition-all w-80 right-4 px-4 py-4">
20
    <div class="flex flex-row gap-2 mb-3 items-center justify-between">
21
        <div class="flex gap-2 font-bold text-lg text-neutral-900 dark:text-neutral-100 transition relative ml-3
22
            before:w-1 before:h-4 before:rounded-md before:bg-[var(--primary)]
23
            before:absolute before:-left-3 before:top-[0.33rem]"
24
        >
25
            背景模糊
26
            <button aria-label="Reset to Default" class="btn-regular w-7 h-7 rounded-md active:scale-90"
27
                    class:opacity-0={blur === defaultBlur} class:pointer-events-none={blur === defaultBlur} on:click={resetBlur}>
28
                <div class="text-[var(--btn-content)]">
29
                    <Icon icon="fa6-solid:arrow-rotate-left" class="text-[0.875rem]"></Icon>
30
                </div>
31
            </button>
32
        </div>
33
        <div class="flex gap-1">
34
            <div id="blurValue" class="transition bg-[var(--btn-regular-bg)] w-10 h-7 rounded-md flex justify-center
35
            font-bold text-sm items-center text-[var(--btn-content)]">
36
                {blur}
37
            </div>
38
        </div>
39
    </div>
40
    <div class="w-full h-6 px-1 bg-[oklch(0.80_0.10_0)] dark:bg-[oklch(0.70_0.10_0)] rounded select-none">
41
        <input aria-label="Background Blur" type="range" min="0" max="50" bind:value={blur}
42
               class="slider" id="blurSlider" step="1" style="width: 100%">
43
    </div>
44
</div>

步骤 5: 更新 ConfigCarrier 组件#

修改 src/components/ConfigCarrier.astro 以传递模糊度配置：

1
---
2
import { siteConfig } from "../config";
3

4
interface Props {
5
  blur?: number;
6
}
7

8
const { blur = siteConfig.background.blur || 10 } = Astro.props;
9
---
10

11
<div id="config-carrier" data-hue={siteConfig.themeColor.hue} data-blur={blur}>
12
</div>

步骤 6: 在 Layout 中添加背景图#

在 src/layouts/Layout.astro 中添加背景图元素和初始化脚本：

1
<body>
2
  <ConfigCarrier blur={siteConfig.background.blur || 10}></ConfigCarrier>
3
  {siteConfig.background.enable && (
4
    <div id="background-wrapper" class="fixed inset-0 -z-10 overflow-hidden">
5
      <img
6
        id="background-image"
7
        src={url(siteConfig.background.src)}
8
        alt="Background image"
9
        class="absolute inset-0 w-full h-full object-cover"
10
        style={`filter: blur(var(--bg-blur, 10px))`}
11
      />
12
    </div>
13
  )}
14
  <slot />
15
</body>

并在内联脚本中添加模糊度加载：

1
<script is:inline>
2
  // 加载模糊度
3
  const configCarrier = document.getElementById('config-carrier');
4
  const defaultBlur = configCarrier?.dataset.blur || '10';
5
  const blur = localStorage.getItem('blur') || defaultBlur;
6
  document.documentElement.style.setProperty('--bg-blur', `${blur}px`);
7
</script>

步骤 7: 添加 CSS 变量#

在 src/styles/variables.styl 中添加 CSS 变量：

1
:root
2
  --radius-large 1rem
3
  --content-delay 150ms
4
  --bg-blur 10px
5

6
define({
7
  // 背景图相关的变量
8
  --card-bg-transparent: oklch(1 0 0 / 0.85) oklch(0.23 0.015 var(--hue) / 0.85)
9
  --navbar-bg: oklch(1 0 0 / 0.8) oklch(0.23 0.015 var(--hue) / 0.8)
10
})

步骤 8: 在导航栏添加模糊设置按钮#

修改 src/components/Navbar.astro，添加模糊设置按钮和面板：

1
<Search client:only="svelte"></Search>
2
{siteConfig.background.enable && (
3
  <button aria-label="Blur Settings" class="btn-plain scale-animation rounded-lg h-11 w-11 active:scale-90" id="blur-settings-switch">
4
    <Icon name="material-symbols:blur-on" class="text-[1.25rem]"></Icon>
5
  </button>
6
)}
7
<LightDarkSwitch client:only="svelte"></LightDarkSwitch>
8

9
<!-- ... -->
10

11
{siteConfig.background.enable && <BlurSettings client:only="svelte"></BlurSettings>}

并添加按钮点击事件处理：

1
<script>
2
function loadButtonScript() {
3
  // ... 其他按钮
4

5
  let blurSettingBtn = document.getElementById("blur-settings-switch");
6
  if (blurSettingBtn) {
7
    blurSettingBtn.onclick = function () {
8
      let blurSettingPanel = document.getElementById("blur-setting");
9
      if (blurSettingPanel) {
10
        blurSettingPanel.classList.toggle("float-panel-closed");
11
      }
12
    };
13
  }
14
}
15

16
loadButtonScript();
17
</script>

步骤 9: 添加半透明卡片样式#

在 src/styles/main.css 中添加半透明卡片样式：

1
@layer components {
2
  .card-base {
3
    @apply rounded-[var(--radius-large)] overflow-hidden bg-[var(--card-bg)] transition;
4
  }
5

6
  .card-base-transparent {
7
    @apply rounded-[var(--radius-large)] overflow-hidden bg-[var(--card-bg-transparent)] backdrop-blur-md transition;
8
  }
9
}

然后将各个组件的 card-base 类替换为 card-base-transparent 以使用半透明效果。

技术实现#

功能实现涉及以下文件：

src/types/config.ts - 配置类型定义
src/config.ts - 配置项
src/layouts/Layout.astro - 背景图渲染
src/components/Navbar.astro - 模糊设置按钮
src/components/widget/BlurSettings.svelte - 模糊调节面板
src/utils/setting-utils.ts - 设置存储和读取
src/styles/variables.styl - 样式变量

注意事项#

背景图片会影响页面加载速度，建议使用压缩后的图片
模糊程度过高可能会影响视觉体验
半透明效果在浅色主题下可能需要调整
移动设备上建议使用较小的背景图片

常见问题#

Q: 为什么背景图不显示？
A: 检查 background.enable 是否为 true，图片路径是否正确。

Q: 如何让背景图固定不滚动？
A: 当前实现已经是固定的，背景图不会随页面滚动。

Q: 可以为不同页面设置不同背景图吗？
A: 当前版本所有页面使用同一背景图，如需不同背景需要修改代码。

希望这个教程能帮助你更好地使用 Fuwari 主题的背景图功能！