# ランタイム API {#runtime-api}

VitePress には、アプリのデータへアクセスするための組み込み API がいくつか用意されています。さらに、グローバルに使用できる組み込みコンポーネントも提供されています。

ヘルパーメソッドは `vitepress` からグローバルインポートでき、主にカスタムテーマの Vue コンポーネントで使われます。Markdown ファイルは Vue の [Single File Component](https://vuejs.org/guide/scaling-up/sfc.html) にコンパイルされるため、`.md` ファイル内でも使用できます。

`use*` で始まるメソッドは [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) の関数（Composable）で、`setup()` または `<script setup>` の中でのみ使用できます。

## `useData` <Badge type="info" text="composable" />

ページ固有のデータを返します。戻り値の型は次のとおりです。

```ts
interface VitePressData<T = any> {
  /**
   * サイト全体のメタデータ
   */
  site: Ref<SiteData<T>>
  /**
   * .vitepress/config.js の themeConfig
   */
  theme: Ref<T>
  /**
   * ページ単位のメタデータ
   */
  page: Ref<PageData>
  /**
   * ページのフロントマター
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * 動的ルートのパラメータ
   */
  params: Ref<PageData['params']>
  title: Ref<string>
  description: Ref<string>
  lang: Ref<string>
  isDark: Ref<boolean>
  dir: Ref<string>
  localeIndex: Ref<string>
  /**
   * 現在の location hash
   */
  hash: Ref<string>
}

interface PageData {
  title: string
  titleTemplate?: string | boolean
  description: string
  relativePath: string
  filePath: string,
  headers: Header[]
  frontmatter: Record<string, any>
  params?: Record<string, any>
  isNotFound?: boolean
  lastUpdated?: number
}
```

**使用例:**

```vue
<script setup>
import { useData } from 'vitepress'

const { theme } = useData()
</script>

<template>
  <h1>{{ theme.footer.copyright }}</h1>
</template>
```

## `useRoute` <Badge type="info" text="composable" />

現在のルートオブジェクトを返します。型は次のとおりです。

```ts
interface Route {
  path: string
  data: PageData
  component: Component | null
}
```

## `useRouter` <Badge type="info" text="composable" />

VitePress のルーターインスタンスを返し、プログラムで別ページへ遷移できます。

```ts
interface Router {
  /**
   * 現在のルート
   */
  route: Route
  /**
   * 新しい URL へ遷移
   */
  go: (to?: string) => Promise<void>
  /**
   * ルートが変わる前に呼ばれる。`false` を返すと遷移をキャンセル
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * ページコンポーネントが読み込まれる前（履歴が更新された後）に呼ばれる。
   * `false` を返すと遷移をキャンセル
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * ページコンポーネントが読み込まれた後（更新前）に呼ばれる
   */
  onAfterPageLoad?: (to: string) => Awaitable<void>
  /**
   * ルートが変わった後に呼ばれる
   */
  onAfterRouteChange?: (to: string) => Awaitable<void>
}
```

## `withBase` <Badge type="info" text="helper" />

- **型**: `(path: string) => string`

設定された [`base`](./site-config#base) を指定の URL パスに付与します。[Base URL](../guide/asset-handling#base-url) も参照。

## `<Content />` <Badge type="info" text="component" />

レンダリング済みの Markdown コンテンツを表示します。［独自テーマの作成時］(../guide/custom-theme) に便利です。

```vue
<template>
  <h1>Custom Layout!</h1>
  <Content />
</template>
```

## `<ClientOnly />` <Badge type="info" text="component" />

スロット内容をクライアント側でのみレンダリングします。

VitePress アプリは静的ビルド時に Node.js 上でサーバーレンダリングされるため、Vue の使用はユニバーサルコードの要件に従う必要があります。要するに、ブラウザ／DOM API へのアクセスは beforeMount / mounted フック内に限定してください。

SSR 非対応（例: カスタムディレクティブを含む）なコンポーネントを使用・デモする場合は、`ClientOnly` でラップできます。

```vue-html
<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>
```

- 関連: [SSR 互換性](../guide/ssr-compat)

## `$frontmatter` <Badge type="info" text="template global" />

Vue の式内で現在ページの [フロントマター](../guide/frontmatter) に直接アクセスします。

```md
---
title: Hello
---

# {{ $frontmatter.title }}
```

## `$params` <Badge type="info" text="template global" />

Vue の式内で現在ページの [動的ルートのパラメータ](../guide/routing#dynamic-routes) に直接アクセスします。

```md
- package name: {{ $params.pkg }}
- version: {{ $params.version }}
```