Vue Showdown

指南 🚀

开始使用

NPM

通过 npm 或 yarn 安装

npm install vue-showdown
# 或者
yarn add vue-showdown

在你的 JS 文件中引入

// 作为 Vue 插件引入
import Vue from 'vue'
import VueShowdown from 'vue-showdown'

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

// 或者： 作为 Vue 组件引入
import Vue from 'vue'
import { VueShowdown } from 'vue-showdown' // 记得引入 vue-showdown 的 esm 文件，即 vue-showdown.esm.js

Vue.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 后面直接通过 <script> 引入。然后可以将 vue-showdown 直接作为 Vue 组件使用。

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

  <script src="https://unpkg.com/vue@2.5.21/dist/vue.min.js"></script>
  <script src="https://unpkg.com/showdown@1.9.0/dist/showdown.min.js"></script>
  <script src="https://unpkg.com/vue-showdown@2.3.0/dist/vue-showdown.min.js"></script>

  <script>
    new Vue({
      el: '#app'
    })
  </script>
</body>

插件选项

import Vue from 'vue'
import VueShowdown from 'vue-showdown'

Vue.use(VueShowdown, {
  // 在这里设置插件选项
})

flavor

设置 showdown 的默认 flavor。查看文档。

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

提示

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

options

设置 showdown 的默认 options。查看文档。

  • type: Object
  • default: {}

提示

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

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

组件 Props

markdown

输入的原始 markdown 代码。

  • 类型： string
  • 默认值： 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
  • 可用的值： 'original', 'vanilla', 'github'

提示

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

options

设置 showdown 的 options。查看 文档。

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

提示

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

extensions

设置 showdown 的 extensions。查看 文档。

  • 类型： [Object, Array]
  • 默认值： null

提示

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

vueTemplate v2.4.0+

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

  • 类型： Boolean
  • 默认值： false

注意

如果你设置该 prop 为 true，你需要使用 Vue 完整版（运行时 + 编译器），因为我们需要在客户端编译模板。查看 运行时 + 编译器 vs. 只包含运行时。

当你有类似 #5 的需求时，可以尝试使用该功能。

进阶用法

Showdown library

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

import Vue from 'vue'
import VueShowdown, { showdown } from 'vue-showdown'

showdown.setFlavor('github')

Vue.use(VueShowdown)

提示

如果你在通过 vue-showdown 引入 showdown 时 (import { showdown } from 'vue-showdown') 发生错误，你可以尝试以下方式：

  • 设置 alias，将 vue-showdown 指向 vue-showdown.esm.js。如果你使用 webpack ，那么就类似于 vue.esm.js 的设置：

    resolve: {
  alias: {
    'vue$': 'vue/dist/vue.esm.js',
    'vue-showdown$': 'vue-showdown/dist/vue-showdown.esm.js',
  },
}

    或者你直接引入 vue-showdown.esm.js 文件：

    import { showdown } from 'vue-showdown/dist/vue-showdown.esm'

  • 通过 VueShowdown.showdown 使用 showdown:

    import VueShowdown from 'vue-showdown'
const showdown = VueShowdown.showdown

  • 直接引入 showdown 。由于 vue-showdown 依赖于 showdown 运行，所以在你通过 npm install vue-showdown 安装 vue-showdown 后，你就可以直接使用 showdown：

    import showdown from 'showdown'

Extensions

根据 showdown extensions 官方文档，目前无法设置全局默认 extensions。

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

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

<script>
export default {
  data () {
    return {
      myExt: () => [{
        type: 'lang',
        regex: /markdown/g,
        replace: 'showdown',
      }],
    }
  },
}
</script>

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

import Vue from 'vue'
import VueShowdown, { showdown } from 'vue-showdown'
// OR:
// import showdown from 'showdown'
// import VueShowdown from 'vue-showdown'

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

Vue.use(VueShowdown)

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