|
| 1 | +#vue-rx[](https://circleci.com/gh/vuejs/vue-rx/tree/master) |
| 2 | + |
| 3 | +[English](README.md) | 简体中文 |
| 4 | + |
| 5 | +将[RxJS v6](https://github.com/ReactiveX/rxjs) 集成到 Vue.js。 |
| 6 | + |
| 7 | +>**相比 5.0 的不兼容变更** |
| 8 | +> |
| 9 | +>- vue-rx v6 现在默认只对 RxJS V6 生效。如果你想继续使用 RxJS v5 风格的代码，安装`rxjs-compat`。 |
| 10 | +
|
| 11 | +###安装 |
| 12 | + |
| 13 | +####NPM + ES2015 |
| 14 | + |
| 15 | +**`rxjs` 需要作为 peer dependency 引入。** |
| 16 | + |
| 17 | +```bash |
| 18 | +npm install vue vue-rx rxjs --save |
| 19 | +``` |
| 20 | + |
| 21 | +```js |
| 22 | +importVuefrom'vue'; |
| 23 | +importVueRxfrom'vue-rx'; |
| 24 | + |
| 25 | +Vue.use(VueRx); |
| 26 | +``` |
| 27 | + |
| 28 | +webpack 打包默认会使用`dist/vue-rx.esm.js`。这样引入最小数量的 Rx 操作符并且保证了最小的打包体积。 |
| 29 | + |
| 30 | +####全局脚本 |
| 31 | + |
| 32 | +如果要在浏览器环境使用，需要引入 UMD 构建版本`dist/vue-rx.js`。在浏览器环境中的 UMD 构建版本会假设`window.rxjs` 已经存在，因此你需要确保在 Vue.js 和 RxJS 之后引入`vue-rx.js`。如果`window.Vue` 存在的话，`vue-rx` 会自动安装。 |
| 33 | + |
| 34 | +例子: |
| 35 | + |
| 36 | +```html |
| 37 | +<scriptsrc="https://unpkg.com/rxjs/bundles/rxjs.umd.js"></script> |
| 38 | +<scriptsrc="https://unpkg.com/vue/dist/vue.js"></script> |
| 39 | +<scriptsrc="../dist/vue-rx.js"></script> |
| 40 | +``` |
| 41 | + |
| 42 | +###如何使用 |
| 43 | + |
| 44 | +```js |
| 45 | +// 用 `subscriptions` 选项提供 Rx observables |
| 46 | +newVue({ |
| 47 | + el:'#app', |
| 48 | + subscriptions: { |
| 49 | + msg: messageObservable |
| 50 | + } |
| 51 | +}); |
| 52 | +``` |
| 53 | + |
| 54 | +```html |
| 55 | +<!-- 绑定到模板--> |
| 56 | +<div>{{ msg }}</div> |
| 57 | +``` |
| 58 | + |
| 59 | +`subscriptions` 选项也可以接受一个函数，这样就可以在每个组件实例中返回独一无二的 observables： |
| 60 | + |
| 61 | +```js |
| 62 | +import {Observable }from'rxjs' |
| 63 | + |
| 64 | +Vue.component('foo', { |
| 65 | +subscriptions:function () { |
| 66 | +return { |
| 67 | + msg:newObservable(...) |
| 68 | + } |
| 69 | + } |
| 70 | +}) |
| 71 | +``` |
| 72 | + |
| 73 | +Observables 会以`vm.$observables` 的形式暴露： |
| 74 | + |
| 75 | +```js |
| 76 | +constvm=newVue({ |
| 77 | + subscriptions: { |
| 78 | + msg: messageObservable |
| 79 | + } |
| 80 | +}); |
| 81 | + |
| 82 | +vm.$observables.msg.subscribe(msg=>console.log(msg)); |
| 83 | +``` |
| 84 | + |
| 85 | +###`v-stream`：流式 DOM 事件 |
| 86 | + |
| 87 | +`vue-rx` 提供`v-stream` 让你向一个 Rx Subject 流式发送 DOM 事件。语法和`v-on` 相似，指令参数对应事件名，绑定值对应 Rx Subject。 |
| 88 | + |
| 89 | +```html |
| 90 | +<buttonv-stream:click="plus$">+</button> |
| 91 | +``` |
| 92 | + |
| 93 | +注意在渲染发生之前你需要在 vm 实例上声明一个`rxjs.Subject` 实例 ——`plus$`，就像声明数据那样。你也可以在`subscriptions` 函数中这样做。 |
| 94 | + |
| 95 | +```js |
| 96 | +import {Subject }from'rxjs'; |
| 97 | +import {map,startWith,scan }from'rxjs/operators'; |
| 98 | + |
| 99 | +newVue({ |
| 100 | +subscriptions() { |
| 101 | +// 声明接收的 Subjects |
| 102 | +this.plus$=newSubject(); |
| 103 | +// ...然后使用 Subjects 作为来源流创建订阅。 |
| 104 | +// 来源流以 `{ event: HTMLEvent, data?: any }` 的格式发送数据 |
| 105 | +return { |
| 106 | + count:this.plus$.pipe( |
| 107 | +map(()=>1), |
| 108 | +startWith(0), |
| 109 | +scan((total,change)=> total+ change) |
| 110 | + ) |
| 111 | + }; |
| 112 | + } |
| 113 | +}); |
| 114 | +``` |
| 115 | + |
| 116 | +或者，使用`domStreams` 简写选项： |
| 117 | + |
| 118 | +```js |
| 119 | +newVue({ |
| 120 | +// 需要传递 `Rx` 给 `Vue.use()` 暴露 `Subject` |
| 121 | + domStreams: ['plus$'], |
| 122 | +subscriptions() { |
| 123 | +// 使用 `this.plus$` |
| 124 | + } |
| 125 | +}); |
| 126 | +``` |
| 127 | + |
| 128 | +最后，使用另一种语法给流传递额外的数据： |
| 129 | + |
| 130 | +```html |
| 131 | +<buttonv-stream:click="{ subject: plus$, data: someData }">+</button> |
| 132 | +``` |
| 133 | + |
| 134 | +当你需要伴随诸如`v-for` 迭代的临时模板变量一起传递，这就非常有用了。你可以直接从来源流撷取想要的数据。 |
| 135 | + |
| 136 | +```js |
| 137 | +constplusData$=this.plus$.pipe(pluck('data')); |
| 138 | +``` |
| 139 | + |
| 140 | +从 3.1 版本开始，你可以传入额外的选项(作为第三个参数一起传入原生的`addEventListener`)： |
| 141 | + |
| 142 | +```html |
| 143 | +<buttonv-stream:click="{ |
| 144 | + subject: plus$, |
| 145 | + data: someData, |
| 146 | + options: { once: true, passive: true, capture: true } |
| 147 | +}">+</button> |
| 148 | +``` |
| 149 | + |
| 150 | +更具体的用法请查阅[实例](https://github.com/vuejs/vue-rx/blob/master/example/counter.html)。 |
| 151 | + |
| 152 | +###`v-stream`：从子组件流式发送自定义事件 |
| 153 | + |
| 154 | +跟流式`DOM` 事件很相似，`v-stream` 也可以被用于组件，它会根据子组件触发的自定义事件创建 observables。运作方式跟`v-on` 相似： |
| 155 | + |
| 156 | +```html |
| 157 | +<div> |
| 158 | +<!-- 自定义组件--> |
| 159 | + <paginationv-on:change="pageChanged()"></pagination> |
| 160 | + |
| 161 | +<!-- 在自定义组件上使用 `v-stream`--> |
| 162 | + <paginationv-stream:change="pageChange$"></pagination> |
| 163 | +</div> |
| 164 | +``` |
| 165 | + |
| 166 | +###其它 API 方法 |
| 167 | + |
| 168 | +####`$watchAsObservable(expOrFn, [options])` |
| 169 | + |
| 170 | +这是一个添加到实例的原型方法。你可以根据一个值的侦听器创建 observable。值会以`{ newValue, oldValue }` 的格式触发： |
| 171 | + |
| 172 | +```js |
| 173 | +import {pluck,map }from'rxjs/operators'; |
| 174 | + |
| 175 | +constvm=newVue({ |
| 176 | + data: { |
| 177 | + a:1 |
| 178 | + }, |
| 179 | +subscriptions() { |
| 180 | +// 用 Rx 操作符声明式地映射成另一个属性 |
| 181 | +return { |
| 182 | + aPlusOne:this.$watchAsObservable('a').pipe( |
| 183 | +pluck('newValue'), |
| 184 | +map(a=> a+1) |
| 185 | + ) |
| 186 | + }; |
| 187 | + } |
| 188 | +}); |
| 189 | + |
| 190 | +// 或者产生副作用... |
| 191 | +vm.$watchAsObservable('a').subscribe( |
| 192 | + ({ newValue, oldValue })=>console.log('stream value', newValue, oldValue), |
| 193 | +err=>console.error(err), |
| 194 | + ()=>console.log('complete') |
| 195 | +); |
| 196 | +``` |
| 197 | + |
| 198 | +可选的`options` 对象，接受的选项与`vm.$watch` 一致。 |
| 199 | + |
| 200 | +####`$eventToObservable(event)` |
| 201 | + |
| 202 | +转化`vue.$on` (包括生命周期事件) 到 Observables。值会以`{ name, msg }` 的格式触发： |
| 203 | + |
| 204 | +```js |
| 205 | +import {interval }from'rxjs'; |
| 206 | +import {take,takeUntil }from'rxjs/operators'; |
| 207 | + |
| 208 | +constvm=newVue({ |
| 209 | +created() { |
| 210 | +this.$eventToObservable('customEvent').subscribe(event=> |
| 211 | +console.log(event.name,event.msg) |
| 212 | + ); |
| 213 | + } |
| 214 | +}); |
| 215 | + |
| 216 | +// `vm.$once` 的 `vue-rx` 版本 |
| 217 | +this.$eventToObservable('customEvent').pipe(take(1)); |
| 218 | + |
| 219 | +// 另一种取消订阅的方法： |
| 220 | +let beforeDestroy$=this.$eventToObservable('hook:beforeDestroy').pipe( |
| 221 | +take(1) |
| 222 | +); |
| 223 | + |
| 224 | +interval(500).pipe(takeUntil(beforeDestroy$)); |
| 225 | +``` |
| 226 | + |
| 227 | +####`$subscribeTo(observable, next, error, complete)` |
| 228 | + |
| 229 | +这是一个添加到实例的原型方法。你可以用它订阅一个 observable，但是得让 VueRx 管理它的 dispose/unsubscribe。 |
| 230 | + |
| 231 | +```js |
| 232 | +import {interval }from'rxjs'; |
| 233 | + |
| 234 | +constvm=newVue({ |
| 235 | +mounted() { |
| 236 | +this.$subscribeTo(interval(1000),function(count) { |
| 237 | +console.log(count); |
| 238 | + }); |
| 239 | + } |
| 240 | +}); |
| 241 | +``` |
| 242 | + |
| 243 | +####`$fromDOMEvent(selector, event)` |
| 244 | + |
| 245 | +这是一个添加到实例的原型方法。可以用它根据实例内部元素的 DOM 事件创建 observable。与`Rx.Observable.fromEvent` 类似，甚至在 DOM 渲染前，在`subscriptions` 函数中使用都是有用的。 |
| 246 | + |
| 247 | +`selector` 用来查找组件根元素的后代节点，如果你想监听根元素，传入`null` 作为第一个参数。 |
| 248 | + |
| 249 | +```js |
| 250 | +import {pluck }from'rxjs/operators'; |
| 251 | + |
| 252 | +constvm=newVue({ |
| 253 | +subscriptions() { |
| 254 | +return { |
| 255 | + inputValue:this.$fromDOMEvent('input','keyup').pipe( |
| 256 | +pluck('target','value') |
| 257 | + ) |
| 258 | + }; |
| 259 | + } |
| 260 | +}); |
| 261 | +``` |
| 262 | + |
| 263 | +####`$createObservableMethod(methodName)` |
| 264 | + |
| 265 | +转化函数调用为输出调用参数的 observable 队列。 |
| 266 | + |
| 267 | +这是一个添加到实例的原型方法。用来根据函数名创建一个共享的，热的 observable。这个函数会被赋值到 vm 方法上去。 |
| 268 | + |
| 269 | +```html |
| 270 | +<custom-form:onSubmit="submitHandler"></custom-form> |
| 271 | +``` |
| 272 | + |
| 273 | +```js |
| 274 | +constvm=newVue({ |
| 275 | +subscriptions() { |
| 276 | +return { |
| 277 | +// 需要 `share` 操作符 |
| 278 | + formData:this.$createObservableMethod('submitHandler') |
| 279 | + }; |
| 280 | + } |
| 281 | +}); |
| 282 | +``` |
| 283 | + |
| 284 | +你可以使用`observableMethods` 选项使代码更加声明式： |
| 285 | + |
| 286 | +```js |
| 287 | +newVue({ |
| 288 | + observableMethods: { |
| 289 | + submitHandler:'submitHandler$' |
| 290 | +// 或者使用数组简写: ['submitHandler'] |
| 291 | + } |
| 292 | +}); |
| 293 | +``` |
| 294 | + |
| 295 | +上面代码会自动在实例上创建两个东西： |
| 296 | + |
| 297 | +1. 一个是可以用`v-on` 绑定到模板的`submitHandler` 方法； |
| 298 | +2. 一个是可以流式调用`submitHandler` 的`submitHandler$` observable。 |
| 299 | + |
| 300 | +[例子](https://github.com/vuejs/vue-rx/blob/master/example/counter-function.html) |
| 301 | + |
| 302 | +###注意事项 |
| 303 | + |
| 304 | +你不能使用`watch` 选项去侦听订阅 (subscriptions)，因为它在设置订阅之前就被处理完毕了。但是你可以在`created` 钩子中使用`$watch` 作为替代方案。 |
| 305 | + |
| 306 | +###示例 |
| 307 | + |
| 308 | +到`/examples` 目录查看一些简单示例。 |
| 309 | + |
| 310 | +###License |
| 311 | + |
| 312 | +[MIT](http://opensource.org/licenses/MIT) |