Skip to content

Commit dcba9bb

Browse files
leaves4jleaves4j
committed
update doc
1 parent 31f08fc commit dcba9bb

File tree

2 files changed

+124
-50
lines changed

2 files changed

+124
-50
lines changed

‎README-zh.md‎

Lines changed: 72 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@ vue-easy-renderer
22
---
33
`vue-easy-renderer` 是一个基于 `vue-server-renderer` 的服务端渲染工具, 他提供了更简单的方式来实现vue的服务端渲染， 包括 `Koa.js` 和 `Express.js` 的插件.
44

5-
+ [Installation](#installation)
6-
+ [Example](#example)
7-
+ [API](#api)
8-
+ [Renderer Options](#renderer-options)
9-
+ [Vue Client Plugin](#vue-client-plugin)
10-
+ [Component Head](#component-head)
11-
+ [Change Log](#change-log)
5+
- [Installation](#installation)
6+
- [Example](#example)
7+
- [API](#api)
8+
- [Renderer 选项](#renderer-选项)
9+
- [Vue Client Plugin](#vue-client-plugin)
10+
- [Component Head](#component-head)
11+
- [vuex or vue-router](#vuex-or-vue-router)
12+
- [ChangeLog](#changelog)
13+
- [License](#license)
1214

1315
## Installation
1416

@@ -24,7 +26,7 @@ npm i vue vuex vue-router vue-loader vue-server-renderer -S
2426

2527
## Example
2628

27-
### Vue File
29+
**Vue File**
2830

2931
创建一个文件 `component/hello_word/hello_word.vue`
3032

@@ -46,7 +48,7 @@ npm i vue vuex vue-router vue-loader vue-server-renderer -S
4648
</script>
4749
```
4850

49-
### Koa.js 2
51+
**Koa.js 2**
5052

5153
```js
5254
'use strict';
@@ -76,7 +78,7 @@ module.exports = app;
7678

7779
```
7880

79-
### Express.js
81+
**Express.js**
8082

8183
```js
8284
'use strict';
@@ -100,7 +102,7 @@ module.exports = app;
100102

101103
```
102104

103-
### Result
105+
**Result**
104106

105107
最后浏览器获取到的html
106108

@@ -118,48 +120,49 @@ Detail in [Full example](https://github.com/leaves4j/vue-easy-renderer/tree/mast
118120

119121
## API
120122

121-
### vueRender(path,data,config)
123+
**vueRender(path,data,config)**
122124

123125
在 `koa.js` 中 `vueRender`挂载在`ctx`上，即 `ctx.vueRender()`，在`express.js`中挂载在`res`上，即 `res.vueRender()`
124126

125-
| 参数 | 类型 | 描述 |
126-
| --- | --- | --- |
127-
| path | `String` | `*.vue` 基于 [`Options.basePath`](#renderer-options) 的路径 |
128-
| data | `Object` | 渲染数据，将会被合并到vue实例的data中或者vuex的state中|
129-
| [config] | `Object` | 渲染选项 |
130-
| [config.pure] | `Boolean` | 默认 `false`, 当设置为`pure:true`时，将会只渲染vue文件的html,不包含头尾|
127+
| 参数 | 类型 | 描述 |
128+
| ------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------ |
129+
| path | `String` | `*.vue` 基于 [`Options.basePath`](#renderer-options) 的路径 |
130+
| data | `Object` | 渲染数据，将会被合并到vue实例的data中或者vuex的state中 |
131+
| [config] | `Object` | 渲染选项 |
132+
| [config.pure] | `Boolean` | 默认 `false`, 当设置为`pure:true`时，将会只渲染vue文件的html,不包含头尾 |
131133
## Renderer 选项
132134

133-
### vueEasyRenderer(basePath,options)
135+
**vueEasyRenderer(basePath,options)**
134136

135-
**获取 vueEasyRenderer**
137+
获取 vueEasyRenderer
136138

137139
With `Koa.js 2`
138140

139141
```js
140142
const vueEasyRenderer = require('vue-easy-renderer').koaRenderer;
143+
const renderer = vueEasyRenderer(basePath, options);
141144
```
142145

143146
With `Express.js`
144147

145148
```js
146149
const vueEasyRenderer = require('vue-easy-renderer').connectRenderer;
150+
const renderer = vueEasyRenderer(basePath, options);
147151
```
148152

149-
**参数:**
153+
**参数**
150154

151-
| 参数 | 类型 | 描述 |
152-
| --- | --- | --- |
153-
| basePath | `string` | `*.vue` 文件路径 |
154-
| [options] | `Object` | renderer 的 options |
155-
| [options.watch] | `Boolean` | 默认值 `false`, 是否监控 '*.vue' 的变更, 当process.env.NODE_ENV|
156-
| [options.plugins] | `Array` \| `string` | vue插件, 如 `[vueRouter]` 或者 `[{plugin: vueRouter,options: {}}]`, 同时也支持字符串，如： `[path.resolve('../app/resource.js')]` |
157-
| [options.preCompile] | `Array` | 需要预编译的 `*.vue` 文件路径列表，如：`['test.vue']` |
158-
| [options.head] | `Object` | 通用的html头部设置， 详情见 [Component Head](#component-head) |
159-
| [options.compilerConfig] | `Object` | 服务端vue文件的编译器配置，为webpack配置文件，默认配置使用 `vue-loader` 、 `css-loader` 、 `babel-loader`|
160-
| [options.onError] | `Function` | 异常处理方法|
161-
| [options.onReady] | `Function` | ready 时间处理方法, renderer 将会在完成初始化工作之后emit一个ready事件|
162-
| [options.global] | `Object` | 全局变量, 这些全局变量将会被注入的vue服务端渲染时的sandbox的作用域，相当于node中的global.xx，浏览器中的window.xx|
155+
| 参数 | 类型 | 描述 |
156+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
157+
| basePath | `string` | `*.vue` 文件路径 |
158+
| [options] | `Object` | renderer 的 options |
159+
| [options.plugins] | `Array` \| `string` | vue插件, 如 `[vueRouter]` 或者 `[{plugin: vueRouter,options: {}}]`, 同时也支持字符串，如： `[path.resolve('../app/resource.js')]` |
160+
| [options.preCompile] | `Array` | 需要预编译的 `*.vue` 文件路径列表，如：`['test.vue']` |
161+
| [options.head] | `Object` | 通用的html头部设置， 详情见 [Component Head](#component-head) |
162+
| [options.compilerConfig] | `Object` | 服务端vue文件的编译器配置，为webpack配置文件，默认配置使用 `vue-loader`、 `babel-loader` |
163+
| [options.onError] | `Function` | 异常处理方法 |
164+
| [options.onReady] | `Function` | ready 时间处理方法, renderer 将会在完成初始化工作之后emit一个ready事件 |
165+
| [options.global] | `Object` | 全局变量, 这些全局变量将会被注入的vue服务端渲染时的sandbox的作用域，相当于node中的global.xx，浏览器中的window.xx |
163166

164167

165168
## Vue Client Plugin
@@ -226,6 +229,42 @@ Then the result
226229
</html>
227230
```
228231

232+
## vuex or vue-router
233+
234+
在服务端渲染中使用vuex或者vue-router时，我们需要为每个请求创建一个vuex或者vue-router实例，因此在跟组件注入vuex或者vue-router实例时，需要在实例上添加一个工厂方法，该方法调用时返回一个实例，默认方法名为`$ssrInstance`，如:
235+
236+
**vuex**
237+
238+
```js
239+
const options = {
240+
state: {
241+
hello: 'world!'
242+
}
243+
};
244+
245+
const store = new Vuex(options);
246+
store.$ssrInstance = () => new Vuex(options);
247+
export default store;
248+
```
249+
250+
**vue-router**
251+
252+
```js
253+
const options = {
254+
mode: 'history',
255+
routes: [
256+
{ path: '/user/:id', component: User }
257+
]
258+
})
259+
260+
const router = new VueRouter(options)
261+
router.$ssrInstance = () => new Vuex(options);
262+
export default router;
263+
```
264+
如果在服务端渲染中使用`vue-router`，需要设置`mode`为`history`
265+
266+
267+
229268
## ChangeLog
230269

231270
[ChangeLog](https://github.com/leaves4j/vue-easy-renderer/blob/master/CHANGELOG.md)

‎README.md‎

Lines changed: 52 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,15 @@ vue-easy-renderer
44

55
[中文说明](https://github.com/leaves4j/vue-easy-renderer/blob/master/README-zh.md)
66

7-
+ [Installation](#installation)
8-
+ [Example](#example)
9-
+ [API](#api)
10-
+ [Renderer Options](#renderer-options)
11-
+ [Vue Client Plugin](#vue-client-plugin)
12-
+ [Component Head](#component-head)
13-
+ [Change Log](#change-log)
7+
- [Installation](#installation)
8+
- [Example](#example)
9+
- [API](#api)
10+
- [Renderer Options](#renderer-options)
11+
- [Vue Client Plugin](#vue-client-plugin)
12+
- [Component Head](#component-head)
13+
- [vuex or vue-router](#vuex-or-vue-router)
14+
- [ChangeLog](#changelog)
15+
- [License](#license)
1416

1517
## Installation
1618

@@ -26,7 +28,7 @@ npm i vue vuex vue-router vue-loader vue-server-renderer -S
2628

2729
## Example
2830

29-
### Vue File
31+
**Vue File**
3032

3133
Create the vue file in `component/hello_word/hello_word.vue`
3234

@@ -48,7 +50,7 @@ Create the vue file in `component/hello_word/hello_word.vue`
4850
</script>
4951
```
5052

51-
### Koa.js 2
53+
**Koa.js 2**
5254

5355
```js
5456
'use strict';
@@ -78,7 +80,7 @@ module.exports = app;
7880

7981
```
8082

81-
### Express.js
83+
**Express.js**
8284

8385
```js
8486
'use strict';
@@ -102,7 +104,8 @@ module.exports = app;
102104

103105
```
104106

105-
### Result
107+
**Result**
108+
106109
The browser get the html:
107110

108111
```html
@@ -119,7 +122,7 @@ Detail in [Full example](https://github.com/leaves4j/vue-easy-renderer/tree/mast
119122

120123
## API
121124

122-
### vueRender(path,data,config)
125+
**vueRender(path,data,config)**
123126

124127
Use `ctx.vueRender()` in koa.js or `res.vueRender()` in express
125128

@@ -132,29 +135,28 @@ Use `ctx.vueRender()` in koa.js or `res.vueRender()` in express
132135

133136
## Renderer Options
134137

135-
### vueEasyRenderer(basePath,options)
136-
137-
**get vueEasyRenderer**
138+
**vueEasyRenderer(basePath,options)**
138139

139140
With `Koa.js 2`
140141

141142
```js
142143
const vueEasyRenderer = require('vue-easy-renderer').koaRenderer;
144+
const renderer = vueEasyRenderer(bastPath, options);
143145
```
144146

145147
With `Express.js`
146148

147149
```js
148150
const vueEasyRenderer = require('vue-easy-renderer').connectRenderer;
151+
const renderer = vueEasyRenderer(bastPath, options);
149152
```
150153

151-
**Params:**
154+
**Options**
152155

153156
| Param | Type | Description |
154157
| --- | --- | --- |
155158
| basePath | `string` | `*.vue` file base path |
156159
| [options] | `Object` | renderer options |
157-
| [options.watch] | `Boolean` | default `false`, watch the '*.vue' file changes |
158160
| [options.plugins] | `Array` \| `string` | vue plugins, e.g. `[vueRouter]` or `[{plugin: vueRouter,options: {}}]`, it also support using plugin path string, e.g. `[path.resolve('../app/resource.js')]` |
159161
| [options.preCompile] | `Array` | pre-compile `*.vue` file list |
160162
| [options.head] | `Object` | common html head config see detail in [Component Head](#component-head) |
@@ -228,6 +230,39 @@ Then the result
228230
</html>
229231
```
230232

233+
## vuex or vue-router
234+
235+
When using vuex or vue-router in server-side rendering, we need to create a vuex or vue-router instance for each request, so when you inject a vuex or vue-router instance into a component, you need to add a factory function to the instance , The function will return an instance when called, the default method is named `$ ssrInstance`, such as:
236+
237+
**vuex**
238+
239+
```js
240+
const options = {
241+
state: {
242+
hello: 'world!'
243+
}
244+
};
245+
246+
const store = new Vuex(options);
247+
store.$ssrInstance = () => new Vuex(options);
248+
export default store;
249+
```
250+
251+
**vue-router**
252+
253+
```js
254+
const options = {
255+
mode: 'history',
256+
routes: [
257+
{ path: '/user/:id', component: User }
258+
]
259+
})
260+
261+
const router = new VueRouter(options)
262+
router.$ssrInstance = () => new Vuex(options);
263+
export default router;
264+
```
265+
If you use `vue-router` in server rendering, you need to set `mode` to `history`
231266
## ChangeLog
232267

233268
[ChangeLog](https://github.com/leaves4j/vue-easy-renderer/blob/master/CHANGELOG.md)

0 commit comments

Comments
 (0)