一、Vssue介绍
Vssue 是一个 Vue 组件 / 插件,可以为你的静态页面开启评论功能。
由于你的页面是静态的,没有数据库和后端 的支持。但是你希望让你的页面拥有评论功能,让用户可以登录和发表评论。代码托管平台(如 Github、Gitlab)为你提供了 OAuth API ,Vssue 可以让用户通过这些平台的帐号登录,将评论存储在这些平台的 Issue 系统中,并在当前页面展示。
这也是 Vssue 名字的由来:由 Vue 驱动并基于 Issue 实现
二、Vssue特点
Vssue 的特点在于:
- 支持多种平台,很容易扩展到其他平台上。不只是 Github,目前还支持了 Gitlab 和 Bitbucket
- 除了发表评论,还可以编辑和删除评论,还可以对评论进行分页
- 基于 Vue 开发,很容易集成到 Vue 项目中,并且提供了 Vuepress 的插件
三、工作过程
用户在平台的授权页面允许 Vssue 接入后,平台会带有 code
重定向回 Vssue 的页面。
Vssue 将会根据 code
向平台请求获取用户的 token
,然后将 token
存储在 localstorage 中,于是用户就成功使用平台的帐号“登录”了 Vssue。
四、使用
Vssue 支持通过 Github, Gitlab, Bitbucket 或者 Gitee 的 Issue 系统来为你的静态页面提供评论功能,你可以选择其中之一来使用。
支持的代码托管平台
指南: http://www.mianshigee.com/tutorial/vssue/b749ee848e702d4b.md
Github REST API V3
- Vssue API 包: @vssue/api-github-v3
- 特点 / 缺点:
- 需要设置 clientSecret
- 评论无法排序
- 评论可以编辑
- 评论可以删除
- 可以不登录浏览评论,但 API 有调用频率限制
GitLab
指南: http://www.mianshigee.com/tutorial/vssue/747e2a3b141fb0a9.md
Gitlab API V4 (Gitlab v11.0+)
- Vssue API 包: @vssue/api-gitlab-v4
- 特点 / 缺点:
- 评论可以排序
- 评论可以编辑
- 评论可以删除
- 要求登陆后才能浏览评论
- 开发者参考:https://docs.gitlab.com/ce/api/
Gitee
指南: http://www.mianshigee.com/tutorial/vssue/a6978e025eabbdb9.md
Gitee API V5
- Vssue API 包: @vssue/api-gitee-v5
- 特点 / 缺点:
- 需要设置 clientSecret
- 评论无法排序
- 评论可以编辑
- 评论可以删除
- 可以不登录浏览评论,但 API 有调用频率限制
- 不能对评论做出 emoji 响应 (喜欢、点赞、踩 等)
选择并配置好平台后,你将会配置好一个 OAuth App,并得到对应的 clientid
和 client secret:
owner
: 对应 repository 的拥有者帐号或者团队repo
: 用来存储评论的 repositoryclientId
: OAuth App 的client id
clientSecret
: OAuth App 的client secret
(只有在使用某些平台时需要)
在浏览器中使用
<head>
<!-- Vssue 的样式文件 -->
<link rel="stylesheet" href="https://unpkg.com/vssue/dist/vssue.min.css">
</head>
<body>
<div id="vssue"></div>
<!-- 先引入 Vue -->
<script src="https://unpkg.com/vue/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 Gitee 版 -->
<script src="https://unpkg.com/vssue/dist/vssue.gitee.min.js"></script>
<!-- 对于 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>
通过包引入
安装 vssue
:
npm install vssue
安装对应平台的包
# 使用 Github V3
npm install @vssue/api-github-v3
# 或:使用 Github V4
npm install @vssue/api-github-v4
# 或:使用 Gitlab V4
npm install @vssue/api-gitlab-v4
# 或:使用 Gitee V5
npm install @vssue/api-gitee-v5
当作插件使用的配置
// 引入 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', // 只有在使用某些平台时需要
})
当作组件使用的配置
<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>
接下来的话,再带大家配置一下OAuth,此处以gitlab为例:
创建一个新的 Application:
五、配置
Vssue 配置 (类型 VssueOptions
)在调用 Vue.use()
时进行设置:
import Vue from 'vue';
import Vssue from 'vssue';
Vue.use(Vssue, {
// Vssue 配置
});
1.api
VssueAPI 类的构造函数,而 VssueAPI 类实现了 VssueAPI.Instance
接口。
Vssue 会使用它创建 VssueAPI 实例,然后通过 VssueAPI 实例向平台发出请求。
import Vue from 'vue';
import Vssue from 'vssue';
import GithubV3 from '@vssue/api-github-v3';
Vue.use(Vssue, {
api: GithubV3,
// 其它 Vssue 配置
});
2.owner
用来存储 Issue 和评论的仓库的拥有者的名称。可能是一个用户,也可能是一个组织
3.repo
用来存储 Issue 和评论的仓库的名称。
Vssue 将通过 owner
和 repo
在平台上定位这个仓库。
4.clientId
它是由平台分配的 client 标识符。你在创建 OAuth App 之后就可以得到它。
Vssue 将使用 clientId
来获取用户的 access token。
5.clientSecret
它是由平台生成的 client 密钥。你在创建 OAuth App 之后就可以得到它。
在和某些平台一起使用时, Vssue 将使用 clientId
和 clientSecret
来获取用户的 access token。
6.baseURL
平台的 base URL。
对于我们支持的平台
7.state
Vssue 将会在重定向到平台认证界面时发送它,并在平台认证返回后检查它是否正确。
它是被设计用来避免 CSRF 的,但是由于我们所有东西都在静态页面上,所以它没有太大作用。忽略这个选项,或者随便设置成什么值都行。
8.labels
用来设置 Vssue 使用的 Issue 的 labels (标签)。
Vssue 只会请求拥有对应标签的 Issue,忽略其他的 Issue。Vssue 通过 title
和 labels
来确定用来存储评论的对应 Issue。传入多个字符串可以设置多个标签,只有同时满足这些标签的 Issue 才会被 Vssue 请求。
9.prefix
Issue 标题的前缀。用于生成存储评论的对应 Issue 的实际标题。
举例来说,如果 prefix
是 '[Vssue]'
,title
是 'Vssue Demo'
,那么 Issue 的实际标题就是 '[Vssue]Vssue Demo'
。
如果 title
的类型是 Function
,这个配置将会被忽略。
10.admins
拥有 admin 权限的用户数组。owner
始终视为拥有 admin 权限。
拥有 admin 权限的用户可以删除所有用户的评论,而其他用户只能删除自己的评论。
只有 admins
才能在存储评论的 Issue 不存在时自动创建它。
11.perPage
默认每页显示的评论数
12.locale
使用的语言。
不设置该选项时,Vssue 会使用 window.navigator.languages
中的语言,如果其中没有 Vssue 支持的语言则会默认使用 'en'
13.
issueContent
Vssue 自动创建 Issue 时使用的内容。
Vssue 将使用该函数的返回值作为 Issue 的内容。
参数包含两个属性:
options
是 Vssue 的 options。url
是当前页面的 URL ,是 Vssue 生成 Issue 时默认使用的内容。
14.autoCreateIssue
如果 autoCreateIssue
设置为 true
,在对应的 Issue 不存在时,Vssue 会自动尝试为你创建 Issue。注意,若你当前没有登录,则 Vssue 会自动跳转到平台的认证页面。
六、组件内配置
1. title
当前 Vssue 组件使用的 Issue 的标题。
- 如果类型是
string
,实际标题是`${prefix}${title}`
。 - 如果类型是
Function
,实际标题是函数的返回值。注意,这个函数的第一个参数是 Vssue 的 options,你可以通过它们来生成实际的标题。
2.issueId
当前 Vssue 组件使用的 Issue 的 ID。
如果设置了 issueId
,下列参数将会被忽略:
- Options:
labels
,prefix
,issueContent
和autoCreateIssue
- Props:
title
3. options
-
在 prop
options
中设置的属性,会覆盖通过Vue.use()
设置的属性。它可以接收VssueOptions
中的所有配置。你可以把通过
Vue.use()
设置的配置当作 Vssue 的 全局 / 默认 配置,把通过 propoptions
设置的配置当作 局部 配置。
七、注意
在使用的时候要注意vssue仅支持history路由模式
vssue可以在vuepress和nuxt中使用
以上就是本篇文章的全部内容了,参考了官方文档,扒出了自认为重要的东西。建议自己动手试试哈,切忌‘纸上谈兵’,emm,踩坑的话记得回来一起分享下,欢迎指正哦~