配置字典:Blog List 与标签列表

$ 发布 2026-11-13 | | 更新 2026-11-14
语境: 说明博客归档与标签列表实际使用的配置字段、主题默认值、范围限制、共享行为和示例,并区分浏览器偏好与站点配置。

查询每页文章数、标签开关、分页窗口、跳页、样式和列表界面文案。


输出
词 3.6k 令牌 4.6k

版本说明: 下文 blogPageSize 的严格配置校验从 0.36.1 起提供,0.36.0 不包含。使用旧版时仍应自行填写合理的正整数。

返回配置字典总入口。本篇覆盖博客归档、标签目录、某个标签下的文章列表,以及它们共用的分页。以当前主题代码为准,不把演示站的文章数量或颜色当作默认值。

中文博客入口为 /zh/blog/,第二页为 /zh/blog/2/;标签目录为 /zh/tags/,单个标签的文章列表使用页面生成的链接。其他语言替换 zh,默认语言首页的地址模式不会去掉这些路径的语言前缀。

所有 TypeScript 示例合并到 src/site.config.ts 现有 defineThemeConfig 对象中。已有 theme、i18n、pagination 时修改其中字段,保留其他配置,不要重复添加同名对象。

1. 每页显示多少篇文章

theme.blogPageSize

  • 类型:number。
  • 主题默认值:10。
  • 作用:博客归档与每个标签文章列表的每页文章数,两处共用。文章先按当前语言筛选,再按 pubDate 从新到旧排列。
  • 状态:生效。
  • 限制:必须为正的安全整数。0、负数、小数、NaN、Infinity 和超出安全整数范围的值会在解析配置时明确报错,不会自动截断或恢复默认值;0 不是关闭分页的开关。
  • 范围:不改变首页最新文章数量,也不改变 Fragments 每页条数。标签目录本身不按这个字段分页。
theme: { blogPageSize: 12 },

博客没有文章时仍生成第一页;只有一页时不显示分页组件。调整每页数量后需要重新构建部署,原来存在的较大页码可能消失,主题不会为它们自动建立重定向。

排序依据不是 updatedDate、文件名或点击量。当前没有 draft/未来日期过滤,也没有列表排序字段;文章内容规则见写第一篇文章。

2. 标签入口与标签页面

theme.tags.enabled

  • 类型:boolean。
  • 主题默认值:true。
  • 作用:控制主题提供的标签入口、标签目录和标签文章列表。文章卡片及正文中的主题标签链接也受它控制。
  • 状态:生效。
  • 限制:设为 false 不会删除 frontmatter 的 tags、文章或已有部署文件;它也不是按标签过滤博客列表的开关。博客列表中的标签快捷入口还要求当前语言确实存在标签;开启但没有标签时,标签目录显示空提示。
theme: { tags: { enabled: false } },

标签来自文章 frontmatter 的 tags 数组,不存在需要维护的 site.config 标签注册表。同篇标签会去除首尾空白、丢弃空项并去重;大小写仍区分,Astro 与 astro 不合并。

标签目录按包含文章数量降序排列,数量相同按标签字符串顺序排列。特殊字符、中文、保留名称和过长标签有稳定编码,使用页面生成的链接;改标签名称可能改变路径,不会自动保留旧地址。

卡片当前最多显示两个标签,没有提供控制显示数量的配置。它不限制文章实际拥有多少标签,也不限制标签目录收录全部有效标签。

3. 页码窗口与跳页

theme.pagination.windowSize

  • 类型:number。
  • 主题默认值:7。
  • 作用:影响分页显示哪些页码、边界页和省略号,不是每页文章数。
  • 状态:条件生效,只有多于一页才有分页组件。
  • 限制:正常数值会向下取整并限制在 5–21。它是页码窗口策略参数,不保证最终“所有数字、上一页/下一页和省略号加起来”恰好等于该值;请使用有限整数。

theme.pagination.showJumpThreshold

  • 类型:number。
  • 主题默认值:12。
  • 作用:总页数严格大于阈值时,才允许出现跳页输入;还需要 jump.enabled 为 true。
  • 状态:条件生效。
  • 限制:正常数值向下取整后至少为 1。默认 12 页不出现,13 页才出现;它不是文章条数阈值,设为 0 也不会被当作无条件显示。

theme.pagination.jump.enabled

  • 类型:boolean。
  • 主题默认值:true。
  • 作用:允许显示跳页表单。
  • 状态与限制:条件生效;必须同时满足总页数大于阈值。false 只移除表单,页码和上一页/下一页链接仍在。跳页交互需要 JavaScript,普通分页链接不依赖它。

theme.pagination.jump.enterToGo

  • 类型:boolean。
  • 主题默认值:true。
  • 作用:允许在跳页输入中按 Enter 导航。
  • 状态与限制:条件生效;仅在跳页表单存在时有作用。false 会阻止输入框 Enter 提交,仍可点击跳转按钮。客户端会去除输入中的非数字字符,并将目标限制到实际页码范围,不提供任意 URL 跳转。

这些字段可以一起设置:

theme: {
  pagination: {
    windowSize: 9,
    showJumpThreshold: 8,
    jump: { enabled: true, enterToGo: false },
  },
},

上述分页行为也用于 Fragments;碎片每页数量仍由它自己的 pageSize 决定。不要为了修改一个标签列表,误以为分页设置只作用于该标签。

4. 分页外观策略

theme.pagination.style.enabled

  • 类型:boolean。
  • 主题默认值:true。
  • 作用:启用分页容器和页码按钮的变体策略。
  • 状态与限制:条件生效;false 使用基础变体 1,不删除分页,不改变文章数量,也不是关闭整页 Cyberpunk 效果。它不控制文章卡片或 Cards/List 切换控件的随机色。

theme.pagination.style.mode

  • 类型:'random' | 'sequential' | 'fixed'。
  • 主题默认值:'random'。
  • 作用:决定分页外观变体如何选择。
  • 状态与限制:条件生效;style.enabled 为 true 才使用该策略。三种模式如下:
模式 当前行为
random 构建时给出稳定的初始变体;客户端初始化后为容器及按钮重新取随机变体,可能重复,不是持续轮换动画
sequential 容器按页码依次选择,按钮按各自序号选择;不同按钮不一定同色,不按时间轮换
fixed 容器与按钮使用 fixedVariant 指定的同一变体

禁用 JavaScript 时,保留静态 HTML 中的初始样式,不会执行客户端随机选择。

theme.pagination.style.variants

  • 类型:number。
  • 主题默认值:9。
  • 作用:参与变体选择的数量,使用编号 1 到 N;不是多选数组,也不是全站主题数量。
  • 状态与限制:条件生效;组件正常数值向下取整后限制在 1–12。但当前共享霓虹颜色只定义了 1–9,10–12 不应当理解为额外三套完整配色,可能回落到继承/基础色。建议使用 1–9,并保留默认 9 作为通常选择。这个范围说明不是新增颜色能力。

theme.pagination.style.fixedVariant

  • 类型:number。
  • 主题默认值:1。
  • 作用:fixed 模式下指定变体编号。
  • 状态与限制:条件生效;正常数值向下取整,并限制在 1 到当前 variants 范围。random 和 sequential 不使用它来固定样式;当前完整霓虹颜色建议选择 1–9。请使用有限整数。

例如固定为第二种分页外观:

theme: {
  pagination: {
    style: { enabled: true, mode: 'fixed', variants: 9, fixedVariant: 2 },
  },
},

只想保留基础分页样式,可以合并 theme: { pagination: { style: { enabled: false } } }。两种示例选需要的使用,不必连续复制来回覆盖。

5. 列表标题、描述和分页文字

以下完整前缀为 i18n.locales.<语言>.messages.blog,类型均为可选的 string 覆盖,状态均为条件生效:只有使用到对应标题、描述或控件时才出现。默认值经内置语言文案及回退解析;下表只列中文与英文,其他语言有自己的内置值。

字段 中文默认 / 英文默认 作用与限制
title 博客 / Blog 博客第一页页面标题及隐藏的区块标题,不是文章标题,也不替换固定的卡片切换按钮文案
pageTitle 博客 - 第 / Blog - Page 博客后续分页标题前缀,也用于标签后续页的标题;代码追加页码,不处理自定义占位符
archiveDescription 关于 AI 时代开发、Web 工程与系统架构的文章。 / Essays on AI-era craft, web engineering, and system architecture. 博客第一页和标签目录的页面元描述,不是每张文章卡片摘要
pageDescription 博客归档页 / Blog archive page 博客后续分页的元描述前缀,代码追加页码和句号;不用于标签文章列表的同一描述位置
i18n: {
  locales: {
    zh: {
      messages: {
        blog: {
          title: '文章归档',
          pageTitle: '文章归档 - 第',
          archiveDescription: '项目、阅读与学习笔记。',
          pageDescription: '文章归档分页',
        },
      },
    },
  },
},

分页相关字段使用相同前缀和 string 类型:

字段 中文默认 / 英文默认 作用与限制
previous 上一页 / Previous 上一页链接的可见文字及可访问名称;第一页不显示该链接
next 下一页 / Next 下一页链接的可见文字及可访问名称;最后一页不显示该链接
paginationAria 分页导航 / Pagination 分页 nav 的可访问名称,不是额外可见大标题
jumpTo 跳转到页 / Jump to page 跳页输入旁的可见文字;表单满足条件才显示
jumpInputLabel 页码 / Page number 输入框隐藏标签,提供可访问名称;不会改变输入格式
jumpGo 跳转 / Go 跳页提交按钮文字,不改变目标路径

这些字段也服务于标签列表和 Fragments 的共享分页。博客路由对空 jumpTo/jumpInputLabel/jumpGo 另有英文备用文字,但标签路由直接传递解析后的值;不要用空字符串来跨页面隐藏控件。需要隐藏跳页用 jump.enabled,保留有意义的可访问名称。

i18n: {
  locales: {
    zh: {
      messages: {
        blog: {
          previous: '前一页',
          next: '后一页',
          paginationAria: '文章分页',
          jumpTo: '前往第几页',
          jumpInputLabel: '目标页码',
          jumpGo: '前往',
        },
      },
    },
  },
},

6. 标签目录和共享入口文字

仍使用 i18n.locales.<语言>.messages.blog,类型为可选 string 覆盖,按普通界面文案回退。作用均依赖相应区域存在:

字段 中文默认 / 英文默认 作用与限制
tags 标签 / Tags 标签快捷入口、目录和标签列表标题,以及相关可访问名称;不修改文章的实际标签文字或 slug
allPosts 全部文章 / All posts 返回全部文章的入口文字,也被首页用作说明;不改变文章总数
noTags 暂无标签 / No tags yet. 标签目录中没有有效标签时的提示;不是博客无文章提示
taggedPosts 文章 / Posts 标签所含文章数量的说明及标签页描述;不是手工设置计数
i18n: {
  locales: {
    zh: {
      messages: {
        blog: {
          tags: '按标签浏览',
          allPosts: '返回全部文章',
          noTags: '暂时没有可浏览的标签。',
          taggedPosts: '篇文章',
        },
      },
    },
  },
},

清空文字不会关闭对应功能,可能留下空白链接或不完整描述。关闭标签用 theme.tags.enabled,而不是将 tags 文案设为 false 或空字符串。

7. Cards/List、封面和其他边界

以下是当前实现行为,不是新增配置字段:

  • 博客和标签文章列表共用 Cards/List 切换。没有记忆时默认 cards;启用 JavaScript 后可切换,浏览器 localStorage 使用同一偏好键,所以跨博客、标签及语言页面共用选择。存储不可用时仍可切换,但不保证记住。
  • 当前没有 site.config 的默认视图、禁用切换按钮、视图文字、列表列名或卡片颜色字段。切换按钮和归档栏使用组件内置语言表,自定义语言没有专用表项时使用英文;不能用 messages.blog.title 修改它们。
  • 当前渲染卡片的标题、日期、封面及最多两个标签;没有配置项开启卡片摘要、改变封面优先候选数量或指定按 updatedDate 排序。description 不会因改列表元描述就成为卡片摘要。
  • 列表前两张实际有封面的候选使用 eager/high,其余 lazy。List 视图隐藏封面不保证这些候选不会下载;图片准备与体积控制见图片教程。
  • 主博客分页切换语言时,目标语言有相应页码就保留页码,否则回该语言博客第一页。标签列表切换语言会寻找相同标签文字,存在则进该标签第一页,不存在则进目标语言标签目录;不会自动翻译标签或匹配近义词。
  • homepage 最新文章数量和穿越效果见首页字典。公共导航、搜索开关、页脚和评论不在本篇重新定义。

本篇未发现需要作为兼容保留收录的列表专用字段;不要把不存在的 blogView、showExcerpt 或 cardTheme 当作已接受字段。未提供配置的外观能力不通过添加任意键生效。

修改后怎么确认?

先在 dev 检查博客第一页、后续分页、标签目录和某个标签列表。跳页必须有足够总页数,样式 fixed 要与 random 区分;元描述查看页面 head,隐藏标签和可访问名称不能只凭页面大字判断。

修改每页文章数或标签名称后,重新构建并完整部署,注意旧分页/旧标签文件残留。发布前停止 dev,运行 npm run doctor 后再用 npm run preview 查看构建结果;doctor 已含构建,无需立即重复 check 和 build。步骤见安装教程和部署教程。