心流笔记

主题

Wilson2025-03-09 07:20:09配置配置
2518
11m

全局配置 ​

全局配置是影响范围较广的配置。

teekTheme ​

  • 类型：boolean
  • 默认值：true

是否启用主题，如果为 false，则不会启用主题的 99% 功能，只保留如下功能：

  • 自动添加侧边栏
  • 自动添加一级标题
  • 自动添加永久链接
  • 文档内容分析（作者、创建时间、文章字数、预计阅读时间等信息）
  • 锚点滚动
  • 深色/浅色模式过渡动画

提示

如果您仍然想要关闭这些部分功能，Teek 也提供了相关配置项来关闭。

配置如下：

config.ts
ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  teekTheme: true,
});

提示

如果想全部清除 Teek 的功能，那么在 .vitepress/theme/index.ts 文件里去掉 Teek 引用。

teekHome ​

  • 类型：boolean
  • 默认值：true

是否启用 Teek 的首页风格，如果为 false，则还原到 Vitepress 的默认首页，其他功能不变。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  teekHome: true,
});
yaml
---
tk:
  teekHome: true
---

vpHome ​

  • 类型：boolean
  • 默认值：true

是否启用 VitePress 首页风格，支持 teekHome 和 vpHome 同时存在。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vpHome: true,
});
yaml
---
tk:
  vpHome: true
---

anchorScroll ​

  • 类型：boolean
  • 默认值：true

是否启用锚点滚动功能，即阅读文章时，自动将 h1 ~ h6 标题添加到地址栏 # 后面。

config.ts
ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  anchorScroll: true,
});

viewTransition ​

  • 类型：boolean
  • 默认值：true

深色、浅色模式切换时是否开启过渡动画。

config.ts
ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  viewTransition: true,
});

codeBlock ​

  • 类型：boolean
  • 默认值：true

是否使用新版代码块样式，如果为 false，则使用 Vitepress 默认样式。

提示

Teek 文档使用的是新版代码块。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  codeBlock: true,
});
yaml
---
codeBlock: true
---

新版代码块的语言默认为大写，如果希望为小写或者首字母大写，通过修改 css var 的 tk-code-block-lang-transform 来达成目标。

提示

tk-code-block-lang-transform 的值等于 CSS 中 text-transform 的值。

先定义一个 css 文件：

tk-code-style.css
css
/* .vitepress/theme/style/tk-code-style.css */
:root {
  /*
   * none：文本中的单词保持默认风格
   * capitalize：文本中的每个单词以大写字母开头
   * lowercase：文本中的每个单词全部转为小写
   * uppercase：定文本中的单次全部转为大写
   */
  tk-code-block-lang-transform: lowercase;
}

在 .vitepress/theme/index.ts 文件引入该 css 文件：

ts
// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import "./style/tk-code-style.css";

export default {
  extends: Teek,
};

bodyBgImg ​

body 背景图片配置，将整个网站的背景色改为图片。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  bodyBgImg: {
    imgSrc: ["/img/bg1.jpg", "/img/bg2.png"], // body 背景图片链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
    imgOpacity: 1, // body 背景图透明度，选值 0.1 ~ 1.0
    imgInterval: 15000, //  body 当多张背景图时（imgSrc 为数组），设置切换时间，单位：毫秒
    imgShuffle: false, // body 背景图是否随机切换，为 false 时按顺序切换
    mask: false, // body 背景图遮罩
    maskBg: "rgba(0, 0, 0, 0.2)", // body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
  };
});
yaml
---
bodyBgImg:
  imgSrc:
    - /img/bg1.jpg
    - /img/bg2.png
  imgOpacity: 1
  imgInterval: 15000
  imgShuffle: false
  mask: false
  maskBg: "rgba(0, 0, 0, 0.2)"
---
ts
interface BodyBgImg {
  /**
   * body 背景图片链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
   */
  imgSrc?: string | string[];
  /**
   * body 背景图透明度，选值 0.1 ~ 1.0
   *
   * @default 1
   */
  imgOpacity?: 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
  /**
   * body 当多张背景图时（imgSrc 为数组），设置切换时间，单位：毫秒
   *
   * @default 15000 (15秒)
   */
  imgInterval?: number;
  /**
   * body 背景图是否随机切换，为 false 时按顺序切换
   */
  imgShuffle?: boolean;
  /**
   * body 背景图遮罩
   *
   * @default false
   */
  mask?: boolean;
  /**
   * body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
   *
   * @default 'rgba(0, 0, 0, 0.2)'
   */
  maskBg?: string | number;
}

提示

bodyBgImg 设置了 imgSrc 后，banner 的图片风格会失效。

themeSetting ​

右下角的主题设置配置。

关于如何使用请看 主题模式，关于如何拓展自定义主题请看 主题模式拓展。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  themeSetting: {
    useThemeStyle: true, // 是否启用主题风格，如果为 false，则不会显示切换按钮
    themeStyle: "vp-default", // 设置当前主题风格
    useThemeSize: true, // 是否使用主题尺寸切换功能
    themeSize: "default", // 设置当前主题尺寸
    // ...
  };
});
ts
interface ThemeSetting {
  /**
   * 是否启用主题风格，如果为 false，则不会显示切换按钮
   *
   * @default true
   */
  useThemeStyle?: boolean;
  /**
   * 设置当前主题风格
   *
   * @default 'vp-default'
   */
  themeStyle?:
    | "vp-default"
    | "vp-green"
    | "vp-yellow"
    | "vp-red"
    | "el-blue"
    | "el-green"
    | "el-yellow"
    | "el-red"
    | string;
  /**
   * 自定义主题风格，将会追加到内置主题风格后面
   */
  themeStyleAppend?: {
    /**
     * 主题组名称
     */
    label: string;
    /**
     * 主题组提示信息，鼠标悬停时显示
     */
    tip?: string;
    /**
     * 主题组内容
     */
    options: {
      /**
       * 主题名称，用于页面文字渲染
       */
      name: string;
      /**
       * 主题标识，在 html 标签的 theme 属性添加该标识
       */
      style: string;
    }[];
  }[];
  /**
   * 主题样式的名称修改
   */
  themeStyleLabel?: {
    /**
     * @default 'VP 主题'
     */
    vpLabel?: string;
    /**
     * @default 'VitePress 主题'
     */
    vpTip?: string;
    /**
     * @default '默认'
     */
    default?: string;
    /**
     * @default '绿色'
     */
    vpGreen?: string;
    /**
     * @default '黄色'
     */
    vpYellow?: string;
    /**
     * @default '红色'
     */
    vpRed?: string;
    /**
     * @default 'EP 主题'
     */
    epLabel?: string;
    /**
     * @default 'Element Plus 主题'
     */
    epTip?: string;
    /**
     * @default '蓝色'
     */
    epBlue?: string;
    /**
     * @default '绿色'
     */
    epGreen?: string;
    /**
     * @default '黄色'
     */
    epYellow?: string;
    /**
     * @default '红色'
     */
    epRed?: string;
  };
  /**
   * 是否使用主题尺寸切换功能
   *
   * @default true
   */
  useThemeSize?: boolean;
  /**
   * 设置当前主题尺寸
   *
   * @default 'default'
   */
  themeSize?: "small" | "default" | "large" | string;
  /**
   * 自定义主题尺寸，将会追加到内置主题尺寸后面
   */
  themeSizeAppend?: {
    /**
     * 主题尺寸名称，用于页面文字渲染
     */
    name: string;
    /**
     * 主题尺寸标识，在 html 标签的 size 属性添加该标识
     */
    size: string;
  }[];
  /**
   * 主题尺寸的名称修改
   */
  themeSizeLabel?: {
    /**
     * @default 'Wide'
     */
    wide?: string;
    /**
     * @default 'Large'
     */
    large?: string;
    /**
     * @default 'Default'
     */
    default?: string;
    /**
     * @default 'Small'
     */
    small?: string;
  };
  /**
   * 回到顶部后的回调
   */
  backTopDone?: () => void;
  /**
   * 滚动到评论后的回调
   */
  toCommentDone?: () => void;
  /**
   * 鼠标悬停时标题提示文案
   */
  titleTip?: {
    /**
     * @default '回到顶部'
     */
    backTop?: string;
    /**
     * @default '前往评论'
     */
    toComment?: string;
    /**
     * @default '主题尺寸'
     */
    themeSize?: string;
    /**
     * @default '主题样式'
     */
    themeStyle?: string;
  };
}

author ​

文章默认的作者信息。

在首页的文章列表和文章页使用该功能。

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  author: {
    name: "Teeker", // 作者名称
    link: "https://github.com/Kele-Bingtang", // 点击作者名称后跳转的链接
  };
});
yaml
---
author:
  name: "Teeker"
  link: "https://github.com/Kele-Bingtang",
---
ts
interface Author {
  /**
   * 作者名称，作用在首页的 PostItem 和文章页
   */
  name: string;
  /**
   * 点击作者名称后跳转的链接
   */
  link?: string;
}

notice ​

公告配置。

公告组件只提供基础功能，不提供任何内容的渲染，需要您自定义组件，然后在 .vitepress/theme/index.ts 中通过 teek-notice-content 插槽传进来。

使用如下：

插槽
ts
// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import MyNoticeContent from "./components/MyNoticeContent.vue";
import { h } from "vue";

export default {
  extends: Teek,
  Layout() {
    return h(Teek.Layout, null, {
      "teek-notice-content": () => h(MyNoticeContent),
    });
  },
};

配置如下：

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  notice: {
    enabled: true, // 是否启用公告功能
    title: "公告", // 公告标题，支持函数式：需要和国际化搭配使用，根据不同语言环境返回不同标题
    initOpen: true,
    duration: 0, // 弹框定时自动关闭，0 不自动消失
    mobileMinify: false, // 移动端自动最小化
    reopen: true,
    useStorage: true, // 是是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
    twinkle: false, // 公告图标是否打开闪烁提示
    position: "top", // 公告弹框出现位置
    // ...
  },
});
yaml
---
notice:
  enabled: true
  title: "公告"
  initOpen: true
  duration: 0
  mobileMinify: false
  reopen: true
  useStorage: true
  twinkle: false
  position: "top"
---
ts
import type { Route } from "vitepress";

interface Notice {
  /**
   * 是否启用公告功能
   *
   * @default false
   */
  enabled?: boolean;
  /**
   * 公告自定义全局样式
   *
   * @example
   * ```css
   * .tk-notice a {
   *    color: var(--vp-c-brand-2);
   * }
   * ```
   */
  noticeStyle?: string;
  /**
   * 公告图标样式
   */
  iconStyle?: Record<string, any>;
  /**
   * 公告弹窗样式
   */
  popoverStyle?: Record<string, any>;
  /**
   * 公告标题，函数式需要和国际化搭配使用，根据不同语言环境返回不同标题
   *
   * @default '公告'
   */
  title?: string | ((localeIndex: string) => string);
  /**
   * 第一次进入页面，是否默认打开公告弹框
   *
   * @default true
   */
  initOpen?: boolean;
  /**
   * 弹框定时自动关闭，0 不自动消失
   *
   * @default 0
   */
  duration?: number;
  /**
   * 移动端自动最小化
   *
   * @default false
   */
  mobileMinify?: boolean;
  /**
   * 关闭公告弹框后，是否支持重新打开，如果为 false，则代表公告只显示一次
   *
   * @default true
   */
  reopen?: boolean;
  /**
   * 是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
   */
  useStorage?: boolean;
  /**
   * 公告图标是否打开闪烁提示
   *
   * @default false
   */
  twinkle?: boolean;
  /**
   * 公告弹框出现位置
   *
   * @default top
   */
  position?: "top" | "center";
  /**
   * 公告图标地址
   *
   * @remark 与 noticeIconType 配合使用
   *
   * 1、noticeIconType 为 svg 时，需要填写 svg 代码
   * 2、noticeIconType 为 iconfont 时，需要填写 class 名
   * 3、noticeIconType 为 img 时，需要填写图片链接
   * 4、noticeIconType 为 el 时，需要传入 ElIcon 的组件
   */
  noticeIcon?: string;
  /**
   * 图标类型
   *
   * @default 'svg'
   */
  noticeIconType?: "svg" | "iconfont" | "img" | "el";
  /**
   * 公告弹框关闭图标地址，与 noticeIcon 配置一致
   */
  closeIcon?: string;
  /**
   * 图标类型，与 noticeIconType 配置一致
   *
   * @default 'svg'
   */
  closeIconType?: "svg" | "iconfont" | "img" | "el";
  /**
   * 路由切换后的自定义回调
   *
   * @param to 切换到的目标路由
   */
  onAfterRouteChange?: (to: Route, noticeShow: boolean, showPopover: boolean) => void;
}

siteAnalytics ​

站点分析配置，目前集成了三种常见的站点统计工具：

  • 百度分析 Baidu Analytics
  • 谷歌分析 Google Analytics
  • Umami 分析

具体使用说明请看 站点统计。

使用如下：

ts
// .vitepress/config.ts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  siteAnalytics: {
    provider: "baidu",
    options: {
      id: "******",
    },
  },
});
ts
import type { BaiduAnalyticsOptions, GoogleAnalyticsOptions, UmamiAnalyticsOptions } from "../../helper";

type SiteAnalytics<T extends keyof SiteAnalyticsProvider = ""> = {
  /**
   * 赞赏位置
   */
  provider: T;
  /**
   * 赞赏配置
   */
  options?: SiteAnalyticsProvider[T];
};

type SiteAnalyticsProvider = {
  "": object;
  baidu: BaiduAnalyticsOptions;
  google: GoogleAnalyticsOptions;
  umami: UmamiAnalyticsOptions;
};
最近更新