Firefly 主题自定义文章封面位置：实现列表模式封面在上方#

Firefly 主题默认的列表模式只支持封面在左侧或右侧，但我想让封面显示在标题上方。于是开始了一番折腾，记录一下完整的修改过程。

最终效果#

修改前（封面在右侧）：

1
┌─────────────────────────────────┐
2
│ 标题                    [封面图] │
3
│ 标签                            │
4
└─────────────────────────────────┘

修改后（封面在上方）：

1
┌─────────────────────────────────┐
2
│ [封面图]                        │
3
│ 标题                            │
4
│ 标签                            │
5
└─────────────────────────────────┘

需要修改的文件#

一共涉及 4 个文件：

src/types/siteConfig.ts — 类型定义
src/config/siteConfig.ts — 配置文件
src/components/layout/PostCard.astro — 文章卡片组件
src/components/layout/PostPage.astro — 文章列表页面

第一步：修改类型定义#

文件： src/types/siteConfig.ts

找到 coverPosition 的类型定义：

1
coverPosition?: "left" | "right" | undefined;

添加 "top" 选项，修改为：

1
coverPosition?: "left" | "right" | "top" | undefined;

第二步：修改配置文件#

文件： src/config/siteConfig.ts

找到 postListLayout 配置中的 coverPosition：

1
postListLayout: {
2
    // 列表模式下封面图显示在哪一侧："right" 右侧，"left" 左侧
3
    coverPosition: "right",
4
    // ...
5
},

修改为：

1
postListLayout: {
2
    // 列表模式下封面图显示在哪一侧："right" 右侧，"left" 左侧，"top" 上方
3
    coverPosition: "top",
4
    // ...
5
},

第三步：修改文章卡片组件#

文件： src/components/layout/PostCard.astro

3.1 添加变量判断#

找到这行代码（约第 53 行）：

1
const coverWidth = "30%";

在它下面添加：

1
const isCoverTop = style.includes("cover-top");

3.2 修改容器 class#

找到容器 div 的 class 定义（约第 107-114 行）：

1
class:list={[
2
    "post-card-wrapper",
3
    hasCover ? "has-cover" : "no-cover",
4
    pinned ? "pinned" : "",
5
    gridCoverFullWidth ? "" : "grid-cover-inset",
6
    "card-base flex flex-col-reverse w-full rounded-(--radius-large) overflow-hidden relative",
7
    className,
8
]}

添加 cover-top 类，修改为：

1
class:list={[
2
    "post-card-wrapper",
3
    hasCover ? "has-cover" : "no-cover",
4
    pinned ? "pinned" : "",
5
    gridCoverFullWidth ? "" : "grid-cover-inset",
6
    isCoverTop ? "cover-top" : "",
7
    "card-base flex flex-col-reverse w-full rounded-(--radius-large) overflow-hidden relative",
8
    className,
9
]}

3.3 添加 CSS 样式#

在文件末尾的 <style> 标签内添加以下 CSS：

1
/* 列表模式封面在上方 - 移动端 */
2
:global(.list-mode.cover-top) .post-card-wrapper {
3
    flex-direction: column-reverse !important;
4
}
5

6
:global(.list-mode.cover-top) .has-cover .post-card-image {
7
    position: relative !important;
8
    top: auto !important;
9
    bottom: auto !important;
10
    right: auto !important;
11
    left: auto !important;
12
    width: 100% !important;
13
    height: 200px !important;
14
    margin: 0 !important;
15
    border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
16
}
17

18
:global(.list-mode.cover-top) .has-cover .post-card-content {
19
    width: 100% !important;
20
}
21

22
/* 列表模式封面在上方 - 桌面端 */
23
@media (min-width: 768px) {
24
    :global(.list-mode.cover-top) .post-card-wrapper {
25
        flex-direction: column-reverse !important;
26
    }
27

28
    :global(.list-mode.cover-top) .has-cover .post-card-image {
29
        position: relative !important;
30
        top: auto !important;
31
        bottom: auto !important;
32
        right: auto !important;
33
        left: auto !important;
34
        width: 100% !important;
35
        height: 300px !important;
36
        margin: 0 !important;
37
        border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
38
    }
39

40
    :global(.list-mode.cover-top) .has-cover .post-card-content {
41
        width: 100% !important;
42
        padding: 1.75rem 2.25rem !important;
43
    }
44

45
    :global(.list-mode.cover-top) .has-cover .post-card-title::before {
46
        display: none !important;
47
    }
48
}

第四步：修改文章列表页面#

文件： src/components/layout/PostPage.astro

找到 coverPositionClass 的定义（约第 28-29 行）：

1
const coverPositionClass =
2
  siteConfig.postListLayout.coverPosition === "left" ? " cover-left" : "";

添加对 "top" 的支持，修改为：

1
const coverPositionClass =
2
  siteConfig.postListLayout.coverPosition === "left" ? " cover-left" :
3
  siteConfig.postListLayout.coverPosition === "top" ? " cover-top" : "";

完整配置参考#

修改完成后，siteConfig.ts 中的 postListLayout 配置示例：

1
postListLayout: {
2
    // 默认布局模式："list" 列表模式，"grid" 网格模式
3
    defaultMode: "list",
4
    // 移动端默认布局模式
5
    mobileDefaultMode: "grid",
6
    // 列表模式下封面图位置："right" 右侧，"left" 左侧，"top" 上方
7
    coverPosition: "top",
8
    // 文章简介显示行数
9
    descriptionLines: 2,
10
    // 其他配置...
11
},

踩坑记录#

问题 1：TypeScript 类型错误#

一开始直接在配置里写 coverPosition: "top"，结果报错：

不能将类型”top”分配给类型”left” | “right” | undefined”

原因： 类型定义文件中没有 "top" 选项。

解决： 先修改 types/siteConfig.ts，添加 "top" 类型。

问题 2：修改后没有效果#

改了配置和样式，但页面没有任何变化。

原因： PostPage.astro 中的 coverPositionClass 只处理了 "left"，没有处理 "top"，导致 cover-top 这个 class 根本没被加到容器上。

解决： 修改 PostPage.astro，添加对 "top" 的判断逻辑。

小结#

整体修改涉及 4 个文件，核心逻辑就是四步：

在类型定义中添加新选项
在配置中启用新选项
在组件中添加对应的 CSS 样式
在页面中添加对应的 class 处理

Firefly 主题的组件化设计很清晰，修改起来逻辑明确，唯一需要注意的就是别漏了 PostPage.astro 里的 class 映射——我一开始就栽在这了，样式写了半天不生效，最后发现是 class 根本没挂上去。

音乐

音乐

Firefly 主题自定义文章封面位置：实现列表模式封面在上方#

最终效果#

需要修改的文件#

第一步：修改类型定义#

第二步：修改配置文件#

第三步：修改文章卡片组件#

3.1 添加变量判断#

3.2 修改容器 class#

3.3 添加 CSS 样式#

第四步：修改文章列表页面#

完整配置参考#

踩坑记录#

问题 1：TypeScript 类型错误#

问题 2：修改后没有效果#

小结#

支持与分享

评论区

音乐

基于Firefly主题的列表封面位置改造

Firefly 主题自定义文章封面位置：实现列表模式封面在上方#

最终效果#

需要修改的文件#

第一步：修改类型定义#

第二步：修改配置文件#

第三步：修改文章卡片组件#

3.1 添加变量判断#

3.2 修改容器 class#

3.3 添加 CSS 样式#

第四步：修改文章列表页面#

完整配置参考#

踩坑记录#

问题 1：TypeScript 类型错误#

问题 2：修改后没有效果#

小结#

支持与分享

评论区