# Storybook vue

供快速进行页面开发和部署的极简 vue.js 模板。

GitHub(opens new window)

# 介绍

此项目可以帮助你在最短的时间内完成以下功能:

  • 开箱即用的开发环境
  • 立刻基于 vue.js 快速开始编写一系列页面代码
  • 自动根据本地文件结构自动生成所有页面的入口菜单
  • 自动在 GitHub 上自动部署网站方便预览和分享
  • 自动在预览网站生成每个页面的源码链接
  • 自动基于您的 git 提交记录在 GitHub 上发布新的版本

你要做的就是在想写点什么的时候,直接基于这个模板开始写内容就好了,写完一页,新建文件再写一页,路由和菜单自动为你生成。

敲几下回车就能提交。

配置一个 token 就能部署。

没有什么复杂功能,只是帮你做了一些自己做会浪费时间的准备,虽然没用多长时间准备这些代码,但是为了节约后人时间,我用了比代码几倍的时间准备这篇文档。

正如其名字,这是一本故事书,你的故事书写之前这只是一个简单的本子。

作者注

我本人厌烦了很多时候测试小东西要新建项目还要搞趁手这段时间的浪费。

# 替你准备好了什么

简单来说这是一个功能 的精简框架。

  • 基于 cli4 的基础项目结构
  • 组件自动注册方案
  • 路由自动注册方案
  • 菜单自动生成方案
  • 部署后每个页面查看对应源码的功能
  • 更美观的滚动条
  • 配置好的 CI 文件帮你自动发版和部署
  • 符合 angular 提交准则的 git 工具
  • 一个简洁的布局,一个简单的页面容器组件
  • ElementUI 和 lodash

# 适用场景

  • 有简单的多页面书写需求,并希望完成后可以在线预览
  • 学习过程中想试验一下并整理成册
  • 分别尝试某个插件的很多功能
  • 部署一个简单的展示网页

# 不适用场景

  • 你想正式写一个全功能网站
  • 你只是需要一个记事本,它不如普通的记事本方便
  • 需要专业的组件隔离展示和测试,不妨试试 storybook.js(opens new window)

# 前提要求

  • 基础的 git 知识
  • GitHub 账户
  • 基础前端开发和 vue.js 相关技能

# 使用方法

首先进入 项目主页(opens new window) 将项目 fork 至您的账号下,然后新建 GitHub 空仓库,模板选择 storybook-vue,并克隆到本地。

删除 docs 文件夹。

修改 package.json 文件中 repository.url 为您仓库的 git 地址。

安装依赖:

yarn

运行:

yarn dev

至此已可以开始您的书写。

# 内置组件

# github-ribbon

右上角的 GitHub 链接绶带,无可接受参数,使用了 d2-ribbons(opens new window) 中的设计,渲染效果是附带图片的 position: fixed 链接,固定在屏幕右上角,默认链接根据 package.json 中的信息自动指向当前仓库地址。

提示

如果你觉得默认图片样式不好看,可以到 d2-ribbons(opens new window) 换一个喜欢的样式

# source-code

一个 <a> 容器,无可接受参数,没有自身样式,有默认 slot。功能是跳转到当前页面的源码页面。仓库地址根据 package.json 中的信息确定,自动确定源码路径依赖 vue-filename-injector(opens new window) 实现。

使用示例:

<source-code>
  <button>点我查看本页源码</button>
</source-code>

# story-container

页面内容容器,无可接受参数,每个页面的根组件应该使用它。具有 default header footer slot。

使用示例:

<template>
  <story-container>
    <template slot="header">我是页头</template>
    我是页面内容
    <template slot="footer">我是页脚</template>
  </story-container>
</template>

# 页面和路由规则

自动生成路由的规则见 vue-route-generator(opens new window) ,项目中使用 vue-cli-plugin-auto-routing(opens new window) 实现自动生成路由配置,并依据生成的路由数据计算出菜单显示。

# 提交

# 准则

请使用 angular 提交准则(opens new window) ,具体可参考:https://www.conventionalcommits.org/zh-hans(opens new window)

本项目已经使用 commitizen(opens new window) 工具进行初始化,可以直接在命令行中体验交互式提交,通过选择+填空的方式生成规范的 commit message:

首先需要在您计算机中全局安装 commitizen :

npm i -g commitizen

提交代码:

git cz

示例:

git status
git add .
git cz
cz-cli@4.0.3, cz-conventional-changelog@3.1.0

? Select the type of change that you're committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip) 
? Write a short, imperative tense description of the change (max 94 chars):
 (5) 修改了首页
? Provide a longer description of the change: (press enter to skip)
? Are there any breaking changes? No
? Does this change affect any open issues? No

[master 85ad888] feat: 修改了首页
 2 files changed, 1 insertion(+), 33 deletions(-)
 delete mode 100644 docs/CHANGELOG.md

# 分支管理

推荐使用 master + dev 模式:

  • master:默认分支,包含了所有的版本 tag,最后一次提交永远是最近一次版本发布,保证同个版本下载的代码都是一致的,同时也和部署到预览的代码一致
  • dev:开发分支,里面是上一次版本发布后,待发布的提交,当需要发布时直接合并到 master
  • gh-pages:部署 Github Pages 时生产的分支,请忽略

开发流程如下:

# ...在 dev 完成多次 commit 后
(dev) git push
(dev) git checkout master
(master) git merge dev # 把即将发布的代码合并到 master
(master) git push
# ...等待发布完成
(master) git pull # 发布的过程中可能会自动产生一些提交
(master) git checkout dev
(dev) git merge master
(dev) git push # 让 dev 与 master 保持一致
# ... 继续在 dev 开发

# 部署

提示

请确认您项目中的 package.json 文件中 repository.url 必须为您仓库的 git 地址。

# 准备

在开始部署之前您需要配置项目的 ACCESS_TOKEN

进入个人设置,选择 Developer settings > Personal access tokens > Generate new token 创建新的 token,名称随意填写,权限勾选 repo。

点击 Generate token 完成创建,记录好生成的 token。

进入当前仓库的设置 > Secrets > Add a new secret 创建新的私有数据。Name 值为 ACCESS_TOKENValue 值为刚刚得到的 token。

点击 Add secret 完成创建。

至此部署准备完成。

# 规则

项目基于 GitHub Action 实现自动发版和部署。具体规则如下:

  • 在 master 分支每次发生提交时,触发新版本发布监检测 release.yml(opens new window) ,此动作会基于您的提交记录判断是否需要变更版本号以及发布新的 release
  • 在发布新的 release 之后,会触发构建命令 deploy.yml(opens new window) ,构建结果提交至 gh-pages 分支作为预览地址

提示

上述自动操作的前提是在代码提交时按照本文档中的要求进行的 git 操作

代码再次变更后将本地项目提交到远程:

git add .
git cz
git push origin master

您可以在仓库的 Action 页面查看自动发版和部署情况:

在 Release pipeline 执行结束后,如果有新版本将会自动部署预览:

所有 Action 结束之后,您可以在仓库的设置页面看到该仓库对应的预览地址: