{% raw %} # API ## 全局配置 `Vue.config` 是一個對象，包含 Vue 的全局配置。可以在啟動應用之前修改下面屬性： ### debug * **類型：** `Boolean` * **默認值：** `false` * **用法：** ``` Vue.config.debug = true ``` 在調試模式中，Vue 會： 1. 為所有的警告打印棧追蹤。 2. 把所有的錨節點以注釋節點顯示在 DOM 中，更易于檢查渲染結果的結構。 只有開發版本可以使用調試模式。 ### delimiters * **類型：** `Array<String>` * **默認值：** `["{{", "}}"]` * **用法：** ``` // ES6 模板字符串 Vue.config.delimiters = ['${', '}'] ``` 修改文本插值的定界符。 ### unsafeDelimiters * **類型：** `Array<String>` * **默認值：** `["{{{", "}}}"]` * **用法：** ``` // make it look more dangerous Vue.config.unsafeDelimiters = ['{!!', '!!}'] ``` 修改原生 HTML 插值的定界符。 ### silent * **類型：** `Boolean` * **默認值：** `false` * **用法：** ``` Vue.config.silent = true ``` 取消 Vue.js 所有的日志與警告。 ### async * **類型：** `Boolean` * **默認值：** `true` * **用法：** ``` Vue.config.async = false ``` 如果關閉了異步模式，Vue 在檢測到數據變化時同步更新 DOM。在有些情況下這有助于調試，但是也可能導致性能下降，并且影響 watcher 回調的調用順序。**`async: false`不推薦用在生產環境中。** ### convertAllProperties * **類型：** `Boolean` * **默認值：** `false` * **用法：** ``` Vue.config.convertAllProperties = true ``` 1.0.8 添加。開啟這個選項后，Vue 可以轉換和觀察由 `Object.defineProperty` 定義的 getters/setter。默認關閉，因為會付出一些性能代價，并且不是常用功能。 ## 全局 API ### Vue.extend( options ) * **參數：** * `{Object} options` * **用法：** 創建基礎 Vue 構造器的“子類”。參數是一個對象，包含組件選項。 這里要注意的特例是 `el` 和 `data` 選項—— 在 `Vue.extend()` 中它們必須是函數。 ``` <div id="mount-point"></div> ``` ``` // 創建可復用的構造器 var Profile = Vue.extend({ template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>' }) // 創建一個 Profile 實例 var profile = new Profile({ data: { firstName: 'Walter', lastName: 'White', alias: 'Heisenberg' } }) // 掛載到元素上 profile.$mount('#mount-point') ``` 結果： ``` <p>Walter White aka Heisenberg</p> ``` * **另見：** [組件](/guide/components.html) ### Vue.nextTick( callback ) * **參數：** * `{Functon} callback` * **用法：** 延遲回調在下次 DOM 更新循環之后執行。在修改數據之后立即使用這個方法，等待 DOM 更新。 ``` // 修改數據 vm.msg = 'Hello' // DOM 沒有更新 Vue.nextTick(function () { // DOM 更新了 }) ``` * **另見：** [異步更新隊列](/guide/reactivity.html#異步更新隊列) ### Vue.set( object, key, value ) * **參數：** * `{Object} object` * `{String} key` * `{*} value` * **返回值：** 設置的值 * **用法：** 設置對象的屬性。如果對象是響應的，將觸發視圖更新。這個方法主要用于解決 不能檢測到屬性添加的限制。 * **另見：** [深入響應](/guide/reactivity.html) ### Vue.delete( object, key ) * **參數：** * `{Object} object` * `{String} key` * **用法：** 刪除對象的屬性。如果對象是響應的，將觸發視圖更新。這個方法主要用于解決 不能檢測到屬性刪除的限制。 * **另見：** [深入響應](/guide/reactivity.html) ### Vue.directive( id, [definition] ) * **參數：** * `{String} id` * `{Function | Object} [definition]` * **用法：** 注冊或獲取全局指令。 ``` // 注冊 Vue.directive('my-directive', { bind: function () {}, update: function () {}, unbind: function () {} }) // 注冊，傳入一個函數 Vue.directive('my-directive', function () { // this will be called as `update` }) // getter，返回已注冊的指令 var myDirective = Vue.directive('my-directive') ``` * **另見：** [自定義指令](/guide/custom-directive.html) ### Vue.elementDirective( id, [definition] ) * **參數：** * `{String} id` * `{Object} [definition]` * **用法：** 注冊或獲取全局的元素指令。 ``` // 注冊 Vue.elementDirective('my-element', { bind: function () {}, // 沒有使用 `update` unbind: function () {} }) // getter，返回已注冊的元素指令 var myDirective = Vue.elementDirective('my-element') ``` * **另見：** [元素指令](/guide/custom-directive.html#元素指令) ### Vue.filter( id, [definition] ) * **參數：** * `{String} id` * `{Function | Object} [definition]` * **用法：** 注冊或獲取全局過濾器。 ``` // 注冊 Vue.filter('my-filter', function (value) { // 返回處理后的值 }) // 雙向過濾器 Vue.filter('my-filter', { read: function () {}, write: function () {} }) // getter，返回已注冊的指令 var myFilter = Vue.filter('my-filter') ``` * **另見：** [自定義過濾器](/guide/custom-filter.html) ### Vue.component( id, [definition] ) * **參數：** * `{String} id` * `{Function | Object} [definition]` * **用法：** 注冊或獲取全局組件。 ``` // 注冊，傳入一個擴展的構造器 Vue.component('my-component', Vue.extend({ /* ... */})) // 注冊，傳入一個選項對象（自動調用 Vue.extend） Vue.component('my-component', { /* ... */ }) // 獲取注冊的組件（始終返回構造器） var MyComponent = Vue.component('my-component') ``` * **另見：** [組件](/guide/components.html). ### Vue.transition( id, [hooks] ) * **參數：** * `{String} id` * `{Object} [hooks]` * **用法：** 注冊或獲取全局的過渡鉤子對象。 ``` // 注冊 Vue.transition('fade', { enter: function () {}, leave: function () {} }) // 獲取注冊的鉤子 var fadeTransition = Vue.transition('fade') ``` * **另見：** [過渡](/guide/transitions.html). ### Vue.partial( id, [partial] ) * **參數：** * `{String} id` * `{String} [partial]` * **用法：** 注冊或獲取全局的 partial。 ``` // 注冊 Vue.partial('my-partial', '<div>Hi</div>') // 獲取注冊的 partial var myPartial = Vue.partial('my-partial') ``` * **另見：** [特殊元素 - <partial>](#partial)。 ### Vue.use( plugin, [options] ) * **參數：** * `{Object | Function} plugin` * `{Object} [options]` * **用法：** 安裝 Vue.js 插件。如果插件是一個對象，必須有一個 `install` 方法。如果它是一個函數，它會被作為安裝方法。安裝方法以 Vue 為參數。 * **另見：** [插件](/guide/plugins.html). ### Vue.mixin( mixin ) * **參數：** * `{Object} mixin` * **用法：** 全局應用一個混合，將影響所有 Vue 實例。插件作者可以用它向組件注入自定義邏輯。**不推薦用在應用代碼中。** * **另見：** [全局混合](/guide/mixins.html#全局混合) ## 選項 / 數據 ### data * **類型：** `Object | Function` * **限制：** 在 `Vue.extend()` 中只能是函數。 * **詳細：** Vue 實例的數據對象。Vue.js 會遞歸地將它全部屬性轉為 getter/setter，從而讓它能響應數據變化。**這個對象必須是普通對象**：原生對象，getter/setter 及原型屬性會被忽略。不推薦觀察復雜對象。 在實例創建之后，可以用 `vm.$data` 訪問原始數據對象。Vue 實例也代理了數據對象所有的屬性。 名字以 `_` 或 `$`開始的屬性**不會**被 Vue 實例代理，因為它們可能與 Vue 的內置屬性與 API 方法沖突。用 `vm.$data._property` 訪問它們。 可以通過將 `vm.$data` 傳入 `JSON.parse(JSON.stringify(...))` 得到原始數據對象。 * **示例：** ``` var data = { a: 1 } // 直接創建一個實例 var vm = new Vue({ data: data }) vm.a // -> 1 vm.$data === data // -> true // 在 Vue.extend() 中必須是函數 var Component = Vue.extend({ data: function () { return { a: 1 } } }) ``` * **另見：** [深入響應](/guide/reactivity.html). ### props * **類型：** `Array | Object` * **詳細：** 包含一些特性——期望使用的父組件數據的屬性。可以是數組或對象。對象用于高級配置，如類型檢查，自定義驗證，默認值等。 * **示例：** ``` // 簡單語法 Vue.component('props-demo-simple', { props: ['size', 'myMessage'] }) // 對象語法，指定驗證要求 Vue.component('props-demo-advanced', { props: { // 只檢測類型 size: Number, // 檢測類型 + 其它驗證 name: { type: String, required: true } } }) ``` * **另見：** [Props](/guide/components.html#Props) ### computed * **類型：** `Object` * **詳細：** 實例計算屬性。getter 和 setter 的 `this` 自動地綁定到實例。 * **示例：** ``` var vm = new Vue({ data: { a: 1 }, computed: { // 僅讀取，值只須為函數 aDouble: function () { return this.a * 2 }, // 讀取和設置 aPlus: { get: function () { return this.a + 1 }, set: function (v) { this.a = v - 1 } } } }) vm.aPlus // -> 2 vm.aPlus = 3 vm.a // -> 2 vm.aDouble // -> 4 ``` * **另見：** * [計算屬性](/guide/computed.html) * [深入響應：計算屬性](/guide/reactivity.html#計算屬性) ### methods * **類型：** `Object` * **詳細：** 實例方法。實例可以直接訪問這些方法，也可以用在指令表達式內。方法的 `this` 自動綁定到實例。 * **示例：** ``` var vm = new Vue({ data: { a: 1 }, methods: { plus: function () { this.a++ } } }) vm.plus() vm.a // 2 ``` * **另見：** [方法與事件處理器](/guide/events.html) ### watch * **類型：** `Object` * **詳細：** 一個對象，鍵是觀察表達式，值是對應回調。值也可以是方法名，或者是對象，包含選項。在實例化時為每個鍵調用 `$watch()` 。 * **示例：** ``` var vm = new Vue({ data: { a: 1 }, watch: { 'a': function (val, oldVal) { console.log('new: %s, old: %s', val, oldVal) }, // 方法名 'b': 'someMethod', // 深度 watcher 'c': { handler: function (val, oldVal) { /* ... */ }, deep: true } } }) vm.a = 2 // -> new: 2, old: 1 ``` * **另見：** [實例方法 - vm.$watch](#vm-watch) ## 選項 / DOM ### el * **類型：** `String | HTMLElement | Function` * **限制：** `Vue.extend()` 內只能是函數 * **詳細：** 為實例提供掛載元素。值可以是 CSS 選擇符，或實際 HTML 元素，或返回 HTML 元素的函數。注意元素只用作掛載點。如果提供了模板則元素被替換，除非 `replace` 為 false。元素可以用 `vm.$el` 訪問。 用在 `Vue.extend` 中必須是函數值，這樣所有實例不會共享元素。 如果在初始化時指定了這個選項，實例將立即進入編譯過程。否則，需要調用 `vm.$mount()`，手動開始編譯。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### template * **類型：** `String` * **詳細：** 實例模板。模板默認**替換**掛載元素。如果 `replace` 選項為 `false`，模板將插入掛載元素內。兩種情況下，掛載元素的內容都將被忽略，除非模板有內容分發 slot。 如果值以 `#` 開始，則它用作選項符，將使用匹配元素的 innerHTML 作為模板。常用的技巧是用 `<script type="x-template">` 包含模板。 注意在一些情況下，例如如模板包含多個頂級元素，或只包含普通文本，實例將變成一個片斷實例，管理多個節點而不是一個節點。片斷實例的掛載元素上的非流程控制指令被忽略。 * **另見：** * [生命周期圖示](/guide/instance.html#生命周期圖示) * [使用 slot 分發內容](/guide/components.html#使用 slot 分發內容) * [片斷實例](/guide/components.html#片斷實例) ### replace * **類型：** `Boolean` * **默認值：** `true` * **限制：** 只能與 **template** 選項一起用 * **詳細：** 決定是否替換模板的掛載元素。如果設為 `false` 模板將覆蓋元素的內容，不會替換元素本身。 * **示例：** ``` <div id="replace"></div> ``` ``` new Vue({ el: '#replace', template: '<p>replaced</p>' }) ``` 結果： ``` <p>replaced</p> ``` `replace` 設為 `false`： ``` <div id="insert"></div> ``` ``` new Vue({ el: '#insert', replace: false, template: '<p>inserted</p>' }) ``` 結果： ``` <div id="insert"> <p>inserted</p> </div> ``` ## 選項 / 生命周期鉤子 ### created * **類型：** `Function` * **詳細：** 在實例創建之后同步調用。此時實例已經結束解析選項，這意味著已建立：數據綁定，計算屬性，方法，watcher/事件回調。但是還沒有開始 DOM 編譯，`$el` 還不存在。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### beforeCompile * **類型：** `Function` * **詳細：** 在編譯開始前調用。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### compiled * **類型：** `Function` * **詳細：** 在編譯結束后調用。此時所有的指令已生效，因而數據的變化將觸發 DOM 更新。但是不擔保 `$el` 已插入文檔。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### ready * **類型：** `Function` * **詳細：** 在編譯結束和 **`$el` 第一次插入文檔**之后調用，如在第一次 `attached` 鉤子之后調用。注意必須是由 Vue 插入（如 `vm.$appendTo()` 等方法或指令更新）才觸發 `ready` 鉤子。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### attached * **類型：** `Function` * **詳細：** 在 `vm.$el` 插入 DOM 時調用。必須是由指令或實例方法（如 `$appendTo()`）插入，直接操作 `vm.$el` **不會** 觸發這個鉤子。 ### detached * **類型：** `Function` * **詳細：** 在 `vm.$el` 從 DOM 中刪除時調用。必須是由指令或實例方法刪除，直接操作 `vm.$el` **不會** 觸發這個鉤子。 ### beforeDestroy * **類型：** `Function` * **詳細：** 在開始銷毀實例時調用。此時實例仍然有功能。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### destroyed * **類型：** `Function` * **詳細：** 在實例被銷毀之后調用。此時所有的綁定和實例的指令已經解綁，所有的子實例也已經被銷毀。 如果有離開過渡，`destroyed` 鉤子在過渡完成**之后**調用。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ## 選項 / 資源 ### directives * **類型：** `Object` * **詳細：** 一個對象，包含指令。 * **另見：** * [自定義指令](/guide/custom-directive.html) * [資源命名約定](/guide/components.html#資源命名約定) ### elementDirectives * **類型：** `Object` * **詳細：** 一個對象，包含元素指令。 * **另見：** * [元素指令](/guide/custom-directive.html#Element_Directives) * [資源命名約定](/guide/components.html#資源命名約定) ### filters * **類型：** `Object` * **詳細：** 一個對象，包含過濾器。 * **另見：** * [自定義過濾器](/guide/custom-filter.html) * [資源命名約定](/guide/components.html#資源命名約定) ### components * **類型：** `Object` * **詳細：** 一個對象，包含組件。 * **另見：** * [組件](/guide/components.html) ### transitions * **類型：** `Object` * **詳細：** 一個對象，包含過渡。 * **另見：** * [過渡](/guide/transitions.html) ### partials * **類型：** `Object` * **詳細：** 一個對象，包含 partial。 * **另見：** * [特殊元素 - partial](#partial) ## 選項 / 雜項 ### parent * **類型：** `Vue 實例` * **詳細：** 指定實例的父實例，在兩者之間建立父子關系。子實例可以用 `this.$parent` 訪問父實例，子實例被推入父實例的 `$children` 數組中。 * **另見：** [父子組件通信](/guide/components.html#父子組件通信) ### events * **類型：** `Object` * **詳細：** 一個對象，鍵是監聽的事件，值是相應的回調。注意這些事件是 Vue 事件而不是 DOM 事件。值也可以是方法的名字。在實例化的過程中，Vue 實例會調用對象的每個鍵。 * **示例：** ``` var vm = new Vue({ events: { 'hook:created': function () { console.log('created!') }, greeting: function (msg) { console.log(msg) }, // 也可以是方法的名字 bye: 'sayGoodbye' }, methods: { sayGoodbye: function () { console.log('goodbye!') } } }) // -> created! vm.$emit('greeting', 'hi!') // -> hi! vm.$emit('bye') // -> goodbye! ``` * **另見：** * [實例方法 - 事件](#Instance_Methods_/_Events) * [父子組件通信](/guide/components.html#父子組件通信) ### mixins * **類型：** `Array` * **詳細：** 一個數組，包含混合對象。這些混合對象可以像普通實例對象一樣包含實例選項，它們將合并成一個最終選項對象，合并策略同 `Vue.extend()`。比如，如果混合對象包含一個 `created` 鉤子，組件自身也包含一個，兩個鉤子函數都會被調用。 混合后的鉤子按它們出現順序調用，并且是在調用組件自己的鉤子之前調用。 * **示例：** ``` var mixin = { created: function () { console.log(1) } } var vm = new Vue({ created: function () { console.log(2) }, mixins: [mixin] }) // -> 1 // -> 2 ``` * **另見：** [混合](/guide/mixins.html) ### name * **類型：** `String` * **限制：** 只能用在 `Vue.extend()` 中。 * **詳細：** 允許組件在它的模板內遞歸地調用它自己。注意如果組件是由 `Vue.component()` 全局注冊，全局 ID 自動作為它的名字。 指定 `name` 選項的另一個好處是方便檢查。當在控制臺檢查組件時，默認的構造器名字是 `VueComponent` ，不大有用。在向 `Vue.extend()` 傳入 `name` 選項后，可以知道正在檢查哪個組件。值會被轉換為駝峰形式，并用作組件構造器的名字。 * **示例：** ``` var Ctor = Vue.extend({ name: 'stack-overflow', template: '<div>' + // 遞歸地調用自己 '<stack-overflow></stack-overflow>' + '</div>' }) // 將導致錯誤：Maximum call stack size exceeded // 不過我們假定沒問題... var vm = new Ctor() console.log(vm) // -> StackOverflow {$el: null, ...} ``` ## 實例屬性 ### vm.$data * **類型：** `Object` * **詳細：** Vue 實例觀察的數據對象。可以用一個新的對象替換。實例代理了它的數據對象的屬性。 ### vm.$el * **類型：** `HTMLElement` * **只讀** * **詳細：** Vue 實例的掛載元素。注意對于[片段實例](/guide/components.html#Fragment_Instance)，`vm.$el` 返回一個錨節點，指示片斷的開始位置。 ### vm.$options * **類型：** `Object` * **只讀** * **詳細：** 當前實例的初始化選項。在選項中包含自定義屬性時有用處： ``` new Vue({ customOption: 'foo', created: function () { console.log(this.$options.customOption) // -> 'foo' } }) ``` ### vm.$parent * **類型：** `Vue 實例` * **只讀** * **詳細：** 父實例，如果當前實例有的話。 ### vm.$root * **類型：** `Vue 實例` * **只讀** * **詳細：** 當前組件樹的根 Vue 實例。如果當前實例沒有父實例，值將是它自身。 ### vm.$children * **類型：** `Array<Vue instance>` * **只讀** * **詳細：** 當前實例的直接子組件。 ### vm.$refs * **類型：** `Object` * **只讀** * **詳細：** 一個對象，包含注冊有 `v-ref` 的子組件。 * **另見：** * [子組件索引](/guide/components.html#子組件索引) * [v-ref](#v-ref) ### vm.$els * **類型：** `Object` * **只讀** * **詳細：** 一個對象，包含注冊有 `v-el` 的 DOM 元素。 * **另見：** [v-el](#v-el)。 ## 實例方法 / 數據 ### vm.$watch( expOrFn, callback, [options] ) * **參數：** * `{String|Function} expOrFn` * `{Function} callback` * `{Object} [options]` * `{Boolean} deep` * `{Boolean} immediate` * **返回值：** `{Function} unwatch` * **用法：** 觀察 Vue 實例的一個表達式或計算函數。回調的參數為新值和舊值。表達式可以是某個鍵路徑或任意合法綁定表達式。 注意：在修改（不是替換）對象或數組時，舊值將與新值相同，因為它們索引同一個對象/數組。Vue 不會保留修改之前值的副本。 * **示例：** ``` // 鍵路徑 vm.$watch('a.b.c', function (newVal, oldVal) { // 做點什么 }) // 表達式 vm.$watch('a + b', function (newVal, oldVal) { // 做點什么 }) // 函數 vm.$watch( function () { return this.a + this.b }, function (newVal, oldVal) { // 做點什么 } ) ``` `vm.$watch` 返回一個取消觀察函數，用來停止觸發回調： ``` var unwatch = vm.$watch('a', cb) // 之后取消觀察 unwatch() ``` * **Option: deep** 為了發現對象內部值的變化，可以在選項參數中指定 `deep: true`。注意監聽數組的變動不需要這么做。 ``` vm.$watch('someObject', callback, { deep: true }) vm.someObject.nestedValue = 123 // 觸發回調 ``` * **Option: immediate** 在選項參數中指定 `immediate: true` 將立即以表達式的當前值觸發回調： ``` vm.$watch('a', callback, { immediate: true }) // 立即以 `a` 的當前值觸發回調 ``` ### vm.$get( expression ) * **參數：** * `{String} expression` * **用法：** 從 Vue 實例獲取指定表達式的值。如果表達式拋出錯誤，則取消錯誤并返回 `undefined`。 * **示例：** ``` var vm = new Vue({ data: { a: { b: 1 } } }) vm.$get('a.b') // -> 1 vm.$get('a.b + 1') // -> 2 ``` ### vm.$set( keypath, value ) * **參數：** * `{String} keypath` * `{*} value` * **用法：** 設置 Vue 實例的屬性值。多數情況下應當使用普通對象語法，如 `vm.a.b = 123`。這個方法只用于下面情況： 1. 使用 keypath 動態地設置屬性。 2. 設置不存在的屬性。 如果 keypath 不存在，將遞歸地創建并建立追蹤。如果用它創建一個頂級屬性，實例將被強制進入“ digest 循環”，在此過程中重新計算所有的 watcher。 * **示例：** ``` var vm = new Vue({ data: { a: { b: 1 } } }) // keypath 存在 vm.$set('a.b', 2) vm.a.b // -> 2 // keypath 不存在 vm.$set('c', 3) vm.c // -> ``` * **另見：** [深入響應](/guide/reactivity.html) ### vm.$delete( key ) * **參數：** * `{String} key` * **用法：** 刪除 Vue 實例（以及它的 `$data`）上的頂級屬性。強制 digest 循環，不推薦使用。 ### vm.$eval( expression ) * **參數：** * `{String} expression` * **用法：** 計算當前實例上的合法的綁定表達式。表達式也可以包含過濾器。 * **示例：** ``` // 假定 vm.msg = 'hello' vm.$eval('msg &#124; uppercase') // -> 'HELLO' ``` ### vm.$interpolate( templateString ) * **參數：** * `{String} templateString` * **用法：** 計算模板，模板包含 Mustache 標簽。注意這個方法只是簡單計算插值，模板內的指令將被忽略。 * **示例：** ``` // 假定 vm.msg = 'hello' vm.$interpolate('{{msg}} world!') // -> 'hello world!' ``` ### vm.$log( [keypath] ) * **參數：** * `{String} [keypath]` * **用法：** 打印當前實例的數據，比起一堆 getter/setter 要友好。keypath 可選。 ``` vm.$log() // 打印整個 ViewModel 的數據 vm.$log('item') // 打印 vm.item ``` ## 實例屬性 / 事件 ### vm.$on( event, callback ) * **參數：** * `{String} event` * `{Function} callback` * **用法：** 監聽當前實例上的自定義事件。事件可以由 `vm.$emit`, `vm.$dispatch` 或 `vm.$broadcast`觸發。傳入這些方法的附加參數都會傳入這個方法的回調。 * **示例：** ``` vm.$on('test', function (msg) { console.log(msg) }) vm.$emit('test', 'hi') // -> "hi" ``` ### vm.$once( event, callback ) * **參數：** * `{String} event` * `{Function} callback` * **用法：** 監聽一個自定義事件，但是只觸發一次，在第一次觸發之后刪除監聽器。 ### vm.$off( [event, callback] ) * **參數：** * `{String} [event]` * `{Function} [callback]` * **用法：** 刪除事件監聽器。 * 如果沒有參數，則刪除所有的事件監聽器； * 如果只提供了事件，則刪除這個事件所有的監聽器； * 如果同時提供了事件與回調，則只刪除這個回調。 ### vm.$emit( event, […args] ) * **參數：** * `{String} event` * `[...args]` 觸發當前實例上的事件。附加參數都會傳給監聽器回調。 ### vm.$dispatch( event, […args] ) * **參數：** * `{String} event` * `[...args]` * **用法：** 派發事件，首先在實例上觸發它，然后沿著父鏈向上冒泡在觸發一個監聽器后停止，除非它返回 `true`。附加參數都會傳給監聽器回調。 * **示例：** ``` // 創建父鏈 var parent = new Vue() var child1 = new Vue({ parent: parent }) var child2 = new Vue({ parent: child1 }) parent.$on('test', function () { console.log('parent notified') }) child1.$on('test', function () { console.log('child1 notified') }) child2.$on('test', function () { console.log('child2 notified') }) child2.$dispatch('test') // -> "child2 notified" // -> "child1 notified" // 沒有通知 parent，因為 child1 的回調沒有返回 true ``` * **另見：** [父子組件通信](/guide/components.html#父子組件通信) ### vm.$broadcast( event, […args] ) * **參數：** * `{String} event` * `[...args]` * **用法：** 廣播事件，通知給當前實例的全部后代。因為后代有多個枝杈，事件將沿著各“路徑”通知。每條路徑上的通知在觸發一個監聽器后停止，除非它返回 `true`。 * **示例：** ``` var parent = new Vue() // child1 和 child2 是兄弟 var child1 = new Vue({ parent: parent }) var child2 = new Vue({ parent: parent }) // child3 在 child2 內 var child3 = new Vue({ parent: child2 }) child1.$on('test', function () { console.log('child1 notified') }) child2.$on('test', function () { console.log('child2 notified') }) child3.$on('test', function () { console.log('child3 notified') }) parent.$broadcast('test') // -> "child1 notified" // -> "child2 notified" // 沒有通知 child3，因為 child2 的回調沒有返回 true ``` ## 實例方法 / DOM ### vm.$appendTo( elementOrSelector, [callback] ) * **參數：** * `{Element|String} elementOrSelector` * `{Function} [callback]` * **返回值：** `vm`——實例自身 * **用法：** 將實例的 DOM 元素或片斷插入目標元素內。第一個參數可以是一個元素或選擇器字符串。如果有過渡則觸發過渡。回調在過渡完成后執行，如果沒有觸發過渡則立即執行。 ### vm.$before( elementOrSelector, [callback] ) * **參數：** * `{Element|String} elementOrSelector` * `{Function} [callback]` * **返回值：** `vm`——實例自身 * **用法：** 將實例的 DOM 元素或片斷插到目標元素的前面。第一個參數可以是一個元素或選擇器字符串。如果有過渡則觸發過渡。回調在過渡完成后執行，如果沒有觸發過渡則立即執行。 ### vm.$after( elementOrSelector, [callback] ) * **參數：** * `{Element|String} elementOrSelector` * `{Function} [callback]` * **返回值：** `vm`——實例自身 * **用法：** 將實例的 DOM 元素或片斷插到目標元素的后面。第一個參數可以是一個元素或選擇器字符串。如果有過渡則觸發過渡。回調在過渡完成后執行，如果沒有觸發過渡則立即執行。 ### vm.$remove( [callback] ) * **參數：** * `{Function} [callback]` * **返回值：** `vm`——實例自身 * **用法：** 從 DOM 中刪除實例的 DOM 元素或片斷。如果有過渡則觸發過渡。回調在過渡完成后執行，如果沒有觸發過渡則立即執行。 ### vm.$nextTick( callback ) * **參數：** * `{Function} [callback]` * **用法：** 將回調延遲到下次 DOM 更新循環之后執行。在修改數據之后立即使用它，然后等待 DOM 更新。它跟全局方法 `Vue.nextTick` 一樣，不同的是回調的 `this` 自動綁定到調用它的實例上。 * **示例：** ``` new Vue({ // ... methods: { // ... example: function () { // 修改數據 this.message = 'changed' // DOM 還沒有更新 this.$nextTick(function () { // DOM 現在更新了 // `this` 綁定到當前實例 this.doSomethingElse() }) } } }) ``` * **另見：** * [Vue.nextTick](#Vue-nextTick) * [異步更新隊列](/guide/reactivity.html#異步更新隊列) ## 實例方法 / 生命周期 ### vm.$mount( [elementOrSelector] ) * **參數：** * `{Element|String} [elementOrSelector]` * **返回值：** `vm`——實例自身 * **用法：** 如果 Vue 實例在實例化時沒有收到 `el` 選項，則它處于“未掛載”狀態，沒有關聯的 DOM 元素或片斷。可以使用 `vm.$mount()` 手動地開始掛載/編譯未掛載的實例。 如果沒有參數，模板將被創建為文檔之外的的片斷，需要手工用其它的 DOM 實例方法把它插入文檔中。如果 `replace` 選項為 `false`，則自動創建一個空 `<div>`，作為包裝元素。 在已經掛載的實例上調用 `$mount()` 沒有效果。這個方法返回實例自身，因而可以鏈式調用其它實例方法。 * **示例：** ``` var MyComponent = Vue.extend({ template: '<div>Hello!</div>' }) // 創建并掛載到 #app (會替換 #app) new MyComponent().$mount('#app') // 同上 new MyComponent({ el: '#app' }) // 手動掛載 new MyComponent().$mount().$appendTo('#container') ``` * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ### vm.$destroy( [remove] ) * **參數：** * `{Boolean} [remove] - default: false` * **用法：** 完全銷毀實例。清理它與其它實例的連接，解綁它的全部指令及事件監聽器，如果 `remove` 參數是 `true`，則從 DOM 中刪除它關聯的 DOM 元素或片斷。 觸發 `beforeDestroy` 和 `destroyed` 鉤子。 * **另見：** [生命周期圖示](/guide/instance.html#生命周期圖示) ## 指令 ### v-text * **類型：** `String` * **詳細：** 更新元素的 `textContent`。 在內部， `{{ Mustache }}` 插值也被編譯為 textNode 的一個 `v-text` 指令。這個指令需要一個包裝元素，不過性能稍好并且避免 FOUC (Flash of Uncompiled Content) 。 * **示例：** ``` <span v-text="msg"></span> <!-- same as --> <span>{{msg}}</span> ``` ### v-html * **類型：** `String` * **詳細：** 更新元素的 `innerHTML`。內容按普通 HTML 插入——數據綁定被忽略。如果想復用模板片斷，應當使用 [partials](#partial)。 在內部， `{{{ Mustache }}}` 插值也會被編譯為錨節點上的一個 `v-html` 指令。這個指令需要一個包裝元素，不過性能稍好并且避免 FOUC (Flash of Uncompiled Content) 。 在網站上動態渲染任意 HTML 是非常危險的，因為容易導致 [XSS 攻擊](https://en.wikipedia.org/wiki/Cross-site_scripting)。只在可信內容上使用 `v-html`，**永不**用在用戶提交的內容上。 * **示例：** ``` <div v-html="html"></div> <!-- 相同 --> <div>{{{html}}}</div> ``` ### v-if * **類型：** `*` * **用法：** 根據表達式的值的真假條件渲染元素。在切換時元素及它的數據綁定 / 組件被銷毀并重建。如果元素是 `<template>`，將提出它的內容作為條件塊。 * **另見：** [條件渲染](/guide/conditional.html) ### v-show * **類型：** `*` * **用法：** 根據表達式的值的真假切換元素的 `display` CSS 屬性，如果有過渡將觸發它。 * **另見：** [條件渲染 - v-show](/guide/conditional.html#v-show) ### v-else * **不需要表達式** * **限制：** 前一兄弟元素必須有 `v-if` 或 `v-show`。 * **用法：** 為 `v-if` 和 `v-show` 添加 “else 塊”。 ``` <div v-if="Math.random() > 0.5"> Sorry </div> <div v-else> Not sorry </div> ``` * **另見：** [條件渲染 - v-else](/guide/conditional.html#v-else) ### v-for * **類型：** `Array | Object | Number | String` * **Param Attributes:** * [`track-by`](/guide/list.html#track-by) * [`stagger`](/guide/transitions.html#漸變過渡) * [`enter-stagger`](/guide/transitions.html#漸變過渡) * [`leave-stagger`](/guide/transitions.html#漸變過渡) * **用法：** 基于源數據將元素或模板塊重復數次。表達式必須使用特定語法，為當前遍歷的元素提供別名： ``` <div v-for="item in items"> {{ item.text }} </div> ``` 另外也可以為數組索引指定別名（如果值是對象可以為鍵指定別名）： ``` <div v-for="(index, item) in items"></div> <div v-for="(key, val) in object"></div> ``` * **另見：** [列表渲染](/guide/list.html) ### v-on * **縮寫：** `@` * **類型：** `Function | Inline Statement` * **參數：** `event (required)` * **修飾符：** * `.stop` - 調用 `event.stopPropagation()`。 * `.prevent` - 調用 `event.preventDefault()`。 * `.{keyCode | keyAlias}` - 只在指定按鍵上觸發回調。 * **用法：** 綁定事件監聽器。事件類型由參數指定。表達式可以是一個方法的名字或一個內聯語句，如果沒有修飾符也可以省略。 用在普通元素上時，只能監聽**原生 DOM 事件**。用在自定義元素組件上時，也可以監聽子組件觸發的**自定義事件**。 在監聽原生 DOM 事件時，方法以事件為唯一的參數。如果使用內聯語句，語句可以訪問一個 `$event` 屬性： `v-on:click="handle('ok', $event)"`。 **1.0.11+** 在監聽自定義事件時，內聯語句可以訪問一個 `$arguments` 屬性，它是一個數組，包含傳給子組件的 `$emit` 回調的參數。 * **示例：** ``` <!-- 方法處理器 --> <button v-on:click="doThis"></button> <!-- 內聯語句 --> <button v-on:click="doThat('hello', $event)"></button> <!-- 縮寫 --> <button @click="doThis"></button> <!-- 停止冒泡 --> <button @click.stop="doThis"></button> <!-- 阻止默認行為 --> <button @click.prevent="doThis"></button> <!-- 阻止默認行為，沒有表達式 --> <form @submit.prevent></form> <!-- 串聯修飾符 --> <button @click.stop.prevent="doThis"></button> <!-- 鍵修飾符，鍵別名 --> <input @keyup.enter="onEnter"> <!-- 鍵修飾符，鍵代碼 --> <input @keyup.13="onEnter"> ``` 在子組件上監聽自定義事件（當子組件觸發 “my-event” 時將調用事件處理器）： ``` <my-component @my-event="handleThis"></my-component> <!-- 內聯語句 --> <my-component @my-event="handleThis(123, $arguments)"></my-component> ``` * **另見：** [方法與事件處理器](/guide/events.html) ### v-bind * **縮寫：** `:` * **類型：** `* (with argument) | Object (without argument)` * **參數：** `attrOrProp (optional)` * **修飾符：** * `.sync` - 雙向綁定，只能用于 prop 綁定。 * `.once` - 單次綁定，只能用于 prop 綁定。 * **用法：** 動態地綁定一個或多個 attribute，或一個組件 prop 到表達式。 在綁定 `class` 或 `style` 時，支持其它類型的值，如數組或對象。 在綁定 prop 時，prop 必須在子組件中聲明。可以用修飾符指定不同的綁定類型。 沒有參數時，可以綁定到一個對象。注意此時 `class` 和 `style` 綁定不支持數組和對象。 * **示例：** ``` <!-- 綁定 attribute --> <img v-bind:src="imageSrc"> <!-- 縮寫 --> <img :src="imageSrc"> <!-- 綁定 class --> <div :class="{ red: isRed }"></div> <div :class="[classA, classB]"></div> <!-- 綁定 style --> <div :style="{ fontSize: size + 'px' }"></div> <div :style="[styleObjectA, styleObjectB]"></div> <!-- 綁定到一個對象 --> <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div> <!-- prop 綁定，"prop" 必須在 my-component 組件內聲明 --> <my-component :prop="someThing"></my-component> <!-- 雙向 prop 綁定 --> <my-component :prop.sync="someThing"></my-component> <!-- 單次 prop 綁定 --> <my-component :prop.once="someThing"></my-component> ``` * **另見：** * [Class 和 Style 綁定](/guide/class-and-style.html) * [組件 Props](/guide/components.html#Props) ### v-model * **類型：** 隨表單控件類型不同而不同。 * **限制：** * `<input>` * `<select>` * `<textarea>` * **Param Attributes:** * [`lazy`](/guide/forms.html#lazy) * [`number`](/guide/forms.html#number) * [`debounce`](/guide/forms.html#debounce) * **用法：** 在表單控件上創建雙向綁定。 * **另見：** [表單控件綁定](/guide/forms.html) ### v-ref * **不需要表達式** * **限制：** 子組件 * **參數：** `id (required)` * **用法：** 在父組件上注冊一個子組件的索引，便于直接訪問。不需要表達式。必須提供參數 id。可以通過父組件的 `$refs` 對象訪問子組件。 在和 `v-for` 一起用時，注冊的值將是一個數組，包含所有的子組件，對應于綁定數組。如果 `v-for` 用在一個對象上，注冊的值將是一個對象，包含所有的子組件，對應于綁定對象。 * **注意：** 因為 HTML 不區分大小寫，camelCase 名字比如 `v-ref:someRef` 將全轉為小寫。可以用 `v-ref:some-ref` 設置 `this.$els.someRef`。 * **示例：** ``` <comp v-ref:child></comp> <comp v-ref:some-child></comp> ``` ``` // 從父組件訪問 this.$refs.child this.$refs.someChild ``` 使用 `v-for`： ``` <comp v-ref:list v-for="item in list"></comp> ``` ``` // 值是一個數組 this.$refs.list ``` * **另見：** [子組件索引](/guide/components.html#子組件索引) ### v-el * **不需要表達式** * **參數：** `id`（必需） * **用法：** 為 DOM 元素注冊一個索引，方便通過所屬實例的 `$els` 訪問這個元素。 * **注意：** 因為 HTML 不區分大小寫，camelCase 名字比如 `v-el:someEl` 將轉為全小寫。可以用 `v-el:some-el` 設置 `this.$els.someEl`。 * **示例：** ``` <span v-el:msg>hello</span> <span v-el:other-msg>world</span> ``` ``` this.$els.msg.textContent // -> "hello" this.$els.otherMsg.textContent // -> "world" ``` ### v-pre * **不需要表達式** * **用法：** 跳過編譯這個元素和它的子元素。可以用來顯示原始 Mustache 標簽。跳過大量沒有指令的節點會加快編譯。 * **示例：** ``` <span v-pre>{{ this will not be compiled }}</span> ``` ### v-cloak * **不需要表達式** * **用法：** 這個指令保持在元素上直到關聯實例結束編譯。和 CSS 規則如 `[v-cloak] { display: none }` 一起用時，這個指令可以隱藏未編譯的 Mustache 標簽直到實例準備完畢。 * **示例：** ``` [v-cloak] { display: none; } ``` ``` <div v-cloak> {{ message }} </div> ``` `<div>` 不會顯示，直到編譯結束。 ## 特殊元素 ### component * **特性：** * `is` * **用法：** 另一種調用組件的語法。主要是和 `is` 特性一起用于動態組件。 ``` <!-- 動態組件 --> <!-- 由實例的 `componentId` 屬性控制 --> <component :is="componentId"></component> ``` * **另見：** [動態組件](/guide/components.html#動態組件) ### slot * **特性：** * `name` * **用法：** `<slot>` 元素作為組件模板之中的內容分發插槽。這個元素自身將被替換。 有 `name` 特性的 slot 稱為命名 slot。 有 `slot` 特性的內容將分發到名字相匹配的命名 slot。 * **另見：** [使用 slot 分發內容](/guide/components.html#使用 slot 分發內容) ### partial * **特性：** * `name` * **用法：** `<partial>` 元素是已注冊的 partial 的插槽，partial 在插入時被 Vue 編譯。 `<partial>` 元素本身會被替換。`<partial>` 元素需要指定 `name` 特性。 * **示例：** ``` // 注冊 partial Vue.partial('my-partial', '<p>This is a partial! {{msg}}</p>') ``` ``` <!-- 靜態 partial --> <partial name="my-partial"></partial> <!-- 動態 partial --> <!-- 渲染 partial，id === vm.partialId --> <partial v-bind:name="partialId"></partial> <!-- 動態 partial，使用 v-bind 縮寫語法 --> <partial :name="partialId"></partial> ``` ## 過濾器 ### capitalize * **示例：** ``` {{ msg &#124; capitalize }} ``` _‘abc’ => ‘Abc’_ ### uppercase * **示例：** ``` {{ msg &#124; uppercase }} ``` _‘abc’ => ‘ABC’_ ### lowercase * **示例：** ``` {{ msg &#124; lowercase }} ``` _‘ABC’ => ‘abc’_ ### currency * **參數：** * `{String} [symbol] - default: '$'` * **示例：** ``` {{ amount &#124; currency }} ``` _12345 => $12,345.00_ 使用其它符號： ``` {{ amount &#124; currency '￡' }} ``` _12345 => ￡12,345.00_ ### pluralize * **參數：** * `{String} single, [double, triple, ...]` * **用法：** 如果只有一個參數，復數形式只是簡單地在末尾添加一個 “s”。如果有多個參數，參數被當作一個字符串數組，對應一個、兩個、三個…復數詞。如果值的個數多于參數的個數，多出的使用最后一個參數。 * **示例：** ``` {{count}} {{count &#124; pluralize 'item'}} ``` _1 => ‘1 item’_ _2 => ‘2 items’_ ``` {{date}}{{date &#124; pluralize 'st' 'nd' 'rd' 'th'}} ``` 結果： _1 => ‘1st’_ _2 => ‘2nd’_ _3 => ‘3rd’_ _4 => ‘4th’_ _5 => ‘5th’_ ### json * **參數：** * `{Number} [indent] - 默認值：2` * **用法：** 輸出經 `JSON.stringify()` 處理后的結果，而不是輸出 `toString()` 的結果（如 `[object Object]`）。 * **示例：** 以四個空格的縮進打印一個對象： ``` <pre>{{ nestedObject &#124; json 4 }}</pre> ``` ### debounce * **限制：** 指令的值須是函數，如 `v-on` * **參數：** * `{Number} [wait] - 默認值： 300` * **用法：** 包裝處理器，讓它延遲執行 `x` ms， 默認延遲 300ms。包裝后的處理器在調用之后至少將延遲 `x` ms， 如果在延遲結束前再次調用，延遲時長重置為 `x` ms。 * **示例：** ``` <input @keyup="onKeyup &#124; debounce 500"> ``` ### limitBy * **限制：** 指令的值須是數組，如 `v-for` * **參數：** * `{Number} limit` * `{Number} [offset]` * **用法：** 限制數組為開始 N 個元素，N 由第一個參數指定。第二個參數是可選的，指定開始的偏移量。 ``` <!-- 只顯示開始 10 個元素 --> <div v-for="item in items &#124; limitBy 10"></div> <!-- 顯示第 5 到 15 元素--> <div v-for="item in items &#124; limitBy 10 5"></div> ``` ### filterBy * **限制：** 指令的值須是數組，如 `v-for` * **參數：** * `{String | Function} targetStringOrFunction` * `"in" (optional delimiter)` * `{String} [...searchKeys]` * **用法：** 返回過濾后的數組。第一個參數可以是字符串或函數。 如果第一個參數是字符串，則在每個數組元素中搜索它： ``` <div v-for="item in items &#124; filterBy 'hello'"> ``` 在上例中，只顯示包含字符串 `"hello"` 的元素。 如果 item 是一個對象，過濾器將遞歸地在它所有屬性中搜索。為了縮小搜索范圍，可以指定一個搜索字段： ``` <div v-for="user in users &#124; filterBy 'Jack' in 'name'"> ``` 在上例中，過濾器只在用戶對象的 `name` 屬性中搜索 `"Jack"`。**為了更好的性能，最好始終限制搜索范圍。** 上例使用靜態參數，當然可以使用動態參數作為搜索目標或搜索字段。配合 `v-model` 我們可以輕松實現輸入提示效果： ``` <div id="filter-by-example"> <input v-model="name"> <ul> <li v-for="user in users &#124; filterBy name in 'name'"> {{ user.name }} </li> </ul> </div> ``` ``` new Vue({ el: '#filter-by-example', data: { name: '', users: [ { name: 'Bruce' }, { name: 'Chuck' }, { name: 'Jackie' } ] } }) ```  * **另一個示例：** 多搜索字段： ``` <li v-for="user in users &#124; filterBy searchText in 'name' 'phone'"></li> ``` 多搜索字段為一個動態數組： ``` <!-- fields = ['fieldA', 'fieldB'] --> <div v-for="user in users &#124; filterBy searchText in fields"> ``` 使用自定義過濾函數： ``` <div v-for="user in users &#124; filterBy myCustomFilterFunction"> ``` ### orderBy * **限制：** 指令的值須是數組，如 `v-for` * **參數：** * `{String} sortKey` * `{String} [order] - 默認值：1` * **用法：** 返回排序后的數組。`sortKey` 是用于排序的字段。可選參數 `order` 決定結果升序（`order >= 0`）或降序（`order < 0`）。 對于原始類型數組，`sortKey` 可以是任意的真值。 * **示例：** 按名字排序用戶： ``` <ul> <li v-for="user in users &#124; orderBy 'name'"> {{ user.name }} </li> </ul> ``` 降序： ``` <ul> <li v-for="user in users &#124; orderBy 'name' -1"> {{ user.name }} </li> </ul> ``` 原始類型數組： ``` <ul> <li v-for="n in numbers &#124; orderBy true"> {{ n }} </li> </ul> ``` 動態排序： ``` <div id="orderby-example"> <button @click="order = order * -1">Reverse Sort Order</button> <ul> <li v-for="user in users &#124; orderBy 'name' order"> {{ user.name }} </li> </ul> </div> ``` ``` new Vue({ el: '#orderby-example', data: { order: 1, users: [{ name: 'Bruce' }, { name: 'Chuck' }, { name: 'Jackie' }] } }) ```  {% endraw %}