Repository files navigation

English |简体中文

RxJS v6+ integration for Vue.js.

BREAKING CHANGES from 5.0

• vue-rx v6 now only works with RxJS v6+ by default. If you want to keep using RxJS v5 style code, installrxjs-compat.

rxjs is required as a peer dependency.

npm install vue vue-rx rxjs --save

importVuefrom'vue'importVueRxfrom'vue-rx'Vue.use(VueRx)

When bundling via webpack,dist/vue-rx.esm.js is used by default. It imports the minimal amount of Rx operators and ensures small bundle sizes.

To use in a browser environment, use the UMD builddist/vue-rx.js. When in a browser environment, the UMD build assumeswindow.rxjs to be already present, so make sure to includevue-rx.js after Vue.js and RxJS. It also installs itself automatically ifwindow.Vue is present.

Example:

<scriptsrc="https://unpkg.com/rxjs/bundles/rxjs.umd.js"></script><scriptsrc="https://unpkg.com/vue/dist/vue.js"></script><scriptsrc="../dist/vue-rx.js"></script>

// provide Rx observables with the `subscriptions` optionnewVue({el:'#app',subscriptions:{msg:messageObservable}})

<!-- bind to it normally in templates --><div>{{ msg }}</div>

Thesubscriptions options can also take a function so that you can return unique observables for each component instance:

import{Observable}from'rxjs'Vue.component('foo',{subscriptions:function(){return{msg:newObservable(...)}}})

The observables are exposed asvm.$observables:

constvm=newVue({subscriptions:{msg:messageObservable}})vm.$observables.msg.subscribe(msg=>console.log(msg))

vue-rx provides thev-stream directive which allows you to stream DOM events to an Rx Subject. The syntax is similar tov-on where the directive argument is the event name, and the binding value is the target Rx Subject.

<buttonv-stream:click="plus$">+</button>

Note that you need to declareplus$ as an instance ofrxjs.Subject on the vm instance before the render happens, just like you need to declare data. You can do that right in thesubscriptions function:

import{Subject}from'rxjs'import{map,startWith,scan}from'rxjs/operators'newVue({subscriptions(){// declare the receiving Subjectsthis.plus$=newSubject()// ...then create subscriptions using the Subjects as source stream.// the source stream emits in the format of `{ event: HTMLEvent, data?: any }`return{count:this.plus$.pipe(map(()=>1),startWith(0),scan((total,change)=>total+change))}}})

Or, use thedomStreams convenience option:

newVue({// requires `Rx` passed to Vue.use() to expose `Subject`domStreams:['plus$'],subscriptions(){// use this.plus$}})

Finally, you can pass additional data to the stream using the alternative syntax:

<buttonv-stream:click="{ subject: plus$, data: someData }">+</button>

This is useful when you need to pass along temporary variables likev-for iterators. You can get the data by simply plucking it from the source stream:

constplusData$=this.plus$.pipe(pluck('data'))

Starting in 3.1 you can also pass along extra options (passed along to nativeaddEventListener as the 3rd argument):

<buttonv-stream:click="{  subject: plus$,  data: someData,  options: { once: true, passive: true, capture: true }}">+</button>

Seeexample for actual usage.

Similar to streamingDOM events,v-stream can be used on components as well and will create observables from custom events emitted by the child component. It works similar tov-on:

<div><!-- Custom component --><paginationv-on:change="pageChanged()"></pagination><!-- v-stream with custom component --><paginationv-stream:change="pageChange$"></pagination></div>

This is a prototype method added to instances. You can use it to create an observable from a value watcher. The emitted value is in the format of{ newValue, oldValue }:

import{pluck,map}from'rxjs/operators'constvm=newVue({data:{a:1},subscriptions(){// declaratively map to another property with Rx operatorsreturn{aPlusOne:this.$watchAsObservable('a').pipe(pluck('newValue'),map(a=>a+1))}}})// or produce side effects...vm.$watchAsObservable('a').subscribe(({ newValue, oldValue})=>console.log('stream value',newValue,oldValue),err=>console.error(err),()=>console.log('complete'))

The optionaloptions object accepts the same options asvm.$watch.

Convert vue.$on (including lifecycle events) to Observables. The emitted value is in the format of{ name, msg }:

import{interval}from'rxjs'import{take,takeUntil}from'rxjs/operators'constvm=newVue({created(){this.$eventToObservable('customEvent').subscribe((event)=>console.log(event.name,event.msg))}})// vm.$once vue-rx versionthis.$eventToObservable('customEvent').pipe(take(1))// Another way to auto unsub:letbeforeDestroy$=this.$eventToObservable('hook:beforeDestroy').pipe(take(1))interval(500).pipe(takeUntil(beforeDestroy$))

This is a prototype method added to instances. You can use it to subscribe to an observable, but let VueRx manage the dispose/unsubscribe.

import{interval}from'rxjs'constvm=newVue({mounted(){this.$subscribeTo(interval(1000),function(count){console.log(count)})}})

This is a prototype method added to instances. Use it to create an observable from DOM events within the instances' element. This is similar toRx.Observable.fromEvent, but usable inside thesubscriptions function even before the DOM is actually rendered.

selector is for finding descendant nodes under the component root element, if you want to listen to events from root element itself, passnull as first argument.

import{pluck}from'rxjs/operators'constvm=newVue({subscriptions(){return{inputValue:this.$fromDOMEvent('input','keyup').pipe(pluck('target','value'))}}})

Convert function calls to observable sequence which emits the call arguments.

This is a prototype method added to instances. Use it to create a shared hot observable from a function name. The function will be assigned as a vm method.

<custom-form:onSubmit="submitHandler"></custom-form>

constvm=newVue({subscriptions(){return{// requires `share` operatorformData:this.$createObservableMethod('submitHandler')}}})

You can use theobservableMethods option to make it more declarative:

newVue({observableMethods:{submitHandler:'submitHandler$'// or with Array shothand: ['submitHandler']}})

The above will automatically create two things on the instance:

1. AsubmitHandler method which can be bound to in template withv-on;
2. AsubmitHandler$ observable which will be the stream emitting calls tosubmitHandler.

example

You cannot use thewatch option to watch subscriptions, because it is processed before the subscriptions are set up. But you can use$watch in thecreated hook instead.

See/examples for some simple examples.

MIT