# 表單綁定

本頁說明 `:model` 如何把表單輸入寫回資料，以及它不會做的事。

## 寫法

```html
<div id="app">
  <input type="text" :model="username" />
  <p>Hello, {{ username }}</p>
</div>

<script>
  const app = new QUI({ id: "app", data: { username: "" } });
</script>
```

## 各元素的行為

| 元素 | 監聽事件 | 寫入 `app.data[key]` 的值 |
|---|---|---|
| `<input>`（文字類）、`<textarea>` | `keyup`、`change` | `value`，空值為 `""` |
| `<select>` | `change` | 選取項目的 `value` |
| `<input type="checkbox">`、`<input type="radio">` | `change` | 頁面上同 `name`、同 `type` 且已勾選者的 `value`，以 `,` 串接 |

其他元素上的 `:model` 會被忽略。

## 限制

| 限制 | 說明 |
|---|---|
| 單向寫回 | 只把輸入寫進資料；程式修改 `app.data.username` 不會改變輸入框的值 |
| 初始值 | 需要預填時另加 `:value="username"` |
| 只限頂層鍵 | `:model="user.name"` 會寫入名為 `"user.name"` 的頂層鍵，而不是 `user` 物件的 `name` |
| 觸發時機 | 文字輸入在 `keyup` 時寫入；以滑鼠貼上要等到 `change`（失焦）才寫入 |
| 核取方塊範圍 | 以整個 `document.body` 中同 `name` 的元素計算，不限於該實例 |

需要即時、雙向同步時，改用 [事件綁定](/zh/event-binding) 的 `@input` 自行寫入資料。