# 开始使用
# 选择你要使用的代码托管平台
Vssue 支持通过 Github, Gitlab, Bitbucket, Gitee 或者 Gitea 的 Issue 系统来为你的静态页面提供评论功能,你可以选择其中之一来使用。
前往 支持的代码托管平台 - 创建 OAuth App 查看详细指引。
完成这一步之后,你将会配置好一个 OAuth App,并得到对应的 client id
和 client secret
,它们将会用于 Vssue 的使用。
owner
: 对应 repository 的拥有者帐号或者团队repo
: 用来存储评论的 repositoryclientId
: OAuth App 的client id
clientSecret
: OAuth App 的client secret
(只有在使用某些平台时需要)
# 在浏览器中使用
Vssue 可以在浏览器中通过 <script>
标签直接使用。由于 Vssue 依赖于 Vue.js,所以你还需要引入 Vue。
<head>
<!-- Vssue 的样式文件 -->
<link rel="stylesheet" href="https://unpkg.com/vssue/dist/vssue.min.css">
</head>
<body>
<div id="vssue"></div>
<!-- 先引入 Vue -->
<!-- Vue 运行时版 (runtime only) -->
<script src="https://unpkg.com/vue@2.7.14/dist/vue.runtime.min.js"></script>
<!-- 或: Vue 完整版 (runtime + compiler) -->
<script src="https://unpkg.com/vue@2.7.14/dist/vue.min.js"></script>
<!-- 在 Vue 之后引入 Vssue -->
<!-- Vssue Github 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.github.min.js"></script>
<!-- 或: Vssue Gitlab 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.gitlab.min.js"></script>
<!-- 或: Vssue Bitbucket 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.bitbucket.min.js"></script>
<!-- 或: Vssue Gitee 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.gitee.min.js"></script>
<!-- 或: Vssue Gitea 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.gitea.min.js"></script>
<!-- 将 Vssue 作为 Vue 组件使用 -->
<!-- 对于 Vue 运行时版,使用渲染函数(render function) -->
<script>
new Vue({
el: '#vssue',
render: h => h('Vssue', {
props: {
// 在这里设置当前页面对应的 Issue 标题
title: 'Vssue Dev',
// 在这里设置你使用的平台的 OAuth App 配置
options: {
owner: 'OWNER_OF_REPO',
repo: 'NAME_OF_REPO',
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
},
}
})
})
</script>
<!-- 或:对于 Vue 完整版,可以使用模板(template) -->
<script>
new Vue({
el: '#vssue',
data: {
title: 'Vssue Dev',
options: {
owner: 'OWNER_OF_REPO',
repo: 'NAME_OF_REPO',
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET', // 只有在使用某些平台时需要
},
},
template: `<vssue :title="title" :options="options"></vssue>`,
})
</script>
</body>
提示
如果你还不了解 Vue
的不同版本间的区别 (即 vue.runtime.min.js
, vue.min.js
等),可以参考 Vue 文档。
Vssue
同样提供了不同版本的构建。细节可以查看对不同构建版本的解释章节。
# 在 Vue 应用中使用
Vssue 是一个 Vue 插件 / 组件,可以在 Vue 项目中引入并使用。
# 通过 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
# 或:使用 Gitea V1
npm install @vssue/api-gitea-v1
# 作为 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 中使用 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 文件夹中:
文件名 | 类型 | Minified | Polyfills | 用途 |
---|---|---|---|---|
vssue.js | ES Module | false | false | 使用构建工具 |
vssue.[platform].min.js | UMD | true | false | 通过现代浏览器的 <script> 标签引入 |
vssue.[platform].polyfill.min.js | UMD | true | true | 通过旧版浏览器的 <script> 标签引入 |
参考 Vue 的不同构建版本