diff --git a/build/rollup.config.js b/build/rollup.config.js index 7f0232b..72f25c4 100644 --- a/build/rollup.config.js +++ b/build/rollup.config.js @@ -25,6 +25,7 @@ export default { banner: `/** * vue-tabs v${version} * (c) ${new Date().getFullYear()} ALEXQDJAY - * @license MIT + * mail: alexqdjay@126.com + * @license Apache2 */` } \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index cf9bbdd..f45cf7b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,5 +2,9 @@ 1. [Installation](./installation.md) 1. [Getting Started](./start.md) +1. [Config](./config.md) 1. [Guards](./guards.md) -1. [API](./api.md) \ No newline at end of file +1. [API](./api.md) +1. [Lazy Loading](./lazy_loading.md) + +[Chinese Documentation (中文版文档)](./zh-cn/README.md) \ No newline at end of file diff --git a/docs/api.md b/docs/api.md index 8f4b46f..91b3bb2 100644 --- a/docs/api.md +++ b/docs/api.md @@ -12,12 +12,17 @@ Only **One VueTaber** exists in our system, it's `this.$taber` inside component Open a Tab, if it has be existed it would be setted `ative`, it would be created. + `key` is a field of param, when the param is a object, and it is optional. The ID of tab equals it's name plus it's key, so if name is 'user' and key is '002', the ID would be 'user#002'. + + If has the same name but key is different，that would create two tabs. + ``` js this.$taber.open('home') // open the tab named 'home' // or object this.$taber.open({ - name: 'home' + name: 'home', + key: user.id }) ``` diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..4e20412 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,55 @@ +# Config + +The configuration of `vue-tabs` is so simple. + + +## VueTaber config + +``` js +const vueTaber = new VueTaber({ + tabs: Array, + persist: Boolean +}) + +``` + +- **tabs** + + A array contains tab configurations. + +- **persist** + + use localStorage to persist opened tabs, then these tabs would be restore when refresh +browser. + + +## Tab config + +```js +const tabs = [{ + name: 'user', // REQUIRED + component: component // REQUIRED, + title: 'title', // REQUIRED + beforeCreate: createHook // [OPTIONAL], + beforeClose: closeHook // [OPTIONAL] +}] + +``` + +- **name** + + The ID of tab equals it's name plus it's key, so if name is 'user' and key is '002', the ID would be 'user#002'. + + The name is used to get the configuration, and key is used to distinguish tabs which has the same name. + +- **component** + + The component will be created, when it's tab is opened. + +- **title** + + The title of tab. + +- **beforeCreate, beforeClose** + + hooks of `vue-tabs`, see [Guards](./guards.md) diff --git a/docs/lazy_loading.md b/docs/lazy_loading.md new file mode 100644 index 0000000..29fb46e --- /dev/null +++ b/docs/lazy_loading.md @@ -0,0 +1,24 @@ +# Lazy Loading + +Because of some components‘ size is so big and rarely used, we can load these components when we open the tab which is mapped to the component. + +Vue has the async component feature, but `vue-tabs` can't use it simply now, `vue-tabs` using Promise to achieve the target. Combining Webpack's code splitting feature, we can easy to lazy-load the compoent. + +A basic example as follows: + +```js + +const Foo = resolve => { + // require.ensure is Webpack's usage + require.ensure(['./Foo.vue'], () => { + resolve(require('./Foo.vue')) + }) +} + +// config of tab +{ + name: 'async', + title: '异步组件', + component: Foo +} +``` \ No newline at end of file diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 0000000..149212c --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,8 @@ +# 文档 + +1. [安装](./installation.md) +1. [开始使用](./start.md) +1. [配置](./config.md) +1. [钩子](./guards.md) +1. [API接口](./api.md) +1. [懒加载](./lazy_loading.md) \ No newline at end of file diff --git a/docs/zh-cn/api.md b/docs/zh-cn/api.md new file mode 100644 index 0000000..bdd9395 --- /dev/null +++ b/docs/zh-cn/api.md @@ -0,0 +1,67 @@ +# 接口 + +## VueTaber 实例 + +在系统中只会存在**一个 VueTaber**, 在组件中可以直接使用`this.$taber`来获取. + +### 方法 + +- **taber.open(tab)** + + - 参数类型: Object/String + + 调用时, 如果没有该的`ID`tab存在, 则新建一个tab, 否则激活该tab. + + `key`是参数`param`的一个可选字段. + + tab的`ID`的构成: name#key, 如name为`user`, key为`002`, 那么ID为`user#002`. + + 所以, 如果name一样, key不一样那么ID也会不一样, 这样会重新打开一个tab. + + ``` js + this.$taber.open('home') // 打开一个`name`为home的tab + + // 也可以传入对象 + this.$taber.open({ + name: 'home', + key: user.id + }) + ``` + + +- **taber.close(tab)** + +- **taber.select(tab)** + +- **taber.$on(event, callback)** + +- **taber.$off(event[, callback])** + +- **taber.beforeCreateEach(hookFn)** + + 添加全局钩子 + + +- **taber.beforeCloseEach(hookFn)** + + +## Tab Object + +**tab 对象** 代表当前标签页的状态数据, 它还包含**标签的配置信息** + +- **tab.name** +- **tab.meta** + + - 类型: Object + + 配置信息 + + +## 事件 + +- **`vue-tabs-active-change: function (tab)`**: 当激活另一个标签页时触发 +- **`ue-tabs-close: function (tab)`**: 当标签页被关闭时触发 + + +这两个事件的响应处理方法都会接受到`tab`这个参数 + diff --git a/docs/zh-cn/config.md b/docs/zh-cn/config.md new file mode 100644 index 0000000..e1c9f29 --- /dev/null +++ b/docs/zh-cn/config.md @@ -0,0 +1,54 @@ +# 配置 + +`vue-tabs`的配置非常简单. + + +## VueTaber 配置 + +``` js +const vueTaber = new VueTaber({ + tabs: Array, + persist: Boolean +}) + +``` + +- **tabs** + + 包含`tab`配置的数组 + +- **persist** + + 配置是否需要用`localStorage`记录已经打开的标签, 这样如果刷新浏览器或者关闭打开浏览器还能恢复这些标签. + + +## Tab 配置 + +```js +const tabs = [{ + name: 'user', // 必需 + component: component // 必需, + title: 'title', // 必需 + beforeCreate: createHook // [可选], + beforeClose: closeHook // [可选] +}] + +``` + +- **name** + + 标签的ID由`name + # + key`生成, 由此来唯一确定一个标签. + + `name`是用来获取标签的配置. 当两个标签的`name`相同时, 可以使用`key`是用来区分标签. + +- **component** + + 配置的组件会在对应标签页打开时创建. + +- **title** + + 标签上显示的标题. + +- **beforeCreate, beforeClose** + + 配置钩子, 详细见[Guards](./guards.md) diff --git a/docs/zh-cn/guards.md b/docs/zh-cn/guards.md new file mode 100644 index 0000000..b02dda2 --- /dev/null +++ b/docs/zh-cn/guards.md @@ -0,0 +1,54 @@ +# 钩子 + +`VueTaber`实例提供了用于响应标签创建和关闭的钩子函数注册. + +目前有两种方式配置钩子函数: 全局配置的和每个标签页配置的. + +### 全局配置 + +```js +const taber = new VueTaber({...}) +taber.beforeCreateEach((tab, next) => { + // ... +}) + +taber.beforeCloseEach((tab, next) => { + // ... +}) +``` + +钩子是按创建顺序进行调用的, 先创建的先被调用. + +每个钩子函数都接收到两个参数: + +- **`tab: Object`**: 目标标签的数据对象 [标签数据对象](./api.md) + +- **`next: Function`**: 这个方法必须被调用, 不然就会没有任何响应, 调用后下一步的动作依赖传入的参数 + + - **`next()`**: 进行下个钩子函数的执行 + + - **`next(false)`**: 放弃本次变化(创建或者关闭标签) + + - **`next(target)`**: `target:Object/String`, 放弃本次变化, 转向其他目标`target`, **只对创建起作用, 关闭时不起作用** + + +### 每个标签配置 + +```js +const vueTaber = new VueTaber({ + tabs: [{ + name: 'home', + title: '首页', + component: Hello, + beforeCreate (tab, next) { + console.log('before create:', tab) + next() + }, + beforeClose (tab, next) { + console.log('before close', tab) + next() + } + }] +}) +``` + diff --git a/docs/zh-cn/installation.md b/docs/zh-cn/installation.md new file mode 100644 index 0000000..7121ad9 --- /dev/null +++ b/docs/zh-cn/installation.md @@ -0,0 +1,37 @@ +# 安装 + +### 直接外联 + +在Html中引入, 它会自动安装 + +``` html + + +``` + +### NPM安装 + +``` bash +npm install vue-tabs +``` + +如果你是模块化开发，那么你`require`或者`import`后需要通过调用`vue.use()`进行安装 + +``` js +import Vue from 'vue' +import VueTaber from 'vue-tabs' + +Vue.use(VueTaber) + +``` + +### 构建开发版 + +你也可以从github上直接使用最新的开发般，然后直接构建 + +``` bash +git clone git@github.com:alexqdjay/vue-tabs.git node_modules/vue-tabs +cd node_modules/vue-tabs +npm install +npm run build +``` diff --git a/docs/zh-cn/lazy_loading.md b/docs/zh-cn/lazy_loading.md new file mode 100644 index 0000000..672f883 --- /dev/null +++ b/docs/zh-cn/lazy_loading.md @@ -0,0 +1,23 @@ +# 懒加载 + +介于有些组件比较大或者一般情况使用不到, 我们可以在打开那些对应的标签时再来加载这些组件. + +vue本身就有异步组件的概念, 但`vue-tabs`暂时没能用到该机制, `vue-tabs`的异步组件是直接基于Promise去实现, 在实际开发中结合 webpack 的`code splitting feature`来实现懒加载是非常简单的事情. + +下面是简单的示例: + +```js + +const Foo = resolve => { + // require.ensure 是 Webpack 的特殊语法, 配置需要分块的文件 + require.ensure(['./Foo.vue'], () => { + resolve(require('./Foo.vue')) + }) +} + +{ + name: 'async', + title: '异步组件', + component: Foo +} +``` \ No newline at end of file diff --git a/docs/zh-cn/start.md b/docs/zh-cn/start.md new file mode 100644 index 0000000..c96098a --- /dev/null +++ b/docs/zh-cn/start.md @@ -0,0 +1,65 @@ +# 开始使用 + +使用`vue + vue-tab`来开发一个SPA(单页面应用)是非常简单的, 你需要做的就是将`Component`和`tab`一一对应起来. + +这里有个简单的例子: + +### Html + +``` html + + + + + +
+ +
+ + +``` + +### JS + +### 1. Tabs Config + +``` js +import Hello from './components/Hello' +export default [{ + name: 'home', // name UNIQUE + title: '首页', // tab's title + component: Hello +}, { + name: 'test1', + title: '测试1', + component: { + template: '

测试1

' + } +}] +``` + +### 2. 创建实例 & Install + +```js +import VueTaber from 'vue-tabs' +import 'vue-tabs/vue-tabs.css' // 导入默认style, 你可以复制出来进行定制修改 +import tabs from './tabs.js' // 导入配置 + +Vue.use(VueTaber) + +const vueTaber = new VueTaber({ + tabs +}) + +new Vue({ + el: '#app', + taber: vueTaber, + template: '', + components: { + App + } +}) +``` + +你可以checkout DEMO的代码, 非常简单 [DEMO演示](http://alexqdjay.oschina.io/vue-tab) + diff --git a/example/components/Hello.vue b/example/components/Hello.vue index 727bb77..982fd5a 100644 --- a/example/components/Hello.vue +++ b/example/components/Hello.vue @@ -21,6 +21,9 @@ \ No newline at end of file diff --git a/src/Tabs.vue b/src/Tabs.vue index a85149c..8b98c1f 100644 --- a/src/Tabs.vue +++ b/src/Tabs.vue @@ -2,7 +2,7 @@
    -
  • {{tab.meta.title}}×
    • +
@@ -10,8 +10,8 @@
-