运行时 API

Teek 提供了几个内置的 API 来让你访问应用程序数据，这些 API 只能在 setup() 或 <script setup> 中使用。

useTeekConfig

获取 Teek 的主题配置数据，获取方式按照优先级如下：

1. provide：在 .vitepress/theme/index.ts 通过 provide 函数注入配置项（优先级最高）
2. frontmatter.tk：在 Markdown 文档的 frontmatter 配置
3. frontmatter：在 Markdown 文档的 frontmatter 配置
4. config：在 .vitepress/config.mts 配置（优先级最低）

警告

• 函数式的配置项无法在 frontmatter 中配置
• 同一个配置项按照优先级获取，不同配置项在尝试所有方式获取后进行合并

<script lang="ts" setup>
import { useTeekConfig } from "vitepress-theme-teek";

const { getTeekConfigRef } = useTeekConfig();

// 获取 tagColor 配置项数据
const tagColor = getTeekConfigRef("tagColor");

// 获取 author 配置项数据，如果获取为空（没有配置），则返回默认值（第二个参数）
const author = getTeekConfigRef("author", {
  name: "Teeker",
  link: "https://github.com/Kele-Bingtang/vitepress-theme-teek",
});

// 返回 computed 响应式类型
console.log(tagColor.value);
console.log(author.value);
</script>

<template></template>

类型：

const useTeekConfig: () => {
  /**
   * 获取 Teek 的主题配置数据
   *
   * @param key 配置项 key
   * @param defaultValue 如果读取 key 不存在时，则返回默认值
   */
  getTeekConfig: <T = any>(key?: keyof TeekConfig | null, defaultValue?: any) => T;
  /**
   * 获取 Teek 的主题配置数据（响应式）
   */
  getTeekConfigRef: <T = any>(key?: keyof TeekConfig | null, defaultValue?: any) => ComputedRef<T>;
};

usePageState

获取功能页面状态：

<script lang="ts" setup>
import { usePageState } from "vitepress-theme-teek";

const { isHomePage, isCategoriesPage, isTagsPage, isArchivesPage, isCataloguePage, isArticleOverviewPage } =
  usePageState();
</script>

<template></template>

类型：

const formatDate: (date: Date | string | number, format = "yyyy-MM-dd hh:mm:ss") => string;
const usePageState: () => {
  /**
   * 当前页面是否为首页（不包含分类页和标签页）
   */
  isHomePage: ComputedRef<boolean>;
  /**
   * 当前页面是否为分类页
   */
  isCategoriesPage: ComputedRef<boolean>;
  /**
   * 当前页面是否为标签页
   */
  isTagsPage: ComputedRef<boolean>;
  /**
   * 当前页面是否为归档页
   */
  isArchivesPage: ComputedRef<boolean>;
  /**
   * 当前页面是否为目录页
   */
  isCataloguePage: ComputedRef<boolean>;
  /**
   * 当前页面是否为文章清单页
   */
  isArticleOverviewPage: ComputedRef<boolean>;
};

usePosts

返回文章数据，当处于国际化环境时，返回对应语言的文章数据，否则返回全部文章数据

<script lang="ts" setup>
import { usePosts } from "vitepress-theme-teek";

const { posts } = usePosts();
</script>
<template></template>

类型：

const usePosts: () => Ref<PostData>;

interface PostData {
  /**
   * 所有文章列表
   */
  allPosts: TkContentData[];
  /**
   * 排除了 article false 和 layout home 的文章列表
   */
  originPosts: TkContentData[];
  /**
   * 根据日期和 sticky 排序的文章列表
   */
  sortPostsByDateAndSticky: TkContentData[];
  /**
   * 根据日期排序的文章列表
   */
  sortPostsByDate: TkContentData[];
  /**
   * 根据年份分组，key 为年份，value 为该年份的文章列表，如 { 2025: [{}, {}], 2024: [{}, {}] }
   */
  groupPostsByYear: Record<string, TkContentData[]>;
  /**
   * 根据年份和月份分组，key 为年份，value 为该年份的月份分组，如：{ 2025: { 01: [{}, {}], 02: [{}, {}] }, 2024: { 01: [], 02: [{}, {}] } }
   */
  groupPostsByYearMonth: Record<string, Record<string, TkContentData[]>>;
  /**
   * 分组的文章列表
   */
  groupPosts: {
    /**
     * 分类信息，格式：{ 分类名: 文章列表 }[]
     */
    categories: Record<string, TkContentData[]>;
    /**
     * 标签信息，格式：{ 标签名: 文章列表 }[]
     */
    tags: Record<string, TkContentData[]>;
  };
  /**
   * 分组卡片信息，用于首页右侧渲染分类和标签卡片
   */
  groupCards: {
    /**
     * 分类信息，格式：{ name: 分类名, length: 文章数量 }[]
     */
    categories: GroupCardItem[];
    /**
     * 标签信息，格式：{ name: 标签名, length: 文章数量 }[]
     */
    tags: GroupCardItem[];
  };
  /**
   * 国际化启用后，key 为语言，value 为该语言目录下的 Posts。如果没有开启国际化，则没有 locales
   */
  locales?: Record<string, PostData>;
}

interface GroupCardItem {
  /**
   * 分类名
   */
  name: string;
  /**
   * 文章数量
   */
  length: number;
}

useTagColor

获取标签颜色

<script lang="ts" setup>
import { useTagColor } from "vitepress-theme-teek";

const tagColor = useTagColor();

类型：

const useTagColor: () => ComputedRef<
  {
    /**
     * 标签背景色
     */
    bg: string;
    /**
     * 标签文本色
     */
    text: string;
    /**
     * 标签边框色
     */
    border: string;
  }[]
>;