开始使用

选择你要使用的代码托管平台

Vssue 支持通过 Github, Gitlab, Bitbucket 或者 Gitee 的 Issue 系统来为你的静态页面提供评论功能，你可以选择其中之一来使用。

前往 支持的代码托管平台 - 创建 OAuth App 查看详细指引。

完成这一步之后，你将会配置好一个 OAuth App，并得到对应的 client id 和 client secret，它们将会用于 Vssue 的使用。

  • owner: 对应 repository 的拥有者帐号或者团队
  • repo: 用来存储评论的 repository
  • clientId: OAuth App 的 client id
  • clientSecret: OAuth App 的 client secret （只有在使用某些平台时需要）

在浏览器中使用

Vssue 可以在浏览器中通过 <script> 标签直接使用。由于 Vssue 依赖于 Vue.js开始使用 - 图1，所以你还需要引入 Vue。

  1. <head>
  2.   <!-- Vssue 的样式文件 -->
  3.   <link rel="stylesheet" href="https://unpkg.com/vssue/dist/vssue.min.css">
  4. </head>
  6. <body>
  7.   <div id="vssue"></div>
  9.   <!-- 先引入 Vue -->
  11.   <!-- Vue 运行时版 (runtime only)  -->
  12.   <script src="https://unpkg.com/vue/dist/vue.runtime.min.js"></script>
  13.   <!-- 或： Vue 完整版 (runtime + compiler) -->
  14.   <script src="https://unpkg.com/vue/dist/vue.min.js"></script>
  16.   <!-- 在 Vue 之后引入 Vssue -->
  18.   <!-- Vssue Github 版  -->
  19.   <script src="https://unpkg.com/vssue/dist/vssue.github.min.js"></script>
  20.   <!-- 或： Vssue Gitlab 版  -->
  21.   <script src="https://unpkg.com/vssue/dist/vssue.gitlab.min.js"></script>
  22.   <!-- 或： Vssue Bitbucket 版  -->
  23.   <script src="https://unpkg.com/vssue/dist/vssue.bitbucket.min.js"></script>
  24.   <!-- 或： Vssue Gitee 版  -->
  25.   <script src="https://unpkg.com/vssue/dist/vssue.gitee.min.js"></script>
  27.   <!-- 将 Vssue 作为 Vue 组件使用 -->
  29.   <!-- 对于 Vue 运行时版，使用渲染函数（render function） -->
  30.   <script>
  31.     new Vue({
  32.       el: '#vssue',
  34.       render: h => h('Vssue', {
  35.         props: {
  36.           // 在这里设置当前页面对应的 Issue 标题
  37.           title: 'Vssue Dev',
  39.           // 在这里设置你使用的平台的 OAuth App 配置
  40.           options: {
  41.             owner: 'OWNER_OF_REPO',
  42.             repo: 'NAME_OF_REPO',
  43.             clientId: 'YOUR_CLIENT_ID',
  44.             clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
  45.           },
  46.         }
  47.       })
  48.     })
  49.   </script>
  51.   <!-- 或：对于 Vue 完整版，可以使用模板（template） -->
  52.   <script>
  53.     new Vue({
  54.       el: '#vssue',
  56.       data: {
  57.         title: 'Vssue Dev',
  59.         options: {
  60.           owner: 'OWNER_OF_REPO',
  61.           repo: 'NAME_OF_REPO',
  62.           clientId: 'YOUR_CLIENT_ID',
  63.           clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
  64.         },
  65.       },
  67.       template: `<vssue :title="title" :options="options"></vssue>`,
  68.     })
  69.   </script>
  70. </body>

提示

如果你还不了解 Vue 的不同版本间的区别 （即 vue.runtime.min.js, vue.min.js 等），可以参考 Vue 文档开始使用 - 图2。

Vssue 同样提供了不同版本的构建。细节可以查看对不同构建版本的解释章节。

在 Vue 应用中使用

Vssue 是一个 Vue 插件 / 组件，可以在 Vue 项目中引入并使用。

提示

Vssue 只提供了 ES2015开始使用 - 图3 代码，因为我们假设你在使用 vue-cli开始使用 - 图4 或其他工具。

通过 npm 安装

安装 vssue:

npm install vssue

安装对应平台的 api 包：

详情可以查看 支持的代码托管平台。

# 使用 Github V3
npm install @vssue/api-github-v3
# 或：使用 Github V4
npm install @vssue/api-github-v4
# 或：使用 Gitlab V4
npm install @vssue/api-gitlab-v4
# 或：使用 Bitbucket V2
npm install @vssue/api-bitbucket-v2
# 或：使用 Gitee V5
npm install @vssue/api-gitee-v5

作为 Vue 插件使用

通过 import Vssue from 'vssue' 你会得到一个 Vue 插件。调用 Vue.use() 来使用它并进行配置。这会注册一个名称为 Vssue 的全局组件。

关于配置的详情，可以查看 配置参考 - Vssue 配置

// 引入 vue
import Vue from 'vue'
// 引入 vssue
import Vssue from 'vssue'
// 引入对应平台的 api 包
import GithubV3 from '@vssue/api-github-v3'
// 引入 vssue 的样式文件
import 'vssue/dist/vssue.css'

Vue.use(Vssue, {
  // 设置要使用的平台 api
  api: GithubV3,

  // 在这里设置你使用的平台的 OAuth App 配置
  owner: 'OWNER_OF_REPO',
  repo: 'NAME_OF_REPO',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
})

然后你就可以在 SFC开始使用 - 图5 中使用 Vssue 组件了：

关于组件 Props 的详情，可以查看 配置参考 - 组件 Props

<template>
  <Vssue
    :title="title"
    :options="options"
  />
</template>

<script>
export default {
  name: 'VssueDemo',

  data () {
    return {
      // 在这里设置当前页面的 Issue 标题
      title: 'Vssue Demo',

      // 注意，这里的 options 会覆盖上面通过 `Vue.use()` 设置的默认 options
      // 如果你不想改变它们，只需要传入 `title` prop 即可，不需要传入 `options` prop
      options: {
        // owner: 'OWNER_OF_REPO',
        // repo: 'NAME_OF_REPO',
        // clientId: 'YOUR_CLIENT_ID',
        // clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
      },
    }
  },
}
</script>

作为 Vue 组件使用

通过 import { VssueComponent } from 'vssue' 你会得到一个 Vue 组件。

提示

当你通过 Vue.use() 把 Vssue 作为插件使用时，这个组件就已经通过 Vue.component() 注册为一个名称为 Vssue 的全局组件了。

如果你不想把它注册为全局组件，你可以通过这种方式引入它。

需要注意的是，如果你只作为组件引入 Vssue，就没有通过 Vue.use() 设置的“全局”配置了，你必须通过 Prop options 传入所有必需的 Vssue 配置。参考 组件 Props - options。

<template>
  <Vssue
    :title="title"
    :options="options"
  />
</template>

<script>
import { VssueComponent } from 'vssue'
import GithubV3 from '@vssue/api-github-v3'
import 'vssue/dist/vssue.css'

export default {
  name: 'VssueDemo',

  components: {
    'Vssue': VssueComponent,
  },

  data () {
    return {
      title: 'Vssue Demo',
      options: {
        api: GithubV3,
        owner: 'OWNER_OF_REPO',
        repo: 'NAME_OF_REPO',
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
      },
    }
  },
}
</script>

对不同构建版本的解释

和 Vue 类似，Vssue 也提供了不同的构建版本以供使用。

这些文件放置在 dist开始使用 - 图6 文件夹中：

文件名类型MinifiedPolyfills用途
vssue.jsES Modulefalsefalse使用构建工具
vssue.[platform].min.jsUMDtruefalse通过现代浏览器的 <script> 标签引入
vssue.[platform].polyfill.min.jsUMDtruetrue通过旧版浏览器的 <script> 标签引入

参考 Vue 的不同构建版本开始使用 - 图7