# [Vue] Built-in Directives 內建指令

###### tags: `Vue`

* 以 `v-` 開頭的屬性，當指令的值改變時，會響應式更新 DOM
* 透過指令的作用與狀態的變化，就可透過改變狀態（資料）來操作整個網頁系統
* 指令的值應為 [JavaScript expressions](https://hackmd.io/@yuna9068/Bkt_r75sP#Expression)，但 `v-for`、`v-on`、`v-slot` 除外

## 內建指令清單
* v-text：設定 `textContent`
* v-html：設定 `innerHTML`
* v-show：改變 `display` 狀態，顯示或隱藏元素
* v-if：依據條件顯示對應的元素。[不要同時使用 v-if 和 v-for](#不要同時使用-v-if-和-v-for)
* v-else：依據條件顯示對應的元素
* v-else-if：依據條件顯示對應的元素
* v-for：列表渲染，資料的類型：Array、Object、number、string、Map、Set。[不要同時使用 v-if 和 v-for](#不要同時使用-v-if-和-v-for)
* v-on：事件綁定。缩写 `@`。[修飾符](#v-on-修飾符)。[event](#v-on-event)
* v-bind：屬性綁定。使用 `:style` 時，Vue 會自動加上瀏覽器相對應的前綴
* v-model：對表單元素（`input`、`textarea`、`select`）或 component 進行資料的雙向綁定。[修飾符](#v-model-修飾符)
* v-slot：插槽
* v-pre：不會解析模板內容，通常用於顯示 `{{}}` 符號及寫在裡面的內容
* v-once：只渲染一次，之後便不再更新
* [v-memo](https://vuejs.org/api/built-in-directives.html#v-memo)：Vue 3.2+ 新增。有條件的停止後續的渲染。根據官方文件說明，適用於性能至上的微小優化，很少需要用到。常見應用情境為搭配 `v-for` 渲染超過 1000 筆資料時
* v-cloak：隱藏尚未完成編譯的 DOM 模板。搭配 `[v-cloak] { display: none; }`。在無構建步驟的環境（直接引入 Vue.js、使用 [petite-vue](https://github.com/vuejs/petite-vue)）才需使用

## 不要同時使用 v-if 和 v-for
* [不要同時使用 v-if 和 v-for，同時使用時，v-if 優先於 v-for](https://vuejs.org/style-guide/rules-essential.html#avoid-v-if-with-v-for "Avoid v-if with v-for")

## v-on 修飾符
### 事件
* stop：阻擋事件冒泡，`event.stopPropagation()`
* prevent：阻擋元素的預設行爲，`event.preventDefault()`
* capture：指定事件以捕獲（capturing）的形式來觸發，外 -> 內
* self：限 `event.target` 是元素本身才會觸發
* once：只會觸發一次
* passive：替 `addEventListener` 添加 `{ passive: true }` ，用途是告訴瀏覽器這個事件處理器不會呼叫 `event.preventDefault()` 來停止瀏覽器的原生行爲，常見用於 touch 事件，改善行動裝置 scroll 時的效能。不可以和 `.prevent` 同時使用，會忽略 `.prevent`。

### 按鍵
==**Vue 3 不支援 keyCodes 的寫法**==
* {keyAlias}：按下指定按鍵時觸發。例：`.enter`、`.tab`、`.delete`、`.esc`、`.space`、`.up`、`.down`、`.left`、`.right`、`page-down` 等等
* 系統按鍵：`.ctrl`、`.alt`、`.shift`、`.meta`（Mac 的 Command 鍵(⌘)，Windows 的 Windows 鍵(⊞)）
* exact：Vue 2.5+ 新增。搭配系統按鍵使用，通常用來判斷系統按鍵的各種組合

    <!-- 按著 ctrl 鍵時觸發，若同時有按下其他按鍵也會觸發 -->
    <button @click.ctrl="onClick">A</button>

    <!-- 只按著 ctrl 鍵，沒有按下其他按鍵時才會觸發  -->
    <button @click.ctrl.exact="onCtrlClick">A</button>

    <!-- 沒有按下任何系統按鍵時觸發 -->
    <button @click.exact="onClick">A</button>

### 滑鼠
* left：滑鼠左鍵觸發
* right：滑鼠右鍵觸發
* middle：滑鼠中鍵觸發

## v-on event
* 若沒有指定參數，預設會將 event 物件當作參數傳入
* 可透過 `$event` 來指定 event 物件

function getEvent(p1, p2) {
  console.log('p1: ', p1);
  console.log('p2: ', p2);
};

<!-- p1: 123, p2: event -->
<button @click="getEvent('123', $event)">getEvent('123', $event)</button>

<!-- p1: 123, p2: event -->
<button @click="(event) => getEvent('123', event)">(event) => getEvent('123', event)</button>

<!-- p1: event, p2: 123 -->
<button @click="getEvent($event, '123')">getEvent($event, '123')</button>

## v-model 修飾符
* lazy：監聽事件從 `input` 改為 `change`
* number：將值透過 `parseFloat()` 轉為數字，失敗時返回原始的值。當有 `type="number"` 屬性時會自動套用
* trim：移除值前後的空白字元

## 參考資料
* [Vue 3 官方文件：Template Syntax - Directives](https://vuejs.org/guide/essentials/template-syntax.html#directives)
* [Vue 3 官方文件：Built-in Directives](https://vuejs.org/api/built-in-directives.html)
* [許國政（Kuro），《重新認識 Vue.js: 008 天絕對看不完的 Vue.js 3 指南》（博碩文化，2021），第1-4章、第1-5章、第1-6章。](https://www.drmaster.com.tw/bookinfo.asp?BookID=MP22026)

---

:::info
建立日期：2024-02-28
更新日期：2024-03-02
:::