Vue Showdown

指南 🚀

注意

当前文档仅适用于 Vue 3 。如果你正在使用 Vue 2 ，前往 这里在新窗口打开 查看对应文档。

开始使用

NPM

通过 npm 安装

npm install vue-showdown

将 vue-showdown 作为 Vue 插件引入：

// 作为 Vue 插件引入
import { createApp } from 'vue';
import { VueShowdownPlugin } from 'vue-showdown';

const app = createApp();

// app.use() 的第二个参数是可选的
app.use(VueShowdownPlugin, {
  // 设置 showdown 默认 flavor
  flavor: 'github',
  // 设置 showdown 默认 options （会覆盖上面 flavor 的 options）
  options: {
    emoji: false,
  },
});

或者将 vue-showdown 作为 Vue 组件引入：

// 作为 Vue 组件引入
import { createApp } from 'vue';
import { VueShowdown } from 'vue-showdown';

const app = createApp();

app.component('VueShowdown', VueShowdown);

接下来，你就可以在你的单文件组件中使用 <VueShowdown /> 了：

<!-- 通过 props 来设置 options -->
<VueShowdown
  markdown="## markdown text"
  flavor="github"
  :options="{ emoji: true }"
/>

提示

同 Vue 一样，vue-showdown 同样提供了 UMD在新窗口打开, CommonJS在新窗口打开 和 ES Module在新窗口打开 版本。查看 Vue 文档在新窗口打开 获取更多细节。

Browser

在 vue.js 和 showdown.js 后面直接通过 <script> 引入。然后可以将 vue-showdown 作为 Vue 插件 / 组件使用。

<body>
  <div id="#app">
    <vue-showdown markdown="## markdown text" />
  </div>

  <script src="https://unpkg.com/vue@3.x/dist/vue.global.prod.js"></script>
  <script src="https://unpkg.com/showdown@1.x/dist/showdown.min.js"></script>
  <script src="https://unpkg.com/vue-showdown@3.x/vue-showdown.min.js"></script>

  <script>
    const app = Vue.createApp();

    // 作为 Vue 插件
    app.use(VueShowdownPlugin);

    // 或者作为 Vue 组件
    app.component('VueShowdown', VueShowdown);

    app.mount('#app');
  </script>
</body>

插件选项

import { createApp } from 'vue';
import { VueShowdownPlugin } from 'vue-showdown';

const app = createApp();

app.use(VueShowdownPlugin, {
  // 在这里设置插件选项
});

flavor

设置 showdown 的默认 flavor。查看文档在新窗口打开。

  • 类型： string | null
  • 默认值： null
  • 可能的值： 'github' | 'original' | 'ghost' | 'vanilla' | 'allOn'

提示

这里的 flavor 将会通过 showdown.setFlavor() 设置为全局 flavor。

options

设置 showdown 的默认 options。查看文档在新窗口打开。

  • type: Object
  • default: {}

提示

这里的 options 将会通过 showdown.setOption() 设置为全局 options。

注意这里的 showdown.setOption() 将会在 showdown.setFlavor() 之后调用，意味着将会覆盖 flavor 本身的默认配置。

组件 Props

markdown

输入的原始 markdown 代码。

  • 类型： string | null
  • 默认值： null
<VueShowdown markdown="# Hello, world!" />
<!-- 渲染为 -->
<div>
  <h1>Hello, world!</h1>
</div>

tag

用来包裹 Markdown 渲染结果的 HTML 标签。与 vue-router 的 tag在新窗口打开 作用相同。

  • 类型： string
  • 默认值： 'div'
<VueShowdown markdown="# Hello, world!" tag="span" />
<!-- 渲染为 -->
<span>
  <h1>Hello, world!</h1>
</span>

flavor

设置 showdown 的 flavor。查看 文档在新窗口打开。

  • 类型： string | null
  • 默认值： null
  • 可用的值： 'github' | 'original' | 'ghost' | 'vanilla' | 'allOn'

提示

如果你通过 props 设置 flavor，那么所有的 options 都会被重置为 flavor 的默认值，这意味着你通过 app.use() 设置的默认 options 也将被覆盖。

options

设置 showdown 的 options。查看 文档在新窗口打开。

  • 类型： Object
  • 默认值： {}

提示

通过 props 设置的 options 将会覆盖通过 app.use() 设置的默认 options。

extensions

设置 showdown 的 extensions。查看 文档在新窗口打开。

  • 类型： Array | null
  • 默认值： null

提示

前往章节 进阶用法 - Extensions 查看使用细节。

vueTemplate

将解析后的 HTML 字符串当作 Vue 模板，允许你在 Markdown 中使用 Vue 模板语法。

  • 类型： Boolean
  • 默认值： false

注意

如果你设置该 prop 为 true，你需要使用 Vue 完整版（运行时 + 编译器），因为我们需要在客户端编译模板。更多细节请参考 Vue 构建文件指南在新窗口打开。

当你有类似 #5在新窗口打开 的需求时，可以尝试使用该功能。

vueTemplateComponents

定义你在 Vue 模板中可以使用的组件。仅在开启 vueTemplate 时有效。

  • 类型： Object
  • 默认值： {}
  • 示例：
<template>
  <VueShowdown
    markdown="## markdown text with <my-component />"
    :vue-template="true"
    :vue-template-components="{ MyComponent }"
  />
</template>

<script>
import { defineComponent, ref } from 'vue';
import MyComponent from './MyComponent.vue';

export default defineComponent({
  setup() {
    return { MyComponent };
  },
});
</script>

vueTemplateData

定义你在 Vue 模板中可以使用的变量。仅在开启 vueTemplate 时有效。

  • 类型： Object
  • 默认值： {}
  • 示例：
<template>
  <VueShowdown
    markdown="## markdown text {{ message }}"
    :vue-template="true"
    :vue-template-data="{ message }"
  />
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const message = ref('hello, vue template in markdown!');
    return { message };
  },
});
</script>

进阶用法

Showdown library

你可以从 vue-showdown 中导入 showdown ，以便进行进阶配置。

import { createApp } from 'vue';
import { VueShowdownPlugin, showdown } from 'vue-showdown';

const app = createApp();

showdown.setFlavor('github');

app.use(VueShowdownPlugin);

Extensions

根据 showdown extensions 官方文档在新窗口打开，目前无法设置全局默认 extensions。

所以目前只能通过 VueShowdown 组件的 extensions prop 来传入 extensions。

<template>
  <VueShowdown markdown="## markdown text" :extensions="[myExt]" />
</template>

<script>
import { defineComponent } from 'vue';

const myExt = () => [
  {
    type: 'lang',
    regex: /markdown/g,
    replace: 'showdown',
  },
];

export default defineComponent({
  setup() {
    return { myExt };
  },
});
</script>

或者，你可以通过 showdown.extension() 全局注册 extensions，然后在 extension prop 中直接通过注册的名称引入。

import { createApp } from 'vue';
import { VueShowdownPlugin, showdown } from 'vue-showdown';

const app = createApp();

showdown.extension('myExt', () => [
  {
    type: 'lang',
    regex: /markdown/g,
    replace: 'showdown',
  },
]);

app.use(VueShowdownPlugin);

<template>
  <VueShowdown markdown="## markdown text" :extensions="['myExt']" />
</template>