VuePress 全局计算属性Global Computed完全指南$site、$page 与全套数据注入机制【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress本文围绕 VuePress 内置的核心计算属性体系展开系统讲解$site、$page、$frontmatter、$lang、$localePath、$title、$description与$themeConfig这八个全局计算属性的数据来源、JSON 形态与实际用途。读完本文你将能够理解这些属性在默认主题与自定义主题中的注入机制并学会在 Markdown 页面与 Vue 组件中正确引用它们从而写出数据驱动、支持多语言的 VuePress 站点。概览全局计算属性从哪来在 VuePress 中每个页面在编译时都会成为一个 Vue 组件而这些组件天然拥有一组以$开头的全局计算属性。它们由核心包 packages/vuepress/core 注入既可供默认主题或自定义主题的布局组件使用也可以在 Markdown 页面中直接通过 Vue 插值访问参见在 Markdown 中使用 Vue。从源码结构看这套属性体系由两个文件共同支撑node/ClientComputedMixin.js定义了一个ClientComputedMixin类通过 getter 实现全部$计算属性同一份代码在服务端与客户端都会执行client/dataMixin.js在客户端运行时读取internal/siteData模块中的站点数据把上述 mixin 的 getter 收集为computed选项并注入所有组件。其中站点数据本身由内部插件 node/internal-plugins/siteData.js 生成它调用ctx.getSiteData()并把结果序列化为siteData.js这一动态模块。而getSiteData()的定义在 node/App.js它把站点配置组装为包含title、description、base、headTags、pages、themeConfig、locales的完整对象。可以说本文介绍的每一个$属性最终都能追溯到App.js中的getSiteData()与Page.js中的页面数据。$site全站元数据$site承载的是整个站点的全局配置数据。以下是官方文档给出的、当前文档站自身的$site值示例{ title: VuePress, description: Vue 驱动的静态网站生成器, base: /, pages: [ { lastUpdated: 1524027677000, path: /, title: VuePress, frontmatter: {} }, ... ] }从实现上看$site的 getter 直接返回siteData见 ClientComputedMixin.js而这个siteData就是getSiteData()的输出。值得注意的是在客户端注入时dataMixin.js 会先对siteData做两件事为locales中每个路径补上path字段然后对整个对象执行Object.freeze冻结防止运行时被意外修改——这解释了为什么$site在页面中始终是稳定只读的。$site的核心字段及其来源字段来源说明titlesiteConfig.title站点标题未配置时为空字符串descriptionsiteConfig.description站点描述basesiteConfig.base站点根路径如/或/my-site/headTagssiteConfig.head需要注入head的标签数组pagesthis.pages.map(page page.toJson())全部页面数据的 JSON 序列化数组themeConfigsiteConfig.themeConfig主题配置对象localessiteConfig.locales多语言配置每个路径会被补上path字段典型使用场景在布局组件中遍历$site.pages生成站点地图、读取$site.base拼接资源路径或在自定义主题中读取$site.themeConfig控制外观。$page当前页面数据$page表示当前正在渲染的页面数据。文档给出的当前页面$page值示例{ title: Global Computed, frontmatter: { sidebar: auto }, regularPath: /zh/miscellaneous/global-computed.html, key: v-bc9a3e3f9692d, path: /zh/miscellaneous/global-computed.html, headers: [ { level: 2, title: $site, slug: site }, { level: 2, title: $page, slug: page }, ... ] }从源码看$page的取值逻辑有两层见 ClientComputedMixin.js如果组件实例上已被setPage(page)设置了__page则直接返回它——SSR 服务端渲染阶段正是通过这种方式把当前页面数据绑定到组件上否则回退到findPageForPath($site.pages, $route.path)根据当前路由路径在$site.pages中查找匹配页面找不到时返回{ path: , frontmatter: {} }这样的空壳对象。而页面对象本身的字段是在 node/Page.js 的Page类构造过程中生成的regularPath由 Markdown 源文件的相对路径转换而来例如fileToPath(relative)key形如v-开头的哈希值即v- hash(filePath regularPath)作为页面的唯一标识path优先取regularPath之后可被permalink覆盖title由 Markdown 内容推断inferTitle或来自 frontmatterheaders通过extractHeaders从内容中提取的标题树默认提取h2、h3frontmatter页面文件头部的 YAML frontmatter。理解$page.key很重要内置的Content组件依赖pageKey渲染指定页面详情可参考在 Markdown 中使用 Vue 内置的组件。$frontmatter页面配置的快捷入口$frontmatter只是$page.frontmatter的引用见 ClientComputedMixin.js语法上更简短适合在模板中高频访问页面级配置。span v-if$frontmatter.sidebar auto自动侧边栏已开启/spanfrontmatter 由Page.js通过parseFrontmatter解析并Object.assign合并进页面对象支持title、sidebar、home、lang、description、meta等大量字段完整清单参见页面 Frontmatter。$lang当前页面语言$lang返回当前页面的语言代码默认值为en-US。其计算顺序如下见 ClientComputedMixin.jsget $lang () { return this.$page.frontmatter.lang || this.$localeConfig.lang || en-US }即优先级为页面 frontmatter 中的lang 当前 locale 配置的langen-US默认值。这套取值逻辑保证了单语言站点无需任何配置即可得到默认值而多语言站点则能精确反映每个语言版本的页面。更多细节参见多语言支持。$localePath当前 locale 路径前缀$localePath返回当前页面的 locale 路径前缀默认值为/。在官方文档站的中文站点中该值为/zh/。其实现为get $localePath () { return this.$localeConfig.path || / }这里依赖$localeConfig的解析逻辑ClientComputedMixin.js遍历$site.locales如果页面路径以某个 locale 路径开头如/zh/就命中该 locale 配置/路径的配置被视作默认语言都不命中时回退到{}。$localePath在插件生态中尤其常用客户端工具函数normalizeConfig就是借助$localePath把{ /: ..., /zh/: ... }形式的多语言配置归一化为当前语言的字符串见 client/util.js。开发者也可以用它拼接多语言站点内的跳转链接。$title页面title标签的值$title返回用于当前页面title标签的字符串。它的取值逻辑是整个体系中较为复杂的见 ClientComputedMixin.jsget $title () { const page this.$page const { metaTitle } this.$page.frontmatter if (typeof metaTitle string) { return metaTitle } const siteTitle this.$siteTitle const selfTitle page.frontmatter.home ? null : ( page.frontmatter.title // explicit title || page.title // inferred title ) return siteTitle ? selfTitle ? (selfTitle | siteTitle) : siteTitle : selfTitle || VuePress }归纳其优先级frontmatter 中的metaTitle若有直接采用首页frontmatter.home为真不取自身标题存在站点标题时非首页拼接为页面标题 | 站点标题无站点标题时仅用页面自身标题最终兜底为VuePress。这套规则也正是 VuePress 默认在浏览器标签栏显示页面标题 | 站点标题的原因。$description页面描述元信息$description返回用于当前页面meta namedescription content...的content值。其计算顺序见 ClientComputedMixin.jsget $description () { // #565 hoist description from meta const description getMetaDescription(this.$page.frontmatter.meta) if (description) { return description } return this.$page.frontmatter.description || this.$localeConfig.description || this.$site.description || }优先级为frontmattermeta数组中name description的条目 frontmatterdescription locale 配置的description 站点级description 空字符串。其中从meta数组中提取描述的getMetaDescription函数是仓库在 issue #565 之后加入的增强逻辑用于兼容meta: [{ name: description, content: ... }]这种写法。该属性通常被updateMetaroot-mixin 消费用于在运行时更新页面head中的描述标签。$themeConfig主题配置对象$themeConfig就是siteConfig.themeConfig的引用get $themeConfig () { return this.$site.themeConfig }它在getSiteData()中被规范化输出为siteConfig.themeConfig || {}。默认主题的导航栏、侧边栏、搜索等配置都从这里读取自定义主题同样推荐通过它暴露自己的配置项。与$themeConfig配套的还有$themeLocaleConfig见 ClientComputedMixin.js它按$localePath从themeConfig.locales中取出当前语言的子配置是构建多语言主题时的常用搭档。完整的主题配置项说明见默认主题配置与编写主题。在 Markdown 中直接使用全局计算属性除了主题组件Markdown 页面本身也能访问这些属性——因为每个 Markdown 文件都会被编译为 Vue 组件。例如在正文中直接输出当前页面数据输入{{ $page }}输出{ path: /using-vue.html, title: Using Vue in Markdown, frontmatter: {} }这依赖dataMixin.js中把ClientComputedMixin的全部 getter 注入为组件computed的机制。模板插值、v-for指令乃至组件间的数据传递都可以借助这套属性完成相关用法可继续阅读在 Markdown 中使用 Vue。优先级速查表属性含义默认值计算来源按优先级$site全站元数据—getSiteData()输出$page当前页面数据空壳对象setPage注入 按路由查找$frontmatter页面 frontmatter{}$page.frontmatter$lang页面语言en-USfrontmatterlang localelang$localePathlocale 路径前缀/$localeConfig.path$titletitle内容VuePressmetaTitle 拼接逻辑$description描述 meta 内容meta 数组 frontmatter locale site$themeConfig主题配置{}siteConfig.themeConfig掌握这套全局计算属性就等于掌握了 VuePress 数据流的入口无论是定制主题、开发插件还是编写文档页面的动态内容都能以统一、只读、可预测的方式读取站点与页面的全部元数据。【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 VuePress 全局计算属性（Global Computed）完全指南：$site、$page 与全套数据注入机制
VuePress 全局计算属性Global Computed完全指南$site、$page 与全套数据注入机制【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress本文围绕 VuePress 内置的核心计算属性体系展开系统讲解$site、$page、$frontmatter、$lang、$localePath、$title、$description与$themeConfig这八个全局计算属性的数据来源、JSON 形态与实际用途。读完本文你将能够理解这些属性在默认主题与自定义主题中的注入机制并学会在 Markdown 页面与 Vue 组件中正确引用它们从而写出数据驱动、支持多语言的 VuePress 站点。概览全局计算属性从哪来在 VuePress 中每个页面在编译时都会成为一个 Vue 组件而这些组件天然拥有一组以$开头的全局计算属性。它们由核心包 packages/vuepress/core 注入既可供默认主题或自定义主题的布局组件使用也可以在 Markdown 页面中直接通过 Vue 插值访问参见在 Markdown 中使用 Vue。从源码结构看这套属性体系由两个文件共同支撑node/ClientComputedMixin.js定义了一个ClientComputedMixin类通过 getter 实现全部$计算属性同一份代码在服务端与客户端都会执行client/dataMixin.js在客户端运行时读取internal/siteData模块中的站点数据把上述 mixin 的 getter 收集为computed选项并注入所有组件。其中站点数据本身由内部插件 node/internal-plugins/siteData.js 生成它调用ctx.getSiteData()并把结果序列化为siteData.js这一动态模块。而getSiteData()的定义在 node/App.js它把站点配置组装为包含title、description、base、headTags、pages、themeConfig、locales的完整对象。可以说本文介绍的每一个$属性最终都能追溯到App.js中的getSiteData()与Page.js中的页面数据。$site全站元数据$site承载的是整个站点的全局配置数据。以下是官方文档给出的、当前文档站自身的$site值示例{ title: VuePress, description: Vue 驱动的静态网站生成器, base: /, pages: [ { lastUpdated: 1524027677000, path: /, title: VuePress, frontmatter: {} }, ... ] }从实现上看$site的 getter 直接返回siteData见 ClientComputedMixin.js而这个siteData就是getSiteData()的输出。值得注意的是在客户端注入时dataMixin.js 会先对siteData做两件事为locales中每个路径补上path字段然后对整个对象执行Object.freeze冻结防止运行时被意外修改——这解释了为什么$site在页面中始终是稳定只读的。$site的核心字段及其来源字段来源说明titlesiteConfig.title站点标题未配置时为空字符串descriptionsiteConfig.description站点描述basesiteConfig.base站点根路径如/或/my-site/headTagssiteConfig.head需要注入head的标签数组pagesthis.pages.map(page page.toJson())全部页面数据的 JSON 序列化数组themeConfigsiteConfig.themeConfig主题配置对象localessiteConfig.locales多语言配置每个路径会被补上path字段典型使用场景在布局组件中遍历$site.pages生成站点地图、读取$site.base拼接资源路径或在自定义主题中读取$site.themeConfig控制外观。$page当前页面数据$page表示当前正在渲染的页面数据。文档给出的当前页面$page值示例{ title: Global Computed, frontmatter: { sidebar: auto }, regularPath: /zh/miscellaneous/global-computed.html, key: v-bc9a3e3f9692d, path: /zh/miscellaneous/global-computed.html, headers: [ { level: 2, title: $site, slug: site }, { level: 2, title: $page, slug: page }, ... ] }从源码看$page的取值逻辑有两层见 ClientComputedMixin.js如果组件实例上已被setPage(page)设置了__page则直接返回它——SSR 服务端渲染阶段正是通过这种方式把当前页面数据绑定到组件上否则回退到findPageForPath($site.pages, $route.path)根据当前路由路径在$site.pages中查找匹配页面找不到时返回{ path: , frontmatter: {} }这样的空壳对象。而页面对象本身的字段是在 node/Page.js 的Page类构造过程中生成的regularPath由 Markdown 源文件的相对路径转换而来例如fileToPath(relative)key形如v-开头的哈希值即v- hash(filePath regularPath)作为页面的唯一标识path优先取regularPath之后可被permalink覆盖title由 Markdown 内容推断inferTitle或来自 frontmatterheaders通过extractHeaders从内容中提取的标题树默认提取h2、h3frontmatter页面文件头部的 YAML frontmatter。理解$page.key很重要内置的Content组件依赖pageKey渲染指定页面详情可参考在 Markdown 中使用 Vue 内置的组件。$frontmatter页面配置的快捷入口$frontmatter只是$page.frontmatter的引用见 ClientComputedMixin.js语法上更简短适合在模板中高频访问页面级配置。span v-if$frontmatter.sidebar auto自动侧边栏已开启/spanfrontmatter 由Page.js通过parseFrontmatter解析并Object.assign合并进页面对象支持title、sidebar、home、lang、description、meta等大量字段完整清单参见页面 Frontmatter。$lang当前页面语言$lang返回当前页面的语言代码默认值为en-US。其计算顺序如下见 ClientComputedMixin.jsget $lang () { return this.$page.frontmatter.lang || this.$localeConfig.lang || en-US }即优先级为页面 frontmatter 中的lang 当前 locale 配置的langen-US默认值。这套取值逻辑保证了单语言站点无需任何配置即可得到默认值而多语言站点则能精确反映每个语言版本的页面。更多细节参见多语言支持。$localePath当前 locale 路径前缀$localePath返回当前页面的 locale 路径前缀默认值为/。在官方文档站的中文站点中该值为/zh/。其实现为get $localePath () { return this.$localeConfig.path || / }这里依赖$localeConfig的解析逻辑ClientComputedMixin.js遍历$site.locales如果页面路径以某个 locale 路径开头如/zh/就命中该 locale 配置/路径的配置被视作默认语言都不命中时回退到{}。$localePath在插件生态中尤其常用客户端工具函数normalizeConfig就是借助$localePath把{ /: ..., /zh/: ... }形式的多语言配置归一化为当前语言的字符串见 client/util.js。开发者也可以用它拼接多语言站点内的跳转链接。$title页面title标签的值$title返回用于当前页面title标签的字符串。它的取值逻辑是整个体系中较为复杂的见 ClientComputedMixin.jsget $title () { const page this.$page const { metaTitle } this.$page.frontmatter if (typeof metaTitle string) { return metaTitle } const siteTitle this.$siteTitle const selfTitle page.frontmatter.home ? null : ( page.frontmatter.title // explicit title || page.title // inferred title ) return siteTitle ? selfTitle ? (selfTitle | siteTitle) : siteTitle : selfTitle || VuePress }归纳其优先级frontmatter 中的metaTitle若有直接采用首页frontmatter.home为真不取自身标题存在站点标题时非首页拼接为页面标题 | 站点标题无站点标题时仅用页面自身标题最终兜底为VuePress。这套规则也正是 VuePress 默认在浏览器标签栏显示页面标题 | 站点标题的原因。$description页面描述元信息$description返回用于当前页面meta namedescription content...的content值。其计算顺序见 ClientComputedMixin.jsget $description () { // #565 hoist description from meta const description getMetaDescription(this.$page.frontmatter.meta) if (description) { return description } return this.$page.frontmatter.description || this.$localeConfig.description || this.$site.description || }优先级为frontmattermeta数组中name description的条目 frontmatterdescription locale 配置的description 站点级description 空字符串。其中从meta数组中提取描述的getMetaDescription函数是仓库在 issue #565 之后加入的增强逻辑用于兼容meta: [{ name: description, content: ... }]这种写法。该属性通常被updateMetaroot-mixin 消费用于在运行时更新页面head中的描述标签。$themeConfig主题配置对象$themeConfig就是siteConfig.themeConfig的引用get $themeConfig () { return this.$site.themeConfig }它在getSiteData()中被规范化输出为siteConfig.themeConfig || {}。默认主题的导航栏、侧边栏、搜索等配置都从这里读取自定义主题同样推荐通过它暴露自己的配置项。与$themeConfig配套的还有$themeLocaleConfig见 ClientComputedMixin.js它按$localePath从themeConfig.locales中取出当前语言的子配置是构建多语言主题时的常用搭档。完整的主题配置项说明见默认主题配置与编写主题。在 Markdown 中直接使用全局计算属性除了主题组件Markdown 页面本身也能访问这些属性——因为每个 Markdown 文件都会被编译为 Vue 组件。例如在正文中直接输出当前页面数据输入{{ $page }}输出{ path: /using-vue.html, title: Using Vue in Markdown, frontmatter: {} }这依赖dataMixin.js中把ClientComputedMixin的全部 getter 注入为组件computed的机制。模板插值、v-for指令乃至组件间的数据传递都可以借助这套属性完成相关用法可继续阅读在 Markdown 中使用 Vue。优先级速查表属性含义默认值计算来源按优先级$site全站元数据—getSiteData()输出$page当前页面数据空壳对象setPage注入 按路由查找$frontmatter页面 frontmatter{}$page.frontmatter$lang页面语言en-USfrontmatterlang localelang$localePathlocale 路径前缀/$localeConfig.path$titletitle内容VuePressmetaTitle 拼接逻辑$description描述 meta 内容meta 数组 frontmatter locale site$themeConfig主题配置{}siteConfig.themeConfig掌握这套全局计算属性就等于掌握了 VuePress 数据流的入口无论是定制主题、开发插件还是编写文档页面的动态内容都能以统一、只读、可预测的方式读取站点与页面的全部元数据。【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考