Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ngVue/ngVue
Use Vue2 components in Angular 1.x
https://github.com/ngVue/ngVue
angular integration ngvue vue-components vuejs
Last synced: 13 days ago
JSON representation
Use Vue2 components in Angular 1.x
- Host: GitHub
- URL: https://github.com/ngVue/ngVue
- Owner: ngVue
- License: mit
- Created: 2016-08-13T13:33:28.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-03-28T02:49:08.000Z (8 months ago)
- Last Synced: 2024-10-18T23:23:00.998Z (22 days ago)
- Topics: angular, integration, ngvue, vue-components, vuejs
- Language: JavaScript
- Homepage:
- Size: 1.06 MB
- Stars: 302
- Watchers: 9
- Forks: 67
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome - ngVue - Use Vue2 components in Angular 1.x (JavaScript)
README
# ngVue
:warning: For Vue 3 support use ngVue3 :warning:
[](https://travis-ci.org/ngVue/ngVue) [](http://standardjs.com/) [](https://badge.fury.io/js/ngVue) [](https://img.shields.io/npm/dm/ngVue.svg) [](https://github.com/prettier/prettier)
[**VueJS**](https://vuejs.org/) is a library to build web interfaces with composable view components and reactive data binding. **ngVue**, inspired by [ngReact](https://github.com/ngReact/ngReact), is an Angular module that allows you to develop/use Vue components in AngularJS applications. ngVue can be used in the existing Angular applications and helps migrate the view parts of the application from Angular 1.x to Vue 2.
The motivation for this is similar to ngReact's:
- The AngularJS application suffers from a performance bottleneck due to a huge amount of scope watchers on the page, but VueJS offers an amazing reactive data-binding mechanism and other optimizations
- Instead of two-way data flow between controllers and views, VueJS defaults to a one-way, parent-to-child data flow between components which makes the application more predictable
- VueJS offers a much easier way to compose the web interfaces, and you can take advantage of the functional reactive programming in VueJS 2. Angular directives introduce a high learning barrier, such as the compile and link function, and the directives are prone to get confused with the components
- The VueJS community offers a component or a UI framework that you would like to try out
- Too deep into an AngularJS application to move it away from the code but you would like to experiment with VueJS
## Table of Contents
- [ngVue](#ngvue)
- [Table of Contents](#table-of-contents)
- [Install](#install)
- [Usage](#usage)
- [Features](#features)
- [The vue-component directive](#the-vue-component-directive)
- [Handling events](#handling-events)
- [Handling HTML attributes](#handling-html-attributes)
- [The createVueComponent factory](#the-createvuecomponent-factory)
- [Composition API](#composition-api)
- [Caveats](#caveats)
- [Plugins](#plugins)
- [TODO](#todo)
## Install
via npm:
```
npm install ngVue
```
## Usage
**ngVue** is a UMD module (known as Universal Module Definition), so it's CommonJS and AMD compatible, as well as supporting browser global variable definition.
First of all, remember to load AngularJS 1.x, VueJS and ngVue:
```html
// load on the page with the `script` tag
```
or ...
```javascript
// the CommonJS style
const ng = require('angular')
const vue = require('vue')
require('ngVue')
// the AMD style
require(['angular', 'vue', 'ngVue'], function(ng, Vue) {
})
// the ECMAScript module style
import angular from 'angular'
import vue from 'vue'
import 'ngVue'
```
and then require `ngVue` as a dependency for the Angular app:
```javascript
angular.module('yourApp', ['ngVue'])
```
## Features
**ngVue** is composed of a directive `vue-component`, a factory `createVueComponent` and a directive helper `v-directives`. It also provides some plugins for enhancement.
- `vue-component` is a directive that delegates data to a Vue component so VueJS can compile it with the corresponding nodes
- `createVueComponent` is a factory that converts a Vue component into a `vue-component` directive
**ngVue** does support VueJS directives but currently they only work with a Vue component in AngularJS templates.
- `v-directives` is a directive to apply the vue directives to the vue components
```html
```
### The vue-component directive
The `vue-component` directive wraps the vue component into an angular directive so that the vue component can be created and initialized while the angular is compiling the templates.
At first an **Angular controller** needs creating to declare the view data like this:
```javascript
const app = angular.module('vue.components', ['ngVue'])
.controller('MainController', function () {
this.person = {
firstName: 'The',
lastName: 'World'
}
})
```
Then declare **a Vue component** like this:
```javascript
const VComponent = Vue.component('hello-component', {
props: {
firstName: String,
lastName: String
},
render (h) {
return (
Hi, { this.firstName } { this.lastName }
)
}
})
```
In the end, **register the Vue component** to the Angular module with `value` method like this:
```javascript
app.value('HelloComponent', VComponent);
```
Now you can use `hello-component` in Angular templates:
```html
```
The `vue-component` directive provides three main attributes:
- `name` attribute checks for Angular injectable of that name
- `v-props` attribute is a string expression evaluated to an object as the data exposed to Vue component
- `v-props-*` attribute allows you to name the partial data extracted from the angular scope. `vue-component` wraps them into a new object and pass it to the Vue component. For example `props-first-name` and `props-last-name` will create two properties `firstName` and `lastName` in a new object as the component data
```html
```
- `watch-depth` attribute indicates which watch strategy AngularJS will use to detect the changes on the scope objects. The possible values as follows:
| value | description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| reference | *(default)* watches the object reference |
| collection | *(rarely used)* same as angular `$watchCollection`, shallow watches the properties of the object: for arrays, it watches the array items; for object maps, it watches the properties |
| value | *(rarely used)* deep watches every property inside the object |
**NOTES**
- `watch-depth` cannot propagate all the changes on the scope objects to VueJS due to the limitation of the reactivity system, but you can read about several solutions in [Caveats](docs/caveats.md#limitations--solutions).
- The `collection` strategy and the `value` strategy are rarely used. The scope object will be converted into a reactive object by VueJS and so any changes on the reactive scope object will trigger the view updates.
- The `value` strategy is **not recommended** because it causes a heavy computation. To detect the change, Angular copies the entire object and traverses every property insides in each digest cycle.
#### Handling events
Events can be handled from Vue to AngularJS components by binding functions references as `v-on-*`:
```javascript
app.controller('MainController', function ($scope) {
this.handleHelloEvent = function (greetings) {
console.log(greetings); // "Hello, World!"
}
})
```
```html
```
```javascript
const VComponent = Vue.component('hello-component', {
methods: {
helloFromVue() {
this.$emit('hello-world', 'Hello, World!');
}
},
render (h) {
return (
)
}
})
```
Events name in `$emit` function should be using kebab-case syntax.
### Handling HTML attributes
Just like regular Vue components, you can pass HTML attributes from the parent Angular component to your Vue component.
The parent's `class` and `style` attributes will be merged with the corresponding Vue component attributes, while others will be passed down unless they conflict with attributes in the Vue component's own template.
Keep in mind that when you pass down literal strings for anything other than `class` and `style` attributes, they must be surrounded by quotes, e.g. `data-value="'enabled'"`.
```javascript
angular.module("app")
.directive("myCustomButton", createVueComponent => {
return createVueComponent(Vue.component("MyCustomButton", MyCustomButton))
})
```
```html
```
```vue
{{ buttonText }}
export default {
name: "my-custom-button",
props: ["buttonText"],
}
```
Note that using `inheritAttrs: false` and binding `$attrs` to another element is also supported:
```vue
{{ buttonText }}
Other elements
export default {
inheritAttrs: false,
name: "my-custom-button",
props: ["buttonText"],
}
```
### The createVueComponent factory
The `createVueComponent` factory creates a reusable Angular directive which is bound to a specific Vue component.
For example, with the `vue-component` directive as mentioned above, you have to register each Vue component with a string name and then write `` repeatedly. With this `createVueComponent` factory, however, you can create `` directives and simply apply the exported Vue components to them.
The factory returns a plain `$compile` options object which describes how to compile the Angular directive with VueJS, and it takes the Vue component as the first argument:
```javascript
app.directive('helloComponent', function (createVueComponent) {
return createVueComponent(VComponent)
})
```
Alternatively, the name of the Vue component registered by `angular.value` can also be provided to the factory:
```javascript
app.directive('helloComponent', function (createVueComponent) {
return createVueComponent('HelloComponent')
})
```
### Composition API
The [Vue 2 Composition API](https://github.com/vuejs/composition-api) plugin is supported with the usual [limitations](https://github.com/vuejs/composition-api#limitations), additionally the component **MUST** include a `setup` function, there isn't a good way to detect it otherwise.
_Uses Composition API_
```js
export default Vue.component('my-component', {
setup() {},
render(h) {
return (
)
}
})
```
_Fall back to Options API_
```js
export default Vue.component('my-component', {
render() {
return (
);
}
});
```
You don't necessarily need to use `Vue.component` when defining Composition API components but without a `setup` method ngVue will not be able to link it.
_This works_
```js
export default {
setup() {},
render(h) {
return (
)
}
}
```
_This will break_
```js
export default {
render(h) {
return (
)
}
}
```
## Caveats
ngVue brings the reactivity system to the dirty checking mechanism and you should therefore understand how they work together and how to avoid some common gotchas. Please read more in the [Caveats](docs/caveats.md).
## Plugins
ngVue is simple but flexible for enhancement. Please read more in the [Plugins](docs/plugins.md).
## TODO
- [x] vue components
- [x] vue directives
- [x] unit tests
- [x] docs + simple examples
- [x] ng filters in VueJS
- [x] supports vuex
- [ ] performance optimization