API زمان اجرا

ویت‌پرس چندین API داخلی را ارائه می‌دهد تا به شما امکان دسترسی به داده‌های برنامه را بدهد. همچنین، ویت‌پرس با چندین کامپوننت داخلی همراه است که می‌توانید به صورت جهانی از آن‌ها استفاده کنید.

متدهای کمکی به صورت جهانی از vitepress قابل وارد کردن هستند و معمولاً در کامپوننت‌های Vue سفارشی تم استفاده می‌شوند. با این حال، آن‌ها همچنین در صفحات .md قابل استفاده هستند زیرا فایل‌های markdown به کامپوننت‌های فایل تکی Vue ترجمه می‌شوند.

متدهایی که با use* آغاز می‌شوند نشان می‌دهند که این یک تابع API ترکیبی Vue 3 ("Composable") است که فقط می‌تواند در setup() یا <script setup> استفاده شود.

useData composable

داده‌های خاص به صفحه را برمی‌گرداند. شیء برگشتی این نوع را دارد:

interface VitePressData<T = any> {
  /**
   * Metadata سطح سایت
   */
  site: Ref<SiteData<T>>
  /**
   * themeConfig از .vitepress/config.js
   */
  theme: Ref<T>
  /**
   * Metadata سطح صفحه
   */
  page: Ref<PageData>
  /**
   * Frontmatter صفحه
   */
  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>
  /**
   * مکان فعلی 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
}

مثال:

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

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

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

useRoute composable

شیء مسیر فعلی را با این نوع برمی‌گرداند:

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

useRouter composable

نمونه راوتر ویت‌پرس را برمی‌گرداند تا بتوانید به صورت برنامه‌ریزی‌شده به صفحه دیگری ناوبری کنید.

interface Router {
  /**
   * Route فعلی
   */
  route: Route
  /**
   * به URL جدید ناوبری کنید.
   */
  go: (to?: string) => Promise<void>
  /**
   * قبل از تغییر مسیر فراخوانی می‌شود. برای لغو ناوبری `false` را برگردانید.
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * قبل از بارگذاری مؤلفه صفحه فراخوانی می‌شود (پس از به‌روزرسانی وضعیت تاریخچه). برای لغو ناوبری `false` را برگردانید.
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * پس از تغییر مسیر فراخوانی می‌شود.
   */
  onAfterRouteChange?: (to: string) => Awaitable<void>
}

withBase helper

• نوع: (path: string) => string

پایه پیکربندی‌شده را به یک مسیر URL داده شده اضافه می‌کند. همچنین به آدرس پایه مراجعه کنید.

<Content /> component

کامپوننت <Content /> محتوای markdown را نمایش می‌دهد. مفید است هنگام ایجاد تم شخصی شما.

<template>
  <h1>چیدمان شخصی!</h1>
  <Content />
</template>

<ClientOnly /> component

کامپوننت <ClientOnly /> فقط اسلات خود را در سمت مشتری رندر می‌کند.

چون برنامه‌های ویت‌پرس هنگام ایجاد از سمت سرور در Node.js رندر می‌شوند، هر استفاده از Vue باید به الزامات کد یکپارچه دنیا پاسخ دهد. به طور خلاصه، اطمینان حاصل کنید که فقط در قالب hooks beforeMount یا mounted به API‌های Browser / DOM دسترسی دارید.

اگر از کامپوننت‌هایی استفاده یا نمایش دهنده‌هایی که با SSR سازگار نیستند (مانند دستورالعمل‌های سفارشی) استفاده می‌کنید، می‌توانید آن‌ها را داخل کامپوننت ClientOnly قرار دهید.

<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>

• مرتبط: سازگاری با SSR

$frontmatter template global

در بیانیه‌های Vue، به صورت مستقیم به داده‌های frontmatter صفحه فعلی دسترسی پیدا کنید.

---
title: سلام
---

# {{ $frontmatter.title }}

$params template global

در بیانیه‌های Vue، به صورت مستقیم به پارامترهای مسیر دینامیک صفحه فعلی دسترسی پیدا کنید.

- نام بسته: {{ $params.pkg }}
- نسخه: {{ $params.version }}