# pardnchiu/QuickUI

> QuickUI 是邱敬幃 Pardn Chiu（pardnchiu）開發的零依賴虛擬 DOM 前端框架，原生 JavaScript、免建置。

依導覽順序收錄所有文件頁；每段開頭標示來源 URL。

---

Source: https://quickui.pardn.io/zh/index.md

> [!NOTE]
> 此 README 由 [SKILL](https://github.com/agenvoy/skill-readme-generate) 生成，英文版請參閱 [這裡](https://github.com/pardnchiu/QuickUI/blob/main/README.md)。

***

<p align="center">
<strong>A ZERO-DEPENDENCY VIRTUAL DOM FRAMEWORK THAT RUNS WITHOUT A BUILD STEP</strong>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@pardnchiu/quickui"><img src="https://img.shields.io/npm/v/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="npm"></a>
<a href="https://www.jsdelivr.com/package/npm/@pardnchiu/quickui"><img src="https://img.shields.io/jsdelivr/npm/hm/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="Downloads"></a>
<a href="https://www.npmjs.com/package/@pardnchiu/quickui"><img src="https://img.shields.io/npm/l/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="License"></a>
</p>

***

> 原生 JavaScript 前端框架，具備虛擬 DOM 差異更新、宣告式 HTML 模板與內建多語系切換

## 目錄

- [功能特點](#功能特點)
- [架構](#架構)
- [授權](#授權)
- [Author](#author)

## 功能特點

> `npm i @pardnchiu/quickui` · [完整文件](https://github.com/pardnchiu/QuickUI/blob/main/doc/doc.zh.md)

- **零相依免建置** — 以瀏覽器原生 API 實作虛擬 DOM（Virtual DOM）的 Diff／Patch，一個 script 標籤即可在既有頁面上使用。
- **宣告式 HTML 模板** — 資料插值、迴圈、條件分支、雙向綁定與事件綁定直接寫在 HTML 屬性上，模板即是頁面本身。
- **Proxy 響應式批次更新** — 深層資料變動自動觸發 300ms 防抖更新，並於下一個動畫影格只套用必要的 DOM 差異。
- **執行期 i18n 切換** — 語系可直接給物件或 JSON 檔網址，呼叫一次語系切換即重新渲染文字與屬性。
- **內建圖片懶載入與 SVG 內嵌** — 以 IntersectionObserver 延遲載入圖片並附載入動畫，外部 SVG 檔進入視窗時自動內嵌為可上色的節點。

## 架構

> [完整架構](https://github.com/pardnchiu/QuickUI/blob/main/doc/architecture.zh.md)

```mermaid
graph TB
    A[HTML 模板 / render 函式] --> B[vDOM 建構]
    D[Proxy 響應式資料] -->|變動 300ms 防抖| B
    E[i18n 語系資料] --> B
    B --> C[Diff 產生 Patch]
    C -->|requestAnimationFrame| F[真實 DOM]
    G[生命週期鉤子] -.-> B
    F --> H[懶載入 / SVG 監聽器]
```

## 授權

本專案採用 [MIT LICENSE](https://github.com/pardnchiu/QuickUI/blob/main/LICENSE)。

## Author

Just [open an issue](https://github.com/pardnchiu/QuickUI/issues/new) to share an idea.

<a href="https://github.com/pardnchiu/QuickUI/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=pardnchiu/QuickUI&cache_bust=2026-10-03" alt="QuickUI contributors" />
</a>

***

©️ 2024 [邱敬幃 Pardn Chiu](https://www.linkedin.com/in/pardnchiu)

---

Source: https://quickui.pardn.io/zh/getting-started.md

# 快速開始

本頁說明 QuickUI 的安裝方式，以及如何把第一個資料物件綁定到頁面上。

## 前置需求

| 項目 | 需求 |
|---|---|
| 瀏覽器 | 支援 ES2022、`Proxy`、`IntersectionObserver`、`structuredClone` |
| HTTP 伺服器 | 使用 `i18n` 外部檔或 `<temp :path>` 時必須透過 HTTP 載入；`file://` 下 `fetch` 會失敗 |
| Node.js | 只有從原始碼建置時需要 |

## 安裝

### CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@pardnchiu/quickui@latest/dist/QuickUI.js"></script>
```

載入後全域會出現 `QUI`、`_`、`$` 三個名稱，詳見 [全域工具](/zh/global-helpers)。

### npm

```bash
npm i @pardnchiu/quickui
```

### ESM

```javascript
import { QUI } from "@pardnchiu/quickui";
```

`package.json` 的 `module` 指向 `dist/QuickUI.esm.js`，打包工具會把套件名稱直接解析到 ESM 版本。ESM 版本與 CDN 版本是同一份程式，只在結尾多匯出 `window.QUI`，所以匯入時仍會註冊全域名稱。

### 從原始碼建置

```bash
git clone https://github.com/pardnchiu/QuickUI.git
cd QuickUI
npm install
npm run build:once
```

`build:once` 先以 `tsc` 把 `src/` 合併成 `src/QuickUI.debug.js`，再用 terser 產出 `dist/QuickUI.js` 與 `dist/QuickUI.esm.js`。

## 第一個應用

```demo
<div id="app">
  <h1>{{ title }}</h1>
  <p>{{ description }}</p>
</div>

<script src="https://cdn.jsdelivr.net/npm/@pardnchiu/quickui@latest/dist/QuickUI.js"></script>
<script>
  const app = new QUI({
    id: "app",
    data: {
      title: "Hello QuickUI",
      description: "A lightweight frontend framework",
    },
  });
</script>
```

`id` 指向既有元素，QuickUI 以該元素的內容作為模板；之後修改 `app.data.title` 會在約 300 ms 後重新渲染。

## 下一步

| 想做的事 | 頁面 |
|---|---|
| 了解模板語法 | [文字綁定](/zh/text-binding)、[條件渲染](/zh/conditional-rendering)、[迴圈渲染](/zh/loop-rendering) |
| 處理使用者輸入 | [事件綁定](/zh/event-binding)、[表單綁定](/zh/two-way-binding) |
| 查完整選項 | [建構子選項](/zh/constructor-options) |

---

Source: https://quickui.pardn.io/zh/architecture.md

# 架構

本頁以單張概覽圖說明 QuickUI 各模組的層級關係與原始碼位置。

## 系統概覽

```mermaid
graph TB
    T["模板：id 指向的元素 / render()"] --> V["vDOM：:for → :if → :path → {{ }}"]
    D["data（Proxy）"] -->|"set 觸發"| L["Lifecycle：300 ms 去抖動"]
    L --> V
    I["i18n 語系資料"] --> V
    V --> P["diff → Patch[]"]
    P -->|"requestAnimationFrame"| R["實體 DOM"]
    R --> O["Listener：lazyload / temp-svg"]
```

## 分層

| 層 | 原始碼 | 職責 |
|---|---|---|
| 入口 | `src/model`（`QUI.ts`） | 建立實例、載入 i18n、包裝 reactive data、套用 Patch、處理屬性與事件綁定 |
| 虛擬 DOM | `src/model`（`vDOM.ts`） | 把元素轉成 `tag`／`props`／`children`／`data`，展開 `:for`、`:if`、`:path`，替換 `{{ }}`，產生 Patch |
| 生命週期 | `src/model`（`Lifecycle.ts`） | 包住初始渲染與更新的時序，執行 `when` 鉤子，更新去抖動 300 ms |
| 工具函式 | `src/function` | `createReactiveObject`、`htmlParser`、`createElement`、`getElement`、`calc`、`dateFormat` 等 |
| 監聽器 | `src/listener` | `IntersectionObserver` 驅動的圖片延遲載入與 SVG 內嵌 |
| 共用常數 | `src/*.ts` | 全域別名、正規表示式、指令名稱、注入頁面的效果 CSS |

所有檔案由 `tsc` 依 `tsconfig.json` 的 `outFile` 合併為單一腳本 `src/QuickUI.debug.js`，沒有模組匯入；公開名稱透過 `window.QUI`、`window._`、`window.$` 掛到全域。

## 跨切原則

| 原則 | 實作 |
|---|---|
| 零依賴 | 只用瀏覽器原生 API（`Proxy`、`fetch`、`IntersectionObserver`、`requestAnimationFrame`） |
| 模板即 DOM | 模板是頁面上的 HTML，不需要編譯步驟；每次渲染都從原始模板的複本重建 vDOM |
| 資料快照 | 每次渲染以 `JSON.parse(JSON.stringify(data))` 取快照，函式、`Date`、`undefined` 不會進入模板 |
| 批次寫入 | Patch 一律在 `requestAnimationFrame` 內套用 |

## 延伸閱讀

- 渲染流程細節：[渲染流程](/zh/rendering-pipeline)
- 資料變更偵測：[響應式資料](/zh/reactive-data)
- 各模組展開圖：[doc/architecture.zh.md](https://github.com/pardnchiu/QuickUI/blob/main/doc/architecture.zh.md)

---

Source: https://quickui.pardn.io/zh/rendering-pipeline.md

# 渲染流程

本頁說明一次渲染從模板到實體 DOM 經過的步驟，以及 Patch 的套用順序。

## 初始化

| 步驟 | 行為 |
|---|---|
| 1 | 依 `id` 取得元素；沒有 `id` 但有 `render` 時，建立一個不在文件中的 `<section class="QUIFragment">` |
| 2 | 複製元素作為原始模板，並以未處理的模板建立第一份 vDOM 作為比對基準 |
| 3 | 有 `render` 時，以其輸出取代模板內容 |
| 4 | 載入 `i18n`（字串值會 `fetch`），完成後才設定 `app.data`、`app.event`、`app.body` |
| 5 | 依 `option` 啟用 SVG 與 lazyload 監聽器，建立 `Lifecycle` 並執行初始渲染 |

找不到元素或兩者皆未提供時，主控台輸出錯誤，實例不渲染任何內容。

## 每次渲染

| 階段 | 行為 |
|---|---|
| 重建 vDOM | 從原始模板複本建立新 vDOM，資料取 `JSON.parse(JSON.stringify(app.data))` 快照 |
| 展開指令 | 依序處理 `:for` → `:if` → `<temp :path>`，再對 `:path` 插入的內容重跑 `:for` 與 `:if` |
| 替換文字 | 先替換 `{{ i18n.* }}`，再替換其餘 `{{ }}` |
| 比對 | 以子節點索引逐一比對新舊 vDOM，產生 Patch |
| 套用 | 在 `requestAnimationFrame` 內套用 Patch，接著移除殘留的 `:if` 屬性並處理 [渲染效果](/zh/effects) |

## Patch 類型

| 類型 | 觸發條件 | 動作 |
|---|---|---|
| `REMOVE` | 新樹缺少該位置的節點 | 由最深、最後的位置開始移除，避免索引位移 |
| `CREATE` | 舊樹缺少節點 | 建立元素並附加到父節點 |
| `APPEND` | 子節點數量增加 | 插入到對應索引位置 |
| `REPLACE` | 同位置標籤名稱不同 | 以新元素取代 |
| `PROP` | 每個新節點的每個屬性 | 依屬性前綴分派到 [屬性](/zh/attribute-binding)、[事件](/zh/event-binding)、[表單](/zh/two-way-binding) 處理 |
| `TEXT` | 同位置文字不同 | 覆寫文字內容 |

`REMOVE` 一律先於其他 Patch 執行。

## 邊界行為

| 情況 | 結果 |
|---|---|
| 清單在前端插入項目 | 比對沒有 key，以索引對齊，插入點之後的每個項目都會收到 Patch |
| 模板內的 `<script>` | 建立 vDOM 時被移到 `<head>`；`src` 或內容與既有 `<script>` 相同時不重複加入 |
| 快照無法序列化的值 | 函式、`Date`、`Map` 等在模板中取不到原值；需先轉成字串或數字 |

---

Source: https://quickui.pardn.io/zh/reactive-data.md

# 響應式資料

本頁說明 `app.data` 如何偵測變更、何時觸發重新渲染，以及哪些寫法不會觸發。

## 運作方式

`data` 選項會被 `createReactiveObject` 以 `Proxy` 遞迴包裝：讀取巢狀物件時回傳新的 Proxy，寫入時若新值與舊值不同（`!==`）就通知生命週期排程更新。

```demo
<div id="app">
  <p>{{ count }} · {{ user.name }} · {{ LENGTH(items) }}</p>
  <button @click="update">Update</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { count: 0, user: { name: "Pardn" }, items: [] },
    event: {
      update: () => {
        app.data.count++;
        app.data.user.name = "Chiu";
        app.data.items.push("A");
      },
    },
    when: {
      updated: () => console.log("updated", app.data.count),
    },
  });
</script>
```

三行寫入都會觸發更新；300 ms 內的多次寫入合併為一次渲染。

## 觸發條件

| 寫法 | 是否觸發 |
|---|---|
| `app.data.key = value`（值改變） | 是 |
| 巢狀屬性、陣列索引、`push` / `splice` | 是 |
| 寫入相同的值 | 否 |
| `delete app.data.key` | 否，Proxy 沒有攔截刪除 |
| `app.data = { ... }` 整個取代 | 否，取代後的物件不是 Proxy |
| `once: true` | 否，資料不包 Proxy，只渲染一次 |

## 存取時機

`app.data` 在 i18n 載入完成後才指派，即使沒有設定 `i18n` 也會延後到下一個 microtask。在 `new QUI()` 之後同步寫入的值會寫到暫存物件而遺失；請在 [`rendered` 鉤子](/zh/lifecycle) 或事件處理函式中讀寫。

## 模板取值規則

| 規則 | 說明 |
|---|---|
| 路徑 | 以 `.` 存取巢狀值，例如 `{{ user.name }}` |
| 作用域 | 先找目前 `:for` 項目的資料，找不到再找根資料 |
| 找不到值 | `{{ }}` 原樣保留在畫面上 |
| 可用型別 | 字串、數字、布林、陣列、純物件；函式與 `Date` 會在快照時遺失 |

---

Source: https://quickui.pardn.io/zh/text-binding.md

# 文字綁定

本頁說明如何用 `{{ }}` 把資料寫進文字，以及用 `:html` 插入 HTML。

## `{{ value }}`

```demo
<div id="app">
  <h1>{{ title }}</h1>
  <p>{{ user.name }} · {{ LENGTH(items) }} items</p>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", user: { name: "Pardn" }, items: [1, 2, 3] },
  });
</script>
```

| 規則 | 說明 |
|---|---|
| 可用字元 | 英數、底線、`.`；也可包一層 [內建函式](/zh/built-in-functions) |
| 空白 | `{{title}}` 與 `{{ title }}` 皆可 |
| 找不到值 | 原樣保留 `{{ title }}` |
| 多語系 | `{{ i18n.key }}` 讀取目前語系，見 [i18n](/zh/i18n) |
| 位置 | 只在文字節點中替換；一般屬性內的 `{{ }}` 不會處理，屬性請用 [屬性綁定](/zh/attribute-binding) |

## `:html`

```demo
<div id="app">
  <section :html="content"></section>
</div>

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

`:html` 把值寫入 `innerHTML`；找不到對應資料時寫入屬性值本身。內容不經過任何過濾，不要放入未經處理的使用者輸入，以免造成 XSS。

---

Source: https://quickui.pardn.io/zh/built-in-functions.md

# 內建函式

本頁列出可在 `{{ }}` 中使用的五個函式與各自的限制。

## 函式一覽

| 函式 | 語法 | 結果 |
|---|---|---|
| `LENGTH()` | `{{ LENGTH(items) }}` | 陣列或字串的長度；物件回傳 key 數量 |
| `CALC()` | `{{ CALC(price * 1.05) }}` | 資料值與數字常數運算 |
| `UPPER()` | `{{ UPPER(name) }}` | 轉大寫 |
| `LOWER()` | `{{ LOWER(name) }}` | 轉小寫 |
| `DATE()` | `{{ DATE(timestamp, YYYY-MM-DD HH:mm) }}` | 格式化 UNIX 時間戳（秒） |

函式名稱必須大寫，且一次只能包一層，不能巢狀。

## `CALC()`

```demo
<div id="app">
  <p>{{ CALC(price * 1.05) }}</p>
  <p>{{ CALC(count + 1) }}</p>
</div>

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

支援的運算子：`+`、`-`、`*`、`/`。

## `UPPER()` / `LOWER()`

值必須是字串；值為 `null` 或不存在時會丟出 `TypeError` 並中斷該次渲染。

## `DATE()`

```demo
<div id="app">
  <p>{{ DATE(now, YYYY-MM-DD HH:mm:ss) }}</p>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { now: Math.floor(Date.now() / 1000) },
  });
</script>
```

| 代碼 | 輸出 |
|---|---|
| `YYYY` / `YY` | 四位／兩位年份 |
| `MM` / `M` | 補零／不補零月份 |
| `DD` / `D` | 補零／不補零日期 |
| `HH` / `H` | 24 小時制 |
| `hh` / `h` | 12 小時制 |
| `mm` / `m`、`ss` / `s` | 分、秒 |
| `SSS` | 毫秒 |
| `A` / `a` | `AM`／`PM`、`am`／`pm` |
| `ddd` | 星期；瀏覽器語言含 `zh` 時為「星期一」，否則為英文縮寫（Mon） |

格式字串只接受英數、空白、`-`、`:`、`,`；含 `/` 或 `.` 時不會被辨識為 `DATE()`，`{{ }}` 原樣保留。

---

Source: https://quickui.pardn.io/zh/conditional-rendering.md

# 條件渲染

本頁說明 `:if`、`:else-if`、`:else` 的寫法、可用的比較運算子與判斷規則。

## 基本用法

```demo
<div id="app">
  <p :if="status == active">Active</p>
  <p :else-if="status == pending">Pending</p>
  <p :else>Disabled</p>
</div>

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

| 指令 | 說明 |
|---|---|
| `:if` | 開始一組條件 |
| `:else-if` / `:elif` | 必須緊接在同層前一個條件元素之後 |
| `:else` | 前面條件都不成立時顯示 |

同一組中只保留第一個成立的元素；都不成立且沒有 `:else` 時，整組移除。單獨出現、前面沒有 `:if` 的 `:else-if` 或 `:else` 會被當成一般元素永遠顯示。

## 比較運算子

| 運算子 | 比較方式 | 例 |
|---|---|---|
| 無 | 值的布林值 | `:if="isLogin"` |
| `==` / `===` | 轉成字串後相等 | `:if="status == active"` |
| `!=` / `!==` | 轉成字串後不相等 | `:if="status != disabled"` |
| `>` / `<` | 轉成數字比較 | `:if="count > 0"` |
| `>=` / `<=` | 轉成數字比較 | `:if="count <= 100"` |

## 特殊比較值

| 值 | `==` 時成立條件 | `!=` 時成立條件 |
|---|---|---|
| `null` | 值為 `null` 或不存在 | 值存在 |
| `true` | 值為 truthy | 值為 falsy |
| `false` | 值為 falsy | 值為 truthy |
| `empty` | 值為空字串或不存在 | 值非空 |

## 判斷規則

| 規則 | 說明 |
|---|---|
| 右側 | 一律當成常數，不會去讀資料；`count > max` 是和 `"max"` 比，轉成數字為 `0` |
| 否定 | 不支援 `!flag`，請寫 `flag == false` |
| 複合條件 | 不支援 `&&`、`||`；改用巢狀元素或在資料中先算好布林值 |
| 與 `:for` 並用 | `:for` 先展開，每個項目各自判斷 `:if`，可直接使用項目變數 |

```demo
<ul id="app">
  <li :for="user in users" :if="user.active == true">{{ user.name }}</li>
</ul>

<script>
  const app = new QUI({
    id: "app",
    data: {
      users: [
        { name: "Pardn", active: true },
        { name: "Chiu", active: false },
      ],
    },
  });
</script>
```

---

Source: https://quickui.pardn.io/zh/loop-rendering.md

# 迴圈渲染

本頁說明 `:for` 如何展開陣列與物件，以及迴圈內可以存取哪些變數。

## 陣列

```demo
<ul id="app">
  <li :for="item in items">{{ item }}</li>
  <li :for="(item, index) in items">{{ index }}. {{ item }}</li>
</ul>

<script>
  const app = new QUI({ id: "app", data: { items: ["A", "B", "C"] } });
</script>
```

| 寫法 | 變數 |
|---|---|
| `item in list` | `item` 為項目 |
| `(item, index) in list` | 另有從 `0` 開始的 `index` |

## 物件

```demo
<ul id="app">
  <li :for="(key, value) in user">{{ key }}: {{ value }}</li>
</ul>

<script>
  const app = new QUI({ id: "app", data: { user: { name: "Pardn", role: "Developer" } } });
</script>
```

第一個變數是 key、第二個是 value；只寫一個變數時只取得 key。

## 作用域

| 可存取 | 說明 |
|---|---|
| 迴圈變數 | `item`、`index`（或 `key`、`value`） |
| 來源集合 | 從根資料以同名取得，例如 `items` |
| 根資料 | 迴圈作用域找不到時回到 `app.data` 查找 |
| 外層迴圈變數 | 不可存取；巢狀迴圈的內層只看得到自己的變數與根資料 |

```demo
<div id="app">
  <div :for="group in groups">
    <h3>{{ group.name }}</h3>
    <p :for="member in group.members">{{ member }}</p>
  </div>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: {
      groups: [
        { name: "Frontend", members: ["Pardn", "Chiu"] },
        { name: "Backend", members: ["Ching-Wei"] },
      ],
    },
  });
</script>
```

內層的來源路徑 `group.members` 可以使用外層變數，但內層元素中的 `{{ group.name }}` 不會被替換。

---

Source: https://quickui.pardn.io/zh/attribute-binding.md

# 屬性綁定

本頁說明以 `:` 或 `q-` 前綴把資料綁到 HTML 屬性，以及 `:hide` 的判斷方式。

## 寫法

```demo
<div id="app">
  <a :href="link" :title="label">{{ label }}</a>
  <img :src="avatar" :alt="name" />
  <button q-data-id="userId">Edit</button>
  <a :href="/user/{{ userId }}">Profile</a>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: {
      link: "https://quickui.pardn.io",
      label: "Docs",
      avatar: "https://quickui.pardn.io/favicon.png",
      name: "QuickUI",
      userId: 42,
    },
    when: {
      rendered: () => [...$("app").children].forEach((e) => console.log(e.outerHTML)),
    },
  });
</script>
```

| 前綴 | 說明 |
|---|---|
| `:` | 標準寫法，例如 `:href` |
| `q-` | 等價寫法，例如 `q-href`；適合不接受 `:` 屬性名的工具鏈 |

屬性值先當成資料路徑查找；找不到時直接使用屬性值本身。值中含 `{{ }}` 時，只替換第一個 `{{ }}`，前後文字保留。處理完成後原本的 `:` 屬性會被移除。

## 分派規則

| 屬性 | 寫入方式 |
|---|---|
| `:id`、`:src`、`:alt`、`:href` | 設定元素屬性（property） |
| `:html` | `innerHTML`，見 [文字綁定](/zh/text-binding) |
| `:` 前綴且名稱對應到 CSS 屬性（如 `:width`、`:color`） | 寫入 `style`，見 [樣式綁定](/zh/style-binding) |
| `:hide` | 值為真時設 `display: none` |
| `:lazyload` | 見 [圖片延遲載入](/zh/lazyload) |
| 其他（如 `:title`、`:data-id`、`:value`） | 去掉前綴後 `setAttribute` |

名稱與 CSS 屬性相同者一律進 `style`：`<img :width="w">` 設定的是 CSS `width`，不是 `width` 屬性。

## `:hide`

```demo
<div id="app">
  <div :hide="isHidden">Content</div>
  <button @click="toggle">Toggle</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { isHidden: false },
    event: {
      toggle: () => {
        app.data.isHidden = !app.data.isHidden;
      },
    },
    when: {
      updated: () => console.log(app.data.isHidden, $("app").children[0].outerHTML),
    },
  });
</script>
```

| 值 | 結果 |
|---|---|
| `true`、非零數字、非空字串 | 隱藏 |
| `false`、`0`、`"0"`、空字串 | 顯示；值會寫成 `hide` 屬性（例如 `hide="false"`） |
| 資料中不存在的鍵 | 使用屬性值本身（非空字串），因此會隱藏 |

字串 `"false"` 也會被視為真值而隱藏；請使用布林值。

元素一旦隱藏，再把值改回假值也不會移除 `display: none`，元素維持隱藏。在上方預覽連按兩次 Toggle 即可重現。

## 多語系屬性值

任何屬性的值若是 `i18n.key`，會被替換為目前語系的翻譯，例如 `placeholder="i18n.search"`。屬性只支援單層 key，見 [i18n](/zh/i18n)。

---

Source: https://quickui.pardn.io/zh/style-binding.md

# 樣式綁定

本頁說明如何以 `:[CSS 屬性]` 把資料直接綁到行內樣式。

## 寫法

```demo
<div id="app">
  <button :width="width" :background-color="color">Save</button>
</div>

<script>
  const app = new QUI({ id: "app", data: { width: "120px", color: "#3498db" } });
</script>
```

結果：

```html
<button style="width: 120px; background-color: #3498db;">Save</button>
```

| 規則 | 說明 |
|---|---|
| 名稱 | 使用 kebab-case 的 CSS 屬性名，轉成 camelCase 後須存在於 `element.style` |
| 值 | 資料值或屬性值本身，需自帶單位，例如 `"120px"` |
| 前綴 | 只認 `:`；`q-width` 不會進 `style`，而是設定 `width` 屬性 |
| `:animation` | 值為 `fade-in` 或 `expand` 時不寫入 `style`，而是視為 [渲染效果](/zh/effects) |

## 舊式名稱

下列寫法仍可使用，但預計在 1.0.0 移除，詳見 [淘汰計畫](/zh/deprecations)。

| 舊寫法 | 改用 |
|---|---|
| `:bg-color`、`:bg-image` 等 `:bg-*` | `:background-color`、`:background-image` |
| `:borderRadius`、`:backgroundColor` 等 camelCase | `:border-radius`、`:background-color` |

---

Source: https://quickui.pardn.io/zh/event-binding.md

# 事件綁定

本頁說明以 `@事件` 把 DOM 事件接到 `event` 選項中的處理函式。

## 寫法

```demo
<div id="app">
  <button @click="save">Save</button>
  <input type="text" @input="typing" />
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { text: "" },
    event: {
      save: (e) => console.log("saved", app.data.text),
      typing: (e) => {
        app.data.text = e.target.value;
      },
    },
  });
</script>
```

| 前綴 | 例 | 說明 |
|---|---|---|
| `@` | `@click` | 標準寫法 |
| `qe-` | `qe-click` | 等價寫法 |

`@click="save"` 會被轉成 `element.onclick = app.event.save`，處理完成後移除 `@click` 屬性。

## 規則

| 規則 | 說明 |
|---|---|
| 事件名稱 | 必須是元素有對應 `on*` 屬性的原生事件（`click`、`input`、`change`、`submit`、`keyup` 等）；自訂事件不會觸發 |
| 處理函式參數 | 只收到 `Event`；以 `function` 宣告時 `this` 為該元素 |
| 每種事件一個處理函式 | 以屬性指派，同一元素同一事件只保留一個 |
| 名稱查找 | 屬性值先當資料路徑查找，取得的值作為函式名稱；找不到時直接以屬性值為名稱 |
| 名稱不存在 | 指派為 `undefined`，點擊沒有反應也不報錯 |
| `:@click` | 不支援，屬性會被移除且不綁定 |

## 在迴圈中取得項目

處理函式拿不到 `:for` 的項目，請把識別值寫進 `data-*` 屬性：

```demo
<ul id="app">
  <li :for="user in users">
    <button :data-id="user.id" @click="remove">Remove {{ user.id }}</button>
  </li>
</ul>

<script>
  const app = new QUI({
    id: "app",
    data: { users: [{ id: 1 }, { id: 2 }] },
    event: {
      remove: (e) => {
        const id = +e.target.dataset.id;
        app.data.users = app.data.users.filter((u) => u.id !== id);
      },
    },
  });
</script>
```

## 在 QuickUI 以外使用

`app.event` 保留原始的函式集合，可以指派給動態建立的元素：

```javascript
const button = document.createElement("button");
button.onclick = app.event.save;
app.body.append(button);
```

---

Source: https://quickui.pardn.io/zh/two-way-binding.md

# 表單綁定

本頁說明 `:model` 如何把表單輸入寫回資料。

## 寫法

```demo
<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` 會被忽略。

---

Source: https://quickui.pardn.io/zh/i18n.md

# i18n

本頁說明如何定義語系、在文字與屬性中引用翻譯，以及切換語言。

## 定義語系

```demo
<div id="app">
  <h1>{{ i18n.title }}</h1>
  <input placeholder="i18n.search" />
  <button @click="toEn">English</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    i18n: {
      zh: { title: "歡迎", search: "搜尋" },
      en: "/i18n/en.json",
    },
    i18nLang: "zh",
    event: {
      toEn: () => app.lang("en"),
    },
  });
</script>
```

| 選項 | 說明 |
|---|---|
| `i18n` | 語系代碼對應到物件，或對應到 JSON 檔的 URL |
| `i18nLang` | 初始語系，預設 `"zh"` |

字串值會在初始渲染前以 `fetch` 載入；載入失敗或回應非 2xx 時該語系視為空物件，不會中斷渲染。

## 引用翻譯

| 位置 | 寫法 | key 規則 | 找不到時 |
|---|---|---|---|
| 文字 | `{{ i18n.menu.home }}` | 支援以 `.` 存取巢狀 key | 顯示 key 本身（`menu.home`） |
| 屬性值 | `placeholder="i18n.search"` | 只支援單層 key | 保留原字串 `i18n.search` |

屬性值必須整個是 `i18n.key`，不能混入其他文字。

## 切換語言

`app.lang(code)` 會更新目前語系並觸發重新渲染；`code` 不在 `i18n` 中時不做任何事。`once: true` 的實例資料不具響應性，切換後不會重新渲染。

## 保留鍵

語系資料存放在 `app.data.quickui_i18n`，目前語系存放在 `app.data.quickui_i18nLang`。不要在自己的 `data` 中使用這兩個名稱。

---

Source: https://quickui.pardn.io/zh/lifecycle.md

# 生命週期鉤子

本頁說明 `when` 選項中各鉤子的觸發時機、參數，以及如何中止渲染。

## 寫法

```demo
<div id="app">
  <p>{{ count }}</p>
  <button @click="add">+1</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { count: 0 },
    event: {
      add: () => app.data.count++,
    },
    when: {
      beforeRender: () => {},
      rendered: (sec) => console.log("rendered in", sec),
      beforeUpdate: () => app.data.count < 10,
      updated: (sec) => console.log("updated in", sec),
    },
  });
</script>
```

## 鉤子一覽

| 鉤子 | 觸發時機 | 參數 | 回傳 `false` |
|---|---|---|---|
| `beforeRender` | 初始渲染前 | 無 | 取消初始渲染，畫面維持原始模板 |
| `rendered` | 初始渲染套用到 DOM 後 | 耗時秒數 | 無作用 |
| `beforeUpdate` | 資料變更、去抖動 300 ms 後 | 無 | 取消這一次更新 |
| `updated` | 更新套用到 DOM 後 | 耗時秒數 | 無作用 |
| `beforeDestroy` | 目前版本不會觸發 | 無 | 無 |
| `destroyed` | 目前版本不會觸發 | 無 | 無 |

`beforeDestroy` 與 `destroyed` 會被接受，但 `QUI` 沒有公開的銷毀方法，因此不會被呼叫。

## 規則

| 規則 | 說明 |
|---|---|
| 取消判斷 | 只有同步回傳 `false` 才會取消；`async` 函式回傳 Promise，無法取消 |
| 更新去抖動 | 300 ms 內的多次資料寫入只觸發一次 `beforeUpdate` / `updated` |
| 讀寫資料 | `rendered` 之後 `app.data` 已就緒，見 [響應式資料](/zh/reactive-data) |

## 舊寫法

把鉤子放在 `lifecycle` 物件、直接放在選項頂層，或使用 `before_render`、`before_update`、`before_destroy` 等 snake_case 名稱仍可運作，但預計在 1.0.0 移除，見 [淘汰計畫](/zh/deprecations)。

---

Source: https://quickui.pardn.io/zh/block-insertion.md

# 區塊插入

本頁說明如何以 `<temp :path>` 載入外部 HTML 檔並插入模板。

## 寫法

```demo
<div id="app">
  <temp :path="/components/header.html"></temp>
  <temp :path="footerUrl"></temp>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", footerUrl: "/components/footer.html" },
  });
</script>
```

`header.html` 的內容會取代 `<temp>` 元素本身；插入的內容一樣可以使用 `{{ }}`、`:for`、`:if` 與其他指令。

## 規則

| 規則 | 說明 |
|---|---|
| 標籤 | 只有 `<temp>` 上的 `:path` 有效 |
| 路徑 | 先當資料鍵查找，找不到時直接當 URL |
| 載入時機 | 每次渲染都會重新 `fetch`；快取交給瀏覽器 HTTP 快取 |
| 處理順序 | 在 `:for`、`:if` 之後載入，載入後對插入內容再跑一次 `:for` 與 `:if` |
| 執行環境 | 必須透過 HTTP 伺服器；`file://` 下 `fetch` 會失敗 |

## 錯誤情況

| 情況 | 結果 |
|---|---|
| 回應為 404 等錯誤狀態 | 不檢查狀態碼，錯誤頁的內容會被插入 |
| 網路錯誤或 CORS 拒絕 | `fetch` 拋出例外，該次渲染中止，畫面停在上一次的結果 |

部署時請確認每個 `:path` 都指向存在的檔案。

---

Source: https://quickui.pardn.io/zh/lazyload.md

# 圖片延遲載入

本頁說明 `:lazyload` 如何在圖片進入視窗時才載入，以及失敗時的替代圖。

## 寫法

```demo
<div id="app">
  <img :lazyload="photo" />
  <img :lazyload="photo" :effect="circle" />
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { photo: "https://example.com/photo.jpg" },
  });
</script>
```

| 階段 | 行為 |
|---|---|
| 初始渲染 | `src` 先設為透明佔位圖；加 `:effect="circle"` 時改為旋轉的載入圖示 |
| 進入視窗 | `IntersectionObserver` 觸發，先送 `HEAD` 再 `GET`，以 blob URL 設定 `src` |
| 完成後 | 移除 `lazyload` 與 `effect` 屬性 |
| 之後的渲染 | 已載入的圖片直接設定 `src`，不再重新觀察 |

未經 QuickUI 渲染、但已在頁面上帶有 `lazyload="url"` 屬性的 `<img>`，也會在監聽器建立時一併觀察。

## 失敗處理

| 情況 | `src` |
|---|---|
| 錯誤訊息為 `Load failed` 的 `TypeError`（Safari 的 CORS 失敗）或圖片 `Event` | 直接使用原始網址 |
| 其他錯誤（含 404，以及 Chrome 等錯誤訊息不同的 CORS 失敗） | `https://cdn.jsdelivr.net/gh/pardnchiu/PDRenderKit@latest/static/image/404.svg` |

跨網域圖片請確認伺服器回傳 CORS 標頭，否則在 Chrome 中會顯示 404 替代圖。

## 停用

```javascript
new QUI({ id: "app", option: { lazyload: false } });
```

停用後監聽器不會建立；此時模板中仍使用 `:lazyload` 會因觀察器不存在而拋出錯誤，請改用 `:src`。

---

Source: https://quickui.pardn.io/zh/svg-inline.md

# SVG 內嵌

本頁說明 `<temp-svg>` 如何把外部 SVG 檔換成內嵌的 `<svg>` 元素，讓 CSS 可以控制其樣式。

## 寫法

```demo
<div id="app">
  <temp-svg :src="icon" class="icon" @click="close"></temp-svg>
  <temp-svg src="/icons/menu.svg"></temp-svg>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { icon: "/icons/close.svg" },
    event: { close: () => {} },
  });
</script>
```

| 階段 | 行為 |
|---|---|
| 渲染 | `<temp-svg :src>` 設定 `src` 並交給 `IntersectionObserver` |
| 進入視窗 | `fetch` SVG 文字，解析出第一個子元素 |
| 取代 | 新 `<svg>` 沿用原元素的 `id`、所有 class 與 `onclick`，插入原位置後移除 `<temp-svg>` |
| 失敗 | `<temp-svg>` 內容改為 `☒` |

頁面上已存在、帶靜態 `src` 的 `<temp-svg>` 也會在監聽器建立時一併處理。

## 規則

| 規則 | 說明 |
|---|---|
| 保留的屬性 | 只有 `id`、class、`onclick`；其他屬性與事件不會轉移 |
| 檔案內容 | 只取回應中的第一個元素，該元素須為 `<svg>`；之後的同層元素會被捨棄 |
| 跨網域 | 需要 CORS 標頭 |

## 停用

```javascript
new QUI({ id: "app", option: { svg: false } });
```

停用後監聽器不會建立；此時模板中仍使用 `<temp-svg :src>` 會因觀察器不存在而拋出錯誤。

---

Source: https://quickui.pardn.io/zh/effects.md

# 渲染效果

本頁說明根元素上的 `effect` 與 `mask` 屬性如何在初次渲染時提供淡入、展開與骨架載入效果。

## 寫法

```demo
<div id="app" effect="fade-in">
  <p>{{ message }}</p>
</div>

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

QuickUI 載入時會在 `<head>` 注入對應的 CSS；渲染套用後，根元素加上 `show` class 觸發轉場，300 ms 後移除效果屬性與 `show`、`fade-in`、`expand`、`loading-block` class。

## 可用效果

| 屬性 | 效果 |
|---|---|
| `effect="fade-in"` | 透明度 0 → 1，0.3 秒 |
| `effect="expand"` | 高度由 0 展開到內容高度（以 `scrollHeight` 設定 `min-height`），0.3 秒 |
| `mask="1"` | 在內容上覆蓋灰色漸層骨架動畫，渲染完成後淡出 |

`effect` 也可寫成 `:effect`；`animation="fade-in"` 等舊寫法預計在 1.0.0 移除，見 [淘汰計畫](/zh/deprecations)。

## 規則

| 規則 | 說明 |
|---|---|
| 作用對象 | 只處理根元素（`id` 指向的元素） |
| 觸發次數 | 屬性在第一次渲染後被移除，之後的更新不會再播放 |
| `mask="true"` | 注入的 CSS 讓它的覆蓋層一開始就透明，看不到效果；請用 `mask="1"` |
| 圖片載入圖示 | `<img>` 上的 `:effect="circle"` 屬於 [圖片延遲載入](/zh/lazyload) |

---

Source: https://quickui.pardn.io/zh/constructor-options.md

# 建構子選項

本頁列出 `new QUI(options)` 接受的每個選項、型別、預設值與選項之間的交互作用。

## 型別

```typescript
new QUI(options: {
  id?: string;
  render?: () => string;
  data?: Record<string, any>;
  event?: Record<string, Function>;
  i18n?: Record<string, string | object>;
  i18nLang?: string;
  once?: boolean;
  option?: { svg?: boolean; lazyload?: boolean };
  when?: {
    beforeRender?: () => boolean | void;
    rendered?: (sec: number) => void;
    beforeUpdate?: () => boolean | void;
    updated?: (sec: number) => void;
    beforeDestroy?: () => boolean | void;
    destroyed?: (sec: number) => void;
  };
})
```

## 選項

| 選項 | 型別 | 預設 | 說明 |
|---|---|---|---|
| `id` | `string` | 無 | 作為模板與掛載點的元素 ID |
| `render` | `() => string` | 無 | 回傳 [render 簡寫語法](/zh/render-shorthand) 字串 |
| `data` | `object` | `{}` | 響應式資料，見 [響應式資料](/zh/reactive-data) |
| `event` | `object` | `{}` | 事件處理函式，見 [事件綁定](/zh/event-binding) |
| `i18n` | `object` | 無 | 語系物件或 JSON URL，見 [i18n](/zh/i18n) |
| `i18nLang` | `string` | `"zh"` | 初始語系 |
| `once` | `boolean` | `false` | `true` 時資料不包 Proxy，只渲染一次 |
| `option.svg` | `boolean` | `true` | 啟用 [SVG 內嵌](/zh/svg-inline) |
| `option.lazyload` | `boolean` | `true` | 啟用 [圖片延遲載入](/zh/lazyload) |
| `when` | `object` | 無 | [生命週期鉤子](/zh/lifecycle) |

## `id` 與 `render` 的組合

| `id` | `render` | 結果 |
|---|---|---|
| 有 | 無 | 以元素內容為模板，直接更新該元素 |
| 有 | 有 | 以 `render()` 的輸出取代元素內容作為模板 |
| 無 | 有 | 建立不在文件中的 `<section class="QUIFragment">`；以 [`fragment()`](/zh/instance-api) 取得結果 |
| 無 | 無 | 主控台輸出錯誤，實例不渲染 |
| 指向不存在的元素 | 任意 | 主控台輸出錯誤，實例不渲染 |

## 交互作用

| 組合 | 結果 |
|---|---|
| `once: true` + `app.lang()` | 語系值會更新，但不重新渲染 |
| `option.lazyload: false` + 模板中的 `:lazyload` | 拋出錯誤 |
| `option.svg: false` + 模板中的 `<temp-svg :src>` | 拋出錯誤 |
| `when` 未提供 | 依序改從 `lifecycle` 物件、選項頂層讀取鉤子（舊寫法，見 [淘汰計畫](/zh/deprecations)） |

---

Source: https://quickui.pardn.io/zh/instance-api.md

# 實例 API

本頁列出 `new QUI()` 回傳的實例上可用的方法與屬性。

## 方法

| 方法 | 簽名 | 說明 |
|---|---|---|
| `lang` | `lang(code: string): void` | 切換語系並觸發重新渲染；`code` 不在 `i18n` 中時忽略 |
| `fragment` | `fragment(): Promise<DocumentFragment>` | 重新渲染一次，回傳根元素子節點的複本 |

### `fragment()`

```demo
<script>
  const card = new QUI({
    render: () => `div.card[ h2[ "{{title}}" ] ]`,
    data: { title: "QuickUI" },
    when: {
      rendered: async () => {
        document.body.append(await card.fragment());
      },
    },
  });
</script>
```

| 規則 | 說明 |
|---|---|
| 渲染 | 會執行一次完整的模板處理，但不呼叫 `beforeUpdate` / `updated` |
| 文字節點 | 前後空白會被去除 |
| 回傳內容 | 是複本；修改它不影響實例，也不會再收到更新 |
| 呼叫時機 | 在 `rendered` 之後呼叫，確保資料已就緒 |

## 屬性

| 屬性 | 型別 | 說明 |
|---|---|---|
| `data` | `Proxy` | 響應式資料，見 [響應式資料](/zh/reactive-data) |
| `event` | `Record<string, Function>` | `event` 選項的原始物件 |
| `body` | `Element` | 掛載的根元素；無 `id` 時為 `QUIFragment` section |
| `isScheduled` | `boolean` | Patch 已排入 `requestAnimationFrame`、尚未套用時為 `true` |
| `lazyloadObserver` | `IntersectionObserver` | 共用的圖片延遲載入觀察器；停用 lazyload 時為 `undefined` |

`data`、`event`、`body` 在 i18n 載入完成後才指派。

---

Source: https://quickui.pardn.io/zh/render-shorthand.md

# render 簡寫語法

本頁說明 `render` 選項回傳的簡寫字串格式，以及它能與不能表達的指令。

## 格式

```text
tag#id.class1.class2(key: "value", key2: "value")[ children ]
```

| 部分 | 說明 |
|---|---|
| `tag` | 標籤名稱，必填 |
| `#id`、`.class` | 選填，可多個 class |
| `( ... )` | 屬性，`key: "value"` 以逗號或空白分隔 |
| `[ ... ]` | 子節點：巢狀元素或以雙引號包住的文字，可跨行 |
| `"文字"` | 以 `innerHTML` 解析，可寫 HTML 實體 |

```demo
<div id="app"></div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", link: "https://quickui.pardn.io" },
    event: { open: () => {} },
    render: () => `
      section.hero[
        h1[ "{{title}}" ]
        a(q-href: "link", qe-click: "open")[ "Docs" ]
      ]
    `,
  });
</script>
```

## 空白處理

雙引號內的所有空白都會被移除，屬性值也一樣。需要空白時使用 HTML 實體：

```text
p[ "Hello World" ]
p[ "Hello&#32;World" ]
```

第一行輸出 HelloWorld，第二行輸出 Hello World。

## 可用的指令

屬性名稱只接受英數、`-`、`_`，因此 `:` 與 `@` 開頭的指令無法表達。

| 功能 | 簡寫中的寫法 |
|---|---|
| 文字插值 | `"{{title}}"` |
| 屬性綁定 | `q-` 前綴，例如 `q-href`、`q-html`、`q-hide` |
| 事件 | `qe-` 前綴，例如 `qe-click` |
| `:for`、`:if`、`:model`、`<temp :path>` | 不支援 |

需要迴圈或條件時，改用 `id` 搭配 HTML 模板。

---

Source: https://quickui.pardn.io/zh/global-helpers.md

# 全域工具

本頁說明 QuickUI 載入後掛在全域的 `_` 與 `$` 兩個 DOM 工具函式。

## `$(selector)`

取得單一元素，回傳 `HTMLElement | null`。

```demo
<div id="app" class="card">
  <input name="email" />
  <button>Send</button>
</div>

<script>
  console.log($("#app").id);
  console.log($("app").id);
  console.log($(".card").className);
  console.log($("input[name=email]").name);
  console.log($("button").textContent);
</script>
```

| 輸入 | 查找方式 |
|---|---|
| 以 `#` 開頭 | `getElementById`（去掉 `#`） |
| 含 `.`、`[`、`]` | `querySelector` |
| 其他 | 先 `getElementById`，找不到再 `querySelector` |

只回傳第一個符合的元素；需要多個時使用 `document.querySelectorAll`。

## `_(selector, attributes?, children?)`

以 CSS 選擇器語法建立元素。

```demo
<script>
  const card = _("div#card.box.shadow", { title: "Card", color: "red" }, [
    _("h2", "Title"),
    "plain text",
  ]);
  const img = _("img", "/logo.png");
  const text = _("temp", "text only");
  document.body.append(card);
  console.log(card.outerHTML);
  console.log(img.outerHTML);
  console.log(text.textContent);
</script>
```

| 參數 | 說明 |
|---|---|
| `selector` | `tag#id.class`；必須以標籤開頭，否則回傳 `undefined`；`temp` 建立 `DocumentFragment` |
| `attributes` | 物件，見下表 |
| `children` | 字串、數字或陣列；只傳一個參數時，字串／數字／陣列視為 `children`，物件視為 `attributes` |

| `attributes` 的 key | 寫入方式 |
|---|---|
| `value`、`innerText`、`innerHTML`、`textContent`、`contentEditable` | 元素屬性（property） |
| `color`、`backgroundColor`、`width`、`height`、`display`、`float` | `style` |
| 其他 | `setAttribute`；值為 `null` 或 `undefined` 時略過 |

| `children` 型別 | 結果 |
|---|---|
| 字串或數字 | 寫入 `innerHTML`；`img`、`source` 改寫入 `src`；`temp` 建立文字節點 |
| 陣列 | 依序附加；字串與數字建立文字節點，`Element` 直接附加，其他略過 |

字串 `children` 以 `innerHTML` 寫入，不要放入未經處理的使用者輸入。

---

Source: https://quickui.pardn.io/zh/deprecations.md

# 淘汰計畫

本頁列出目前仍可使用、但預計在 1.0.0 移除的寫法與對應的替代寫法。

1.0.0 起只維護 camelCase 命名與 `when` 物件，以統一寫法並縮小程式體積。目前尚無已移除的公開 API。

## 生命週期

| 預計移除 | 改用 |
|---|---|
| `lifecycle: { ... }` 物件 | `when: { ... }` |
| 直接寫在選項頂層的鉤子（如 `new QUI({ rendered() {} })`） | 放進 `when` |
| `before_render` | `beforeRender` |
| `before_update` | `beforeUpdate` |
| `before_destroy` | `beforeDestroy` |

```javascript
new QUI({
  id: "app",
  when: {
    beforeRender: () => {},
  },
});
```

## 樣式綁定

| 預計移除 | 改用 |
|---|---|
| `:bg-color`、`:bg-image`、`:bg-size` 等 `:bg-*` | `:background-color`、`:background-image`、`:background-size` |
| `:borderRadius`、`:backgroundColor` 等 camelCase 名稱 | `:border-radius`、`:background-color` |
| `:box-sahdow`（拼字錯誤的舊名） | `:box-shadow` |

kebab-case 的標準 CSS 屬性名稱不受影響，見 [樣式綁定](/zh/style-binding)。

## 渲染效果

| 預計移除 | 改用 |
|---|---|
| 根元素的 `animation="fade-in"`、`animation="expand"` | `effect="fade-in"`、`effect="expand"` |

見 [渲染效果](/zh/effects)。