Node API 是由 @vuepress/core 包提供的。它是 vuepress 包的依赖之一,当然你也可以单独安装它:
npm i -D @vuepress/core@next
插件 API 的所有 Hooks 中都可以获取到 App 实例。
BuildApp
和 DevApp
除了 build 和 dev 方法外,拥有一样的属性和方法。
- 函数签名:
const createBuildApp: (config: AppConfig) => BuildApp
- 参数:
参数 | 类型 | 描述 |
---|---|---|
config | AppConfig |
创建 VuePress App 的选项。 |
-
详情:
创建一个 Build 模式的 App 实例,用于构建静态文件。
-
示例:
const build = async () => {
const app = createBuildApp({
// ...配置项
})
// 初始化和准备
await app.init()
await app.prepare()
// 构建
await app.build()
// 处理 onGenerated hook
await app.pluginApi.hooks.onGenerated.process(app)
}
- 函数签名:
const createDevApp: (config: AppConfig) => DevApp
- 参数:
参数 | 类型 | 描述 |
---|---|---|
config | AppConfig |
创建 VuePress App 的选项。 |
-
详情:
创建一个 Dev 模式的 App 实例,用于启动开发服务器。
-
示例:
const dev = async () => {
const app = createDevApp({
// ...配置项
})
// 初始化和准备
await app.init()
await app.prepare()
// 启动开发服务器
const closeDevServer = await app.dev()
// 准备文件监听器
const watchers = []
// 重启开发服务器
const restart = async () => {
await Promise.all([
// 关闭所有监听器
...watchers.map((item) => item.close()),
// 关闭当前的开发服务器
closeDevServer(),
])
await dev()
}
// 处理 onWatched hook
await app.pluginApi.hooks.onWatched.process(app, watchers, restart)
}
-
类型:
AppOptions
-
详情:
VuePress App 的配置项。
这些配置项来自于 createBuildApp / createDevApp 的
config
参数,但所有可选的字段都填充上了默认值。
-
类型:
SiteData
-
详情:
由用户设置的站点数据,包含所有的 站点配置 ,可以在客户端代码中使用。
-
类型:
string
-
详情:
VuePress App 的版本,即
@vuepress/core
包的版本。
-
类型:
boolean
-
详情:
用于判断 App 是否运行在 Build 模式的环境标记,即当前 App 是否是 BuildApp 实例。
-
类型:
boolean
-
详情:
用于判断 App 是否运行在 Dev 模式的环境标记,即当前 App 是否是 DevApp 实例。
-
类型:
boolean
-
详情:
用于判断 App 是否开启 Debug 模式的环境标记。
-
类型:
MarkdownIt
-
详情:
用于解析 Markdown 内容的 markdown-it 实例。
它仅在 onInitialized 以及之后的 Hooks 中才可用。
-
类型:
Page[]
-
详情:
Page 对象数组。
它仅在 onInitialized 以及之后的 Hooks 中才可用。
-
工具函数:
dir.cache()
: 解析至缓存目录dir.temp()
: 解析至临时文件目录dir.source()
: 解析至源文件目录dir.dest()
: 解析至输出目录dir.client()
: 解析至@vuepress/client
目录dir.public()
: 解析至 Public 文件目录
-
函数签名:
type AppDirFunction = (...args: string[]) => string
-
详情:
用于解析对应目录下的文件绝对路径的一些工具函数。
如果你不传入任何参数,就会返回对应目录的绝对路径。
-
示例:
// 解析 `${sourceDir}/README.md` 文件的绝对路径
const homeSourceFile = app.dir.source('README.md')
- 函数签名:
writeTemp(file: string, content: string): Promise<string>
- 参数:
参数 | 类型 | 描述 |
---|---|---|
file | string |
要写入的临时文件的路径,相对于临时文件目录。 |
content | string |
要写入的临时文件路径的内容。 |
-
详情:
用于写入临时文件的方法。
写入的文件可以在客户端文件中通过
@temp
别名来引入。 -
示例:
export default {
// 在 onPrepared hook 中写入临时文件
async onPrepared() {
await app.writeTemp('foo.js', 'export const foo = \'bar\'')
}
}
// 在客户端文件中引入临时文件
import { foo } from '@temp/foo'
- 函数签名:
init(): Promise<void>
-
详情:
初始化 VuePress App 。
-
参考:
- 函数签名:
prepare(): Promise<void>
-
详情:
准备客户端临时文件。
-
参考:
- 函数签名:
build(): Promise<void>
-
详情:
生成静态站点文件。
该方法仅在 BuildApp 中可用。
-
参考:
- 函数签名:
dev(): Promise<() => Promise<void>>
-
详情:
启动开发服务器。
该方法仅在 DevApp 中可用。
-
参考:
- 函数签名:
const createPage: (app: App, options: PageOptions) => Promise<Page>
- 参数:
参数 | 类型 | 描述 |
---|---|---|
app | App |
VuePress App 实例。 |
options | PageOptions |
创建 VuePress Page 的选项。 |
-
详情:
创建一个 VuePress Page 对象。
-
示例:
import { createPage } from '@vuepress/core'
export default {
// 在 onInitialized hook 中创建一个额外页面
async onInitialized(app) {
app.pages.push(
await createPage(app, {
path: '/foo.html',
frontmatter: {
layout: 'Layout',
},
content: `\
# 某个 Page
你好,世界。
`,
})
)
},
}
-
类型:
string
-
详情:
该 Page 的标识。
Page Key 会被用作页面路由的 name。
-
参考:
-
类型:
string
-
详情:
该 Page 的路由路径。
-
参考:
-
类型:
string
-
详情:
该 Page 的标题。
-
参考:
-
类型:
string
-
详情:
该 Page 的语言。
-
示例:
'en-US'
'zh-CN'
-
参考:
-
类型:
PageFrontmatter
-
详情:
该 Page 的 Frontmatter 。
-
参考:
- 类型:
PageHeader[]
interface PageHeader {
level: number
title: string
slug: string
children: PageHeader[]
}
-
详情:
该 Page 的小标题。
-
参考:
- 类型:
PageData
interface PageData {
key: string
path: string
title: string
lang: string
frontmatter: PageFrontmatter
headers: PageHeader[]
}
-
详情:
该 Page 的数据。
Page 数据可以在客户端代码中使用。
-
参考:
-
类型:
string
-
详情:
该 Page 的未经渲染的原始内容。
-
类型:
string
-
详情:
该 Page 的渲染后的内容。
-
类型:
string
-
详情:
该 Page 的日期,遵从 'yyyy-MM-dd' 格式。
-
示例:
'0000-00-00'
'2021-08-16
'
-
参考:
-
类型:
string[]
-
详情:
该 Page 的依赖。
举例来说,如果在页面中导入了代码片段,那么被导入文件的绝对路径就会被添加到
deps
中。 -
参考:
- 类型:
MarkdownLink[]
interface MarkdownLink {
raw: string
relative: string
absolute: string
}
-
详情:
该 Page 内容中包含的链接。
-
类型:
Record<string, unknown>
-
详情:
在使用 markdown-it 解析 Markdown 内容时的
env
对象。一些 markdown-it 插件可能会在这个对象中存储一些额外的信息,你可以使用它们来进行高级定制化。
需要注意的是,其他的一些 Page 属性其实也是从
env
对象中获取到的,但是我们已经把这些属性从page.markdownEnv
中移除掉了。 -
参考:
-
类型:
string | null
-
详情:
该 Page 根据文件路径推断出的路由路径。
默认情况下,路由路径是根据 Markdown 源文件的相对文件路径推断出来的。然而,用户可能会显式指定页面路由,比如通过 permalink 来指定该页面最终使用的路由路径。因此我们在 Page 属性中保留推断出来的路径,以便于你在某些情况下可能会用到它。
如果该 Page 不是来自于 Markdown 源文件,那么该属性会为
null
。 -
示例:
'/'
'/foo.html'
-
参考:
-
类型:
string
-
详情:
该 Page 路由路径的 Locale 前缀。
它是根据页面的 Markdown 源文件相对路径、以及用户配置的
locales
的键推断得到的。 -
示例:
'/'
'/en/'
'/zh/'
-
参考:
-
类型:
string | null
-
详情:
该 Page 的永久链接。
-
参考:
-
类型:
Record<string, unknown>
-
详情:
附加到 vue-router 路由记录上的额外数据。
-
参考:
::: tip Route Meta 和 Page Data 的区别是什么? Route Meta 和 Page Data 都可以在客户端代码中使用。然而, Route Meta 是附加在路由记录上的,因此当用户进入你的站点时,所有页面的 Route Meta 都会立即被加载。相比之下, Page Data 是存储在单独的文件中的,只有在用户进入对应页面时才会被加载。
因此,不建议在 Route Meta 中存储大量的信息,否则在站点有很多页面时,将会影响站点的初始加载速度。 :::
-
类型:
MarkdownSfcBlocks
-
详情:
该 Page 中提取出的 Vue SFC Blocks 。
-
参考:
-
类型:
string
-
详情:
该 Page 的 Slug 。
它是根据页面的 Markdown 源文件的文件名推断得到的。
-
类型:
string | null
-
详情:
该 Page 的 Markdown 源文件的绝对路径。
如果该 Page 不是来自于 Markdown 源文件,那么该属性会为
null
。
-
类型:
string | null
-
详情:
该 Page 的 Markdown 源文件的相对路径。
如果该 Page 不是来自于 Markdown 源文件,那么该属性会为
null
。