自定義指令 · vue

--- title: 自定義指令 type: guide order: 14 --- ## 基礎除了內置指令，Vue.js 也允許注冊自定義指令。自定義指令提供一種機制將數據的變化映射為 DOM 行為。可以用 `Vue.directive(id, definition)` 方法注冊一個全局自定義指令，它接收兩個參數**指令 ID** 與**定義對象**。也可以用組件的 `directives` 選項注冊一個局部自定義指令。 ### 鉤子函數定義對象可以提供幾個鉤子函數（都是可選的）： - **bind**：只調用一次，在指令第一次綁定到元素上時調用。 - **update**：在 `bind` 之后立即以初始值為參數第一次調用，之后每當綁定值變化時調用，參數為新值與舊值。 - **unbind**：只調用一次，在指令從元素上解綁時調用。 **示例** ``` js Vue.directive('my-directive', { bind: function () { // 準備工作 // 例如，添加事件處理器或只需要運行一次的高耗任務 }, update: function (newValue, oldValue) { // 值更新時的工作 // 也會以初始值為參數調用一次 }, unbind: function () { // 清理工作 // 例如，刪除 bind() 添加的事件監聽器 } }) ``` 在注冊之后，便可以在 Vue.js 模板中這樣用（記著添加前綴 `v-`）： ``` html <div v-my-directive="someValue"></div> ``` 當只需要 `update` 函數時，可以傳入一個函數替代定義對象： ``` js Vue.directive('my-directive', function (value) { // 這個函數用作 update() }) ``` ### 指令實例屬性所有的鉤子函數將被復制到實際的**指令對象**中，鉤子內 `this` 指向這個指令對象。這個對象暴露了一些有用的屬性： - **el**: 指令綁定的元素。 - **vm**: 擁有該指令的上下文 ViewModel。 - **expression**: 指令的表達式，不包括參數和過濾器。 - **arg**: 指令的參數。 - **name**: 指令的名字，不包含前綴。 - **modifiers**: 一個對象，包含指令的修飾符。 - **descriptor**: 一個對象，包含指令的解析結果。 <p class="tip">你應當將這些屬性視為只讀的，不要修改它們。你也可以給指令對象添加自定義屬性，但是注意不要覆蓋已有的內部屬性。</p> 示例： ``` html <div id="demo" v-demo:hello.a.b="msg"></div> ``` ``` js Vue.directive('demo', { bind: function () { console.log('demo bound!') }, update: function (value) { this.el.innerHTML = 'name - ' + this.name + '<br>' + 'expression - ' + this.expression + '<br>' + 'argument - ' + this.arg + '<br>' + 'modifiers - ' + JSON.stringify(this.modifiers) + '<br>' + 'value - ' + value } }) var demo = new Vue({ el: '#demo', data: { msg: 'hello!' } }) ``` **結果** <div id="demo" v-demo:hello.a.b="msg"></div> <script> Vue.directive('demo', { bind: function () { console.log('demo bound!') }, update: function (value) { this.el.innerHTML = 'name - ' + this.name + '<br>' + 'expression - ' + this.expression + '<br>' + 'argument - ' + this.arg + '<br>' + 'modifiers - ' + JSON.stringify(this.modifiers) + '<br>' + 'value - ' + value } }) var demo = new Vue({ el: '#demo', data: { msg: 'hello!' } }) </script> ### 對象字面量如果指令需要多個值，可以傳入一個 JavaScript 對象字面量。記住，指令可以使用任意合法的 JavaScript 表達式： ``` html <div v-demo="{ color: 'white', text: 'hello!' }"></div> ``` ``` js Vue.directive('demo', function (value) { console.log(value.color) // "white" console.log(value.text) // "hello!" }) ``` ### 字面修飾符當指令使用了字面修飾符，它的值將按普通字符串處理并傳遞給 `update` 方法。`update` 方法將只調用一次，因為普通字符串不能響應數據變化。 ``` html <div v-demo.literal="foo bar baz"> ``` ``` js Vue.directive('demo', function (value) { console.log(value) // "foo bar baz" }) ``` ### 元素指令有時我們想以自定義元素的形式使用指令，而不是以特性的形式。這與 Angular 的 “E” 指令非常相似。元素指令可以看做是一個輕量組件。可以像下面這樣注冊一個自定義元素指令： ``` js Vue.elementDirective('my-directive', { // API 同普通指令 bind: function () { // 操作 this.el... } }) ``` 不這樣寫： ``` html <div v-my-directive></div> ``` 這樣寫： ``` html <my-directive></my-directive> ``` 元素指令不能接受參數或表達式，但是它可以讀取元素的特性從而決定它的行為。迥異于普通指令，元素指令是**終結性**的，這意味著，一旦 Vue 遇到一個元素指令，它將跳過該元素及其子元素——只有該元素指令本身可以操作該元素及其子元素。 ## 高級選項 ### params 自定義指令可以接收一個 `params` 數組，指定一個特性列表，Vue 編譯器將自動提取綁定元素的這些特性。例如： ``` html <div v-example a="hi"></div> ``` ``` js Vue.directive('example', { params: ['a'], bind: function () { console.log(this.params.a) // -> "hi" } }) ``` 此 API 也支持動態屬性。`this.params[key]` 會自動保持更新。另外，可以指定一個回調，在值變化時調用： ``` html <div v-example v-bind:a="someValue"></div> ``` ``` js Vue.directive('example', { params: ['a'], paramWatchers: { a: function (val, oldVal) { console.log('a changed!') } } }) ``` ### deep 如果自定義指令用在一個對象上，當對象內部屬性變化時要觸發 `update`，則在指令定義對象中指定 `deep: true`。 ``` html <div v-my-directive="obj"></div> ``` ``` js Vue.directive('my-directive', { deep: true, update: function (obj) { // 在 `obj` 的嵌套屬性變化時調用 } }) ``` ### twoWay 如果指令想向 Vue 實例寫回數據，則在指令定義對象中指定 `twoWay: true` 。該選項允許在指令中使用 `this.set(value)`: ``` js Vue.directive('example', { twoWay: true, bind: function () { this.handler = function () { // 將數據寫回 vm // 如果指令這樣綁定 v-example="a.b.c" // 它將用給定值設置 `vm.a.b.c` this.set(this.el.value) }.bind(this) this.el.addEventListener('input', this.handler) }, unbind: function () { this.el.removeEventListener('input', this.handler) } }) ``` ### acceptStatement 傳入 `acceptStatement:true` 可以讓自定義指令接受內聯語句，就像 `v-on` 那樣： ``` html <div v-my-directive="a++"></div> ``` ``` js Vue.directive('my-directive', { acceptStatement: true, update: function (fn) { // 傳入值是一個函數 // 在調用它時將在所屬實例作用域內計算 "a++" 語句 } }) ``` 明智地使用，因為通常你要在模板中避免副效應。 ### priority 可以給指令指定一個優先級（默認是 1000）。同一個元素上優先級高的指令會比其它指令處理得早一些。優先級一樣的指令按照它在元素特性列表中出現的順序依次處理，但是不能保證這個順序在不同的瀏覽器中是一致的。可以在 [API](/api/#指令) 中查看內置指令的優先級。另外，流程控制指令 `v-if` 和 `v-for` 在編譯過程中始終擁有最高的優先級。