配置

行内链接预览插件目前提供了与国际化和预览弹窗相关的配置选项。

如何在 VitePress 中进行配置

由于 VitePress 对于默认主题没有提供更多关于主题配置的拓展的功能，从某种程度上来说，如果我们直接修改 VitePress 的配置文件为插件提供配置的话对类型检查和配置的维护并不友好，所以这里我们使用 Vue 的依赖注入来提供配置：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

import type {  as ThemeConfig } from 'vitepress'
import  from 'vitepress/theme'

import {  } from '@nolebase/vitepress-plugin-inline-link-preview/client'

export const : ThemeConfig = {
  : ,
  : () => {
    // 其他部分的代码...
  },
  ({  }) {
    // 其他部分的代码...

    .(, { 
      // 配置...
    }) 

    // 其他部分的代码...
  },
}

如果想要了解更多关于国际化配置的信息，请参阅 国际化。

配置选项

完整的可以配置的选项

/**
 * Options
 */
export interface Options {
  /**
   * 链接预览的宽度
   */
  ?: number
  /**
   * 链接预览的高度
   */
  ?: number
  /**
   * 是否预览所有的 host name
   *
   * 当设置为 true 时，所有与 host name 相关的选项都会被忽略，包括 `handleShouldPreviewHostNames` 选项。
   *
   * @default false
   */
  ?: boolean
  /**
   * 设置为 true 时，预览本地（部署位置，或 `window.location.host`）主机名。
   *
   * @default true
   */
  ?: boolean
  /**
   * 允许预览的主机名。
   * 当指定时，只有在此数组中的主机名才会被预览。
   *
   * @default []
   */
  ?: string[]
  /**
   * 阻止预览的主机名。
   * 当指定时，此数组中的主机名将不会被预览。
   *
   * @default []
   */
  ?: string[]
  /**
   * 程序化处理是否应该预览主机名。
   *
   * 当指定时，此函数将被调用以确定是否应该预览主机名，并在 `previewHostNamesAllowed` 和 `previewHostNamesBlocked` 选项之前。
   *
   * @param href 链接
   * @returns 是否应该预览主机名
   * @default undefined
   */
  ?: (: string) => boolean
  /**
   * 用于在弹窗打开时隐藏 iframe 中的元素的选择器。
   * 当你有很多自定义元素的类不想在弹窗中显示时，这个选项会很有用。
   */
  ?: string[]
  /**
   * 程序化处理 iframe 加载事件，你可以使用这个处理函数来程序化地改变 iframe 内容，
   * 比如给 body 元素添加一个类，或者隐藏 iframe 中的一些元素。
   *
   * @param hostWindow 原窗口的 window 对象
   * @param element iframe 元素
   * @returns 支持 Promise
   * @default undefined
   */
  ?: (: Window, : HTMLIFrameElement) => <void> | void
  /**
   * 弹窗在生成的时候所指向的目标元素的选择器。
   *
   * 默认情况下，弹窗会被附加到 body 元素上，因为 VitePress 目前只支持将元素传送到 body 元素。
   *
   * @default 'body'
   */
  ?: string
  /**
   * 预览弹窗的延迟时间
   *
   * @default 1000
   */
  ?: number
  /**
   * 本地化
   *
   * @example { 'zh-CN': { popup: { loading: '加载中...', loadingAriaLabel: '加载中' } }
   */
  ?: <string, Locale>
}

国际化

注意

行内链接预览插件并没有使用 vue-i18n 来作为国际化的工具库，因为绝大多数 VitePress 可能是直接使用的 VitePress 自带的国际化功能 来进行国际化的，所以行内链接预览插件的本地化文案并不能通过 vue-i18n 来覆盖文案，但是你可以通过 配置 中的 locales 字段来覆盖本地化的文案。

行内链接预览插件默认提供了国际化的支持，默认支持了英文和简体中文。

你可以通过配置来对插件的本地化文案进行复写，在开始配置之前，你需要了解 VitePress 是如何进行国际化的：VitePress 的国际化。行内链接预览插件默认会读取 VitePress 的语言字段，所以你在配置的时候需要注意将国际化的语言代码与 VitePress 的语言代码保持一致。

如何在 VitePress 中进行配置

在 配置 章节中，我们已经了解到了如何在 VitePress 中为行内链接预览插件提供配置选项，我们在配置选项中添加 locales 字段就可以配置国际化了：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

import type {  as ThemeConfig } from 'vitepress'
import  from 'vitepress/theme'

import {  } from '@nolebase/vitepress-plugin-inline-link-preview/client'

// 其他部分的代码...

export const : ThemeConfig = {
  : ,
  : () => {
    // 其他部分的代码...
  },
  ({  }) {
    // 其他部分的代码...

    .(, {
      : { // 配置国际化
        'zh-CN': { // configure for Simplified Chinese
          : { 
            : '加载中...', 
            : '加载中', 
          } 
        }, 
        'en': { // configure for English
          : { 
            : 'Loading...', 
            : 'Loading', 
          } 
        } 
      } 
    })

    // 其他部分的代码...
  },
}

国际化字段选项

完整的国际化字段选项

interface Locale extends <string, any> {
  /**
   * 弹窗文案
   */
  ?: {
    /**
     * 弹窗加载中的文案
     */
    ?: string
    /**
     * 弹窗加载中的文案的 aria-label
     */
    ?: string
    /**
     * 弹窗加载失败的文案
     */
    ?: string
    /**
     * 弹窗加载失败的文案的 aria-label
     */
    ?: string
    /**
     * iframe 弹窗的 aria-label
     */
    ?: string
  }
}

无障碍

行内链接预览插件默认提供了无障碍的支持，你可以通过 配置 来对无障碍的文案进行复写，使用方法和 国际化 一样，有关无障碍有哪些文案可以配置，请参阅 国际化字段选项。

更多自定义能力？

可以的，没问题。

注意

自由配置是为那些了解并清楚自己在做什么的用户准备的，如果你不清楚自己在做什么，或者在配置期间遭遇到了问题，那么请使用开箱即用的 VitePress 配置。

行内链接预览插件会导出内部使用的组件，所以如果你不喜欢默认组件的样式和封装，你可以创建自己的组件来代替它们。

作为 Vue 插件使用

import {
   
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

如果您正在使用 VitePress，并希望将其安装到 Vue 实例中，可以这样做：

import type {  as ThemeConfig } from 'vitepress'
import  from 'vitepress/theme'

import {  } from '@nolebase/vitepress-plugin-inline-link-preview/client'

// Rest of the code...

export const : ThemeConfig = {
  : ,
  : () => {
    // Rest of the code...
  },
  ({  }) {
    .() 
  },
}

export default 

按需导入弹出式 iframe 封装组件

import {
  ,  
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

配置插件或组件后，您需要自定义 markdown-it 插件如何将 []() 链接标记或 <a> 元素转换为您的自定义组件，而不是默认的 <VPNolebaseInlineLinkPreview> 组件。

自定义 markdown-it 插件

import {  } from 'vitepress'

import {
  , 
} from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

export default ({
  : 'en',
  : 'Site Name',
  : {
    // rest of the options...
  },
  : {
    () {
      // other markdown-it configurations...
      .(, { : 'YourComponentName' }) 
    }
  }
})

贡献者

Neko Rizumu

页面历史

最后编辑于 大约 1 个月前查看完整历史

e690e-docs: refactored docs to better guide users

9f66c-feat(inline-link-preview): migrated to unbuild, wrapped with standalone markdown-it plugin, added fancy documentations (#155)

68b21-feat(docs): better docs, fixed ui components previewing, type issues (#116)

3b240-docs: added docs

68604-docs: added docs for plugins

acd31-docs: rename to integrations

aea84-docs: updated structure and links