Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@KaygNas
KaygNas committed Sep 14, 2022
1 parent 3b3a9d2 commit f5088c2
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 361 deletions.
379 changes: 36 additions & 343 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,360 +1,53 @@
# Vue Property Decorator

[![npm](https://img.shields.io/npm/v/vue-property-decorator.svg)](https://www.npmjs.com/package/vue-property-decorator)
[![Build Status](https://travis-ci.org/kaorun343/vue-property-decorator.svg?branch=master)](https://travis-ci.org/kaorun343/vue-property-decorator)
This library fully depends on [vue-class-component](https://github.com/vuejs/vue-class-component), so please read its README before using this library.

This library fully depends on [vue-class-component](https://github.com/vuejs/vue-class-component), so please read its README **BEFORE** using this library.
This repository is fork from [kaorun343/vue-property-decorator](https://github.com/kaorun343/vue-property-decorator).

## License

MIT License

## Install

```bash
npm i -S vue-property-decorator vue-class-component vue
```

## Usage

There are several decorators:

- [`@Prop`](#Prop)
- [`@Model`](#Model)
- [`@Watch`](#Watch)
- [`@Provide`](#Provide)
- [`@Inject`](#Inject)
- [`@Emit`](#Emit)
- [`@Ref`](#Ref)

Also, these are re-exported from `vue-class-component`

- `@Options`
- `mixins`
- `Vue`

### <a id="Prop"></a> `@Prop` decorator

#### Description

Each prop's default value need to be defined as same as the example code shown in above.
It's **not** supported to define each `default` property like `@Prop() prop = 'default value'` .

#### Example

```ts
import { Vue, Prop } from 'vue-property-decorator'

export default class YourComponent extends Vue {
@Prop(Number) readonly propA: number | undefined
@Prop({ default: 'default value' }) readonly propB!: string
@Prop([String, Boolean]) readonly propC: string | boolean | undefined
}
```

is equivalent to
## Dependencies

```js
export default {
props: {
propA: Number,
propB: {
default: 'default value',
},
propC: {
type: [String, Boolean],
},
},
}
```

### <a id="Model"></a> `@Model` decorator

#### Description

The first argument is the prop's name that the component accepts from its parent component. If you set the name as `modelValue`, then the component can use `v-model` .

The second argument is the same with `@Prop` decorator's argument.

#### Example

```ts
import { Vue, Model } from 'vue-property-decorator'

export default class YourComponent extends Vue {
@Model('modelValue', { type: String, default: 'Default Value' })
readonly value!: string
}
```

is equivalent to
- [Vue](https://github.com/vuejs/vue)
- [vue-class-component](https://github.com/vuejs/vue-class-component)

```js
export default {
props: {
modelValue: {
type: String,
default: 'Default Value',
},
},
emits: ['update:modelValue'],
computed: {
value: {
get() {
return this.modelValue
},
set(newValue) {
this.$emit('update:modelValue')
},
},
},
}
```

### <a id="Watch"></a> `@Watch` decorator

#### Example

```ts
import { Vue, Watch } from 'vue-property-decorator'

export default class YourComponent extends Vue {
@Watch('child')
onChildChanged(val: string, oldVal: string) {}
## Backward Compatible
Since `vue-property-decorator@8.0.0-rc.1` has multiple breaking change, in order to make migration from vue2 to vue3, some of API in `^7.0.0` are implemented with a prefix **Legacy**, it would make migration easier.

@Watch('person', { immediate: true, deep: true })
onPersonChanged1(val: Person, oldVal: Person) {}

@Watch('person')
onPersonChanged2(val: Person, oldVal: Person) {}
}
```

is equivalent to

```js
export default {
watch: {
child: [
{
handler: 'onChildChanged',
},
],
person: [
{
handler: 'onPersonChanged1',
immediate: true,
deep: true,
},
{
handler: 'onPersonChanged2',
},
],
},
methods: {
onChildChanged(val, oldVal) {},
onPersonChanged1(val, oldVal) {},
onPersonChanged2(val, oldVal) {},
},
}
```
Here's the list:
(Those with ✅ behind mean they work the same as the previous version.)

### <a id="Provide"></a> `@Provide` decorator
- @Prop ✅
- @PropSync
- @Model -> @LegacyModel ✅
- @ModelSync
- @Watch ✅
- @Provide
- @Inject
- @ProvideReactive -> @LegacyProvideReactive ✅
- @InjectReactive -> @LegacyInjectReactive ✅
- @Emit ✅
- @Ref ✅
- @VModel
- @Component ✅
- Mixins ✅

#### Description
## Attention

If you set `reactive` to true, the provided value is wrapped with `computed` function.
Provided values with `reactive` option dispatches their new values to child components.
- This forking is trying to help project using vue2 migrate to vue3.
- Since the next version of `vue-class-component` stayed rc for over two years, it's recommended not to depend on `vue-property-decorator` for further coding.
- This forking might not be maintain for anymore.

#### Example
## Installation

```ts
import { Vue, Provide } from 'vue-property-decorator'

const symbolKey = Symbol()

export class MyComponent extends Vue {
@Provide() foo = 'foo'
@Provide({ to: 'bar' }) baz = 'bar'
@Provide({ to: symbolKey }) nice = 'nice'
@Provide({ reactive: true }) age = 30
}
```

is equivalent to

```js
import { computed } from 'vue'

const symbolKey = Symbol()

export default {
data() {
return {
foo: 'foo',
baz: 'bar',
nice: 'nice',
age: 30,
}
},
provide() {
return {
foo: this.key,
bar: this.baz,
[symbolKey]: this.nice,
age: computed(() => this.age),
}
},
}
```

#### <a id="Inject"></a> `@Inject` decorator

#### Example

```ts
import { Vue, Inject } from 'vue-property-decorator'

export class MyComponent extends Vue {
@Inject() foo!: string
@Inject({ from: 'bar' }) baz!: string
@Inject({ default: '' }) nice!: string
}
```

is equivalent to

```js
export default {
inject: {
foo: 'foo',
baz: {
from: 'bar',
},
nice: {
default: '',
},
},
}
```

### <a id="Emit"></a> `@Emit` decorator

#### Description

The functions decorated by `@Emit` `$emit` their return value followed by their original arguments. If the return value is a promise, it is resolved before being emitted.

If the name of the event is not supplied via the `event` argument, the function name is used instead. In that case, the camelCase name will be converted to kebab-case.

#### Example

```ts
import { Vue, Emit } from 'vue-property-decorator'

export default class YourComponent extends Vue {
count = 0

@Emit()
addToCount(n: number) {
this.count += n
}

@Emit('reset')
resetCount() {
this.count = 0
}

@Emit()
returnValue() {
return 10
}

@Emit()
onInputChange(e) {
return e.target.value
}

@Emit()
promise() {
return new Promise((resolve) => {
setTimeout(() => {
resolve(20)
}, 0)
})
}
}
```

is equivalent to

```js
export default {
data() {
return {
count: 0,
}
},
methods: {
addToCount(n) {
this.count += n
this.$emit('add-to-count', n)
},
resetCount() {
this.count = 0
this.$emit('reset')
},
returnValue() {
this.$emit('return-value', 10)
},
onInputChange(e) {
this.$emit('on-input-change', e.target.value, e)
},
promise() {
const promise = new Promise((resolve) => {
setTimeout(() => {
resolve(20)
}, 0)
})

promise.then((value) => {
this.$emit('promise', value)
})
},
},
}
```bash
$ npm install --save kaygnas-vue-property-decorator
# or
$ yarn add kaygnas-vue-property-decorator
```

### <a id="Ref"></a> `@Ref` decorator

#### Example

```ts
import { Vue, Ref } from 'vue-property-decorator'
import AnotherComponent from '@/path/to/another-component.vue'
## Usage

export default class YourComponent extends Vue {
@Ref() readonly anotherComponent!: AnotherComponent
@Ref('aButton') readonly button!: HTMLButtonElement
}
```
for usage, please check [kaorun343/vue-property-decorator](https://github.com/kaorun343/vue-property-decorator)

is equivalent to
## License

```js
export default {
computed() {
anotherComponent: {
cache: false,
get() {
return this.$refs.anotherComponent as AnotherComponent
}
},
button: {
cache: false,
get() {
return this.$refs.aButton as HTMLButtonElement
}
}
}
}
```
MIT
Loading

0 comments on commit f5088c2

Please # to comment.