---
url: /blog-program/getting-to-know-effect-ts.md
description: Promise<User> 到底告訴了你什麼？來認識把錯誤跟依賴通通寫進型別的 Effect ( •̀ ω •́ )✧
---

![getting-to-know-effect-ts](/getting-to-know-effect-ts.webp){.cover}

# `Promise<User>` 到底告訴了你什麼？來認識 Effect ( •̀ ω •́ )✧

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

這篇是上下兩篇的**上篇**，講 Effect 的核心概念，看完你會知道它到底在解什麼問題。

下篇[Effect 接進真實專案](/blog-program/effect-ts-in-real-projects)則是實戰，Vue、NestJS、oRPC 怎麼接，還有效能實測。

其實兩年前我就研究過 Effect 了，翻完文件的結論是「東西很好，但我用不起」，門檻跟心智負擔都太高，於是在新手村就被勸退。%(´\_ゝ\`)%

兩年後我回鍋了，因為當年那些門檻在 AI 協助開發後，基本上都不存在了。

至於卡在哪、現在又怎麼解，[回到兩年前](#回到兩年前)那節會算總帳，好奇的話可以先跳過去看。

不趕時間的話就跟著往下讀，從頭講起比較好懂。%( •̀ ω •́ )✧%

## 先問一個問題

大家有沒有接手過這種函數？

```ts
function getUser(id: string): Promise<User>
```

型別看完，你只能確定一件事，成功的話會拿到 `User`。

其他通通不知道。

* 它會不會失敗？會，但型別沒說
* 失敗有幾種？查無此人？網路斷線？權限不夠？型別還是沒說
* 它需要什麼才跑得起來？資料庫？API 金鑰？型別依然沒說

只好翻進去看，結果它又呼叫了五個函數，於是再一層一層翻下去。%( ´•̥̥̥ ω •̥̥̥\` )%

鱈魚：「翻到最後我已經忘記本來要查什麼了。%(´\_ゝ\`)%」

路人：「...這不是每天都在發生嗎？%(´・ω・\`)%」

今天要聊的 Effect，就是把這三個答案通通寫進型別。

## Effect 到底是什麼

大家常把 Effect 歸類成「Promise 的升級版」或「管理服務的工具」，它的定位其實更底層。

它是一套**描述程式的型別**，長這樣。

```ts
Effect<A, E, R>
```

三個欄位剛好對應剛才那三個問題。

| 欄位 | 意思 | 對應的問題 |
|---|---|---|
| `A` | 成功會拿到什麼 | 回傳值是什麼 |
| `E` | 可能會怎麼失敗 | 會噴哪些錯 |
| `R` | 需要什麼才能跑 | 依賴哪些服務 |

`Promise<User>` 只有第一欄。

路人：「另外兩件事寫在 JSDoc 裡不就好了？%(・∀・)%」

鱈魚：「可以啊，然後呢？%(´\_ゝ\`)%」

```ts
/**
 * @throws {UserNotFound} 查無此人
 * @throws {NetworkError} 連線失敗
 */
function getUser(id: string): Promise<User>
```

寫得很認真，問題是**沒有人會檢查它對不對**。

* 少寫一種錯誤，編譯器不會有意見
* 改了實作忘記改註解，註解就開始說謊
* 最麻煩的是它**不會自己長大**，`getUser` 裡面呼叫的函數哪天多噴一種錯誤，這份清單不會跟著更新

註解是寫給人看的備忘錄，型別是編譯器會拿去驗算的東西，差別就在這裡。%( ˘•ω•˘ )%

`Effect<User, UserNotFound, Database>` 三欄都在，後面兩欄由編譯器算出來，不用手寫，也不會過期。%( •̀ ω •́ )✧%

### Effect 寫好了也不會跑

理解 Effect 的另一個關鍵。

Promise 一建立就開始跑。

```ts
const promise = fetch('/api/user') // 這行跑完，請求已經送出去了
```

Effect 不會。

```ts
const program = Effect.promise(() => fetch('/api/user')) // 什麼事都沒發生
```

`program` 只是一段「等一下要去打這支 API」的描述，躺在那裡不動，交給執行器才會動起來。

```ts
Effect.runPromise(program) // 這時候才真的送出去
```

路人：「多此一舉吧？直接跑不是比較快？%(・∀・)%」

鱈魚：「因為還沒跑的東西才有辦法加工。%( •̀ ω •́ )%」

已經在跑的 Promise，你能做的事很有限，頂多 `.then` 接一下。

還沒跑的描述就不一樣了，丟去執行之前，你可以先說「失敗重試三次」、「超過五秒放棄」、「跟另外兩個一起併發」。

```ts
program.pipe(
  Effect.retry({ times: 3 }),
  Effect.timeout('5 seconds'),
)
```

到這裡都還是描述，一行都還沒執行。%(ゝ∀・)b%

### Effect 的守備範圍

介紹 Effect 的文章常常只挑其中一欄講，容易讓人以為它就只做那件事，其實它的守備範圍涵蓋一整包平常散落各處的東西。

| 你原本用什麼 | Effect 裡對應的 |
|---|---|
| `Promise`、`async/await` | `Effect`、`Effect.gen` |
| `try/catch` | `E` 欄位、`catchTag` |
| 一層一層傳參數，或自己寫的服務容器 | `R` 欄位、`Layer` |
| `Promise.all`、`AbortController` | Fiber、`Effect.all`、中斷機制 |
| 自己寫的 retry 迴圈 | `Effect.retry`、`Schedule` |
| `try/finally` 關資源 | `Scope`、`Effect.acquireRelease` |
| `vi.useFakeTimers` | `TestClock` |

一篇文章塞不下這麼多，這次挑最常遇到的兩欄下手，`E` 跟 `R`。%(´,,•ω•,,)%

## 從最小的 Effect 開始長

與其一次看完整範例，不如從最小的形狀開始，一次加一樣東西。

```ts
import { Effect } from 'effect'

const program = Effect.succeed(42)
// Effect<number, never, never>
```

成功會給 42、不會失敗、不需要任何東西，兩個 `never` 就是這個意思。

接著讓它可能失敗。錯誤得先定義成帶標籤的類別，後面才有辦法靠標籤分辨。

```ts
import { Data, Effect } from 'effect'

class UserNotFound extends Data.TaggedError('UserNotFound')<{
  readonly id: string;
}> {}

const program = Effect.fail(new UserNotFound({ id: 'u1' }))
// Effect<never, UserNotFound, never>
```

`E` 那欄出現 `UserNotFound` 了。

最後讓它需要一個服務，這裡用 `Effect.Service` 定義。

```ts
interface User {
  id: string;
  name: string;
}

class Database extends Effect.Service<Database>()('Database', {
  effect: Effect.sync(() => ({
    findUser: (id: string): Effect.Effect<User> => Effect.succeed({ id, name: '鱈魚' }),
    save: (user: User): Effect.Effect<void> => Effect.void,
  })),
}) {}

const program = Effect.gen(function* () {
  const database = yield* Database
  return yield* database.findUser('u1')
})
// Effect<User, never, Database>
```

`R` 那欄從 `never` 變成 `Database` 了。

沒人手動宣告這件事，編譯器看到 `yield* Database` 就自己算出來。%( •̀ ω •́ )✧%

三個欄位到齊，接下來把那個奇怪的星號講清楚。

## 等等，`yield*` 是什麼鬼

路人：「我從剛剛就想問了，那個星號到底是什麼？%(´・ω・\`)%」

鱈魚：「Effect 看起來最像外星語的地方，先講結論，它就是 `await`。%(ゝ∀・)b%」

先澄清一件事，`yield*` 是 JavaScript 原生語法，2015 年就進標準，跟 Effect 沒關係，正式名稱叫**委派**（delegation），只能用在 generator function 裡面。

```ts
function* getAnswer() {
  return 42
}

function* main() {
  const answer = yield* getAnswer()
  console.log(answer) // 42
}
```

`yield*` 把控制權交給另一個 generator，等它跑完，再**把回傳值接回來**，Effect 借的就是這個行為。

### 心智模型：把它念成 await

async 版本跟 Effect 版本擺在一起，對應關係很齊全，一家人整整齊齊。

| async/await | Effect |
|---|---|
| `async function` | `Effect.gen(function* () {})` |
| `await promise` | `yield* effect` |
| `Promise<User>` | `Effect<User, E, R>` |

同一段邏輯，兩種寫法。

```ts
// async 版本
async function getUser(id: string) {
  const user = await database.findUser(id)
  return user
}
```

```ts
// Effect 版本
function getUser(id: string) {
  return Effect.gen(function* () {
    const database = yield* Database
    const user = yield* database.findUser(id)
    return user
  })
}
```

`async` 換成 `Effect.gen(function* ...)`、`await` 換成 `yield*`，剩下只差 `database` 從 import 進來變成跟環境拿。

讀 Effect 程式碼時，看到 `yield*` 就在心裡念成 `await`，八成不會出錯。%(´,,•ω•,,)%

### 那為什麼不乾脆用 await

路人：「都一樣的話，幹嘛不用 `await` 就好？%(・∀・)%」

鱈魚：「因為 `await` 綁死了，它只認 Promise。%( ˘•ω•˘ )%」

`await` 寫死在語言規格裡，它接受什麼、錯誤怎麼處理，都是 JavaScript 說了算，函式庫插不上手。

`yield*` 剛好相反，交出去之後要做什麼，接手的人自己決定。Effect 接手時就順便做了兩件 `await` 做不到的事。

* **把錯誤記到型別上**。`await` 的錯誤只會 `throw` 出去，型別是 `unknown`；`yield*` 會把錯誤累積到 `E` 那欄
* **把依賴記到型別上**。也就是那個 `R`，`await` 完全沒有對應概念

換句話說，每 `yield*` 一次，編譯器就默默幫你更新一次 `E` 跟 `R` 的清單。%( •̀ ω •́ )✧%

### 為什麼 `yield* Database` 能拿到服務

再回頭看這兩行，長得很像，做的事卻好像不同。

```ts
const database = yield* Database // 拿到服務
const user = yield* database.findUser(id) // 執行動作
```

路人：「一個是 class，一個是函數呼叫，為什麼都能 `yield*`？%(´・ω・\`)%」

鱈魚：「因為 `Database` 本身就是 Effect。%(ﾉ>ω<)ﾉ%」

`Effect.Service` 生出來的 class 除了當型別標籤，同時也是個「跟環境要一份 `Database`」的 Effect，型別長這樣。

```ts
Effect<Database, never, Database>
```

成功會給你一份服務、不會失敗、需要環境裡有這個服務。

所以那兩行其實是同一件事，只是一個負責要東西，另一個負責做事情。%(´,,•ω•,,)%

### 忘記寫星號會怎樣

新手最常踩的坑，而且症狀比忘記 `await` 更詭異。

```ts
database.save(user) // 忘了 yield*
```

忘記 `await`，那個 Promise 至少還是會跑，只是沒人等它。

忘記 `yield*`，那行**根本不會執行**。%(°ㅂ°)%

Effect 是惰性的描述，沒交給執行器之前，它就只是躺在那裡的物件，跟你寫了一行 `{ type: 'save' }` 沒什麼兩樣。

路人：「這不是很可怕嗎？資料就這樣人間蒸發了？%(;´༎ຶД༎ຶ\`)%」

鱈魚：「所以這是 Effect 少數得靠習慣防守的地方，寫久了看到沒有 `yield*` 開頭的那行會很刺眼。%( ˘•ω•˘ )%」

### 流程控制照常寫

Effect 另一種寫法是用 `pipe` 把函數串起來，而 `Effect.gen` 最大的好處是**流程控制照常寫**。

迴圈、`if`、`try` 這些原生語法通通能用。

```ts
Effect.gen(function* () {
  const failedList: string[] = []

  for (const id of idList) {
    const result = yield* database.findUser(id).pipe(Effect.either)

    if (result._tag === 'Left') {
      failedList.push(id)
    }
  }

  return failedList
})
```

同樣的邏輯用 `pipe` 串起來會非常痛苦，難怪官方文件現在幾乎都拿 `Effect.gen` 當範例。%( •̀ ω •́ )✧%

### `yield*` 的三個限制

不過 `yield*` 有幾條硬規則，踩到會很困惑，先講清楚比較好。

**一、只能寫在 generator 函數的本體裡**

這條最容易中招。上面那段能不能改成 `forEach`？

```ts
Effect.gen(function* () {
  idList.forEach((id) => {
    const result = yield* database.findUser(id) // [!code error]
  })
})
```

**不行，這樣直接編譯失敗。**%(°ㅂ°)%

原因是 `forEach` 的 callback 是**另一個函數**，而 `yield*` 只能出現在 `function*` 自己的函數體內。跨進 callback 就沒有 generator 可以交棒了。

`await` 也有一樣的毛病，只是 `await` 至少可以把 callback 改成 `async`，`yield*` 連這條路都沒有。

所以在 `Effect.gen` 裡面，`for...of` 是你的好朋友，`forEach`、`map`、`filter` 的 callback 裡通通不能 `yield*`。

真的想用宣告式寫法，Effect 有對應的替代品。

```ts
Effect.gen(function* () {
  // 依序跑，收集結果
  const userList = yield* Effect.forEach(idList, (id) => database.findUser(id))

  // 併發跑，最多同時五個
  const fastList = yield* Effect.forEach(idList, (id) => database.findUser(id), {
    concurrency: 5,
  })

  return { userList, fastList }
})
```

`Effect.forEach` 的 callback 回傳 **Effect 本身**，callback 裡不需要 `yield*`，由外層那個 `yield*` 統一收。%(ゝ∀・)b%

**二、只能 `yield*` Effect 或有實作 Yieldable 的東西**

Promise 跟一般的值都不行。

```ts
Effect.gen(function* () {
  const bad = yield* fetch('/api') // [!code --] 這是 Promise，不是 Effect
  const good = yield* Effect.promise(() => fetch('/api')) // [!code ++] 先包成 Effect
})
```

Promise 得先用 `Effect.promise` 或 `Effect.tryPromise` 轉換過。

**三、`Effect.gen` 裡面不能用 `async`**

```ts
Effect.gen(async function* () { }) // [!code error]
```

`Effect.gen` 收的是同步的 generator，非同步的事情交給 `yield*` 處理就好，不需要也不能加 `async`。

路人：「限制還真不少。%(´・ω・\`)%」

鱈魚：「習慣就好，而且第一條有官方 lint 規則會提醒你。%( ˘•ω•˘ )%」

## `E` 那一欄，錯誤不再是 unknown

語法講完，回頭看那三個欄位到底解決了什麼。

先看 `E`。原生 `try/catch` 抓到的 `error` 型別是 `unknown`（沒開 strict 的話是 `any`，更慘），想知道是哪一種，只能用 `instanceof` 慢慢猜。

```ts
try {
  await database.findUser(id)
}
catch (error) {
  if (error instanceof UserNotFoundError) {
    return null
  }
  else {
    throw error // 忘記寫這行，其他錯誤就被吃掉了
  }
}
```

漏掉最後那行 `throw`，網路逾時、權限不足這些錯誤就這樣消失了，編譯器不會有意見，因為 `catch` 區塊裡放什麼都合法。%( ´•̥̥̥ ω •̥̥̥\` )%

Effect 版本用 `catchTag` 指定要處理哪一種，沒指定到的照樣往外傳。

```ts
database.findUser(id).pipe(
  Effect.catchTag('UserNotFound', () => Effect.succeed(null)),
)
```

處理掉的錯誤會從 `E` 那欄消失，剩下沒處理的還留著。

```ts
// 處理前 Effect<User, UserNotFound | NetworkError, Database>
// 處理後 Effect<User | null, NetworkError, Database>
```

想知道呼叫這個函數可能收到什麼錯誤，看型別就好，不用翻進去找 `throw`。%(ゝ∀・)b%

## `R` 那一欄，這個函數需要什麼

接著是 `R`，這欄會直接改變你怎麼寫測試。

先看原生寫法會出什麼事。

某天你寫了一個註冊功能，很單純，把使用者存起來就好。

```ts
// register-user.ts
import { database } from './database'

export async function registerUser(user: User): Promise<User> {
  await database.save(user)
  return user
}
```

測試也很單純，把 `database` mock 掉就行了。

```ts
// register-user.test.ts
import { database } from './database'
import { registerUser } from './register-user'

vi.mock('./database')

it('註冊會把使用者存起來', async () => {
  const user = { id: 'u1', name: '鱈魚' }

  await registerUser(user)

  expect(database.save).toHaveBeenCalledWith(user)
})
```

一切美好，測試綠燈。%(´,,•ω•,,)%

半年後，有人幫註冊流程加了一行寄歡迎信。

```ts
export async function registerUser(user: User): Promise<User> {
  await database.save(user)
  await emailService.sendWelcomeEmail(user.email) // [!code ++]
  return user
}
```

他改完跑了一次測試，綠燈，直接送出 PR。

沒人記得回去改那份半年前寫的測試，因為它跟這次改動看起來八竿子打不著。%(・∀・)%

路人：「等等，`emailService` 沒 mock，測試不是應該壞掉嗎？%(´・ω・\`)%」

鱈魚：「它又不影響 `registerUser` 的回傳值，斷言照樣通過啊。%( ˘•ω•˘ )%」

於是測試維持綠燈，只是每跑一次，就真的往某個不存在的信箱寄一封歡迎信出去。

某天早上 Slack 跳出一封「歡迎加入」，收件人是 `test@example.com`，你才發現這件事已經持續三個月。%(;´༎ຶД༎ຶ\`)%

這裡沒有人偷懶。真正的問題是 `registerUser` 用到哪些東西**藏在函數內部**，型別上完全看不出來。

多加一個 import，型別系統一個字都不會抱怨，它本來就不管這件事。

### 換成 Effect

同一份邏輯，依賴改成跟環境拿。

這裡的 `Database` 就是前面「從最小的 Effect 開始長」定義過的那個服務，用 `Effect.Service` 生出來的 class。

```ts
import { Effect } from 'effect'
import { Database } from './database' // 前面用 Effect.Service 定義的那個

export function registerUser(user: User) {
  return Effect.gen(function* () {
    const database = yield* Database

    yield* database.save(user)

    return user
  })
}
// Effect<User, never, Database>
```

請注意 `Database` 是 import 進來的，但 import 的是**服務的名牌**，不是實作。

實作長什麼樣、連哪個資料庫，這個檔案從頭到尾都不知道，它只說「我需要一個叫 `Database` 的東西」。%( ˘•ω•˘ )%

半年後那位同事一樣加了寄信那行。

```ts
const emailService = yield* EmailService // [!code ++]

yield* database.save(user)
yield* emailService.sendWelcomeEmail(user.email) // [!code ++]
```

這兩行一加，`R` 那欄自動變成 `Database | EmailService`。

沒人維護這份清單，全是編譯器算出來的。%( •̀ ω •́ )✧%

### 這件事有個正式名稱

「函數不要自己 import 該用哪個實作，改成由外面塞進去」，這個做法叫做**依賴注入**（Dependency Injection，常縮寫成 DI）。

聽起來很唬人，其實你早就在用了。

```ts
// 自己去拿，這叫相依
function registerUser(user: User) {
  return database.save(user)
}

// 由外面給，這就是依賴注入
function registerUser(user: User, database: Database) {
  return database.save(user)
}
```

第二種寫法讓呼叫端決定要塞哪個 `database` 進去，正式環境塞真的，測試塞假的，函數本身完全不用改。%(´,,•ω•,,)%

路人：「那多加一個參數不就好了，幹嘛搞這麼複雜？%(・∀・)%」

鱈魚：「兩三層還行，十層就哭了。%(´\_ゝ\`)%」

參數傳遞最麻煩的部分在於它會**傳染**。

最底層的函數要用 `database`，呼叫它的人也得先拿到才有辦法往下傳，再上一層又是同樣狀況，一路傳到最外面。

中間那些函數根本用不到，卻得在簽章上多掛一個參數，只因為底下有人要用。%( ˘•ω•˘ )%

於是各家框架發明各種容器來代勞，Effect 則是把這份清單收進 `R` 欄位，要用的人自己跟環境拿，中間那些函數一個字都不用改。

### 那 Layer 又是什麼

前面一直說「跟環境拿」，那環境裡的東西是誰放進去的？答案是 **Layer**。

一句話講完，**Layer 就是服務的建造說明書**。%(´,,•ω•,,)%

```ts
// 這是「名牌」，只講有哪些能力，不講怎麼實作
class Database extends Context.Tag('Database')<Database, {
  readonly save: (user: User) => Effect.Effect<void>;
}>() {}

// 這是「說明書」，代表「Database 實際上長這樣」
const DatabaseLive = Layer.succeed(Database, {
  save: (user) => Effect.promise(() => db.insert(user)), // 真的寫進資料庫
})
```

這裡改用 `Context.Tag` 而不是 `Effect.Service`，是為了把名牌跟說明書拆成兩段看。兩者的差別等一下講。

`registerUser` 只認名牌，不認說明書。

執行之前用 `Effect.provide` 把說明書交出去，環境才算齊備。

```ts
registerUser(user).pipe(
  Effect.provide(DatabaseLive), // 把說明書塞進去
)
```

之所以要分成兩個東西，是因為同一張名牌可以配好幾份說明書。

| 說明書 | 用在哪 |
|---|---|
| `DatabaseLive` | 正式環境，真的連資料庫 |
| `DatabaseTest` | 測試，回傳假資料 |
| `DatabaseMemory` | 本機開發，存在記憶體 |

`registerUser` 完全不知道自己拿到哪一份，也不需要知道。%( •̀ ω •́ )✧%

那前面一直用的 `Effect.Service` 又是什麼？它是**把名牌跟說明書綁在一起**的懶人包，會自動生一份叫 `Default` 的說明書。

```ts
Effect.provide(Database.Default) // Effect.Service 自動生的那份
```

[官方文件](https://effect.website/docs/requirements-management/layers/#effectservice-vs-contexttag)的建議是這樣。

* **應用程式碼、實作只有一種** → 用 `Effect.Service`，少寫樣板
* **函式庫、或沒有哪個實作該當預設** → 用 `Context.Tag`，只發布名牌，讓使用者自己決定

Layer 還能互相組合、互相依賴（`Database` 需要 `Config`，`Config` 需要環境變數），這部分展開會太長，先知道「它是說明書」就夠用了。

### 那所有套件都要包成服務嗎？

鱈魚：「來吧，讓我們把 lodash、dayjs、zod 通通包起來！%( •̀ ω •́ )✧%」

路人：「太麻煩了吧！%ლ（´口\`ლ）%」

鱈魚：「開玩笑的啦，不用都包起來。%(´,,•ω•,,)%」

判斷標準只有一句話，**你會不會想換掉它**。

| | 直接 import | 包成服務 |
|---|---|---|
| 例子 | `date-fns`、`zod`、`remeda` | 資料庫、外部 API、寄信、檔案 |
| 特徵 | 同樣輸入永遠同樣輸出 | 結果隨環境改變 |
| 測試時 | 不會想換掉 | 一定不想真的碰 |

純函數包成服務只是徒增樣板，測試也不會因此變好寫。%( ˘•ω•˘ )%

而且要注意，「把資料庫包成服務」指的是包**你自己那層封裝**，不是幫 `drizzle` 寫一層 Layer。

```ts
import { drizzle } from 'drizzle-orm/node-postgres' // 照常 import，沒在客氣

export class Database extends Effect.Service<Database>()('Database', {
  effect: Effect.sync(() => {
    const db = drizzle(process.env.DATABASE_URL!)

    return {
      findUser: (id: string) => Effect.promise(() => db.query.users.findFirst(/* ... */)),
    }
  }),
}) {}
```

套件照常 import，被包起來的是 `findUser` 這個**你定義的介面**。外面只認得介面，不曉得底下是 drizzle、Prisma 還是一包假資料。%( •̀ ω •́ )✧%

至於時間、亂數、環境變數這幾個常見的，Effect 已經內建，不用自己動手。

```ts
const now = yield* Clock.currentTimeMillis // 取代 Date.now()
const dice = yield* Random.nextIntBetween(1, 7) // 取代 Math.random()
const apiKey = yield* Config.string('API_KEY') // 取代 process.env
```

測試時搭配 `TestClock` 就能把時間快轉，不用真的等五秒，也就是前面那張守備範圍表裡 `vi.useFakeTimers` 那列。%(ゝ∀・)b%

最後提醒一下，包越多 `R` 那欄就越長，每個呼叫端都要跟著 provide。

判斷不出來的時候先直接 import，等到「這裡測試很難寫」再抽出來也不遲。%(´,,•ω•,,)%

### 測試差異，眼見為憑

原生版本得靠 `vi.mock` 把整個模組換掉，前面已經看過會出什麼包。

Effect 版本改成**換一份說明書**，也就是換一顆 Layer。

```ts
// register-user.test.ts
import { expect, it } from '@effect/vitest'
import { Effect, Layer } from 'effect'
import { Database, registerUser } from './register-user'

const DatabaseTest = Layer.succeed(Database, {
  save: () => Effect.void,
})

it.effect('註冊會把使用者存起來', () =>
  Effect.gen(function* () {
    const user = { id: 'u1', name: '鱈魚' }
    const result = yield* registerUser(user)
    expect(result).toEqual(user)
  }).pipe(
    Effect.provide(DatabaseTest),
  ))
```

有人把 `EmailService` 加進 `registerUser` 那天，這段測試不用等執行，**編譯就先紅了**。

```text
Type 'Effect<void, never, EmailService>' is not assignable
to type 'Effect<void, never, TestServices>'.
Type 'EmailService' is not assignable to type 'TestServices'.
```

紅的是 IDE 裡那條波浪線，只要 CI 有跑型別檢查，這種 PR 就過不了。%( •̀ ω •́ )✧%

路人：「所以 Effect 靠編譯器抓漏 mock，原生只能靠人記得改測試？%(´・ω・\`)%」

鱈魚：「對，這就是最大的差別。原生版本那份清單就算寫進註解也沒人會去對，Effect 搬進型別系統，編譯器每次都幫你對一遍。%(ゝ∀・)b%」

## 回到兩年前

開頭說我棄坑過，看到這裡你應該有感覺了，該來說說當年的理由。

前面出現過的東西，剛好就是當時勸退我的五樣。

**一、型別錯誤訊息長到看不懂**

還記得前面那段「少 provide 一顆 Layer 就編譯失敗」嗎？文章裡我只貼了三行，實戰版通常是一大串巢狀泛型，`Effect` 裡面包 `Effect`，重點藏在第七行的某個角落。

新手看到那種訊息只有一個反應，關掉。%(°ㅂ°)%

**二、API 表面積大到會迷路**

這篇只用到 `Effect`、`Data`、`Layer`、`Context` 而已，實際上還有 `Schedule`、`Stream`、`Scope`、`Queue`、`Fiber`、`STM`、`Schema`⋯⋯每個底下又是幾十上百個函數。

想做一件很簡單的事，光是「該用哪個」就要翻很久。

這點官方自己也認了。[Myths 頁面](https://www.effect.website/docs/v3/additional-resources/myths)有一條就叫「Effect is impossible to learn, there are so many functions and modules!」，開頭第一個字是 **True**。%(°ㅂ°)%

> 沒錯，完整的 Effect 生態系相當龐大，有些 module 包含上千個函數。但實際上你不需要全部學會才能開始產出，只要知道 10 到 20 個函數就可以安心開始用，剩下的慢慢認識就好。

後面還附了「常用的 15 個函數」跟「常用的 7 個 module」兩張清單，等於官方直接幫你畫重點。

這個回應很誠實，不過它解的是「要不要全部學會」，沒解到「當下這件事該用哪個函數」。%( ˘•ω•˘ )%

**三、命名來自函數式傳統，猜不到**

`flatMap`、`tap`、`zipRight`、`acquireRelease`、`provide`。知道的人覺得精準，不知道的人根本不曉得要去哪裡找。

前面 `Effect.either` 那招也是，你不會憑直覺想到「把失敗轉成值」要用這個字。

**四、同一件事有好幾種寫法**

`pipe` 還是 `gen`？`Context.Tag` 還是 `Effect.Service`？`Layer.succeed` 還是 `Layer.effect`？選擇障礙直接發作。%(´・ω・\`)%

**五、卡住了 Google 不到**

這點最致命。社群還小，Stack Overflow 幾乎沒有答案，遇到問題只能翻文件或去 Discord 問。

對於習慣「卡住就查、查到就繼續」的開發節奏，這等於整條路被切斷。

五點加起來就是所謂的心智負擔。概念本身不算難，難的是**每寫一行都要付出額外的查詢成本**，而那個成本高到讓人懷疑人生。%( ´•̥̥̥ ω •̥̥̥\` )%

### 這五點在 AI 面前都不太成立了

一條一條對回去看，會發現它們有個共通點，全都是**查資料的成本**。%(ﾉ>ω<)ﾉ%

| 當年的門檻 | 現在怎麼解 |
|---|---|
| 型別訊息看不懂 | 貼給它，直接告訴你少了什麼 |
| 不知道該用哪個函數 | 描述你要做的事，它給你名字 |
| 命名猜不到 | 同上，不用先知道叫什麼才找得到 |
| Google 不到 | 它讀過文件跟原始碼 |
| 選擇障礙 | 把專案慣例講清楚，它會跟著走 |

而查資料剛好是 AI 最擅長的事。

當年那個「用不起」的結論，前提已經不成立了。%( •̀ ω •́ )✧%

### 但 AI 會生出過期的語法

先別急著開心，直接叫 AI 寫 Effect 會踩到一個大雷，**它很容易生出過期的語法**。

原因是 Effect 這幾年改動很大。

* `Effect.gen` 的 adapter 寫法（`function* (_) { yield* _(...) }`）從 2024 年 4 月起就不需要了，但它至今仍然能編譯能執行，所以編譯器不會攔你，而訓練資料裡又到處都是
* 現在 npm 上 `latest` 是 v3，v4 已經進 RC，兩份文件並存
* v4 又把 `Context.Tag`、`Effect.Tag`、`Effect.Service` 通通合併成 `Context.Service`

三個世代的 API 混在一起，AI 想不搞混也難。%(´\_ゝ\`)%

### 官方給的三樣工具

好消息是官方正在處理這件事，有三樣東西可以直接用。

**一、官方 skills**

Effect 官方開了 [skills repo](https://github.com/Effect-TS/skills)，一行指令裝好。

```bash
npx skills add Effect-TS/skills
```

裡面兩個 skill，`effect-ts` 負責日常開發，`effect-v3-to-v4` 專門處理升級。

有趣的是 `effect-ts` 本身**幾乎沒有內容**，它只做一件事，叫 agent 去讀 `node_modules/effect/AGENTS.md`。

**二、套件裡自帶的 AI 文件**

這招很聰明。Effect v4 直接把 `AGENTS.md`（17KB）跟 `ai-docs/`（近 150KB、五十幾個 `.ts` 範例）**包進 npm 套件裡**。

```text
node_modules/effect/
├── AGENTS.md
├── CLAUDE.md
└── ai-docs/
```

文件永遠跟你裝的版本綁在一起，不會出現「文件講 v4、專案跑 v3」的慘案。%( •̀ ω •́ )✧%

要注意 v3 沒有這些檔案，這是 v4 才有的待遇。

**三、`@effect/language-service`**

這個我覺得最實用，它是 TypeScript 的 LSP plugin，專門抓 Effect 的寫法問題。

```bash
npm install -D @effect/language-service
```

裡面幾條規則根本是為 AI 生成的程式碼量身訂做。

| 規則 | 抓什麼 |
|---|---|
| `effectGenUsesAdapter` | 用了 2024 年就淘汰的 adapter 寫法 |
| `missingStarInYieldEffectGen` | 前面講過的，`yield` 忘記加星號 |
| `floatingEffect` | 建立了 Effect 卻沒有人執行它 |
| `outdatedApi` | 用到 v4 已經改名或移除的 API |

還記得前面那個「忘記寫星號，資料就人間蒸發」嗎？`missingStarInYieldEffectGen` 就是專門守這關的。%(ゝ∀・)b%

另外官方部落格有篇 [The One Weird Git Trick That Makes Coding Agents More Effect-ive](https://effect.website/blog/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive/)，主張用 `git subtree` 把 Effect 原始碼放進專案，讓 agent 直接讀原始碼。

文中那句話蠻有意思的，agent 拿到「寫給人看的文件」時，效率明顯比較差。%(´,,•ω•,,)%

路人：「所以現在有 AI 就可以無腦上了？%(・∀・)%」

鱈魚：「當然沒這麼好康，有兩件事 AI 幫不了你。%( ˘•ω•˘ )%」

**第一，你還是得看得懂它寫了什麼。**

AI 產出的 Effect 程式碼你 review 不了，那就只是把技術債外包出去，出事還是你要扛。

**第二，心智模型還是要自己建立。**

`Effect<A, E, R>` 那三欄代表什麼、為什麼要惰性、Layer 怎麼組合，這些理解不會因為 AI 會寫就自動長進你腦袋裡。

AI 砍掉的是**打字跟查資料的成本**，理解的成本它砍不掉。%( ˘•ω•˘ )%

不過話說回來，查資料跟猜 API 的成本一旦消失，當年那個「用不起」的結論就得重算一次。

所以我又回鍋了。%(´,,•ω•,,)%

## 總結 🐟

* `Promise<User>` 只講了成功會拿到什麼，`Effect<A, E, R>` 把「會怎麼失敗」跟「需要什麼」也寫進型別，後兩欄由編譯器算，不會像 JSDoc 那樣過期
* Effect 寫好了不會馬上跑，還沒跑的描述才加得上重試、逾時、併發，它也才管得動錯誤、依賴、資源、測試時鐘一整包
* `yield*` 就是 Effect 版的 `await`，每 `yield*` 一次編譯器就順手更新 `E` 跟 `R`，代價是它只能寫在 generator 本體，`forEach` 的 callback 裡放不了
* 那份依賴清單沒人手動維護，測試也就從「換掉整個模組」變成「換一顆 Layer」，少換一顆直接編譯失敗
* 別把所有套件都包成服務，判斷標準只有「你會不會想換掉它」，純函數直接 import 就好

概念的部分到這裡告一段落。

下篇[Effect 接進真實專案](/blog-program/effect-ts-in-real-projects)會把這些東西實際接到 Vue、NestJS 跟 oRPC 上，也有跟 Express、Fastify 的效能實測，最後動手做一支跑得動的 todo API。%( •̀ ω •́ )✧%

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

---

---
url: /blog-vue/vue-composable-outer-variable-trap.md
description: 把 ref 放在 composable 外面共用狀態，方便是方便，但是可能會埋下地雷喔。(´・ω・`)
---

![vue-composable-outer-variable-trap](/vue-composable-outer-variable-trap.webp){.cover}

# AI 可能會寫的 Vue Composable 地雷，你踩過了嗎？

大家有沒有請 AI 幫忙寫過 Vue composable？

甚麼？你問現在誰還在手寫程式？抱歉我多問了。%(´；ω；\`) %

請 AI 寫一個「多個元件共用狀態」的 composable，雖然不是每次，但是他有可能會給你這樣的程式碼（尤其是降智的時候 %( ◔ ௰◔)%）。

```ts
import { ref } from 'vue'

const count = ref(0)

export function useCounter() {
  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  return { count, increment, decrement }
}
```

把 `ref` 放在函式外面，這樣不管哪個元件呼叫 `useCounter()`，拿到的都是同一份 `count`，完美實現共用狀態。

AI 還會貼心地解釋：「把變數宣告在模組層級，所有呼叫者就能共用同一份響應式狀態。」%...(́⊙◞౪◟⊙‵)%

::: tip 為什麼放外面就能共用？
ES Module 只會被執行一次，之後不管多少地方 `import`，拿到的都是同一個模組實例。

所以宣告在模組頂層的變數，自然就變成全域共用的單例（Singleton）。
:::

看起來很合理對吧？但其實這段程式碼可能在無意間埋下地雷。%ԅ( ˘ω˘ԅ)%

## 這段程式碼有什麼問題？

既然知道這是利用 ES Module 的單例特性，讓我們想想這代表什麼。

`count` 這個 `ref` 從程式啟動到結束，永遠只有一份。

如果你的專案用了 Nuxt 這類有 SSR 的框架，要特別注意。

在 SSR 環境中，server 端的模組被所有請求共用。

::: tip SPA 就不用擔心了吧？
純 SPA 的確不會有跨請求污染的問題，不過難保未來專案不會加上 SSR，到時候就變成埋在深處的地雷了。

既然有更安全的寫法，不如一開始就避開這顆潛在的地雷。

甚麼？你說你就是想埋？我不知道，我甚麼都沒聽到。%(。-\`ω´-)%
:::

也就是說，Request A 的使用者修改了 `count`，Request B 的使用者進來時，拿到的 `count` 就是 A 改過的值。

```ts
// 模組層級的變數，server 端所有請求共用
const count = ref(0)

export function useCounter() {
  // Request A 呼叫 increment()，count 變成 1
  // Request B 進來時，count 已經是 1 了
  function increment() {
    count.value++
  }

  return { count, increment }
}
```

這就是 Vue 官方文件中特別警告的 [**Cross-Request State Pollution**](https://vuejs.org/guide/scaling-up/ssr.html#cross-request-state-pollution)（跨請求狀態污染）。

使用者 A 的資料洩漏到使用者 B 的頁面上，輕則顯示錯誤，重則變成資安事件。

## 正確的替代方案

經典用法是請出我們可愛的鳳梨 Pinia。( ´ ▽ \` )ﾉ🍍

Pinia 的 store 綁定在 Vue 的 app instance 上，SSR 時每個請求都會拿到獨立的 store 實例，從根本上解決跨請求污染問題。

```ts
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)

  function increment() {
    count.value++
  }

  return { count, increment }
})
```

如果你用的是 Nuxt，官方提供了 `useState` 這個 composable，專門用來建立 SSR 安全的共用狀態。

以剛才的 `useCounter` 為例，可以改寫成：

```ts
export function useCounter() {
  const count = useState('count', () => 0)

  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  return { count, increment, decrement }
}
```

`useState` 底層會將狀態綁定在請求的 context 上，server 端不同請求之間不會互相污染，同時還會自動將 server 端的狀態序列化傳遞給 client 端，避免 hydration mismatch。

## 一定要用 Pinia 嗎？

有些時候你只是想讓幾個元件共用一個 composable 的狀態，又覺得為了這點小事特地開一顆鳳梨（Pinia store）感覺有點太重了。

這時候可以試試 VueUse 提供的 `createSharedComposable`。

```ts
import { createSharedComposable } from '@vueuse/core'
import { ref } from 'vue'

function _useCounter() {
  const count = ref(0)

  function increment() {
    count.value++
  }

  return { count, increment }
}

export const useCounter = createSharedComposable(_useCounter)
```

`createSharedComposable` 會確保不管多少個元件呼叫 `useCounter()`，底層的 `_useCounter` 只會執行一次，所有元件拿到的都是同一份狀態。

而且在 SSR 環境下會自動退回非共用模式，每個請求都拿到獨立的實例，不會有跨請求污染問題。%( •̀ ω •́ )✧%

簡單整理一下選擇方式：

| 需求 | 方案 |
|---|---|
| 各元件獨立狀態 | 變數放函式內部 |
| 輕量共用，不想開 store | `createSharedComposable` |
| 複雜共用狀態、需要 devtools | Pinia |

## 總結 🐟

* 把 `ref` 放在 composable 函式外面，利用 ES Module 單例特性共用狀態，在 SSR 環境下會造成跨請求狀態污染
* 即使目前是純 SPA，也建議避開這種寫法，為未來可能加入 SSR 預留彈性
* 需要跨元件共用狀態時，優先考慮 Pinia，Nuxt 專案可用 `useState`
* 覺得開 store 太重，可以試試 VueUse 的 `createSharedComposable`，輕量且 SSR 安全

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

有錯誤或任何想法還請多多指教。%( ´∀\`)~♥%

---

---
url: /blog-program/cyclomatic-complexity-in-the-ai-era.md
description: AI 很乖，需求一層一層疊上去，程式疊得比 100 還高 Σ(ˊДˋ;)
---

![cyclomatic-complexity-in-the-ai-era](/cyclomatic-complexity-in-the-ai-era.webp){.cover}

# AI 都幫我寫好了，還需要管複雜度嗎？( ・ิω・ิ)

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

你朋友現在寫 code 是不是都把需求丟給 AI，十秒後交件，附測試，全綠，掃一眼就 merge。

先不管那個朋友是不是你自己。%(◐‿◑)%

總之你朋友都把需求丟給 AI，不過 AI 有沒有可能偷懶，只會疊，不會整理，越改越亂？

什麼？你說公司前人寫的祖傳程式碼都超過幾千行，早就習慣了？敬佩敬佩。%(́⊙◞౪◟⊙‵)%

有沒有什麼客觀指標，可以用來表示程式碼複雜度？

搜尋了一下，發現有個 1976 年就發明出來的老指標，叫做圈複雜度（Cyclomatic Complexity）。

這篇拿酷酷元件（[chill-component](https://chillcomponent.codlin.me/)）裡一支真實函式開刀，最後再回頭看 AI 時代還需不需要這個數字。

## 數字怎麼來

圈複雜度代表程式裡有幾條分支路徑。

名字裡的圈來自圖論，把程式流程畫成圖之後數獨立迴路有幾個。

聽起來很抽象很學術，實際上就是數分支啦。%(´,,•ω•,,)%

從 1 開始算，每遇到一個決策點就 +1：

* `if`、`else if`
* `for`、`while`、`do...while`
* `case`（每一個都算）
* `catch`
* 三元運算子 `? :`
* 邏輯運算子 `&&`、`||`、`??`
* 選擇性串連 `?.`

最多人搞錯 `else` 與 `default`，這兩個都不算。

看個例子。

```ts
function calcShippingFee(order: Order) { // 起手 1
  if (order.vip) { // +1 → 2
    return 0
  }
  if (order.total > 1000) { // +1 → 3
    return 0
  }
  if (order.couponCode && order.total > 500) { // +2 → 5
    return 30
  }
  return 60
}
```

5 分。畫成圖就很清楚，確實有五條走得完的路。

```mermaid
---
title: calcShippingFee 的五條路
---
flowchart TD
    S((進入)) --> A{vip}
    A --是--> R1[/回傳 0/]
    A --否--> B{total 大於 1000}
    B --是--> R2[/回傳 0/]
    B --否--> C{有 couponCode}
    C --否--> R4[/回傳 60/]
    C --是--> D{total 大於 500}
    D --是--> R3[/回傳 30/]
    D --否--> R4
```

至於 `else`，加了也不會變。

```ts
function calcShippingFeeWithElse(order: Order) { // 起手 1
  if (order.vip) { // +1 → 2
    return 0
  }
  else { // 不算
    return 60
  }
}
```

只有 2 分。`if` 早就把路岔成兩條了，`else` 只是替其中一條取名字。%(ゝ∀・)b%

## 三十秒掃出自己專案的排行榜

ESLint 內建 `complexity` 規則，什麼都不用裝。

```js
// eslint.config.mjs
rules: {
  complexity: ['warn', { max: 10, variant: 'modified' }],
}
```

`variant` 是 ESLint 9.12 之後才有的選項，差別只在 `switch`。classic 模式每個 `case` 都 +1，一個十路 `switch` 直接 11 分起跳，可是那種扁平的對照表其實超好讀，被誤殺很冤。modified 模式把整個 `switch` 算成 1 分。

實測同一份程式碼：

| 寫法 | classic | modified |
|---|---|---|
| 三個 `if`（其中一個帶 `&&`） | 5 | 5 |
| 五個 `case` 加 `default` 的 `switch` | 6 | 2 |

不想動設定檔的話，臨時加規則跑一次也可以。

```bash
npx eslint . --rule '{"complexity":["warn",{"max":10,"variant":"modified"}]}'
```

規則設 warn 不設 error，讓它當雷達用，只把超標的函式標出來。設成 error 就變成閘門，超標直接擋下 CI。

我拿酷酷元件跑了一輪，45 個函式超標，前五名長這樣。

| 函式 | 分數 |
|---|---|
| `compileCreasePattern` | 61 |
| `createStem` | 39 |
| `createStemList` | 29 |
| `btn-attention-seeker` 的 watch | 27 |
| `updateAndRender` | 25 |

一掃下去，酷酷元件的程式碼我寫得有多隨便，馬上就露餡了。%(◐‿◑)%

不過光看這一欄其實沒什麼鑑別度，`complexity` 最大的罩門在於它對巢狀沒感覺。

\~~不是因為他腳麻~~，是因為深度要交給 `cognitive-complexity`。%(´・ω・\`)%

三個平行的 `if` 跟三層巢狀的 `if` 同樣都是 4 分，可是後者糾纏得多。

加上 `eslint-plugin-sonarjs`，計算認知複雜度（Cognitive Complexity），它會對巢狀加權，越深加越重。

```js
// eslint.config.mjs
rules: {
  'complexity': ['warn', { max: 10, variant: 'modified' }],
  'sonarjs/cognitive-complexity': ['warn', 15],
}
```

兩欄一起量，就拿排行榜第四名那段 watch 開刀，圈複雜度 27、認知複雜度 5、最深巢狀 2、只有 28 行。

## 案例：27 分的 watch

[btn-attention-seeker](https://chillcomponent.codlin.me/components/btn-attention-seeker/) 是一顆很有事的按鈕，滑鼠靠近會湊過來，卡到視窗上下緣時會探個頭出來刷存在感。

它的核心是這段 watch。

```ts
watch(() => [distanceToFrame, frameBounding], () => {
  // 視窗邊界探頭
  if (isBoundary.value) {
    if (frameBounding.bottom < props.topOffset) {
      carrierPositionAnimatable?.x?.(0)
      carrierPositionAnimatable?.y?.(frameBounding.bottom * -1 + props.topOffset + frameBounding.height * 0.75)
      carrierPositionAnimatable?.rotate?.(-10)
      return
    }
    else if (frameBounding.top > (windowSize.height - props.bottomOffset)) {
      carrierPositionAnimatable?.x?.(0)
      carrierPositionAnimatable?.y?.(
        windowSize.height - frameBounding.top - frameBounding.height * 0.75 + props.bottomOffset,
      )
      carrierPositionAnimatable?.rotate?.(10)
      return
    }
  }

  if (isFollowing.value) {
    const x = frameWithMouse.elementX - frameWithMouse.elementWidth / 2
    const y = frameWithMouse.elementY - frameWithMouse.elementHeight / 2

    carrierPositionAnimatable?.x?.(x)
    carrierPositionAnimatable?.y?.(y)
    return
  }

  carrierPositionAnimatable?.x?.(0)
  carrierPositionAnimatable?.y?.(0)
  carrierPositionAnimatable?.rotate?.(0)
}, { deep: true })
```

可是這裡只有四個 `if`。認知複雜度更怪，只有 5 分。

27 對 5，代表這段程式的結構其實很扁平，分數卻高得嚇人。

那 22 分的落差是哪來的？%ლ（´口\`ლ）%

我把所有 `?.` 換成直接呼叫再量一次，圈複雜度立刻剩個位數。

答案是 `carrierPositionAnimatable?.x?.()` 這種選擇性串連。

一開始我覺得指標在亂哀，想想好像也不算。%(́⊙◞౪◟⊙‵)%

`?.` 真的是分支，左邊是 `null` 就整條短路。

而這串三行的動畫呼叫，在同一個函式裡重複了四遍，所以問題點其實是多處重複。%(°ㅂ°)%

那就改善重複問題，讓每一段只負責算出目標位置，最後統一送給動畫。

```ts
interface Position { x: number; y: number; rotate: number }

const HOME_POSITION: Position = { x: 0, y: 0, rotate: 0 }

/** 探頭：視窗上下緣被遮住時，把按鈕推回可視範圍 */
function calcPeekPosition(): Position | undefined {
  if (frameBounding.bottom < props.topOffset) {
    return {
      x: 0,
      y: frameBounding.bottom * -1 + props.topOffset + frameBounding.height * 0.75,
      rotate: -10,
    }
  }

  if (frameBounding.top > windowSize.height - props.bottomOffset) {
    return {
      x: 0,
      y: windowSize.height - frameBounding.top - frameBounding.height * 0.75 + props.bottomOffset,
      rotate: 10,
    }
  }
}

/** 跟隨：滑鼠靠近時，按鈕往滑鼠方向偏移 */
function calcFollowPosition(): Position | undefined {
  if (!isFollowing.value) {
    return
  }

  return {
    x: frameWithMouse.elementX - frameWithMouse.elementWidth / 2,
    y: frameWithMouse.elementY - frameWithMouse.elementHeight / 2,
    rotate: 0,
  }
}

function updateCarrierPosition() {
  const { x, y, rotate } = calcPeekPosition() ?? calcFollowPosition() ?? HOME_POSITION

  carrierPositionAnimatable?.x?.(x)
  carrierPositionAnimatable?.y?.(y)
  carrierPositionAnimatable?.rotate?.(rotate)
}
```

重新量一次：

| 函式 | 圈複雜度 | 認知複雜度 |
|---|---|---|
| `updateCarrierPosition` | 9 | 0 |
| `calcPeekPosition` | 3 | 2 |
| `calcFollowPosition` | 2 | 1 |

程式碼變多了，可是四段重複的動畫呼叫收斂成一處，主線變成一行 `??` 串接，兩欄分數也一起掉到個位數。%( •̀ ω •́ )✧%

## AI 都幫我寫好了，還需要這個數字嗎

當初發明圈複雜度，很大一部分理由是人腦一次裝不下太多東西。接下來直接假設最極端的情況，**程式完全交給 AI 寫，沒有人會再打開那個檔案**。「人讀不動」這條理由不再成立，還有其他理由嗎？%( ・ิω・ิ)%

把問題丟給 AI，它講得頭頭是道，複雜度越高越容易改壞別的分支、每次只塞一個 `if` 最後會疊成爛攤子。AI 最擅長瞎掰道理，還是實際實驗看看。%ԅ( ˘ω˘ԅ)%

### 十二個專案，跑二十週

題目是完整的訂單伺服器，NestJS 加 SQLite。12 個專案隨機分成三組，CLAUDE.md 是唯一變因。最小改動派不用任何指標，只做需求要求的事；自律派也不用指標，每次做完要把整份 src 整理到自己滿意；指標派設圈複雜度 10、認知複雜度 15 當門檻，超標 CI 就紅，不准調高也不准略過。

每週開一個全新的 Claude Sonnet 5（2026 年 9 月透過 Claude Code 啟動），只給它專案資料夾、CLAUDE.md 與當週需求，上週的測試我也收走，做完跑 `npm run ci` 就結束，錯了不修也不提示。

關鍵機制叫**全域慣例**。前六週各立一條「之後新增的每一個 X 都適用」的慣例，像是寫入要留稽核紀錄、刪除一律軟刪除、有狀態的資源要有歷程路由。第 7 週起不斷加新資源，需求文件**一次都不再提起這些慣例**。CLAUDE.md 只提醒「有這種全域規則，之後不會再講」，沒有列出是哪幾條，AI 得自己從既有程式碼找出來。

評分不靠人工計算。另外維護一份參考伺服器當標準答案，每週產生 400 條固定種子的請求序列，逐個呼叫比對狀態碼與回應內容，二十週合計 96000 條。

### 結果：錯了，可是錯在別的地方 %(́⊙◞౪◟⊙‵)%

前四週三組全對，第 5 週開始失誤，第 6 週起 12 個專案週週都有失誤。扣最多分的全是新資源缺少的歷程路由與 `includeDeleted`，三組扣分的地方幾乎一樣；每週明寫在需求裡的路由、欄位、錯誤碼，三組幾乎全做對，240 次交件裡沒有一次把上週做對的東西改壞。

**這些洞沒有一個跟複雜度有關。** 全是加新資源時忘了接上舊慣例，函式太糾纏所以改壞的那一種，二十週一次都沒發生，門檻壓到 5 也擋不掉。%( ˙꒳​˙)%

漏與不漏的規律很清楚。稽核做成守衛、重播檢查做成攔截器，這兩種都是每個請求進來會自動經過的一層，不用每條路由各自呼叫；分頁做成共用函式。新路由都自動套用這幾條，二十週零錯誤。反過來，歷程路由、`includeDeleted` 這種要在每個新資源各接一次線的，三組全滅。會不會漏，取決於慣例能不能做成機制，跟函式多複雜無關。

自律派的準則要求它每週重讀整份 src，三組裡就屬它最接近「回頭檢查」，漏掉的東西照樣跟另外兩組一模一樣。連每週把程式碼從頭讀一遍都救不回來，靠複雜度門檻更不可能。%(´・ω・\`)%

### 那門檻到底有沒有用？還是測不到

前八週表面上指標派贏了，不符數只有最小改動派的 0.61 倍。可是三組漏掉同樣五個洞，每個專案的不符總數只有 786 或 277 兩種值，差別只在有沒有多漏其中一個。0.61 其實只是「多漏的專案三個對一個對一個」，四個樣本跟擲硬幣沒兩樣。%(´・ω・\`)%

更根本的問題是**門檻幾乎沒有東西可擋**，沒設門檻的兩組八週合計 64 次交件只有 11 次寫出超標函式，指標派幾乎沒有需要重構的時候。前八週的比值講不了什麼。

後半段就不一樣了。程式碼長到五千行之後，最小改動派 80 次交件裡超標 46 次、自律派 45 次，指標派 0 次，它的 CI 二十週沒紅過，門檻對它一直是事前的約束，不曾當過事後的閘門。指標派的圈複雜度全程停在 9，最小改動派最高衝到 19、認知複雜度 29。形狀差到這種程度，正確率呢？

| 週次 | 最小改動派 | 自律派 | 指標派 | 指標派對最小改動派 |
|---|---|---|---|---|
| 第 1 到 8 週 | 2635 | 1729 | 1617 | 0.61 |
| 第 9 到 20 週 | 14563 | 13384 | 13017 | 0.89 |

另外兩組天天超標之後，比值反而從 0.61 走到 0.89，往「沒有差別」的方向跑。而且後半段剩下的差距也跟門檻無關。到第 20 週，每個專案不符的序列有八成是前幾週漏掉的洞照常扣分，剩下的差距集中在四個專案的兩個洞，都跟慣例無關，最小改動派有兩個專案忘了替商品的版本號加一，指標派有兩個專案算錯訂單狀態。只算漏掉慣例造成的不符，後半段指標派對最小改動派是 0.97。%(´・ω・\`)%

門檻管得住最大值，管不住總量。指標派的函式數比最小改動派多兩成二、行數多 9%，圈複雜度總和 976.5 看起來也是三組最高，可是每個函式起手就有 1 分，扣掉起手分後三組是最小改動派 459.5、自律派 425、指標派 446.5，幾乎一樣。門檻把大函式切小，分支總量沒有變少，只是攤到更多函式。成本三組一樣，指標派的總 token 只比最小改動派多 2%，最貴的反而是每週重讀整份 src 的自律派。而自律派的圈複雜度也只壓到 13.5，離門檻的 10 還很遠，叫 AI 自己判斷，專案一大就不管用了。%(›´ω\`‹ )%

### 讀結論前先打折

這個實驗有幾個地方要先講清楚。%(´・ω・\`)%

* **沒有測「把慣例寫進 CLAUDE.md」這一組。** 現實裡最便宜的做法就是列在 CLAUDE.md，這裡刻意不列才逼得出遺漏，所以「AI 會漏舊慣例」只在沒人把慣例寫下來的前提下成立。
* **複雜度最高只到 38。** 這次最小改動派二十週最高只到圈複雜度 19、認知 29，NestJS 的 controller、service、DTO 分層本身就是一道隱性門檻。前幾批純函式的題目有爬到 38，同樣零錯誤。前面那支 61 分的函式從沒出現過，所以「複雜度不影響 AI 正確率」只在 38 分以下有資料。
* **只跑到第 20 週。** 原本設計裡最可能讓「函式太糾纏所以改壞」發生的，是第 24、26 週那種回頭改舊行為的需求，這次沒跑到，「沒有一次改壞上週做對的東西」這句話的份量要跟著打折。
* **第 9 到 20 週是看過前八週結果才決定延長的。** 那一段只能當觀察，不能拿來下定論。
* **兩次環境洩漏。** 第 1 週專案資料夾放在實驗的 git repo 裡，`git show` 讀得到參考伺服器；第 17 週有一位受試者用 grep 看到需求與參考的檔案路徑。兩位都自述沒有進一步查看，細節都在報告裡。

完整設計與每週資料都在[實驗報告](https://github.com/Codfisher/cod-aquarium/blob/main/docs/cyclomatic-complexity-in-the-ai-era.md)。

## 別人的研究怎麼說

我的實驗有三個發現，逐一去翻論文對照。%(´・ω・\`)%

**發現一，有沒有門檻，AI 寫錯的機率量不出差別。** 論文跟這個一致。[Pan 等人](https://arxiv.org/abs/2508.13666)（ICSE 2026）把程式碼的縮排、空白、換行全部拔掉再餵給十個模型，答對率最多只掉 4.2%，模型不太在意程式長什麼樣子。[Xie 等人](https://arxiv.org/abs/2602.07882)（ICML 2026）直接檢驗圈複雜度這類傳統指標能不能預測 LLM 覺得一段程式難不難，結論是沒有一致的關聯。[Ashrafi](https://arxiv.org/abs/2606.00308) 讓六種架構的 AI 代理人寫同一批題目，寫出來的複雜度差了 50% 到 130%，答對率卻沒差。三篇的結論一樣，圈複雜度只能反映人讀起來多累，跟 AI 會不會寫錯無關。

**發現二，明寫的需求不會錯，不再重述的舊慣例會穩定遺漏。** 這一點文獻講得比我更清楚。[Codified Context](https://arxiv.org/abs/2602.20478) 直接指出 AI 代理人沒有跨場次的記憶，每一場都從零開始，忘記專案慣例、重犯已知錯誤。[20574 場真實開發場次的分析](https://arxiv.org/abs/2605.29442)發現 41% 的回合使用者得回頭糾正它，而九成以上的問題要等到人明講才解得掉。[RoadmapBench](https://arxiv.org/abs/2605.15846) 用真實的版本升級當題目，中位數要改 51 個檔案 3700 行，Claude Opus 4.7 只解得掉 39.1%，常見的失敗是完成一部分目標之後卡在整合。我這個實驗把同一件事做得更乾淨，慣例都寫在需求裡、AI 也讀過，隔幾週新資源出現時照樣漏掉。

**發現三，沒有門檻，複雜度就會往上跑。** 最小改動派爬到 16，自律派 13.5，指標派二十週都停在 9。2026 年的 [SlopCodeBench](https://arxiv.org/abs/2603.24755) 跟這個實驗最像，讓 15 個 AI 代理人在 196 個檢查點反覆擴充自己的程式碼，判定結構劣化的門檻剛好也是圈複雜度 10。沒有任何指引時，77% 的專案越跑越劣化；加一段品質指引，劣化少了 57.6%，成本只多 12.1%。劣化歸劣化，答對率沒有跟著掉，這一半跟我「形狀變了、正確率沒變」的結果一樣。另一半我沒複現。那段品質指引在我這裡就是自律派的準則，可是專案長到五千行之後，自律派的複雜度壓不到門檻以內，八十次交件裡照樣超標 45 次。

| 我的發現 | 論文 | 對照 |
|---|---|---|
| 有沒有門檻，正確率量不出差別 | 傳統複雜度指標與 LLM 表現沒有一致關聯 | 一致 |
| 明寫的需求不會錯 | 九成以上的問題要人明講才解得掉 | 一致 |
| 不再重述的舊慣例會漏掉 | 代理人沒有跨場次記憶，忘記專案慣例 | 一致 |
| 一段文字指引就能壓住劣化 | 77% 專案劣化，一段指引降 57.6% | 我沒複現，專案一大就失效 |

回到標題，AI 都幫我寫好了，還需要管複雜度嗎？拆成三個問題才答得準。

* **能不能讓 AI 少寫錯？量不到。** 我的實驗跟論文都量不到關聯。AI 只會在加新功能時漏掉幾週前立的規矩，這種錯跟函式多複雜無關，另外兩組天天超標之後差距反而更小。要擋這種錯，得把規矩做成攔截器，或者一開始就寫進 CLAUDE.md，門檻幫不上忙。
* **能不能防止程式越疊越亂？能，管得住最大值。** 設門檻那組二十週沒有一次超標，另外兩組後半段週週超標。只是分支總量沒有變少，程式碼反而更多。
* **人還讀不讀得懂？這一條完全沒變。** 圈複雜度本來就是為人設計的，論文沒有推翻這一點，前面幾節那套判斷照用。

## 總結 🐟

AI 都幫我寫好了，還需要管複雜度嗎？結論是看有沒有人要讀那份程式碼。%(´・ω・\`)%

* **有人要讀，就要管，方法照舊。** 圈複雜度就是數分支，`else` 不算，`?.` 與 `&&` 都算，ESLint 三十秒掃出整個專案的排行榜；它對巢狀沒感覺，要搭配認知複雜度一起看，兩欄一起高才代表真的糾纏。
* **沒有人要讀，門檻有沒有用還量不到。** 十二個專案跑二十週，設門檻的那組程式碼最整齊，漏掉的規矩卻跟另外兩組一模一樣；會因為函式太糾纏而改壞的那種錯，二十週一次都沒發生，門檻擋不擋得住也無從量起。
* **AI 錯在別的地方，門檻擋不到。** 它幾乎不會把明寫的需求做錯，也不曾因為函式太長改壞東西，只會在加新功能時漏掉幾週前立的規矩；要擋這種錯，得把規矩做成攔截器。
* **門檻留著不虧，別指望它擋錯。** 它壓得住最大複雜度，程式碼雖然多一成，token 沒有跟著多，也沒有多錯；它只是把分支分散到更多函式，總量不會變少。

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。%( ´ ▽ \` )ﾉ%

---

---
url: /aquarium/beybattle.md
description: 組裝你的戰鬥陀螺，挑戰 AI 對手！
---


---

---
url: /aquarium/codstack.md
description: 在網頁上組裝 3D 模型像疊積木一樣簡單 (・∀・)９
---


---

---
url: /column-cod-toys/01-origin.md
description: '沒有順手的小工具怎麼辦？用 Electron 動手做一個吧！(´,,•ω•,,)'
---

![快樂堆積木的魚](/cod-toys.webp){.cover}

# CodToys - EP01：緣起

自己寫文章時習慣在文字中穿插顏文字。%( •̀ ω •́ )✧%

最近較常寫文章分享，輸入顏文字的次數也越來越多了。

雖然 Windows 可以按下「Window + .」也可以快速選擇顏文字

但是身為資深顏文字愛好者，一定有自己的顏文字庫啊！

於是萌生了自己做一個鍵盤快捷鍵小工具的念頭，此專案就這麼誕生了。%ԅ(´∀\` ԅ)%

讓我們搶先看一下成果！%ˋ( ° ▽、° )%

![shortcut-key-selection-options](/cod-toys/shortcut-key-selection-options.gif)

路人：「聽說現在年輕一輩沒人在用顏文字的捏。('◉◞⊖◟◉\` )」

鱈魚：「我就老，我就是要用。ᕕ( ﾟ ∀。)ᕗ 」

## 背景

開始前來簡單了解一下相關背景。

* PowerToys

  [PowerToys](https://learn.microsoft.com/zh-tw/windows/powertoys/) 是微軟釋出的開源專案，提供了一系列實用功能。例如：[顏色選擇器](https://learn.microsoft.com/zh-tw/windows/powertoys/color-picker)、[找不到命令](https://learn.microsoft.com/zh-tw/windows/powertoys/cmd-not-found)等等。

  其中 [PowerToys Run](https://learn.microsoft.com/zh-tw/windows/powertoys/run) 工具是我們的主要靈感來源，本專案~~抄襲~~借鑑其設計。

* Electron

  [Electron](https://www.electronjs.org/) 是一個可以用 HTML、CSS、JavaScript 建立跨平台桌面應用程式的框架。

  此框架由 GitHub 開發，有許多知名應用程式也用 Electron 開發，例如：[VS Code](https://code.visualstudio.com/)、[Slack](https://slack.com/)、[Discord](https://discord.com/) 等等。

## 特點

目前主要功能規劃與特點如下：

* 鍵盤優先

  呼叫工具、選擇功能皆使用鍵盤操作，盡可能在不中斷輸入的情況下快速使用

* 關鍵字搜尋

  根據輸入的關鍵字過濾，提供候選功能

* 功能：顏文字資料庫

  從 Notion Database 取得顏文字資料，選擇後複製至剪貼簿

介面則模仿 [PowerToys Run](https://learn.microsoft.com/zh-tw/windows/powertoys/run) 的啟動器，按下 `Ctrl + Space` 就會跳出類似下圖輸入框。

![power-toys-run](/cod-toys/power-toys-run.png)

讓我們開始吧！%( •̀ ω •́ )✧%

## 開發

專案基於以下技術或套件開發：

* Vue 3、Pinia
* [VueUse](https://vueuse.org/functions.html)
* [unplugin-vue-router](https://github.com/posva/unplugin-vue-router)
* [UnoCSS](https://unocss.dev/)
* [Quasar](https://quasar.dev/)
* [Electron](https://www.electronjs.org/)

### 在現有 Vue 專案中加入 Electron

雖然官方推薦使用 [Electron Forge](https://www.electronforge.io/) 建立專案，不過我已經有一個設定完成的 Vue 模板，所以這次使用 `vite-plugin-electron` 來整合 Electron。

步驟沒什麼特別的部分，基本上完全依照[文件](https://github.com/electron-vite/vite-plugin-electron)操作。

一陣猛如虎的操作後，我們得到了[初始環境](https://github.com/Codfisher/side-project-cod-toys/tree/init)！%ˋ( ° ▽、° )%

### 開啟視窗

第一步當然是先做一個簡單的輸入框。

`src\pages\index.vue`

```vue
<template>
  <div class="flex-col">
    <q-input
      v-model="inputValue"
      placeholder="要來點甚麼？...(´,,•ω•,,)"
      autofocus
      outlined
      square
    >
      <template #prepend>
        <q-icon name="search" />
      </template>
    </q-input>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const inputValue = ref('')
</script>
```

接著讓我們啟動 Electron 魔法，把網頁變成應用程式視窗！%◝( •ω• )◟%

`electron\main.ts`

```ts
import process from 'node:process'
import {
  app,
  BrowserWindow,
} from 'electron'

async function createInputWindow() {
  const newWindow = new BrowserWindow({
    width: 400,
    height: 100,
    backgroundColor: '#fff',
    frame: false,
    resizable: false,
  })
  // 隱藏預設系統選單
  newWindow.setMenu(null)

  if (process.env.VITE_DEV_SERVER_URL) {
    await newWindow.loadURL(process.env.VITE_DEV_SERVER_URL)
  }
  else {
    await newWindow.loadFile('dist/index.html')
  }

  return newWindow
}

let mainWindow: BrowserWindow | undefined

app.whenReady().then(async () => {
  mainWindow = await createInputWindow()
})

// 當所有視窗關閉時退出應用程式
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})
```

`BrowserWindow` 表示一個視窗，就像是開啟一個網頁一般。

`app.whenReady` 則表示在應用程式準備好時執行。

現在讓我們執行 `npm run dev` 看看效果吧！

![first-window](/cod-toys/first-window.png)

輸入框出現惹！%(/≧▽≦)/%

### 綁定全域快捷鍵

接著是最重要的一步，要綁定全域快捷鍵，當按下 `Ctrl + Space` 時顯示視窗。

這裡需要使用 [`globalShortcut` 模組](https://www.electronjs.org/docs/latest/api/global-shortcut)。

此模組可以註冊全域快捷鍵，即使視窗沒有聚焦，依然可以執行已註冊的按鍵事件。

一開始先保持簡單，按鍵組合先寫死 `Ctrl + Space`，未來有需要再加入設定功能。

`electron\main.ts`

```ts
// ...

async function createInputWindow() {
  const display = screen.getPrimaryDisplay()

  const newWindow = new BrowserWindow({
    // 設為螢幕寬度的三分之一
    width: display.bounds.width / 3,
    height: 100,
    // 一開始隱藏視窗
    show: false,
    // ...
  })

  // ...
}

let mainWindow: BrowserWindow | undefined

app.whenReady().then(async () => {
  mainWindow = await createInputWindow()

  const ret = globalShortcut.register('Ctrl+Space', () => {
    if (!mainWindow)
      return

    if (mainWindow?.isVisible()) {
      mainWindow.hide()
      return
    }

    mainWindow.show()
  })

  if (!ret) {
    console.error('registration failed')
  }
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }

  globalShortcut.unregisterAll()
})
```

現在讓我們按按看 `Ctrl + Space`。

![shortcut-open-window](/cod-toys/shortcut-open-window.gif)

可以看到視窗出現與隱藏了！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

現在讓我們加上一些小細節：

* 視窗失去焦點時自動隱藏視窗
* 視窗會出現在滑鼠所在螢幕中往上 1/3 處
* 視窗隱藏後，會自動回復焦點到原本的視窗，這樣才可以繼續輸入

`electron\main.ts`

```ts
// ...

async function createInputWindow() {
  // ...
  newWindow.setMenu(null)

  // 失去焦點時自動隱藏視窗
  newWindow.on('blur', () => {
    newWindow.hide()
  })

  // ...
}

app.whenReady().then(async () => {
  mainWindow = await createInputWindow()

  const ret = globalShortcut.register('CmdOrCtrl+Space', () => {
    if (!mainWindow)
      return

    if (mainWindow?.isVisible()) {
      // focusable 設為 false，才可以讓焦點回到原本位置。例如正在輸入的編輯器
      mainWindow.setFocusable(false)
      mainWindow.hide()

      return
    }

    // 取得滑鼠所在螢幕
    const cursorPoint = screen.getCursorScreenPoint()
    const display = screen.getDisplayNearestPoint(cursorPoint)

    // 設定滑鼠位置之視窗中間往上 1/3 的位置
    const [width, height] = mainWindow.getSize()
    mainWindow?.setPosition(
      Math.floor(display.bounds.x + display.bounds.width / 2 - width / 2),
      Math.floor(display.bounds.y + display.bounds.height / 3 - height / 2),
    )

    mainWindow.setFocusable(true)
    mainWindow.show()
  })

  // ...
})

// ...
```

![auto-refocus](/cod-toys/auto-refocus.gif)

可以注意到開關輸入框，並不會影響原本的輸入焦點。

看起來是不是很有模有樣啊！%੭ ˙ᗜ˙ )੭%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/side-project-cod-toys/tree/feat/global-shortcut)

* 使用 Electron 開發桌面應用程式
* `globalShortcut` 可以綁定全域快捷鍵

下一章讓我們來實作候選功能的部分吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-cod-toys/02-feature-card.md
description: 上一章節我們完成了快捷鍵開關視窗功能，這一章節我們來實作功能選項部分吧！
---

![快樂堆積木的魚](/cod-toys.webp){.cover}

# CodToys - EP02：功能選項

上一章節我們完成了快捷鍵開關視窗功能，這一章節我們來實作功能選項部分吧！

## 開發

本章節預計會建立以下內容：

* 輸入候選：在輸入框輸入內容時，會顯示候選功能選項
* 功能選項：提供使用者選擇功能，且可以透過滑鼠或鍵盤選擇
* 建立「搜尋顏文字、Google 搜尋」功能

### 功能選項元件

第一步讓我們新增功能選項元件

`src\components\feature-option.vue`

```vue
<template>
  <div
    ref="optionRef"
    class="flex items-center gap-2 duration-300"
    :class="{ 'bg-primary/30': selected }"
    @click="props.action()"
  >
    <q-icon
      v-if="props.icon"
      :name="props.icon"
      size="1.5rem"
    />
    <slot>
      {{ props.text }}
    </slot>
  </div>
</template>

<script setup lang="ts">
import { useElementHover } from '@vueuse/core'
import { computed, ref } from 'vue'

interface Props {
  icon?: string;
  text?: string;
  action?: () => void;
}
const props = withDefaults(defineProps<Props>(), {
  action: () => () => { },
})

defineSlots<{
  default?: () => unknown;
}>()

const optionRef = ref<HTMLDivElement>()
const isHover = useElementHover(optionRef)
const selected = computed(() => isHover.value)
</script>
```

此元件負責呈現可用的功能選項，並且可以透過 `action` 來設定點擊後的行為。

滑鼠 `hover` 或使用鍵盤選擇時，會變更背景色，這裡預留 `selected`，晚點來實作鍵盤導航功能。

在使用 `feature-option` 元件前，先讓我們封裝一下目前的輸入框元件。

`src\components\main-input.vue`

```vue
<template>
  <q-input
    v-model="inputText"
    placeholder="要來點甚麼？...(´,,•ω•,,)"
    autofocus
    outlined
    square
  >
    <template #prepend>
      <q-icon name="search" />
    </template>
  </q-input>
</template>

<script setup lang="ts">
const inputText = defineModel({ default: '' })
</script>
```

最後在首頁中引入 `feature-option` 與 `main-input` 元件。

`src\pages\index.vue`

```vue
<template>
  <div class="flex-col">
    <main-input v-model="inputText" />

    <div class="flex-col">
      <feature-option
        text="選項 1"
        class="p-4"
      />
      <feature-option
        text="選項 2"
        class="p-4"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import FeatureOption from '../components/feature-option.vue'
import MainInput from '../components/main-input.vue'

const inputText = ref('')
</script>
```

看起來是不是乾淨很多呢？%ヾ(◍'౪\`◍)ﾉﾞ%

現在讓我們打開視窗。

![feature-option](/cod-toys/feature-option.png)

...會發現「選項 2」被切掉啦！%Σ(ˊДˋ;)%

這是因為視窗高度沒有隨著內容增加而增加，讓我們來修正一下吧。

### 自動調整視窗高度

由於視窗由 main process 控制，我們需要讓視窗與 main process 通訊並調整視窗大小。

使用 `preload.ts` 來對 renderer process，也就是網頁視窗提供直通 main process 的 API 吧。

::: tip 甚麼 process？(\*´･д･)
Electron 基於 multi-process 架構，[詳細請參考官方文件](https://www.electronjs.org/docs/latest/tutorial/process-model)。
:::

`electron\preload.ts`

```ts
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('main', {
  updateHeight(height: number) {
    return ipcRenderer.send('updateHeight', height)
  },
  hideWindow() {
    return ipcRenderer.send('hideWindow')
  },
})
```

[`ipcRenderer`](https://www.electronjs.org/docs/latest/api/ipc-renderer) 模組提供了 `send` 方法，可以將事件發送到 main process。

[`contextBridge`](https://www.electronjs.org/docs/latest/api/context-bridge) 模組則負責將 `main` 物件注入在 window 中，我們可以在網頁中使用 `window.main` 來呼叫 main process 的方法。

接著我們要在 main process 中接收這些事件，使用 `ipcMain` 模組來收聽事件，順便重構一下 main 程式碼。

`electron\main.ts`

```ts
import path from 'node:path'
import process from 'node:process'
import {
  app,
  BrowserWindow,
  globalShortcut,
  ipcMain,
  screen,
} from 'electron'

async function createInputWindow() {
  const display = screen.getPrimaryDisplay()

  const newWindow = new BrowserWindow({
    width: display.bounds.width / 3,
    height: 100,
    show: false,
    backgroundColor: '#fff',
    frame: false,
    resizable: false,
    webPreferences: {
      preload: path.join(__dirname, './preload.js'),
    },
  })
  // 隱藏預設系統選單
  newWindow.setMenu(null)

  // 失去焦點時自動隱藏視窗
  newWindow.on('blur', () => {
    newWindow.hide()
  })

  if (process.env.VITE_DEV_SERVER_URL) {
    await newWindow.loadURL(process.env.VITE_DEV_SERVER_URL)
  }
  else {
    await newWindow.loadFile('dist/index.html')
  }

  return newWindow
}

function initGlobalShortcut(mainWindow: BrowserWindow) {
  const ret = globalShortcut.register('Ctrl+Space', () => {
    if (mainWindow?.isVisible()) {
      // focusable 設為 false，才可以讓焦點回到原本位置。例如正在輸入的編輯器
      mainWindow.setFocusable(false)
      mainWindow.hide()

      return
    }

    const cursorPoint = screen.getCursorScreenPoint()
    const display = screen.getDisplayNearestPoint(cursorPoint)

    // 設定滑鼠位置之視窗中間往上 1/3 的位置
    const [width, height] = mainWindow.getSize()
    if (!width || !height)
      return

    mainWindow?.setPosition(
      Math.floor(display.bounds.x + display.bounds.width / 2 - width / 2),
      Math.floor(display.bounds.y + display.bounds.height / 3 - height / 2),
    )

    mainWindow.setFocusable(true)
    mainWindow.show()
  })

  if (!ret) {
    console.error('registration failed')
  }
}

function initIpcMain(mainWindow: BrowserWindow) {
  ipcMain.on('updateHeight', (event, height: number) => {
    mainWindow.setBounds({ height })
  })

  ipcMain.on('hideWindow', (event) => {
    mainWindow.setFocusable(false)
    mainWindow.hide()
  })
}

app.whenReady().then(async () => {
  const mainWindow = await createInputWindow()

  initGlobalShortcut(mainWindow)
  initIpcMain(mainWindow)
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }

  globalShortcut.unregisterAll()
})
```

現在我們需要在網頁中使用 `mainApi`，既然是 TypeScript 專案，第一步當然是定義型別啦。

`electron\electron-env.d.ts`

```ts
export interface MainApi {
  updateHeight: (height: number) => void;
  hideWindow: () => void;
}

declare global {
  interface Window {
    main: MainApi;
  }
}

export { }
```

接著把 `contextBridge` 模組注入的 `main` 物件透過 Composition API 形式提供，保留未來更動彈性。

`src\composables\use-main-api.ts`

```ts
/** 提供 Electron main process API */
export function useMainApi() {
  return window.main
}
```

現在讓視窗根據內容高度自動調整，使用 `useElementBounding` 輕鬆完成！%ヽ(●\`∀´●)ﾉ%

```vue
<template>
  <div
    ref="pageRef"
    class="flex-col"
  >
    // ...
  </div>
</template>

<script setup lang="ts">
const mainApi = useMainApi()

const inputText = ref('')

// 同步視窗與頁面高度
const pageRef = ref<HTMLDivElement>()
const { height } = useElementBounding(pageRef)

watchEffect(() => {
  mainApi.updateHeight(height.value)
})
</script>
```

現在開啟視窗，可以看到這次選項 2 順利出現了。

![window-auto-resize](/cod-toys/window-auto-resize.png)

最後我們把原本在 `main.ts` 中的「視窗 blur 時自動隱藏視窗」的邏輯移到首頁中，方便未來依頁面需求自定義。

`electron\main.ts`

```ts
// ...
async function createInputWindow() {
  // ...

  // 失去焦點時自動隱藏視窗 // [!code --]
  newWindow.on('blur', () => { // [!code --]
    newWindow.hide() // [!code --]
  }) // [!code --]

  // ...
}
// ...
```

所以網頁中要怎麼判斷視窗是否 blur？%(´･ω･\`)%

其實很簡單，透過 `useWindowFocus` 輕鬆實現！

`src\pages\index.vue`

```vue
<template>
  // ...
</template>

<script setup lang="ts">
// ...

// 視窗 blur 時，清空 inputText 並隱藏視窗
const focused = useWindowFocus()
whenever(
  () => !focused.value,
  () => {
    inputText.value = ''
    mainApi.hideWindow()
  },
)
</script>
```

感恩 VueUse！讚嘆 VueUse！(\*´∀\`)~♥

### 鍵盤導航

選項有了，那就來實作鍵盤導航功能吧。

這裡讓 `feature-option` 元件註冊自己的 ID，透過 ID 選擇可用的 option。

建立一個 `feature.store.ts` 來管理並註冊 option。

`src\stores\feature.store.ts`

```ts
import { defineStore } from 'pinia'
import { pipe, sortBy } from 'remeda'
import { computed, ref, shallowRef, triggerRef } from 'vue'

interface OptionValue {
  action: () => void;
}

export const useFeatureStore = defineStore('feature', () => {
  const optionMap = shallowRef(new Map<string, OptionValue>())
  const optionIdList = computed(() => pipe(
    [...optionMap.value.keys()],
    /** 依照數字排序，保證 option 順序 */
    sortBy((id) => Number.parseInt(id.replace(/\D/g, ''), 10)),
  ))

  function addOption(id: string, value: OptionValue) {
    optionMap.value.set(id, value)
    triggerRef(optionMap)
  }
  function removeOption(id: string) {
    optionMap.value.delete(id)
    triggerRef(optionMap)
  }

  const selectedOptionId = ref('')
  function setOption(id: string) {
    selectedOptionId.value = id
  }
  function nextOption() {
    const first = optionIdList.value.at(0)

    const index = optionIdList.value.indexOf(selectedOptionId.value)
    if (index < 0 && first) {
      selectedOptionId.value = first
      return
    }

    const target = optionIdList.value[index + 1]
    if (target || first) {
      selectedOptionId.value = (target ?? first)!
    }
  }
  function prevOption() {
    const last = optionIdList.value.at(-1)

    const index = optionIdList.value.indexOf(selectedOptionId.value)
    if (index < 0 && last) {
      selectedOptionId.value = last
      return
    }

    const target = optionIdList.value[index - 1]
    if (target || last) {
      selectedOptionId.value = (target ?? last)!
    }
  }

  const currentOption = computed(() => optionMap.value.get(selectedOptionId.value))

  return {
    optionIdList,
    addOption,
    removeOption,

    selectedOptionId,
    setOption,
    nextOption,
    prevOption,

    currentOption,
  }
})
```

`feature.store` 主要提供以下邏輯：

* 註冊、移除 option
* 設定或前後選擇 option

接著在 `feature-option` 新增邏輯：

* 註冊自己的 ID 與 `action`
* `onUnmounted` 時移除 ID。
* `selected` 依照 `feature.store` 資料判斷

`src\components\feature-option.vue`

```vue
<template>
  // ...
</template>

<script setup lang="ts">
// ...

const featureStore = useFeatureStore()

const id = useId()

featureStore.addOption(id, {
  action: props.action,
})
onUnmounted(() => {
  featureStore.removeOption(id)
})

// ...
const selected = computed(
  () => isHover.value || featureStore.selectedOptionId === id,
)
</script>
```

最後讓我們在 `main-input` 中註冊鍵盤事件，實現鍵盤選擇選項功能。

`src\components\main-input.vue`

```vue
<template>
  <q-input
    ...
    @keydown="handleKeydown"
  >
    // ...
  </q-input>
</template>

<script setup lang="ts">
// ...
const keydownEventMap: Record<
  /** key name
   *
   * https://developer.mozilla.org/zh-CN/docs/Web/API/UI_Events/Keyboard_event_key_values
   */
  string,
  (event: KeyboardEvent) => Promise<void>
> = {
  async Escape() {
    // 已清空則隱藏視窗
    if (inputText.value === '') {
      mainApi.hideWindow()
    }

    inputText.value = ''
  },
  async ArrowDown(event) {
    event.preventDefault()
    featureStore.nextOption()
  },
  async ArrowUp(event) {
    event.preventDefault()
    featureStore.prevOption()
  },
  async Enter() {
    featureStore.currentOption?.action()
  },
}
function handleKeydown(event: KeyboardEvent) {
  keydownEventMap[event.key]?.(event)
}
</script>
```

現在我們可以透過鍵盤觸發以下功能：

* Escape 清空輸入框，若內容為空則隱藏視窗
* 上下鍵選擇選項
* Enter 執行選項。

![keyboard-selection-option](/cod-toys/keyboard-selection-option.gif)

越來越有模有樣了！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

### 新增功能卡片

接著讓我們新增功能卡片，功能卡片會自動根據使用者輸入內容提供可用選項。

可預期每個卡片都會有自己的專屬邏輯，所以我們將卡片元件獨立在 `domains` 資料夾中。

#### 搜尋顏文字

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
      class="p-4"
      icon="emoticon"
      text="輸入 @ 搜尋顏文字"
      :action="() => setText('@')"
    />

    <template v-else>
      <feature-option
        v-for="text, i in textList"
        :key="i"
        class="p-4"
        :text
        :action="() => copy(text)"
      />
    </template>
  </template>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import FeatureOption from '../../components/feature-option.vue'
import { useMainApi } from '../../composables/use-main-api'

const mainApi = useMainApi()

const inputText = defineModel({ default: '' })

const visible = computed(() => {
  return !inputText.value || inputText.value.startsWith('@')
})

const isFeature = computed(() => inputText.value.startsWith('@'))

function setText(text: string) {
  inputText.value = text
}

function copy(text: string) {
  navigator.clipboard.writeText(text)
  mainApi.hideWindow()
}

const textList = [
  '(´▽`ʃ♡ƪ)',
  '੭ ˙ᗜ˙ )੭',
  '(*´∀`)~♥',
]
</script>
```

因為還沒連接資料庫，所以先暫時寫死 3 個顏文字測試功能。

接著在首頁中引入功能卡片。

`src\pages\index.vue`

```vue
<template>
  <div>
    // ...

    <div class="flex-col">
      <feature-card-kaomoji v-model="inputText" />
    </div>
  </div>
</template>

<script setup lang="ts">
import FeatureCardKaomoji from '../domains/feature-card-kaomoji/index.vue'
</script>
```

現在輸入 `@` 即可搜尋顏文字，而且選擇後可以直接複製到剪貼簿。

![select-and-copy-kaomoji](/cod-toys/select-and-copy-kaomoji.gif)

#### Google 搜尋

只有一個功能有點孤單，讓我們再新增一個可以快速開始 Google 搜尋的功能卡片吧！%(/≧▽≦)/%

這裡需要在 `mainApi` 新增一個 API，用來開啟瀏覽器。

`electron\electron-env.d.ts`

```ts
export interface MainApi {
  // ...
  openExternal: (url: string) => void;
}

// ...
```

`electron\preload.ts`

```ts
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('main', {
  // ...
  openExternal(url: string) {
    return ipcRenderer.send('openExternal', url)
  },
})
```

`electron\main.ts`

```ts
// ...

function initIpcMain(mainWindow: BrowserWindow) {
  // ...

  ipcMain.on('openExternal', (event, url: string) => {
    shell.openExternal(url)
  })
}

// ...
```

這裡使用了 [`shell`](https://www.electronjs.org/docs/latest/api/shell) 模組，可以讓我們開啟外部瀏覽器。

接著讓我們新增 `feature-card-google` 功能卡片元件。

`src\domains\feature-card-google\index.vue`

```vue
<template>
  <feature-option
    v-if="visible"
    class="p-4"
    icon="search"
    text="在 Google 上搜尋"
    :action
  />
</template>

<script setup lang="ts">
import { computed } from 'vue'
import FeatureOption from '../../components/feature-option.vue'
import { useMainApi } from '../../composables/use-main-api'

const mainApi = useMainApi()

const inputText = defineModel({ default: '' })

const visible = computed(() => {
  if (!inputText.value) {
    return false
  }

  return !inputText.value.startsWith('@')
})

function action() {
  const url = [
    `https://www.google.com/search?q=`,
    encodeURIComponent(inputText.value),
  ].join('')
  mainApi.openExternal(url)
  mainApi.hideWindow()
}
</script>
```

接著在首頁引入功能卡片。

不過每次新增功能卡片都要手動引入好麻煩，讓我們自動引入吧！%( ´ ▽ \` )ﾉ%

`src\pages\index.vue`

```vue
<template>
  <div>
    // ...

    <div class="flex-col">
      <component
        :is="card"
        v-for="card, key in featureCards"
        :key
        v-model="inputText"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
const featureCards = import.meta.glob('../domains/feature-card-*/index.vue', {
  import: 'default',
  eager: true,
})

// ...
</script>
```

::: tip
這裡使用了 Vite 的 [glob 功能](https://vite.dev/guide/features#glob-import)
:::

現在可以輸入任何內容並開啟瀏覽器跳轉 Google 搜尋了！%◝(≧∀≦)◟%

![google-search](/cod-toys/google-search.gif)

核心功能基本上都完成了，感覺超讚！%(≧∇≦)ﾉ%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/side-project-cod-toys/tree/feat/feature-card)

* 完成依照關鍵字候選功能選項
* `ipcRenderer` 可以讓網頁與 main process 通訊
* 完成搜尋顏文字與 Google 搜尋功能

下一章讓我們來實作連接 Notion Database 與模糊搜尋吧。%(≖‿ゝ≖)✧%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-cod-toys/03-kaomoji-database.md
description: 上一章節我們完成了快捷鍵開關視窗功能，這一章節我們來實作功能選項部分吧！
---

![快樂堆積木的魚](/cod-toys.webp){.cover}

# CodToys - EP03：顏文字資料庫

上一章節我們完成了快捷鍵開關視窗功能，這一章節我們來實作功能選項部分吧！

## 開發

本章節預計會建立以下內容：

* 產生 Tray：用來查看狀態與開啟設定視窗
* 儲存設定檔：儲存使用者之 Notion API 資料
* 連接 Notion Database
* 模糊搜尋顏文字資料

### 產生 Tray

使用 [Tray 模組](https://www.electronjs.org/docs/latest/api/tray)，輕鬆完成。◝( •ω• )◟

同時將 `app` 的 `window-all-closed` 事件移到 `app.whenReady` 中，減少對於全域變數的依賴。

`electron\main.ts`

```ts
import path from 'node:path'
import process from 'node:process'
import {
  app,
  BrowserWindow,
  globalShortcut,
  Menu,
  shell,
  Tray,
} from 'electron'
import { version } from '../package.json'

function createTray(
  {
    mainWindow,
  }: {
    mainWindow: BrowserWindow;
  },
) {
  const tray = new Tray(
    path.join(__dirname, '../public/fish.ico'),
  )
  const contextMenu = Menu.buildFromTemplate([
    {
      label: '暫時停用',
      type: 'checkbox',
      click(item) {
        if (item.checked) {
          globalShortcut.unregisterAll()
        }
        else {
          initGlobalShortcut({ mainWindow })
        }
      },
    },
    {
      label: '詳細設定',
      submenu: [
        {
          label: '開啟設定視窗',
        },
      ],
    },
    {
      label: '關於',
      click: () => shell.openExternal('https://codlin.me/column-cod-toys/01-origin.html'),
    },
    { type: 'separator' },
    {
      label: '退出應用程式',
      click: () => app.quit(),
    },
  ])
  tray.setToolTip(`CodToys v${version}`)
  tray.setContextMenu(contextMenu)

  return tray
}

app.whenReady().then(async () => {
  const mainWindow = await createInputWindow()

  initGlobalShortcut({ mainWindow })

  initIpcMain({ configStore })

  const tray = createTray({ mainWindow })

  app.on('window-all-closed', () => { // [!code ++]
    if (process.platform !== 'darwin') { // [!code ++]
      app.quit()// [!code ++]
    }// [!code ++]

    globalShortcut.unregisterAll()// [!code ++]
    tray.destroy()// [!code ++]
  })// [!code ++]
})

app.on('window-all-closed', () => { // [!code --]
  if (process.platform !== 'darwin') { // [!code --]
    app.quit()// [!code --]
  }// [!code --]

  globalShortcut.unregisterAll()// [!code --]
})// [!code --]
```

現在會注意到系統托盤會出現魚的圖示，點擊右鍵會出現更多選單。

![create-tray](/cod-toys/create-tray.png)

### 儲存使用者設定

這裡使用 [electron-store](https://www.npmjs.com/package/electron-store) 來儲存使用者設定。

安裝套件後，第一步先來定義一下使用者設定型別並新增 `ConfigApi`，用於存取使用者設定。
`electron\electron-env.d.ts`

```ts
export interface MainApi {
  // ...
}

export interface UserConfig {
  kaomoji: {
    databaseId: string;
    token: string;
  };
}
export interface ConfigApi {
  get: () => Promise<UserConfig>;
  update: (data: Partial<UserConfig>) => Promise<void>;
  onUpdate: (callback: (config: UserConfig) => void) => void;
}

declare global {
  interface Window {
    main: MainApi;
    config: ConfigApi; // [!code ++]
  }
}

export { }
```

接著在 main process 初始化 store 並註冊 `ipcMain`。

這裡同時重構一下 `ipcMain` 的部分，window 相關控制改為針對發送的 window，不限定只能控制 `mainWindow`。

`electron\main.ts`

```ts{20-30,36-50,72}
import type { UserConfig } from './electron-env'
import {
  app,
  BrowserWindow,
  ipcMain,
  shell,
} from 'electron'
import Store from 'electron-store'

type ConfigStore = Store<{ config: UserConfig }>

function initIpcMain(
  {
    configStore,
  }: {
    configStore: ConfigStore;
  },
) {
  // main
  ipcMain.on('main:updateHeight', (event, height: number) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setBounds({ height })
  })
  ipcMain.on('main:hideWindow', (event) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setFocusable(false)
    window?.hide()
  })
  ipcMain.on('main:openExternal', (event, url: string) => {
    shell.openExternal(url)
  })

  // config
  ipcMain.handle('config:get', async () => {
    return configStore.get('config')
  })
  ipcMain.handle('config:update', async (event, config) => {
    const data = configStore.get('config')
    configStore.set('config', {
      ...data,
      ...config,
    })

    // 向所有視窗觸發 config:onUpdate 事件
    BrowserWindow.getAllWindows().forEach((window) => {
      window.webContents.send('config:onUpdate', config)
    })
  })
}

function createConfigStore(): ConfigStore { // [!code ++]
  const config: UserConfig = { // [!code ++]
    kaomoji: { // [!code ++]
      databaseId: '', // [!code ++]
      token: '', // [!code ++]
    }, // [!code ++]
  } // [!code ++]

  return new Store({ // [!code ++]
    name: 'config', // [!code ++]
    defaults: { config }, // [!code ++]
  }) // [!code ++]
} // [!code ++]

app.whenReady().then(async () => {
  const configStore = createConfigStore()

  // ...

  initIpcMain({ configStore })

  // ...
})
```

接著在 preload 實作 API。

`electron\preload.ts`

```ts
// ...

contextBridge.exposeInMainWorld('config', {
  get() {
    return ipcRenderer.invoke('config:get')
  },
  update(data: Partial<UserConfig>) {
    return ipcRenderer.invoke('config:update', data)
  },
  onUpdate(callback: (config: UserConfig) => void) {
    ipcRenderer.on('config:onUpdate', (event, config) => {
      callback(config)
    })
  },
})
```

現在我們可以儲存設定檔了，還需要一個頁面輸入資料才行。

### 開啟設定頁面

預計使用 Vue Router，由於 Electron 本身沒有 Web Server，所以沒辦法直接使用 History 模式，這裡我們將 router 改為 Hash 模式解決。

`src\main.ts`

```ts
import { createRouter, createWebHashHistory } from 'vue-router/auto'

// ...

const router = createRouter({
  history: createWebHashHistory(import.meta.env.BASE_URL), // [!code highlight]
  routes,
})

// ...
```

接著新增設定頁面吧。

`src\pages\kaomoji-config\index.vue`

```vue
<template>
  <q-form
    class="relative flex-col gap-6 p-6"
    @submit="handleSubmit"
  >
    <q-input
      v-model="form.databaseId"
      outlined
      label="databaseId"
    />

    <q-input
      v-model="form.token"
      outlined
      label="token"
    />

    <q-btn
      label="儲存"
      type="submit"
      unelevated
      color="primary"
    />

    <q-inner-loading :showing="isLoading" />
  </q-form>
</template>

<script setup lang="ts">
import type { UserConfig } from '../../../electron/electron-env'
import { useAsyncState } from '@vueuse/core'
import { useQuasar } from 'quasar'
import { clone } from 'remeda'
import { ref } from 'vue'
import { useConfigApi } from '../../composables/use-config-api'

const configApi = useConfigApi()
const $q = useQuasar()

document.title = '顏文字設定'

const form = ref<UserConfig['kaomoji']>({
  databaseId: '',
  token: '',
})

const {
  isLoading,
} = useAsyncState(
  () => configApi.get(),
  undefined,
  {
    onSuccess(data) {
      if (data) {
        form.value = data.kaomoji
      }
    },
  },
)

function handleSubmit() {
  // clone 處理，避免 Error: An object could not be cloned
  configApi.update(clone({
    kaomoji: form.value,
  })).then(() => {
    $q.notify({
      type: 'positive',
      message: '儲存成功',
    })
  }).catch(() => {
    $q.notify({
      type: 'negative',
      message: '儲存失敗',
    })
  })
}
</script>
```

現在讓我們透過 Tray 的選單開啟此設定頁面吧。

建立 `createConfigWindow` 用於開啟指定頁面並將目標 route path 加在 # 後面即可。

```ts
// ...

async function createConfigWindow(route: keyof RouteNamedMap) {
  const newWindow = new BrowserWindow({
    backgroundColor: '#fff',
    webPreferences: {
      preload: path.join(__dirname, './preload.js'),
    },
  })
  // 隱藏預設系統選單
  newWindow.setMenu(null)

  if (process.env.VITE_DEV_SERVER_URL) {
    await newWindow.loadURL(
      `${process.env.VITE_DEV_SERVER_URL}#${route}`,
    )
    // newWindow.webContents.openDevTools()
  }
  else {
    // loadFile 可以指定 hash
    await newWindow.loadFile('dist/index.html', {
      hash: route,
    })
  }

  return newWindow
}

// ...

function createTray(
  // ...
) {
  // ...
  const contextMenu = Menu.buildFromTemplate([
    // ...
    {
      label: '詳細設定',
      submenu: [
        {
          label: '開啟設定視窗',
          click: () => createConfigWindow('/kaomoji-config/'), // [!code ++]
        },
      ],
    },
    // ...
  ])
  // ...
}

// ...
```

:::tip
`RouteNamedMap` 是 `unplugin-vue-router` 自動產生的型別，用於定義所有頁面路由與參數。
:::

現在讓我們從 Tray 開啟設定頁面看看吧！(/≧▽≦)/

![kaomoji-config](/cod-toys/kaomoji-config.png)

...可以看到畫面相當簡潔有力，有機會再來慢慢美化吧。%( •̀ ω •́ )✧%

### 連接 Notion Database

現在讓我們透過 Notion API 來連接指定的 Database 吧！

首先需要先建立 Integrations，前往[設定頁面](https://www.notion.so/profile/integrations)並依照步驟建立。

1. 點擊畫面中的「+ New integration」
2. Associated workspace 選擇要使用的 Workspace
3. Type 選擇 Internal
4. 按下 Save

這樣就建立完成了！接著我們需要取得並調整一下 Token 設定。

在 Integrations 頁面中，點擊剛剛建立的 Integration，會進到設定頁面，讓我們限縮以下此 Token 權限，保持最小權限原則。

基本上就是只有 Read 權限，如下圖。

![notion-token-capabilities](/cod-toys/notion-token-capabilities.png)

複製 Internal Integration Secret 中的 token，並貼到設定頁面中。

接著來建立 Database。

1. 將原本預設的 Name 欄位改名為 value，內容為顏文字
2. 新增一個名為 tags 的多選欄位，用來提供篩選資料
3. 將 database 使用 open as page 開啟
4. 點擊最右上角的三個點，將 Connections 設定為剛剛建立的 Integration

完成後結果會如下圖。

![notion-connections](/cod-toys/notion-connections.png)

最後目前網頁的 URL 會是 `https://www.notion.so/{workspace}/{databaseId}?xxx`，將此 URL 中的 databaseId 複製下來，貼到設定頁面中後按下儲存即可。

![save-kaomoji-config](/cod-toys/save-kaomoji-config.png)

### 取得 Notion Database 資料

現在設定資料有了，讓我們串接 Notion API 吧。

安裝 `@notionhq/client` 套件來存取 Notion API 並加入取得資料邏輯。

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
      class="p-4"
      icon="emoticon"
      text="輸入 @ 搜尋顏文字"
      :action="() => setText('@')"
    />

    <template v-else>
      <feature-option
        v-for="item, i in list"
        :key="i"
        class="w-full px-4 py-2"
        :action="() => copy(item.value)"
      >
        <div class="flex-1">
          {{ item.value }}
        </div>

        <div class="flex">
          <q-chip
            v-for="tag in item.tags"
            :key="tag"
            :label="tag"
          />
        </div>
      </feature-option>
    </template>
  </template>
</template>

<script setup lang="ts">
import type { UserConfig } from '../../../electron/electron-env'
import { Client } from '@notionhq/client'
import { useAsyncState } from '@vueuse/core'
import dayjs from 'dayjs'
import { get } from 'lodash-es'
import { pipe, reduce, take } from 'remeda'
import { computed, ref, shallowRef, triggerRef } from 'vue'
import FeatureOption from '../../components/feature-option.vue'
import { useConfigApi } from '../../composables/use-config-api'
import { useFeatureStore } from '../../stores/feature.store'

const configApi = useConfigApi()
const featureStore = useFeatureStore()

// ...

const {
  state: config,
  execute: refreshConfig,
} = useAsyncState(
  () => configApi.get(),
  undefined,
  { immediate: false },
)

let notionClient: Client | undefined
function initNotionClient(config: UserConfig) {
  notionClient = new Client({
    auth: config.kaomoji.token,
  })
}

const updatedAt = shallowRef(dayjs())
const notionData = shallowRef<any[]>([])
const startCursor = ref('')
const {
  isLoading: isDataLoading,
  execute: getData,
} = useAsyncState(
  async () => {
    const databaseId = config.value?.kaomoji.databaseId
    if (!databaseId) {
      throw new Error('尚未設定 databaseId')
    }

    return notionClient?.databases.query({
      database_id: databaseId,
      start_cursor: startCursor.value ? startCursor.value : undefined,
    })
  },
  undefined,
  {
    immediate: false,
    onSuccess(result) {
      notionData.value.push(...(result?.results ?? []))

      if (result?.has_more && result.next_cursor) {
        startCursor.value = result.next_cursor
        getData()
        return
      }

      triggerRef(notionData)
      updatedAt.value = dayjs()
    },
  },
)

function refreshData() {
  startCursor.value = ''
  notionData.value = []
  getData()
}

interface ListItem {
  value: string;
  tags: string[];
}
const list = computed(() => pipe(
  notionData.value,
  reduce((acc: ListItem[], result) => {
    acc.push({
      // @notionhq/client 的型別與實際資料有點出入，自行從回應判斷
      value: get(result, 'properties.value.title[0].plain_text', '') as string,
      tags: pipe(
        get(result, 'properties.tags.multi_select', []) as { name: string }[],
        (value) => {
          if (!value) {
            return []
          }

          return value.map((item) => item.name)
        },
      ),
    })

    return acc
  }, []),
  // 先顯示 5 個看看
  take(5),
))

configApi.onUpdate(async (config) => {
  init(config)
})

async function init(config?: UserConfig) {
  const _config = config ?? await refreshConfig()
  if (!_config) {
    return
  }

  initNotionClient(_config)
  refreshData()
}
init()
</script>
```

![get-kaomoji-database-data](/cod-toys/get-kaomoji-database-data.png)

資料進來了！( ´ ▽ \` )ﾉ

接著新增更新用的按鈕，讓使用者可以手動更新資料。

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
      ...
    />

    <template v-else>
      <feature-option
        v-for="item, i in list"
        :key="i"
        ...
      >
        ...
      </feature-option>

      <feature-option
        class="relative w-full bg-primary/10 p-4"
        :action="() => refreshData()"
      >
        <div class="w-full flex items-center justify-around">
          <span class="flex-1">
            更新資料
          </span>
          <span class="flex-1 text-right text-xs text-gray-500">
            共 {{ list.length }} 筆，最後更新於 {{ updatedAt.format('YYYY/MM/DD HH:mm:ss') }}
          </span>
        </div>

        <q-inner-loading :showing="isDataLoading" />
      </feature-option>
    </template>
  </template>
</template>
```

![refresh-kaomoji-database-data](/cod-toys/refresh-kaomoji-database-data.gif)

由於資料可能很多，最後讓我們實現分頁功能吧！

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
    />

    <template v-else>
      <!-- WARNING --> // [!code highlight]
      <div
        :key="pagination.page"
        class="flex-col"
      >
        <feature-option
          v-if="nextPageVisible"
          class="w-full px-4 py-2"
          :action="() => nextPage()"
        >
          <span class="flex-1">
            下一頁 ({{ pagination.page + 1 }}/{{ totalPages }})
          </span>
        </feature-option>

        ...
      </div>
    </template>
  </template>
</template>

<script setup lang="ts">
import { chunk, pipe } from 'remeda'
import { computed, nextTick, ref } from 'vue'
import FeatureOption from '../../components/feature-option.vue'

// ...

const pagination = ref({
  page: 0,
  itemsPerPage: 5,
})
watch(inputText, () => {
  pagination.value.page = 0
})
const totalPages = computed(() => Math.ceil(list.value.length / pagination.value.itemsPerPage))

const paginationList = computed(() => pipe(
  list.value,
  chunk(pagination.value.itemsPerPage),
  (data) => data[pagination.value.page] ?? [],
))

const nextPageVisible = computed(() => totalPages.value > 1)
async function nextPage() {
  pagination.value.page += 1
  pagination.value.page %= totalPages.value

  await nextTick()
  featureStore.setOption(featureStore.optionIdList[0] ?? '')
}

configApi.onUpdate(async (config) => {
  init(config)
})

// ...
</script>
```

::: warning
程式碼中有個 `<!-- WARNING -->` 部分，`:key="pagination.page"` 是為了在換頁時強制重新渲染，才能保證所有 option 順序一致，這個方法會有不必要的性能損號，未來再來改進。
:::

![pagination-kaomoji-data](/cod-toys/pagination-kaomoji-data.gif)

所有的資料都進來了！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

### 模糊過濾

最後讓我們來實作模糊過濾功能吧！

我們希望即使只有部分文字符合，也能候選最接近的資料。

這裡使用 [fuse.js](https://fusejs.io/) 實作模糊過濾功能。

這個部份很單純，困難的部分 `fuse.js` 已經幫我們處理好了，我們只要爽爽用就行惹。%ψ(｀∇´)ψ%

`src\domains\feature-card-kaomoji\index.vue`

```vue
// ...

<script setup lang="ts">
// ...

const fuseInstance = new Fuse(list.value, {
  keys: ['tags'],
})
watch(list, (value) => {
  fuseInstance.setCollection(value)
})

const filteredList = computed(() => {
  if (inputText.value === '@') {
    return list.value
  }

  const text = pipe(
    inputText.value,
    (value) => {
      if (value.startsWith('@')) {
        return value.slice(1)
      }

      return value
    },
    (value) => value.trim(),
  )

  const result = fuseInstance.search(text)

  return pipe(
    result,
    map(prop('item')),
  )
})

// ...

const totalPages = computed(() => Math.ceil(
  list.value.length / pagination.value.itemsPerPage, // [!code --]
  filteredList.value.length / pagination.value.itemsPerPage, // [!code ++]
))

const paginationList = computed(() => pipe(
  list.value, // [!code --]
  filteredList.value, // [!code ++]
  chunk(pagination.value.itemsPerPage),
  (data) => data[pagination.value.page] ?? [],
))

// ...
</script>
```

![fuse-search](/cod-toys/fuse-search.gif)

就這麼簡單。(\*´∀\`)~♥

現在讓我們完整的展示一次功能。

* 輸入 @ 可以開始搜尋顏文字
* 沒有匹配任何功能時，則開啟 Google 搜尋

![phase-1-completed](/cod-toys/phase-1-completed.gif)

感覺超讚！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

## 改進與重構

實際上使用後發現有些地方需要改進，讓我們來改進一下吧！%੭ ˙ᗜ˙ )੭%

### 取消滑鼠 hover 效果

滑鼠 hover 效果會讓使用者混淆目前選項，狠心刪除。%ԅ( ˘ω˘ԅ)%

`src\components\feature-option.vue`

```vue
// ...

<script setup lang="ts">
// ...
const optionRef = ref<HTMLDivElement>()
const isHover = useElementHover(optionRef) // [!code --]
const selected = computed( // [!code --]
  () => isHover.value || featureStore.selectedOptionId === id, // [!code --]
) // [!code --]
const selected = computed(() => featureStore.selectedOptionId === id) // [!code ++]
</script>
```

### feature-option 重複使用時，選擇順序錯誤問題

剛剛提到 `<!-- WARNING -->` 強制更新部分，這裡我們來改進一下。

`featureStore` 註冊 option 時，多提供元件 y 座標位置，只要根據 y 座標排序，選項順序就會同步自然順序了。

`src\stores\feature.store.ts`

```ts
import { defineStore } from 'pinia'
import { map, pipe, sortBy } from 'remeda'
import { computed, shallowRef } from 'vue'

interface OptionValue {
  y: number; // [!code ++]
  action: () => void;
}

export const useFeatureStore = defineStore('feature', () => {
  const optionMap = shallowRef(new Map<string, OptionValue>())
  const optionIdList = computed(() => pipe(
    [...optionMap.value.keys()], // [!code --]
    /** 依照數字排序，保證 option 順序 */ // [!code --]
    sortBy((id) => Number.parseInt(id.replace(/\D/g, ''), 10)), // [!code --]
    [...optionMap.value.entries()], // [!code ++]
    /** 依照畫面 y 座標排序，保證 option 自然順序 */// [!code ++]
    sortBy((data) => data[1].y), // [!code ++]
    map(([id]) => id), // [!code ++]
  ))

  // ...
})
```

feature-option 元件註冊時提供 y 座標。

`src\components\feature-option.vue`

```vue
// ...

<script setup lang="ts">
// ...

const { y } = useElementBounding(optionRef)

featureStore.addOption(id, { // [!code --]
  action: props.action, // [!code --]
}) // [!code --]

watch(y, (value) => { // [!code ++]
  featureStore.addOption(id, { // [!code ++]
    y: value, // [!code ++]
    action: props.action, // [!code ++]
  }) // [!code ++]
}) // [!code ++]
// ...
</script>
```

### 數字鍵盤快速選擇

一直按上下鍵有點麻煩，加個使用數字鍵快速選擇功能。( •̀ ω •́ )✧

使用 VueUse 的 `useMagicKeys` 輕鬆實現。%(´,,•ω•,,)%

開始前先讓我們整理、重構一下內容，讓元件內的程式碼更內聚一點。

元件與資料可以獨立存在，所以首先抽離資料部分。

`src\domains\feature-card-kaomoji\use-kaomoji-data.ts`

```ts
// ...

export function useKaomojiData(
  inputText: Ref<string>,
) {
  const configApi = useConfigApi()
  const featureStore = useFeatureStore()

  const {
    state: config,
    execute: refreshConfig,
  } = useAsyncState(
    // ...
  )

  let notionClient: Client | undefined
  function initNotionClient(config: UserConfig) {
    // ...
  }

  const updatedAt = shallowRef(dayjs())
  const notionData = shallowRef<any[]>([])
  const startCursor = ref('')
  const {
    isLoading,
    execute: getData,
  } = useAsyncState(
    // ...
  )

  function refreshData() {
    // ...
  }

  interface ListItem {
    value: string;
    tags: string[];
  }
  const list = computed(() => pipe(
    // ...
  ))

  const fuseInstance = new Fuse(list.value, {
    keys: ['tags'],
  })
  watch(list, (value) => {
    fuseInstance.setCollection(value)
  })

  const filteredList = computed(() => {
    // ...
  })

  const pagination = ref({
    page: 0,
    itemsPerPage: 5,
  })
  watch(inputText, () => {
    pagination.value.page = 0
  })
  const totalPages = computed(() => Math.ceil(
    filteredList.value.length / pagination.value.itemsPerPage,
  ))

  const paginationList = computed(() => pipe(
    // ...
  ))

  async function nextPage() {
    // ...
  }

  configApi.onUpdate(async (config) => {
    init(config)
  })

  async function init(config?: UserConfig) {
    // ...
  }

  return {
    isLoading,
    updatedAt,

    list,

    pagination,
    paginationList,
    totalPages,
    nextPage,

    init,
    refreshData,
  }
}
```

基本上就是把資料的部份抽離，所以具體內容就不贅述了。

現在元件內部變得相當簡潔。

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  ...
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { useKaomojiData } from './use-kaomoji-data'

// ...

function copy(text: string) {
  // ...
}

const {
  isLoading,
  updatedAt,
  pagination,
  paginationList,
  list,
  nextPage,
  totalPages,
  refreshData,
  init,
} = useKaomojiData(inputText)
init()

const nextPageVisible = computed(() => totalPages.value > 1)
</script>
```

現在讓我們在 `featureStore` 新增一個 method。

`src\stores\feature.store.ts`

```ts
// ...
export const useFeatureStore = defineStore('feature', () => {
  // ...
  function setOptionByIndex(index: number) {
    selectedOptionId.value = optionIdList.value[index] ?? ''
  }
  // ...

  return {
    // ...
    setOptionByIndex,
  }
})
```

最後在元件中使用 `useMagicKeys` 並加上快捷鍵提示吧。੭ ˙ᗜ˙ )੭

`src\domains\feature-card-kaomoji\index.vue`

```vue
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
      ...
    />

    <template v-else>
      <feature-option
        v-if="nextPageVisible"
        ...
      >
        <q-chip
          v-if="isFeature"
          label="Ctrl+1"
          square
          outline
          color="primary"
        />
        <span class="flex-1">
          下一頁 ({{ pagination.page + 1 }}/{{ totalPages }})
        </span>
      </feature-option>

      <feature-option
        v-for="item, i in paginationList"
        :key="i"
        ...
      >
        <q-chip
          v-if="isFeature"
          :label="`Ctrl+${i + textStartIndex}`"
          square
          outline
          color="primary"
        />

        ...
      </feature-option>

      ...
    </template>
  </template>
</template>

<script setup lang="ts">
// ...

const nextPageVisible = computed(() => totalPages.value > 1)

const textStartIndex = computed(() => nextPageVisible.value ? 2 : 1)

const { current } = useMagicKeys()

watch(current, (keySet) => {
  // 僅使用此功能才作用，避免干擾其他功能
  if (!isFeature.value || keySet.size === 0)
    return

  if (!keySet.has('control'))
    return

  /** 1~6 */
  const numberKey = [...keySet].find((key) => key.match(/^[1-6]$/))
  if (numberKey) {
    const index = Number(numberKey) - 1
    featureStore.setOptionByIndex(index)
    featureStore.currentOption?.action()
  }
}, { deep: true })
</script>
```

現在我們可以很快速地選擇目標顏文字了！( •̀ ω •́ )✧

![shortcut-key-selection-options](/cod-toys/shortcut-key-selection-options.gif)

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/side-project-cod-toys/tree/feat/kaomoji-database)

* 串接 Notion API，完成顏文字資料庫功能
* 抽離、重構程式碼，讓程式碼更具內聚性
* 加入快捷鍵功能，讓使用者更快速選擇顏文字

感覺還可以加入很多很有趣的功能，歡迎大家留言或寫信許願喔！(´▽\`ʃ♡ƪ)

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-cod-toys/04-kaomoji-add-llm.md
description: 忘記原本的關鍵字怎麼辦？請支援近義詞搜尋 ლ(╹ε╹ლ)
---

![快樂堆積木的魚](/cod-toys.webp){.cover}

# CodToys - EP04：請支援近義詞

上一章我們可以很快速地選擇目標顏文字了。

但是日子久了，一不小心就忘記當初顏文字的 tag 是甚麼，導致一時找不到想要的顏文字。%( ´•̥̥̥ ω •̥̥̥\` )%

路人：「自己新增的 tag 還能忘記喔？%(◉◞౪◟◉ )%」

鱈魚：「我就鱈魚腦，你有意見膩？%(;´༎ຶД༎ຶ\`)%」

你是個成熟的程式惹，該自己知道近義詞了！%(。-\`ω´-)%

這樣即使忘記原本的 tag，也可以透過相近的字詞找到想要的顏文字了！%ヾ(◍'౪\`◍)ﾉﾞ%

## 開發

目前想到的實作方式為：「使用 LLM（Language Learning Model）來回答 tag 的中英文近義詞，再對近義詞進行模糊匹配」

本章節預計會建立以下內容：

* 在 Electron 中運行 LLM
* 讓 LLM 對每個顏文字的 tag 產生近義詞
* 根據近義詞搜尋並顯示結果

### 來運行 LLM 吧！

這裡依賴 [`node-llama-cpp`](https://github.com/withcatai/node-llama-cpp) 這個套件，藉由此套件我們可以很簡單的在 Node.js 中運行 LLM。

這裡選用小型的模型（大模型也跑不動就是了 (\´・ω・\`)），目前實際測試 `gemma-2-2b-it-Q6_K_L` 和 `Llama-3.2-3B-Instruct.Q6_K`。

程式碼很單純，基本上就是微調官方範例而已。

讓模型回答特定單字的中英文近義詞，並將結果顯示出來。

```typescript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import chalk from 'chalk'
import { getLlama, LlamaChatSession, resolveModelFile } from 'node-llama-cpp'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const modelsDirectory = path.join(__dirname, '..', 'models')

const llama = await getLlama()

const qList = [
  '快樂的 10 個繁體中文、10 個英文近義詞，全部合併，逗號分隔，不要任何附加資訊，不要標題，不需解釋',
  '慶祝的 10 個繁體中文、10 個英文近義詞，全部合併，逗號分隔，不要任何附加資訊，不要標題，不需解釋',
  '發瘋的 10 個繁體中文、10 個英文近義詞，全部合併，逗號分隔，不要任何附加資訊，不要標題，不需解釋'
]

{
  console.log(chalk.yellow('gemma: '))

  const modelPath = await resolveModelFile(
    'hf_bartowski_gemma-2-2b-it-Q6_K_L.gguf',
    modelsDirectory
  )

  const model = await llama.loadModel({ modelPath })
  const context = await model.createContext()
  const session = new LlamaChatSession({
    contextSequence: context.getSequence()
  })
  console.log()

  for (const q of qList) {
    const a = await session.prompt(q)
    console.log(a)
  }

  await model.dispose()
}

{
  console.log(chalk.yellow('llama: '))

  const modelPath = await resolveModelFile(
    'hf_mradermacher_Llama-3.2-3B-Instruct.Q6_K.gguf',
    modelsDirectory
  )

  const model = await llama.loadModel({ modelPath })
  const context = await model.createContext()
  const session = new LlamaChatSession({
    contextSequence: context.getSequence()
  })
  console.log()

  for (const q of qList) {
    const a = await session.prompt(q)
    console.log(a)
  }

  await model.dispose()
}
```

以下是運行結果。

gemma:

```text
幸福、欣喜、愉悅、歡樂、開心、滿足、喜悅、興奮、滿足、舒暢
joy, happiness, delight, exhilaration, contentment, pleasure, satisfaction, excitement, bliss, comfort

慶祝、歡慶、慶典、盛會、派對、聚會、節慶、紀念、典禮、嘉年華
celebration, festivities, party, gathering, jubilee, festival, commemoration, gala, ceremony, parade, anniversary

發瘋、瘋狂、失控、歇斯底里、狂躁、衝動、失序、失常、暴躁、躁狂
madness, frenzy, unhinged, manic, agitated, impulsive, chaotic, disordered, irritable, erratic
```

llama:

```text
快樂、愉悅、幸福、欣快、高興、快意、悅目、愉悅、快樂、快暢

慶祝、祝賀、紀念、紀念、祝福、慶典、節日、節慶、紀念、祝賀

發瘋、癲癇、瘋狂、亢進、狂躁、癡呆、癲癇、瘋狂、亢進、狂躁
```

可以看出 gemma 的回答品質比 llama 好很多，所以接下來讓我們採用 gemma 實現近義詞搜尋吧。%( ´ ▽ \` )ﾉ%

### 新增 LLM API

安裝 `node-llama-cpp` 之後，新增自動下載模型的 scripts。

`package.json`

```json
{
  "name": "cod-toys",
  // ...
  "scripts": {
    "dev": "vite --host",
    "build": "vue-tsc --noEmit --skipLibCheck && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest run --coverage",
    "blueprint": "vite-node scripts/create-blueprint.ts",
    "lint": "eslint \"{src,apps,libs,test}/**/*.(ts|vue)\" --fix",
    "postinstall": "npm run models:pull", // [!code ++]
    "models:pull": "node-llama-cpp pull --dir ./resources/models \"hf:bartowski/gemma-2-2b-it-GGUF/gemma-2-2b-it-Q6_K_L.gguf\"" // [!code ++]
  },
  "dependencies": {
    // ...
  },
  "devDependencies": {
    // ...
  }
}
```

接下來新增一個 preload 的 API，用來執行 LLM。

不過在開始前，我們來重構一下目前 `preload` 的程式碼，讓 `electron-env.d.ts` 的形別自動推導，不要再手動定義一次。

`electron\preload.ts`

```typescript
import type { UserConfig } from './electron-env'
import { contextBridge, ipcRenderer } from 'electron'

export const mainApi = {
  updateHeight(height: number) {
    return ipcRenderer.send('main:updateHeight', height)
  },
  hideWindow() {
    return ipcRenderer.send('main:hideWindow')
  },
  openExternal(url: string) {
    return ipcRenderer.send('main:openExternal', url)
  },
}
contextBridge.exposeInMainWorld('main', mainApi)

export const configApi = {
  get() {
    return ipcRenderer.invoke('config:get')
  },
  update(data: Partial<UserConfig>) {
    return ipcRenderer.invoke('config:update', data)
  },
  onUpdate(callback: (config: UserConfig) => void) {
    ipcRenderer.on('config:onUpdate', (event, config) => {
      callback(config)
    })
  },
}
contextBridge.exposeInMainWorld('config', configApi)
```

`electron-env.d` 只要引入 `preload` 的 API 定義即可。

`electron\electron-env.d.ts`

```typescript
import type { configApi, mainApi } from './preload'

export interface UserConfig {
  kaomoji: {
    databaseId: string;
    token: string;
  };
}

declare global {
  interface Window {
    main: typeof mainApi;
    config: typeof configApi;
  }
}

export { }
```

現在來新增 LLM API。

`electron\preload.ts`

```typescript
// ...

export const llmApi = {
  prompt(message: string): Promise<string> {
    return ipcRenderer.invoke('llm:prompt', message)
  },
}
contextBridge.exposeInMainWorld('llm', llmApi)
```

`electron\electron-env.d.ts`

```typescript
// ...

declare global {
  interface Window {
    main: typeof mainApi;
    config: typeof configApi;
    llm: typeof llmApi; // [!code ++]
  }
}

export { }
```

接著在 `main` 中實作 LLM 的 API。

`electron\main.ts`

```typescript
// ...

async function initIpcMain(
  {
    configStore,
  }: {
    configStore: ConfigStore;
  },
) {
  // main
  ipcMain.on('main:updateHeight', (event, height: number) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setBounds({ height })
  })
  ipcMain.on('main:hideWindow', (event) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setFocusable(false)
    window?.hide()
  })
  ipcMain.on('main:openExternal', (event, url: string) => {
    shell.openExternal(url)
  })

  // config
  ipcMain.handle('config:get', async () => {
    return configStore.get('config')
  })
  ipcMain.handle('config:update', async (event, config) => {
    const data = configStore.get('config')
    configStore.set('config', {
      ...data,
      ...config,
    })

    // 向所有視窗觸發 config:onUpdate 事件
    BrowserWindow.getAllWindows().forEach((window) => {
      window.webContents.send('config:onUpdate', config)
    })
  })

  // llm
  /**
   * node-llama-cpp 只支援 ESM
   *
   * 直接 import 會出現 Error [ERR_REQUIRE_ESM]: require() of ES Module 錯誤
   *
   * https://node-llama-cpp.withcat.ai/guide/troubleshooting#using-in-commonjs
   */
  const { getLlama, LlamaChatSession, resolveModelFile } = await import('node-llama-cpp')

  const modelPath = await resolveModelFile(
    'hf_bartowski_gemma-2-2b-it-Q6_K_L.gguf',
    modelsDirectory,
  )

  const llama = await getLlama()
  const model = await llama.loadModel({ modelPath })
  const context = await model.createContext()

  let session: LlamaChatSession | undefined
  ipcMain.handle('llm:prompt', async (event, message: string) => {
    if (session) {
      session.dispose({ disposeSequence: true })
    }

    session = new LlamaChatSession({
      contextSequence: context.getSequence(),
    })

    const answer = await session.prompt(message)
    session.dispose({ disposeSequence: true })
    session = undefined

    return answer
  })
}

// ...

app.whenReady().then(async () => {
  const configStore = createConfigStore()
  await initIpcMain({ configStore })

  const mainWindow = await createInputWindow()

  initGlobalShortcut({ mainWindow })
  const tray = createTray({ mainWindow })

  app.on('window-all-closed', () => {
    if (process.platform !== 'darwin') {
      app.quit()
    }

    globalShortcut.unregisterAll()
    tray.destroy()
  })
})
```

現在讓我們來試試效果。

`src\App.vue`

```vue
<template>
  {{ ans }}
  <router-view />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useLlmApi } from './composables/use-llm-api'

// ...

const llmApi = useLlmApi()

const ans = ref('')
llmApi.prompt('你好 gemma').then((answer) => {
  ans.value = answer
})
</script>

// ...
```

![prompt-test](/cod-toys/prompt-test.png)

成功取得 gemma 回應！%( ´ ▽ \` )ﾉ%

### 重構 main.ts

`main.ts` 的東西越來越多了，現在讓我們重構一下，將範疇明確的程式碼分離。

拆分的檔案結構如下：

```txt
.
└── electron/
    ├── app/
    │   ├── config.ts
    │   ├── global-shortcut.ts
    │   ├── llm.ts
    │   └── tray.ts
    ├── electron-env.d.ts
    ├── main.ts
    └── preload.ts
```

內容就不一一列出了，主要就是將 `main.ts` 中的程式碼分別放到 `app` 目錄下的檔案中。

現在 `main.ts` 變得相當精簡。

`electron\main.ts`

```typescript
import type { ConfigStore } from './electron-env'
import process from 'node:process'
import {
  app,
  BrowserWindow,
  globalShortcut,
  ipcMain,
  shell,
} from 'electron'
import {
  createConfigStore,
  initConfigIpc,
} from './app/config'
import { initGlobalShortcut } from './app/global-shortcut'
import { initLlmIpc } from './app/llm'
import { createTray } from './app/tray'

async function createInputWindow() {
  // ...
}

async function initIpcMain(
  {
    configStore,
  }: {
    configStore: ConfigStore;
  },
) {
  // main
  ipcMain.on('main:updateHeight', (event, height: number) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setBounds({ height })
  })
  ipcMain.on('main:hideWindow', (event) => {
    const window = BrowserWindow.fromWebContents(event.sender)

    window?.setFocusable(false)
    window?.hide()
  })
  ipcMain.on('main:openExternal', (event, url: string) => {
    shell.openExternal(url)
  })

  await Promise.all([
    initConfigIpc({ configStore }),
    initLlmIpc({ configStore }),
  ])
}

app.whenReady().then(async () => {
  const configStore = createConfigStore()
  await initIpcMain({ configStore })

  const mainWindow = await createInputWindow()

  await initGlobalShortcut({ mainWindow })
  const tray = await createTray({ mainWindow })

  app.on('window-all-closed', () => {
    if (process.platform !== 'darwin') {
      app.quit()
    }

    globalShortcut.unregisterAll()
    tray.destroy()
  })
})
```

### 產生 tag 近義詞

現在來對顏文字的 tag 產生近義詞吧。

由於調用 LLM 極度消耗資源，同時希望產生每個 tag 的近義詞後，都立即更新到目前的顏文字列表中。

所以我們需要一個佇列來處理這些非同步任務，這裡使用 `p-queue` 執行非同步任務，一次只執行一個任務。

`src\domains\feature-card-kaomoji\use-kaomoji-data.ts`

```typescript
import type { Ref } from 'vue'
import PQueue from 'p-queue'
import { flatMap, unique } from 'remeda'
import { useLlmApi } from '../../composables/use-llm-api'

export function useKaomojiData(
  inputText: Ref<string>,
) {
  const llmApi = useLlmApi()
  // ...

  const tagSynonymMap = shallowRef(new Map<string, string>())
  const tagSynonymQueue = new PQueue({
    concurrency: 1,
    timeout: 1000 * 60 * 5,
  })
  watch(list, piped(
    // 先清空 tagSynonymQueue
    tap(() => tagSynonymQueue.clear()),
    flatMap((item) => item.tags),
    unique(),
    forEach((tag) => {
      tagSynonymQueue.add(async () => {
        const synonym = await llmApi.prompt(
          `${tag}的 5 個繁體中文近義詞，5 個英文近義詞，全部合併，逗號分隔，不要任何附加資訊，不要標題，不需解釋`,
        )
        tagSynonymMap.value.set(tag, synonym)
        triggerRef(tagSynonymMap)
      })
    }),
  ))

  // ...
}
```

接著將 tag 與近義詞內容匹配並放入模糊搜尋中。

`src\domains\feature-card-kaomoji\use-kaomoji-data.ts`

```typescript
export function useKaomojiData(
  inputText: Ref<string>,
) {
  const listWithSynonym = computed(() => pipe(
    list.value,
    map((item) => {
      /** 全部拼在一起即可 */
      const synonym = pipe(
        item.tags,
        map((tag) => tagSynonymMap.value.get(tag) ?? ''),
        join(','),
      )

      return {
        ...item,
        synonym,
      }
    }),
  ))

  const fuseInstance = new Fuse(listWithSynonym.value, { // [!code highlight]
    keys: ['tags', 'synonym'], // [!code highlight]
  })
  watch(listWithSynonym, (value) => { // [!code highlight]
    fuseInstance.setCollection(value)
  })

  const filteredList = computed(() => {
    if (inputText.value === '@') {
      return listWithSynonym.value // [!code highlight]
    }

    const text = pipe(
      inputText.value,
      (value) => {
        if (value.startsWith('@')) {
          return value.slice(1)
        }

        return value
      },
      (value) => value.trim(),
    )

    const result = fuseInstance.search(text)

    return pipe(
      result,
      map(prop('item')),
    )
  })

  // ...
}
```

最後讓我們把有近義詞的項目用個小圖示標註一下。

`src\domains\feature-card-kaomoji\index.vue`

```vue{26-31}
<template>
  <template v-if="visible">
    <feature-option
      v-if="!isFeature"
      // ...
    />

    <template v-else>
      // ...

      <feature-option
        v-for="item, i in paginationList"
        :key="i"
        class="w-full px-4 py-1"
        :action="() => copy(item.value)"
      >
        // ...

        <div class="flex items-end">
          <q-chip
            v-for="tag in item.tags"
            :key="tag"
            :label="tag"
          />

          <q-icon
            v-if="item.synonym"
            color="gray"
            name="task_alt"
            size="1rem"
          />
        </div>
      </feature-option>

      // ...
    </template>
  </template>
</template>

// ...
```

![synonym-search](/cod-toys/synonym-search.gif)

使用體驗提升！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/side-project-cod-toys/tree/feat/kaomoji-add-llm)

我們成功實作了近義詞搜尋，讓使用者可以更快速地找到想要的顏文字。%(\*´∀\`)~♥%

模型選用或提詞內容其實還可以持續調整，這個我決定留給未來的自己惹。

---

---
url: /blog-program/using-comlink.md
description: Web Worker 很棒，但 postMessage 用起來實在太痛苦了，讓 Comlink 來救場吧！( •̀ ω •́ )✧
---

![using-comlink](/using-comlink.webp){.cover}

# Comlink 讓 Web Worker 不再難用

大家有沒有遇過這種情境，點了按鈕後，整個頁面就瞬間凍結，久久沒有回應，就像那個停留在「哈哈去洗澡」的對話框一樣。%( ´•̥̥̥ ω •̥̥̥\` )%

這通常是因為有段很重的計算邏輯跑在主執行緒（Main Thread），把 JavaScript 的單執行緒塞爆了。

解法大家都知道，那就是 Web Worker，把粗活丟給別的執行緒去跑。

不過 Web Worker 原生的 API 用起來嘛...

路人：「和你一樣煩人？」

鱈魚：「說好得尊重呢？%( ˘･з･)%」

今天要來介紹一個神奇小工具 **Comlink**，讓 Web Worker 用起來像呼叫普通的 async function 一樣爽。%( •̀ ω •́ )✧%

## Web Worker 是什麼

Web Worker 說穿了就是瀏覽器提供的「背景打工仔」機制。

主執行緒就像是老闆，專門處理畫面渲染、使用者互動這些重要事情，不能被打擾。

Worker 就是打工仔，被指派去做耗時的重活，例如大量資料運算、影像處理、加解密等等，完成後再把結果回報給老闆。

兩邊溝通使用的是 `postMessage` 與 `onmessage`。

聽起來簡單易懂對吧？%( ・ิω・ิ)%

## 原生 postMessage 有多麻煩

來看看傳統的 Web Worker 用法。

假設我們有個很重的計算，需要把一個大陣列的每個元素做費波那契數列計算。

路人：「和鱈魚一樣重嗎？」

鱈魚：「重...重才值錢啊。%ლ(・´ｪ\`・ლ)%」

首先建立打工仔檔案：

`src/workers/heavy-calc.worker.ts`

```ts
function fibonacci(n: number): number {
  if (n <= 1)
    return n
  return fibonacci(n - 1) + fibonacci(n - 2)
}

self.onmessage = (event: MessageEvent<number[]>) => {
  const list = event.data
  const result = list.map((n) => fibonacci(n))
  self.postMessage(result)
}
```

然後在主執行緒呼叫：

```ts
const worker = new Worker(
  new URL('../workers/heavy-calc.worker.ts', import.meta.url),
  { type: 'module' }
)

worker.postMessage([40, 41, 42])

worker.onmessage = (event: MessageEvent<number[]>) => {
  console.log('結果：', event.data)
}
```

路人：「這樣看起來還好嘛，哪裡麻煩了？」

鱈魚：「問題來了，現實中打工仔通常不只做一件事，老闆也不只發一個命令。」

各位社畜一定很懂吧？%ლ(・´ｪ\`・ლ)%

如果我想讓同一個 Worker 支援多種計算，就要自己手刻一套訊息分發機制：

```ts
// worker 端
self.onmessage = (event: MessageEvent) => {
  const { type, payload, id } = event.data

  if (type === 'fibonacci') {
    const result = payload.map(fibonacci)
    self.postMessage({ id, result })
  }
  else if (type === 'sort') {
    const result = [...payload].sort((a, b) => a - b)
    self.postMessage({ id, result })
  }
  // 越來越多 else if...
}
```

```ts
// 主執行緒
let callId = 0
const pendingMap = new Map<number, (result: unknown) => void>()

worker.onmessage = (event: MessageEvent) => {
  const { id, result } = event.data
  pendingMap.get(id)?.(result)
  pendingMap.delete(id)
}

function callWorker(type: string, payload: unknown) {
  return new Promise((resolve) => {
    const id = callId++
    pendingMap.set(id, resolve)
    worker.postMessage({ type, payload, id })
  })
}

const result = await callWorker('fibonacci', [40, 41])
```

這根本是在自己刻一個 RPC 框架，而且錯誤處理、TypeScript 型別、cleanup 邏輯都還沒算進去。%Σ(ˊДˋ;)%

## Comlink 出場

[Comlink](https://github.com/GoogleChromeLabs/comlink) 是 Google Chrome 團隊開發的小工具，它做的事情很單純，就是把上面那堆 `postMessage` 的麻煩事全部包起來。

讓你可以在主執行緒直接呼叫 Worker 裡面的 function，就像呼叫普通的 async function 一樣。

先安裝：

```bash
npm install comlink
```

先來看改寫後的打工仔：

`src/workers/heavy-calc.worker.ts`

```ts
import { expose } from 'comlink'

function fibonacci(n: number): number {
  if (n <= 1)
    return n
  return fibonacci(n - 1) + fibonacci(n - 2)
}

const api = {
  calcFibonacci(list: number[]): number[] {
    return list.map((n) => fibonacci(n))
  },

  sortNumbers(list: number[]): number[] {
    return [...list].sort((a, b) => a - b)
  },
}

expose(api)

export type WorkerApi = typeof api
```

然後在主執行緒：

```ts
import type { WorkerApi } from './workers/heavy-calc.worker'
import { wrap } from 'comlink'

const worker = new Worker(
  new URL('./workers/heavy-calc.worker.ts', import.meta.url),
  { type: 'module' }
)

const api = wrap<WorkerApi>(worker)

// 直接呼叫，完全感覺不到 postMessage 的存在
const result = await api.calcFibonacci([40, 41, 42])
const sorted = await api.sortNumbers([3, 1, 4, 1, 5, 9])
```

是不是很讚啊！之前那堆 `callId`、`pendingMap`、訊息分發邏輯全部不見了。%( •̀ ω •́ )✧%

而且因為有 `export type WorkerApi`，TypeScript 的型別提示也完整保留了！%ヽ(●\`∀´●)ﾉ%

## 在 Vue 中整合 Comlink

知道 Comlink 怎麼用之後，所以該怎麼在 Vue 中應用呢？

推薦寫成 Composable，讓 Worker 的生命週期跟著元件走，不用手動管理。

### 建立 Composable

`src/composables/use-heavy-calc-worker.ts`

```ts
import type { WorkerApi } from '../workers/heavy-calc.worker'
import { wrap } from 'comlink'
import { onScopeDispose, shallowRef } from 'vue'

export function useHeavyCalcWorker() {
  const worker = new Worker(
    new URL('../workers/heavy-calc.worker.ts', import.meta.url),
    { type: 'module' }
  )

  const api = wrap<WorkerApi>(worker)

  const isLoading = shallowRef(false)

  // 元件解除時自動清理 Worker
  onScopeDispose(() => {
    worker.terminate()
  })

  async function calcFibonacci(list: number[]) {
    isLoading.value = true
    try {
      return await api.calcFibonacci(list)
    }
    finally {
      isLoading.value = false
    }
  }

  return {
    isLoading,
    calcFibonacci,
  }
}
```

### 在元件中使用

`src/components/HeavyCalc.vue`

```vue
<template>
  <div>
    <q-btn
      :loading="isLoading"
      color="primary"
      label="開始計算"
      @click="handleCalc"
    />

    <div v-if="result">
      結果：{{ result }}
    </div>
  </div>
</template>

<script setup lang="ts">
import { shallowRef } from 'vue'
import { useHeavyCalcWorker } from '../composables/use-heavy-calc-worker'

const { isLoading, calcFibonacci } = useHeavyCalcWorker()
const result = shallowRef<number[]>()

async function handleCalc() {
  result.value = await calcFibonacci([38, 39, 40, 41, 42])
}
</script>
```

這樣就完成了！主執行緒完全不會被卡住，使用者點按鈕之後畫面繼續流暢運作，繁重任務在背景處理，默默壓榨 Worker。%( ´థ౪థ)b%

## Worker 共享還是獨立？

有個小細節值得討論，Worker 的建立方式會影響它的生命週期與資源使用。

### 每個元件自己的 Worker

剛才的做法是每個元件實例都建立一個新的 Worker，優點是元件解除後 Worker 自動跟著清掉，不會有資源洩漏問題。

缺點是如果同一個頁面有很多元件都需要這個 Worker，就會建立很多 Worker 實例，消耗比較多資源。

### 全域共享 Worker

如果同一個打工仔需要被很多地方使用，可以用 VueUse 提供的 [`createSharedComposable`](https://vueuse.org/shared/createSharedComposable/) 把剛才的 Composable 升級成全域共享版本。

`createSharedComposable` 會讓所有呼叫這個 Composable 的元件共用同一個狀態實例，當最後一個使用它的元件解除後，才會執行清理邏輯。

`src/composables/use-heavy-calc-worker.ts`

```ts
import type { WorkerApi } from '../workers/heavy-calc.worker'
import { createSharedComposable } from '@vueuse/core'
import { wrap } from 'comlink'
import { onScopeDispose, shallowRef } from 'vue'

function _useHeavyCalcWorker() {
  // 整個 app 只建立一個 Worker
  const worker = new Worker(
    new URL('../workers/heavy-calc.worker.ts', import.meta.url),
    { type: 'module' }
  )
  const api = wrap<WorkerApi>(worker)

  const isLoading = shallowRef(false)

  onScopeDispose(() => {
    worker.terminate()
  })

  async function calcFibonacci(list: number[]) {
    isLoading.value = true
    try {
      return await api.calcFibonacci(list)
    }
    finally {
      isLoading.value = false
    }
  }

  return { isLoading, calcFibonacci }
}

export const useHeavyCalcWorker = createSharedComposable(_useHeavyCalcWorker)
```

元件的使用方式完全不用改，但現在不管幾個元件呼叫 `useHeavyCalcWorker`，都只會建立一個 Worker 實例。%( •̀ ω •́ )✧%

不過要注意的是，Worker 是單執行緒的，如果同時發出多個請求，它們會排隊執行。%(´● ω ●\`)%

### 簡單判斷原則

* 計算量輕、元件少 → 每個元件自己的 Worker，簡單乾淨
* 計算量重、多處使用 → 全域共享 Worker，節省資源
* 需要同時跑多個任務 → 建立 Worker Pool（這個比較進階，之後有機會再寫）

## 使用限制

Comlink 雖然好用，但還是有些需要注意的地方。

### 只能傳遞可序列化的資料

Worker 之間的通訊底層還是依賴 `postMessage`，所以傳遞的資料必須是可以被 [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) 複製的類型。

Function、DOM 元素、class 實例（method 會消失）這類都沒辦法傳遞。

如果需要傳遞大型 ArrayBuffer，可以使用 Comlink 提供的 `transfer` 工具：

```ts
import { transfer, wrap } from 'comlink'

const api = wrap<WorkerApi>(worker)

const buffer = new ArrayBuffer(1024 * 1024)

// transfer 會轉移所有權，主執行緒就不再能使用這個 buffer
await api.processBuffer(transfer(buffer, [buffer]))
```

### Worker 內無法存取 DOM

打工仔不能碰 DOM，這是天條，只能做純粹的資料計算。

### TypeScript 設定

Vite 專案通常不需要額外設定，但如果遇到 Worker 內的 TypeScript 型別問題，可以在 `tsconfig.json` 加上：

```json
{
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "WebWorker"]
  }
}
```

## 總結 🐟

* Web Worker 讓耗時計算不阻塞主執行緒，頁面保持流暢
* 原生 `postMessage` 需要手刻訊息分發機制，相當麻煩
* Comlink 的 `expose` 與 `wrap` 把這些苦活全包了，直接像呼叫 async function 一樣使用
* 搭配 Vue Composable 使用，可以讓 Worker 生命週期跟著元件走
* Worker 只能傳遞可序列化的資料，不能操作 DOM

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教 %(\*´∀\`)~♥%

---

---
url: /aquarium/cyber-scales-desktop.md
description: 科幻風格的 Web Desktop 應用程式
---


---

---
url: /blog-program/effect-ts-in-real-projects.md
description: Effect 接進 Vue、NestJS、oRPC 是什麼感覺？順便實測效能，最後做一支 todo API ( •̀ ω •́ )✧
---

![effect-ts-in-real-projects](/effect-ts-in-real-projects.webp){.cover}

# Effect 接進真實專案是什麼感覺？Vue、NestJS、oRPC 通通試一遍 ( •̀ ω •́ )✧

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

這篇是上下兩篇的**下篇**。

上篇[來認識 Effect](/blog-program/getting-to-know-effect-ts)講完了核心概念，用一句話複習就是，Effect 把「會怎麼失敗」跟「需要什麼」寫進 `Effect<A, E, R>` 的型別裡，而且後兩欄由編譯器自己算。

沒看過上篇的話建議先去看，這篇會直接用 `yield*`、`Layer` 這些詞，也會一直提到 `Effect<A, E, R>` 那三欄。

先複習一下那三欄各自代表什麼，免得後面看得霧煞煞。

| 欄位 | 意思 |
|---|---|
| `A` | 成功會拿到什麼 |
| `E` | 可能會怎麼失敗 |
| `R` | 需要哪些服務才跑得起來 |

概念講完，接下來是真正會踩到的問題。

* 接進 Vue 元件是什麼感覺？值不值得？
* `@effect/platform` 跟 NestJS 差在哪？效能呢？
* 已經在用 oRPC 的話，兩者會不會打架？
* 從零開始寫一支 API，到底要多少行？

一個一個來。%( •̀ ω •́ )✧%

## Vue 要怎麼接

聊完後端邏輯，換個場景，Effect 寫的服務要怎麼接進 Vue 元件？

先講 npm 上的現況，因為這件事最近剛翻盤。%(´,,•ω•,,)%

Effect v4 把響應式綁定收進核心，`@effect/atom-vue` 成了**官方套件**，跟 React、Solid 並列三個官方支援的前端框架。

不過有個現實問題，`@effect/atom-vue` **只支援 v4**，而 v4 目前還在 RC。

現在 `npm install effect` 裝到的是 v3，v3 時代的 Vue 綁定是 Effect 核心成員 tim-smart 個人維護的 [`@effect-atom/atom-vue`](https://github.com/tim-smart/effect-atom)。

路人：「所以到底能不能用？%(´・ω・\`)%」

鱈魚：「能，但你會是很前面的那批白老鼠。%(´\_ゝ\`)%」

考量到版本還沒穩定，接下來還是示範怎麼自己接，反正就三十行，順便也看得懂官方套件在做什麼。

第一步準備一個 app 層級的 runtime，把 Layer 組合起來，變成可重複使用的執行環境。

```ts
// runtime.ts
import { Layer, ManagedRuntime } from 'effect'
import { Database, EmailService } from './register-user'

const AppLayer = Layer.mergeAll(
  Database.Default,
  EmailService.Default,
)

export const appRuntime = ManagedRuntime.make(AppLayer)
```

再包一層 composable，把 Effect 的執行結果接回 Vue 的 `ref`。

```ts
// useRegisterUser.ts
import { Effect, Fiber } from 'effect'
import { onUnmounted, ref } from 'vue'
import { registerUser, type User } from './register-user'
import { appRuntime } from './runtime'

export function useRegisterUser() {
  const user = ref<User | null>(null)
  const error = ref<unknown>(null)
  const loading = ref(false)

  let fiber: Fiber.RuntimeFiber<User, unknown> | undefined

  function submit(target: User) {
    loading.value = true
    error.value = null

    fiber = appRuntime.runFork(
      registerUser(target).pipe(
        Effect.tap((result) => Effect.sync(() => (user.value = result))),
        Effect.tapError((cause) => Effect.sync(() => (error.value = cause))),
        Effect.ensuring(Effect.sync(() => (loading.value = false))),
      ),
    )
  }

  onUnmounted(() => {
    if (fiber) {
      Effect.runFork(Fiber.interrupt(fiber))
    }
  })

  return { user, error, loading, submit }
}
```

還記得前面說 Effect 寫好了也不會跑嗎？`runFork` 就是把描述交出去執行的那一刻。

它不等結果，馬上回傳一個 `Fiber`，元件卸載時呼叫 `Fiber.interrupt` 就能中斷，跟原生用 `AbortController` 取消 `fetch` 是同一件事，只是換了個名字。

路人：「一定要用 `ManagedRuntime` 嗎？直接 `Effect.runPromise` 不行嗎？%(´・ω・\`)%」

鱈魚：「單次呼叫用 `Effect.runPromise` 完全沒問題，只是每次都要重新 provide 一次 Layer，跟全 app 共用一個 runtime 比起來浪費資源，服務也沒辦法重複使用。%( •̀ ω •́ )%」

元件測試或 Storybook 想塞一顆假的 `EmailService`，就別直接 import 那個單例 runtime，改用 `provide`/`inject` 傳下去。

```ts
// runtime-provider.ts
import type { ManagedRuntime } from 'effect'
import type { Database, EmailService } from './register-user'
import { inject, type InjectionKey, provide } from 'vue'

type AppRuntime = ManagedRuntime.ManagedRuntime<Database | EmailService, never>

const runtimeKey: InjectionKey<AppRuntime> = Symbol('effect-runtime')

export function provideRuntime(runtime: AppRuntime) {
  provide(runtimeKey, runtime)
}

export function useRuntime() {
  const runtime = inject(runtimeKey)
  if (!runtime) {
    throw new Error('找不到 runtime，記得先 provideRuntime')
  }
  return runtime
}
```

測試時在最外層塞一顆帶測試 Layer 的 runtime，底下所有 composable 拿到的就是測試版本，元件本身完全不用改，跟後端替換 Layer 是同一套心智模型。%(´,,•ω•,,)%

### 那前端到底該不該用？

教完怎麼接，還是得講一下該不該接。

先講我的看法，**多數 Vue 專案不值得**。%(´\_ゝ\`)%

上面那個 composable 就是證據，三十行的膠水，做的事情 `useMutation` 大概三行就交代完了。

原因有這幾個。

**一、`R`（依賴服務）在前端沒什麼用武之地**

`Effect<A, E, R>` 的第三欄，記錄這段程式需要哪些服務才跑得起來。它最大的價值是測試時可以換掉那些服務，但前端測元件通常不從服務那層換。

主流做法是拿 [MSW](https://mswjs.io/) 在**網路那層**攔截，元件、composable、`fetch` 全部照原樣跑，攔的是 HTTP 請求本身。

這種測法更接近使用者的真實路徑，也不用為了好測而改生產程式碼的架構。Layer 替換的優勢，在這裡幾乎用不上。%( ˘•ω•˘ )%

**二、`E`（可能錯誤）到了畫面上會被壓扁**

第二欄，記錄這段程式可能失敗的所有原因。

後端區分 `UserNotFound` 跟 `NetworkError` 很有意義，因為要回不同的 status code。

前端呢？多數情況就三種反應，顯示錯誤訊息、重試、當作沒發生。

八種錯誤型別到了 UI 層常常被壓成同一個 `catch`，那份精細度就浪費了。

**三、該有的輪子早就有人造好了**

Effect 的 `retry`、`timeout`、Fiber 中斷聽起來很威，但這些正是 [TanStack Query](https://tanstack.com/query)、[Pinia Colada](https://pinia-colada.esm.dev/) 這類套件的本業。

而且它們還多做了 Effect 不管的事，快取、失效重取、視窗聚焦重新整理、devtools。

拿 Effect 從頭刻這些，其實是降級。

**四、bundle size 是真的成本**

後端多幾百 KB 沒人在意，前端每一 KB 都要使用者用流量跟載入時間去付。

官方的 [Myths 頁面](https://www.effect.website/docs/v3/additional-resources/myths)有一條就叫「The bundle size is HUGE!」，可見這個質疑常被提出。官方的回應是這樣。

> Effect 的最低成本大約是 25k 的 gzipped 程式碼，那個 chunk 包含 Effect Runtime，而且已經涵蓋一般 app 會用到的幾乎所有函數。
>
> 從那之後 Effect 對 tree-shaking 很友善，你只會打包到自己用到的部分。

這個說法有它的道理，關鍵字是 **tree-shaking**。25KB 是「起跳價」，不是整包的大小。

不過那個數字沒有附上量測方法，而且它比較的基準是「你也寫了同樣功能的程式碼」。官方另外提到採用 Effect 後自己的程式碼會變短，總成本被攤平，這點就得看專案實際情況了。%( ˘•ω•˘ )%

務實的建議是別直接相信任何一方的數字，接上 bundle 分析工具實際量一次。

後端完全不用煩惱這件事，這一條是前端獨有的成本。

**五、官方綁定還沒進穩定版**

前面提過，`@effect/atom-vue` 只支援還在 RC 的 v4，文件頁也幾乎是空的。

自己接的話，那個 composable 沒有人幫你維護，Vue 改版、Effect 改版都是你自己的事。

路人：「所以你剛剛教那一大段是白教的？%(´・ω・\`)%」

鱈魚：「還是有值得用的時候，只是我想來想去只想到一種。%( ˘•ω•˘ )%」

**那就是前端真的有很複雜的非同步流程。**

多步驟上傳佇列要重試跟退避、即時協作要處理競態、離線同步要對帳，這種場景拿 `AbortController` 配一堆 flag 硬拼會很痛苦，Fiber 的中斷模型確實舒服很多。

不過老實說，這種情況比大家想像的少。

大部分畫面就是「拿資料、顯示、送出表單」，這種需求用不到 Effect 三成的能力，卻要付出全部的學習成本。%( ˘•ω•˘ )%

## `@effect/platform` 不只是 HTTP

Vue 那段是把服務接到畫面上，換個方向，`registerUser` 要變成一支 HTTP API 呢？

Effect 生態圈負責這塊的是 `@effect/platform`。

不過先澄清一個常見誤解，很多人把它當成「Effect 版的 Express」，它真正的定位是**跨平台的系統能力抽象層**。

HTTP 只是其中一個模組，同一包裡面還有這些。

| 模組 | 管什麼 |
|---|---|
| `HttpApi`、`HttpServer`、`HttpClient` | REST API、發請求 |
| `Socket` | WebSocket 與 TCP socket |
| `FileSystem`、`Path` | 檔案讀寫、路徑處理 |
| `Command` | 開子行程、串接 stdin/stdout |
| `Worker` | Web Worker 與 `worker_threads` |
| `Terminal` | CLI 的終端機輸入輸出 |
| `KeyValueStore` | 鍵值儲存，可換成記憶體、檔案或其他後端 |

這些模組只定義**介面**，真正的實作放在各平台的套件裡。

```bash
npm install effect @effect/platform @effect/platform-node
```

以 `Worker` 為例，同一份丟工作給背景執行緒的程式碼，在 Node 由 `@effect/platform-node` 接到 `worker_threads`，在瀏覽器由 `@effect/platform-browser` 接到 Web Worker，換的是最外層那顆 Layer。

看出來了嗎？這就是 `R`（依賴服務）那一欄的老把戲，只是這次被抽換的是**執行環境本身**。%( •̀ ω •́ )✧%

::: tip 不是每個模組每個平台都有實作
`FileSystem` 跟 `Command` 這種東西，瀏覽器根本沒有對應的能力，自然就沒有 browser 版。

`@effect/platform-browser` 提供的是 `BrowserKeyValueStore`（背後是 localStorage）、`BrowserSocket`、`BrowserWorker` 這些瀏覽器真的做得到的事。

所以「跨平台」指的是**介面一致**，不是每個平台都通吃。
:::

回到 HTTP，核心是 `HttpApi`。

第一步先宣告這支 API 長什麼樣，`api.ts`

```ts
import { HttpApi, HttpApiEndpoint, HttpApiGroup } from '@effect/platform'
import { Schema } from 'effect'

export const UserSchema = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
})

export class EmailSendFailed extends Schema.TaggedError<EmailSendFailed>()('EmailSendFailed', {
  email: Schema.String,
}) {}

export const UsersApi = HttpApi.make('UsersApi').add(
  HttpApiGroup.make('users').add(
    HttpApiEndpoint.post('register', '/users')
      .setPayload(UserSchema)
      .addSuccess(UserSchema)
      .addError(EmailSendFailed, { status: 502 }),
  ),
)
```

這個檔案沒有任何實作，純粹描述「收什麼、回什麼、可能出什麼錯」。

錯誤型別從 `Data.TaggedError` 換成 `Schema.TaggedError`，因為它要轉成 JSON 送給前端，得有 schema 才知道怎麼轉。

第二步接上實作，`api-live.ts`

```ts
import { HttpApiBuilder } from '@effect/platform'
import { Layer } from 'effect'
import { UsersApi } from './api'
import { registerUser } from './register-user'

const UsersLive = HttpApiBuilder.group(UsersApi, 'users', (handlers) =>
  handlers.handle('register', ({ payload }) => registerUser(payload)))

export const ApiLive = HttpApiBuilder.api(UsersApi).pipe(
  Layer.provide(UsersLive),
)
```

請看 handler 那行，`registerUser(payload)` 直接回傳，**`registerUser` 一個字都沒改**。

也請注意這裡**沒有** provide 任何服務，`ApiLive` 到現在還缺著 `Database` 跟 `EmailService`，那份清單原封不動掛在型別上。

第三步才把真的服務填進去，順便跑起來，`server.ts`

```ts
import { createServer } from 'node:http'
import { HttpApiBuilder, HttpApiSwagger } from '@effect/platform'
import { NodeHttpServer, NodeRuntime } from '@effect/platform-node'
import { Layer } from 'effect'
import { ApiLive } from './api-live'
import { Database, EmailService } from './register-user'

const ServerLive = HttpApiBuilder.serve().pipe(
  Layer.provide(HttpApiSwagger.layer()),
  Layer.provide(ApiLive),
  Layer.provide(Database.Default),
  Layer.provide(EmailService.Default),
  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
)

Layer.launch(ServerLive).pipe(NodeRuntime.runMain)
```

`npx tsx server.ts` 跑下去，`POST /users` 就活了，打開 `/docs` 還有一份 Swagger 在等你。

那份文件不用另外寫，從 `api.ts` 的 `Schema` 長出來，同一份定義還能再產一支型別安全的前端 client。%( •̀ ω •́ )✧%

宣告、實作、組裝剛好三個檔案，一路上沒有裝飾器，也沒有「框架偷偷幫你做了什麼」的環節。

「什麼時候把依賴填進去」一路推到最外面那層，等一下講測試會再回來咬一口。%(´,,•ω•,,)%

### 換 NestJS 寫一次

同一支 API 用 NestJS 寫，大概長這樣。

```ts
// users.controller.ts
@Controller('users')
export class UsersController {
  constructor(
    private readonly database: Database,
    private readonly emailService: EmailService,
  ) {}

  @Post()
  async register(@Body() dto: RegisterUserDto) {
    await this.database.save(dto)
    await this.emailService.sendWelcomeEmail(dto.email)
    return dto
  }
}
```

```ts
// users.module.ts
@Module({
  controllers: [UsersController],
  providers: [Database, EmailService],
})
export class UsersModule {}
```

平心而論，NestJS 這段寫得很舒服，建構子把依賴列得清清楚楚，比前面那個直接 import 單例的版本好太多。%(´,,•ω•,,)%

路人：「那不就一樣？依賴也是攤在明面上啊。%(・∀・)%」

鱈魚：「差在**保護範圍**跟**什麼時候發現**。%( ˘•ω•˘ )%」

建構子注入只在 class 裡成立，`registerUser` 這種普通函數一旦搬出 controller，依賴又躲回 import 裡了。Effect 沒有這個限制，那份清單跟著 `Effect` 型別走，是函數是 class 都一樣。

至於什麼時候發現，`UsersModule` 的 `providers` 少填一個，TypeScript 完全不會有意見，因為那只是一個陣列，得等啟動時 Nest 組裝容器才會噴 `can't resolve dependencies`。

Effect 版本少 provide 一顆 Layer，紅的是編譯器。%(°ㅂ°)%

### 測試的時候差更多

回到前面那個問題，測這支 API 要怎麼換掉 `EmailService`？

NestJS 有一套測試專用的模組 API，得把模組重新宣告一次，再指定要蓋掉誰。

```ts
const moduleRef = await Test.createTestingModule({
  controllers: [UsersController],
  providers: [Database, EmailService],
})
  .overrideProvider(EmailService)
  .useValue({ sendWelcomeEmail: vi.fn() })
  .compile()

const controller = moduleRef.get(UsersController)
```

Effect 這邊沒有「測試專用 API」這種東西。

還記得剛剛把依賴推到最外層嗎？正式環境在 `server.ts` 填真的，測試就填假的，如此而已。

```ts
Layer.provide(EmailService.Default) // [!code --]
Layer.provide(EmailServiceTest) // [!code ++]
```

`api.ts`、`api-live.ts`、`registerUser` 三個檔案完全不用動，因為它們從頭到尾就沒決定過要用哪個實作。%(ゝ∀・)b%

整理成表格比較好認。

| 比較項目 | NestJS | Effect Platform |
|---------|--------|------------------|
| 依賴注入 | 建構子加裝飾器，執行期組裝容器 | `Context`/`Layer`，清單寫在型別的 `R` 那一欄 |
| 漏了依賴 | 啟動時噴 `can't resolve dependencies` | 編譯器直接紅 |
| 保護範圍 | 只有 class 有 | 函數、class、endpoint 都一樣 |
| 資料驗證 | class-validator 寫 DTO | `Schema`，順便長出文件跟 client |
| 中介層 | `@UseGuards`、Interceptor，另一套機制 | `HttpApiMiddleware`，跟一般服務同一套 Layer |
| 測試替換 | `Test.createTestingModule().overrideProvider()` | `Effect.provide`，跟測普通函數同一招 |

### 那效能呢？

路人：「講這麼多，跑起來到底快不快？%(・∀・)%」

鱈魚：「先講結論，這大概不是你該煩惱的事，不過數字還是值得看。%(´\_ゝ\`)%」

資料來源是 [SaltyAom 的 HTTP 框架 benchmark](https://github.com/SaltyAom/bun-http-framework-benchmark)，目前唯一同時收錄 Effect 跟 NestJS 的公開測試。

**看數字之前，先講三個一定要知道的前提。**%( ˘•ω•˘ )%

* 表中的 Effect 是 **v4 beta 的 `effect/unstable/http`**，跟你現在 `npm install @effect/platform` 裝到的 v3 是兩套程式碼。v3 那條線沒有任何公開效能數據
* Effect 那組**關掉了 tracing 跟 request logging**，兩者都是框架預設開啟的。照預設寫的服務不會有這個表現
* NestJS 跑**預設的 Express adapter**，官方文件說換成 Fastify adapter 可以快將近一倍，那個組合沒人測過

所以底下的數字只能當**方向參考**，不能當結論。

底下只列 Node 的數字，Bun 那組跳過，畢竟多數人的正式環境還是跑 Node。

#### 一、吞吐量

| 框架 | 平均 req/s |
|---|---:|
| Fastify | 97,934 |
| Hono | 91,090 |
| **Effect** | **58,684** |
| Express | 42,226 |
| NestJS | 31,271 |

Effect 大約是 NestJS 的 1.9 倍、Express 的 1.4 倍，但只有 Fastify 的六成。

這張表能證明的只有一件事，**Effect 的 HTTP 層沒有大家想像中那麼肥**。%(´,,•ω•,,)%

#### 二、延遲

先講壞消息，**P99 這類百分位數字沒有**。

那份 benchmark 用 bombardier 壓測，而百分位要加 `-l` 參數才會輸出，他們沒加。想要 p99 就得自己 clone 下來重跑。%(´\_ゝ\`)%

不過延遲資料本身是有的，只是不在 README 那張表上。

repo 裡有 commit 原始的壓測輸出（`results/node/*.txt`），bombardier 預設就會印**平均、標準差、最大值**這三項，下面的數字都是從那些檔案挖出來的。

標準差跟最大值其實更好玩，因為它們反映的正是**尾端延遲穩不穩**，跟 P99 想回答的是同一個問題。

以 `GET /` 這條路由、500 連線跑十秒來看。

| 框架 | 平均延遲 | 標準差 | 最大延遲 |
|---|---:|---:|---:|
| Fastify | 3.33 ms | 5.93 ms | 777 ms |
| **Effect** | **5.49 ms** | **15.04 ms** | **1.44 s** |
| Express | 7.68 ms | 23.55 ms | 1.90 s |
| NestJS | 10.32 ms | 42.07 ms | 3.20 s |

看最後兩欄，排序跟平均延遲一致，但差距被放大了。

NestJS 平均 10ms 看起來還好，標準差卻是 42ms、最壞情況 3.2 秒。這代表**有一小撮倒楣的請求等了非常久**，而那些人剛好就是 P99 會抓出來的族群。%(°ㅂ°)%

Effect 的尾端比 Express 跟 NestJS 收斂，但離 Fastify 還有一段距離。

所以只看平均延遲會少看很多東西，那幾個等到天荒地老的使用者，全都藏在後面兩欄裡。%( ˘•ω•˘ )%

#### 三、冷啟動與基準記憶體

| 框架 | 啟動時間 | 啟動後 RSS | Bundle |
|---|---:|---:|---:|
| Hono | 45.2 ms | 95.7 MB | 61.2 KB |
| Express | 50.2 ms | 86.6 MB | 603.6 KB |
| Fastify | 67.2 ms | 98.4 MB | 554.7 KB |
| **Effect** | **80.9 ms** | **90.7 MB** | 357.6 KB |
| NestJS | 110.3 ms | 119.0 MB | 1.3 MB |

啟動時間量的是「行程 spawn 到第一個請求成功回應」，Effect 比 NestJS 快約 27%，但輸給 Express 跟 Hono。

基準記憶體大家其實差不多，NestJS 的 119MB 稍微突出，bundle 也是唯一破 1MB 的。

要注意的是**這不等於 serverless 冷啟動**。Lambda、Workers 那種環境還有 INIT、快照還原一整套流程，含 Effect 的冷啟動實測我完全找不到。

如果你要部署到 Cloudflare Workers，倒是有個數字要留意，`effect` 本身壓縮後約 293KB、`@effect/platform` 約 1.49MB（未 tree-shaking 的上限值），而 Workers 免費方案的限制是 1MB。%( ˘•ω•˘ )%

#### 四、高負載後的資源釋放

這欄我覺得最有意思。同一份表格記錄了壓測前後的 RSS 變化。

| 框架 | 壓測前 | 壓測後 | 成長 |
|---|---:|---:|---:|
| **Effect** | 90.7 MB | 114.6 MB | **+23.9 MB（+26%）** |
| Fastify | 98.4 MB | 162.3 MB | +63.9 MB（+65%） |
| NestJS | 119.0 MB | 224.8 MB | +105.8 MB（+89%） |
| Hono | 95.7 MB | 217.1 MB | +121.4 MB（+127%） |
| Express | 86.6 MB | 223.8 MB | +137.2 MB（+158%） |

Effect 的記憶體成長是 Express 的六分之一、NestJS 的四分之一。

而且它的吞吐量還比這兩個高，照理說配置率應該更高才對，結果反而長最少。%(⊙ロ⊙)%

路人：「是 Effect 的 Scope 在做資源回收嗎？%(・∀・)%」

鱈魚：「我一開始也這樣猜，但查完文件發現不能這樣講。%( ˘•ω•˘ )%」

`Scope` 保證的是檔案、連線這類**明確取得的資源**會被確實釋放，但這份 benchmark 的路由根本沒開這些東西，機制等於沒出場。

所以合理的講法是，**Effect 在這次評測的設定下記憶體成長明顯較低，但別急著歸功給哪個機制**。%(´,,•ω•,,)%

順帶一提，Effect 從來沒進過 [TechEmpower](https://www.techempower.com/benchmarks/) 那套主流框架 benchmark，NestJS 有。想找更權威的對照，目前找不到。

### 但這真的是你的瓶頸嗎

講完數字，還是要把話說回來。

Pydantic 團隊寫過一篇[實測文章](https://pydantic.dev/articles/web-framework-performance)，結論是「**框架本身很少會是瓶頸**」。他們把整個請求拆開看，資料庫查詢跟序列化吃掉絕大多數時間，框架路由只佔中間那幾條細縫。

那篇講的是 Python，但道理跨語言通用。

Effect 官方的 [Myths 頁面](https://www.effect.website/docs/v3/additional-resources/myths)也很坦白。

> 前端有跑到 120fps 還重度使用 Effect 的應用，所以 Effect 大概不會是你的效能問題。

一支 API 只要碰了資料庫，那幾毫秒的 IO 就足以淹沒框架層的差距。

真的在意每秒幾萬個請求，該問的是「要不要用 Bun」跟「資料庫查詢有沒有寫爛」，而不是「該用哪個框架」。%(ゝ∀・)b%

## 那 oRPC 呢？

看過[前一篇 oRPC 的文章](/blog-ocean-world/orpc-vs-ts-rest)的朋友可能會想，這兩個是不是打架？

答案是不會，而且**合約優先的人有一條特別順的路**。%(ﾉ>ω<)ﾉ%

### 把 oRPC 掛在 Effect 的 HTTP server 上

關鍵在於契約優先本來就把**契約**跟**HTTP 傳輸**拆開了。

契約是一份獨立的東西，放在私有 npm 或 monorepo 裡，前後端各自拿去對照。

```ts
// @project-code/shared
export const todoContract = {
  create: oc.input(/* ... */).output(/* ... */),
}
```

後端用 `implement(todoContract)` 實作，前端用 `ContractRouterClient` 推型別。至於這些東西**用什麼跑起來**，是另一件事。

所以可以讓 oRPC 出契約跟路由，HTTP server 交給 Effect。%( •̀ ω •́ )✧%

橋接方式意外地簡單，因為兩邊剛好在同一個介面上會合。

* oRPC 的 fetch adapter 是 `(Request) => Promise<Response>`
* `@effect/platform` 有個 `HttpApp.fromWebHandler`，收的正好就是這種函數

```ts
const orpcApp = HttpApp.fromWebHandler(async (request) => {
  const result = await rpcHandler.handle(request, { prefix: '/rpc', context: {} })
  return result.matched ? result.response : new Response('Not Found', { status: 404 })
})

const app = HttpRouter.empty.pipe(
  HttpRouter.get('/health', HttpServerResponse.text('ok')),
  HttpRouter.mountApp('/rpc', orpcApp, { includePrefix: true }),
)
```

契約優先全程保留，`oc` 定契約、`implement` 實作、前端照樣 `ContractRouterClient`，連 event iterator 串流都能正常穿透。

**最棒的是這條路全部用穩定版就能跑。**

```bash
npm install @orpc/server @orpc/contract effect @effect/platform @effect/platform-node
```

`@orpc/server` 對 `effect` 零依賴，所以裝起來完全沒有 peer 衝突。%(´,,•ω•,,)%

::: warning `includePrefix` 一定要設 `true`
預設的 `false` 會改寫請求 URL 來剝除前綴，但 `toWeb` 有個 fast-path 會直接回傳原始 request。

在 Node 上剛好沒事，在 Bun、Deno、Workers 上那個改寫會被無聲忽略，oRPC 會收到沒剝除前綴的路徑。
:::

不過動手之前先想清楚**你到底想換到什麼**。

| | 內容 |
|---|---|
| 拿得到 | 單一 port、Effect 的 logger／CORS／OTel 包住 RPC、Layer 生命週期與優雅關機 |
| 拿不到 | procedure 內部仍是普通 async function，沒有型別化的錯誤，也沒有服務清單 |

想在 handler 裡跑 Effect，還是得 `ManagedRuntime.runPromise`，而那一步會把型別化錯誤打回 rejected promise。

所以這條路只買到**傳輸層**的 Effect。%( ˘•ω•˘ )%

務實的建議是這樣。

* oRPC 是你唯一的 HTTP 出口 → 用 `@orpc/server/node` 配 `ManagedRuntime` 更單純，找到的唯一一個真實 oRPC + Effect 專案就是這樣做
* 已經有其他 Effect 路由、想統一成同一個 server → 橋接才划算

順帶一提，`@effect/platform` 不只是 HTTP，`FileSystem`、`Command`、`Worker` 那些模組跟 HTTP 無關，走這條路的話也一起拿到了。%(´,,•ω•,,)%

### 補充：oRPC v2 的官方 Effect 整合

上面那條路的 procedure 還是普通 async function。想讓型別化錯誤跟服務清單進到業務邏輯裡，oRPC v2 有**官方的 Effect 整合**。

```ts
os.create.handler(async ({ input }) => { // [!code --]
  await database.save(input) // [!code --]
}) // [!code --]
os.create.handler(handlerGen(function* ({ input }) { // [!code ++]
  const database = yield* Database // [!code ++]
  yield* database.save(input) // [!code ++]
})) // [!code ++]
```

`handlerGen` 會把執行跟錯誤處理包好，不用自己呼叫 `Effect.runPromise`。服務則走 oRPC 的 context，塞一個 `effect/context` 進去。

好消息是**契約完全不用動**。

`handlerGen` 的型別裡沒有 schema 的位置，它對契約的要求只有「符合 Standard Schema」，Zod 本來就符合。所以整份 Zod 契約一行都不用改寫成 Effect Schema。%( •̀ ω •́ )✧%

::: danger 這條路現在全線都是 beta
以 **2026 年 8 月 21 日**的狀態為準。

| 套件 | 穩定版 | 這條路要用的版本 |
|---|---|---|
| `effect` | 3.22.1 | **4.0.0-beta**（v4 已進 RC） |
| `@orpc/server`、`@orpc/contract` | 1.15.0 | **2.0.0-beta.29** |
| `@orpc/experimental-effect` | 無穩定版 | **2.0.0-beta.29** |

Effect 跟 oRPC 都得押在 beta 上，套件名還掛著 `experimental`。side project 玩玩沒問題，正式產品建議等兩邊都出正式版。

還有三個坑：npm 的 `latest` 標籤指到誤發布的舊版，一定要加 `@beta`；三個 oRPC 套件版號必須完全一致，否則 npm 會裝出巢狀的第二份 `@orpc/server`，讓 prototype 擴充打到錯的 class，執行期噴 `os.xxx.effect is not a function`；最後，它的 peer 寫死 Effect v4 beta，跟 `@effect/platform` 裝不進同一棵樹，**等於放棄前面那個橋接**。
:::

### 那 `HttpApi` 什麼時候才輪得到

其實你早就看過 `HttpApi` 的合約優先了，就是前面那兩個檔案，`api.ts` 只有宣告，`api-live.ts` 才是實作。

概念跟 oRPC 一模一樣，差別在合約的**形狀**跟**流通範圍**。

| | oRPC 合約 | `HttpApi` |
|---|---|---|
| 合約長相 | 函式簽章（input、output、errors） | HTTP 端點（method、path、schema） |
| 驗證庫 | 任何 Standard Schema，Zod 直接可用 | 只吃 Effect `Schema` |
| 前端要不要碰 Effect | 完全不用 | 產 client 就會拉進 Effect |
| 前端查詢整合 | TanStack Query、Pinia Colada、SWR | 沒有 |
| 部署目標 | 二十幾種，含 Hono、Next、SvelteKit、Cloudflare | Node、Bun、Deno、瀏覽器 |

判斷標準不是「哪個比較好」，而是看**合約要給誰看**。

合約要跨團隊、前端不想碰 Effect，就留在 oRPC。整個後端都是 Effect、前端也吃得下，`HttpApi` 才有登場的理由。

要注意的是，**已經用 Zod 寫好的合約沒辦法搬去 `HttpApi`**。

`HttpApiEndpoint` 的 `setPayload` 型別上只收 `Schema.Schema.Any`，而 Effect Schema 的識別靠一個 `unique symbol`，Zod 結構上無法冒充。轉換也只有 Effect Schema → Standard Schema 這個方向，反過來沒有。

所以那不是「改個 import 就好」，是整份重寫。%( ˘•ω•˘ )%

補充一下，Effect 圈內還有個 `@effect/rpc`，走 RPC 形狀而非 REST 形狀，定位比較接近 oRPC，同一份 `Schema` 可以共用，不過它還在 0.x，暫時不用急著看。

## 動手做一個最小的 todo server

講了一整篇，最後把東西湊起來，做一支真的跑得動的 todo API。

不用登入、資料用 [Drizzle](https://orm.drizzle.team/) 存進 PostgreSQL，而且照 feature 拆好資料夾。

```text
src/
├── todos/
│   ├── todo.table.ts      # Drizzle 的資料表定義
│   ├── todo.api.ts        # 這個 feature 的 endpoint 宣告
│   ├── todo.store.ts      # 服務與 Layer
│   └── todo.handlers.ts   # handler 實作
├── api.ts                 # 把各 feature 的宣告併起來
└── server.ts              # 組裝所有 Layer 並啟動
```

熟悉 NestJS 的話，`todo.api.ts` 大致等於 controller 的路由表、`todo.store.ts` 等於 provider、`api.ts` 等於 `AppModule`。%(´,,•ω•,,)%

::: tip 為什麼檔名用點號分隔
`實體.型別.ts` 這種寫法源自 Angular Style Guide，NestJS 沿用至今。

有趣的是 Angular 自己在 v20 已經不這樣產生檔案了，理由是他們認為 `Service` 這類後綴沒有傳達實質資訊，`UserDataClient` 比 `UserService` 有用得多，細節可以看[那份 RFC 討論](https://github.com/angular/angular/discussions/58412)。不過這個寫法在後端圈還是很通行。

選它有兩個實際理由。

* **模糊搜尋好用**，在編輯器打 `todo tab` 就能直達資料表定義，這也是 Angular 當年列的理由之一
* **glob 抓得精準**，Drizzle 的 `schema: './src/**/*.table.ts'` 不會誤中 `lookup-table.ts` 這種檔案，換成連字號的 `*-table.ts` 就會

不喜歡點號的話，換成 `todo-table.ts` 或 feature 資料夾內用裸名 `table.ts` 都行，只要整個專案一致就好。
:::

### 一、資料表長什麼樣

`todos/todo.table.ts` 就是一般的 Drizzle 寫法，跟 Effect 沒有關係。

```ts
import { boolean, pgTable, serial, text } from 'drizzle-orm/pg-core'

export const todoTable = pgTable('todos', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  done: boolean('done').notNull().default(false),
})
```

建表就照 Drizzle 的常規流程，`npx drizzle-kit push` 或跑 migration 都行。

### 二、宣告這個 feature 的 API

`todos/todo.api.ts` 只描述形狀，沒有任何實作。

```ts
import { HttpApiEndpoint, HttpApiGroup } from '@effect/platform'
import { Schema } from 'effect'

export const Todo = Schema.Struct({
  id: Schema.Number,
  title: Schema.String,
  done: Schema.Boolean,
})

export type Todo = typeof Todo.Type

export class DatabaseError extends Schema.TaggedError<DatabaseError>()('DatabaseError', {
  message: Schema.String,
}) {}

export const TodoGroup = HttpApiGroup.make('todos')
  .add(
    HttpApiEndpoint.get('list', '/todos')
      .addSuccess(Schema.Array(Todo))
      .addError(DatabaseError, { status: 500 }),
  )
  .add(
    HttpApiEndpoint.post('create', '/todos')
      .setPayload(Schema.Struct({ title: Schema.String }))
      .addSuccess(Todo)
      .addError(DatabaseError, { status: 500 }),
  )
```

錯誤型別用 `Schema.TaggedError` 而不是 `Data.TaggedError`，理由跟前面一樣，它要轉成 JSON 送給前端。

而且**每個 endpoint 都要用 `.addError` 掛上去**，沒掛的話 handler 回傳這個錯誤會編譯失敗，因為 endpoint 宣告的錯誤通道裡根本沒有它。%( ˘•ω•˘ )%

### 三、服務與說明書

`todos/todo.store.ts` 分成兩半，名牌跟說明書。

```ts
import { drizzle } from 'drizzle-orm/node-postgres'
import { Context, Effect, Layer } from 'effect'
import { DatabaseError, type Todo } from './todo.api'
import { todoTable } from './todo.table'

// 名牌，只講有哪些能力
export class TodoStore extends Context.Tag('TodoStore')<TodoStore, {
  readonly list: Effect.Effect<ReadonlyArray<Todo>, DatabaseError>;
  readonly create: (title: string) => Effect.Effect<Todo, DatabaseError>;
}>() {}

// 說明書，連線字串由外面決定
export const TodoStorePostgres = (connectionUri: string) =>
  Layer.sync(TodoStore, () => {
    const db = drizzle(connectionUri)

    return {
      list: Effect.tryPromise({
        try: () => db.select().from(todoTable),
        catch: (cause) => new DatabaseError({ message: String(cause) }),
      }),
      create: (title: string) =>
        Effect.tryPromise({
          try: () => db.insert(todoTable).values({ title, done: false }).returning(),
          catch: (cause) => new DatabaseError({ message: String(cause) }),
        }).pipe(Effect.map((rowList) => rowList[0]!)),
    }
  })
```

這裡用 `Context.Tag` 而不是 `Effect.Service`，因為連線字串要由外面給。

`TodoStorePostgres` 是一台生產說明書的機器，餵不同的連線字串會吐出不同的 Layer，等一下測試就靠這件事。%( •̀ ω •́ )✧%

### 四、把宣告併起來

`api.ts` 就是 `AppModule` 的角色。

```ts
import { HttpApi } from '@effect/platform'
import { TodoGroup } from './todos/todo.api'

export const Api = HttpApi.make('Api').add(TodoGroup)
```

以後多一個 feature 就多一行 `.add(UserGroup)`。

### 五、實作 handler

`todos/todo.handlers.ts` 才碰到真正的邏輯。

```ts
import { HttpApiBuilder } from '@effect/platform'
import { Effect } from 'effect'
import { Api } from '../api'
import { TodoStore } from './todo.store'

export const TodoLive = HttpApiBuilder.group(Api, 'todos', (handlers) =>
  handlers
    .handle('list', () =>
      Effect.gen(function* () {
        const store = yield* TodoStore
        return yield* store.list
      }))
    .handle('create', ({ payload }) =>
      Effect.gen(function* () {
        const store = yield* TodoStore
        return yield* store.create(payload.title)
      })))
```

注意第一個參數收的是**整份 `Api`**，不是單一個 group，所以這個檔案要回頭 import 根目錄的 `api.ts`。

也就是說 feature 資料夾沒辦法像 NestJS 的 module 那樣完全自給自足。好在宣告跟實作是分開的檔案，依賴方向是 `todo.api` → `api` → `todo.handlers`，不會繞成循環。%( ˘•ω•˘ )%

### 六、組裝並啟動

`server.ts` 是唯一決定「用哪個實作」的地方。

```ts
import { createServer } from 'node:http'
import { HttpApiBuilder, HttpApiSwagger } from '@effect/platform'
import { NodeHttpServer, NodeRuntime } from '@effect/platform-node'
import { Layer } from 'effect'
import { Api } from './api'
import { TodoLive } from './todos/todo.handlers'
import { TodoStorePostgres } from './todos/todo.store'

const ServerLive = HttpApiBuilder.serve().pipe(
  Layer.provide(HttpApiSwagger.layer()),
  Layer.provide(HttpApiBuilder.api(Api).pipe(Layer.provide(TodoLive))),
  Layer.provide(TodoStorePostgres(process.env.DATABASE_URL!)),
  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
)

Layer.launch(ServerLive).pipe(NodeRuntime.runMain)
```

跑起來。

```bash
DATABASE_URL=postgres://... npx tsx src/server.ts
```

```bash
curl -X POST localhost:3000/todos -H 'content-type: application/json' -d '{"title":"買鱈魚"}'
# {"id":1,"title":"買鱈魚","done":false}

curl localhost:3000/todos
# [{"id":1,"title":"買鱈魚","done":false}]
```

打開 `localhost:3000/docs` 還有一份 Swagger。%( •̀ ω •́ )✧%

加起來一百行左右，但你已經拿到這些東西。

* 請求跟回應都經過 `Schema` 驗證，型別錯了直接擋在門口
* Swagger 文件自動生成，沒有另外寫
* 資料庫錯誤掛在 `E`（可能錯誤）那一欄，呼叫端看型別就知道會噴 `DatabaseError`
* 換資料庫只要改 `server.ts` 那一行，其他檔案動都不用動

路人：「用 Express 寫可能更短欸。%(・∀・)%」

鱈魚：「對，但那一百行裡面有一半是型別跟文件在幫你做事。%( ˘•ω•˘ )%」

## 測試接上真的 PostgreSQL

`TodoStore` 現在寫進 PostgreSQL，測試就不能靠假物件混過去了。

拿假的 client 來 mock 意義不大，因為 SQL 有沒有寫對它驗不出來。比較實在的做法是用 [Testcontainers](https://node.testcontainers.org/) 開一個真的資料庫。

先把容器包成服務，`test/pg-container.ts`

```ts
import { PostgreSqlContainer } from '@testcontainers/postgresql'
import { Effect } from 'effect'

export class PgContainer extends Effect.Service<PgContainer>()('PgContainer', {
  scoped: Effect.acquireRelease(
    Effect.promise(() => new PostgreSqlContainer('postgres:17-alpine').start()),
    (container) => Effect.promise(() => container.stop()),
  ),
}) {}
```

`Effect.acquireRelease` 收兩個東西，怎麼開跟怎麼關。只要宣告一次，之後不管測試成功、失敗還是被中斷，容器都保證會關掉。%( •̀ ω •́ )✧%

接著把連線字串餵給**正式環境那份** `TodoStorePostgres`。

```ts
const TodoStoreTest = Layer.unwrapEffect(
  Effect.gen(function* () {
    const container = yield* PgContainer
    return TodoStorePostgres(container.getConnectionUri())
  }),
).pipe(Layer.provide(PgContainer.Default))
```

前面那台「生產說明書的機器」在這裡派上用場了。測到的是真的 SQL，不是假的替身。

測試本體，`test/todo.test.ts`

```ts
import { expect, layer } from '@effect/vitest'
import { Effect } from 'effect'

layer(TodoStoreTest, { timeout: '60 seconds' })('TodoStore', (it) => {
  it.effect('新增之後應該查得到', () =>
    Effect.gen(function* () {
      const store = yield* TodoStore

      const created = yield* store.create('買鱈魚')
      const todoList = yield* store.list

      expect(created.title).toBe('買鱈魚')
      expect(todoList).toHaveLength(1)
    }))
})
```

用 `layer(...)` 包起來，容器**整個區塊只開一次**，區塊結束才關，裡面每個 `it.effect` 共用同一個資料庫。

如果改成在每條測試各自 `Effect.provide(TodoStoreTest)`，那就會每跑一條就開關一次容器，慢到懷疑人生。%(´\_ゝ\`)%

::: tip 這段的版本
`@effect/vitest@0.30`（peer 是 `effect ^3.22`）搭 `@testcontainers/postgresql@12`，後者要求 Node 22.22 以上。

另外 Effect v4 把 `it.scoped` 拿掉了，`it.effect` 自帶 `Scope`，升級時要注意。
:::

## 同一支 API 換 NestJS 寫

有了對照才知道差在哪，同樣的功能用 NestJS 寫大概是這樣。

```text
src/
├── todos/
│   ├── dto/create-todo.dto.ts
│   ├── todo.controller.ts
│   ├── todo.service.ts
│   └── todo.module.ts
├── app.module.ts
└── main.ts
```

資料夾切法幾乎一樣，差別在 NestJS 多了一個 `todo.module.ts` 把整包收起來。

先是資料驗證，NestJS 這邊靠 class-validator。

```ts
// todos/dto/create-todo.dto.ts
import { IsString } from 'class-validator'

export class CreateTodoDto {
  @IsString()
  title: string
}
```

接著是服務。

```ts
// todos/todo.service.ts
@Injectable()
export class TodoService {
  constructor(@Inject(DATABASE) private readonly db: Database) {}

  list() {
    return this.db.select().from(todoTable)
  }

  create(title: string) {
    return this.db.insert(todoTable).values({ title, done: false }).returning()
  }
}
```

再來是 controller 跟 module。

```ts
// todos/todo.controller.ts
@Controller('todos')
export class TodoController {
  constructor(private readonly todoService: TodoService) {}

  @Get()
  list() {
    return this.todoService.list()
  }

  @Post()
  create(@Body() dto: CreateTodoDto) {
    return this.todoService.create(dto.title)
  }
}
```

```ts
// todos/todo.module.ts
@Module({
  controllers: [TodoController],
  providers: [TodoService],
})
export class TodoModule {}
```

老實說 NestJS 這版讀起來相當舒服，裝飾器把路由跟依賴標得清清楚楚，行數也差不多。%(´,,•ω•,,)%

### NestJS 這邊怎麼測

同樣接真的 PostgreSQL。

```ts
describe('TodoService', () => {
  let container: StartedPostgreSqlContainer
  let app: INestApplication

  beforeAll(async () => {
    container = await new PostgreSqlContainer('postgres:17-alpine').start()
    const db = createDatabase(container.getConnectionUri())

    const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
      .overrideProvider(DATABASE)
      .useValue(db)
      .compile()

    app = moduleRef.createNestApplication()
    await app.init()
  }, 180_000)

  afterAll(async () => {
    await app?.close()
    await container?.stop()
  })

  it('新增之後應該查得到', async () => {
    // ⋯⋯
  })
})
```

功能上完全等價，差別在**收尾這件事得自己顧**。

* `beforeAll` 跟 `afterAll` 要自己配對
* 關閉順序要自己排對，先關 app 再關容器
* timeout 要自己記得加，不然抓映像檔那次會逾時
* `app?.` 那個問號是因為 `beforeAll` 可能中途失敗，變數還是 `undefined`

我翻了幾個 GitHub 上的真實專案，**忘記寫 `container.stop()` 的比例高得驚人**，測試跑完容器就留在那邊。%(°ㅂ°)%

Effect 那邊不用擔心這件事，因為「怎麼開」跟「怎麼關」在 `Effect.acquireRelease` 是綁在一起宣告的，`layer(...)` 負責在正確的時機關掉，順序由 `Scope` 保證。

### 整理一下差別

| | Effect | NestJS |
|---|---|---|
| 組合單位 | Layer | `@Module` |
| API 文件 | `HttpApiSwagger.layer()` 一行 | 要另外裝 `@nestjs/swagger`，並在 DTO 補 `@ApiProperty` |
| 回應驗證 | `addSuccess` 會驗 | 不驗，回傳什麼就送什麼 |
| 漏了依賴 | 編譯器直接紅 | 啟動時才噴 `can't resolve dependencies` |
| 測試替換 | `Layer.provide`，跟正式環境同一招 | `Test.createTestingModule().overrideProvider()` |
| 測試資源收尾 | `acquireRelease` 綁在一起宣告 | 自己寫 `afterAll`，順序自己排 |
| 型別安全的前端 client | 從同一份定義產出 | 沒有，要自己寫或另接工具 |

最值得注意的是**回應驗證**那列。

NestJS 的 `ValidationPipe` 只擋進來的請求，回傳的東西沒人檢查。`TodoService` 哪天多回傳一個欄位、或少了 `done`，前端才會發現。

Effect 版本的 `addSuccess(Todo)` 是雙向的，回傳值對不上 schema 當場就爆。%( ˘•ω•˘ )%

至於資料夾，兩邊都拆得開，差別在**邊界的形狀**。

NestJS 的邊界是 module，一個 class 把 controller 跟 provider 都包住。Effect 的邊界是 Layer，而路由宣告跟路由實作被拆到兩層去了。

代價是 feature 資料夾沒那麼獨立，換到的是那份宣告可以獨立拿去產 client 跟文件。%( ˘•ω•˘ )%

這其實就是整篇文章的縮影，Effect 前期一定寫得比較多，換到的是後面改動時編譯器會擋住你。

專案越小越不划算，越大越值得。%(´,,•ω•,,)%

## 那 Effect 是不是萬靈丹

一路看下來好像 Effect 完勝，該說的壞話還是要說一下。%(｢･ω･)｢%

* **學習曲線真的陡**，`Effect.gen`、`pipe`、`Layer`、`Context` 一次要吃下好幾個新概念，團隊要有人願意帶
* **小工具不值得**，十行的 CLI script 用 Effect 包起來，樣板程式碼比原本邏輯還多
* **生態圈小很多**，遇到問題能查到的資料，跟 Node.js 原生寫法差一大截
* **跟現有程式碼混用有摩擦**，專案裡一半 Promise 一半 Effect，來回轉換的樣板碼會讓人很煩躁

### AI 全時代，Effect 真的該優先於 NestJS 嗎？

路人：「上篇你自己都說，AI 幫你砍掉了查資料的成本，你才回鍋 Effect 的。既然門檻不是問題了，遇到金流、訂單、Worker、Realtime 這種複雜後端，Effect 應該要電爆 NestJS 才對吧？%(・∀・)%」

鱈魚：「前半句對，後半句是另一件事，兩句接在一起講就跳太快了。%( ˘•ω•˘ )%」

上篇[來認識 Effect](/blog-program/getting-to-know-effect-ts)「回到兩年前」那節講的是**用得起**，AI 靠官方塞進 npm 套件的 `AGENTS.md`、`@effect/language-service` 這些專門養出來的工具，把當年那五道查資料的門檻拆掉了。

這篇要查的是另一件事，**用得起**不等於**該優先選它**，尤其複雜後端系統這種場景，得分開查證。%( •̀ ω •́ )✧%

先看 Effect 官方自己怎麼講。[effect.website 首頁](https://effect.website)現在的標語是這樣。

> Build production-ready systems your team can ship, customers can depend on, and AI agents can work with.

往下滑還有一整區塊叫「Write Effect code with AI」，理由跟上篇提過的那套工具邏輯一致，型別結構固定讓 AI 不用猜、錯誤訊息夠精細讓 AI 能精準自我修正。

這段行銷詞跟一開始那個說法幾乎一字不差，說白了，那是 Effect 官方現在的行銷主軸，不是鱈魚查出來的新發現。%(´\_ゝ\`)%

那有沒有真的拿 Effect 扛複雜系統的案例？查到幾家。

| 公司 | 用在哪 | 來源 |
|---|---|---|
| Vercel | Domains 團隊，由 Dillon Mulroy 主導導入 | Effect Days 2025 演講、Cause & Effect podcast |
| MasterClass | 即時語音 AI orchestration，撐 Gordon Ramsay、Mark Cuban 這些名人課程的對話 | effect.website 案例研究 |
| Warp（薪資合規平台，不是終端機那個 Warp） | 金流與薪資系統，CTO Adam Rankin 親自談的 | Cause & Effect podcast |
| OpenCode（sst 那支開源終端機 coding agent） | 大型 TypeScript codebase 遷移，架構其實是 Effect 混 Zod | effect.website 案例、Kit Langton 訪談 |

案例確實對得上金流、Realtime、第三方 API 串接這幾個場景，不算亂講。%( ˘•ω•˘ )%

路人：「這樣不就證明了？%(・∀・)%」

鱈魚：「證明 Effect 官方找得到案例，離『比 NestJS 更適合』還有一段距離。這四家全是 Effect 自己收集、自己訪談的故事，沒有一家附上『我們原本用 NestJS，換過來之後 XX 變好』這種對照數字，也找不到任何獨立第三方比較。%(´・ω・\`)%」

還有件事上篇已經提醒過，AI 寫 Effect 容易生出過期語法，三代 API 混在訓練資料裡，得靠官方 skills、`@effect/language-service` 這些工具才壓得住。

換句話說，讓 AI 幫忙扛 Effect 這件事本身就是一份持續要投資的工具鏈，不是裝完就沒事了。把這筆成本算進「該不該 Effect-first」的天平，結論不會像那句行銷標語那麼一面倒。%( ˘•ω•˘ )%

風險也還在。`HttpApi`、`RPC`、`Workflow` 這幾個模組現在全收在 unstable 目錄下，官方目標是 2026 Q3、Q4 出正式版，這之前 API 隨時可能改，跟上篇提過的 v4 RC 是同一件事。

真要走這條路，務實的做法是把這些還不穩定的平台介面集中包一層，日後版本升級或 API 變動，改動範圍縮在那一層裡，不會炸到整個專案。%(´,,•ω•,,)%

務實一點的判斷方式，看**那三欄有沒有東西可填**。

錯誤只有一種、要用的服務只有一兩個、流程直來直去，原生 TypeScript 配上好好設計的參數傳遞就很夠用。

錯誤分支很多、服務一堆、還要重試跟併發，那三欄填滿的價值就出來了，很值得那份學習成本。%( ˘•ω•˘ )%

## 總結 🐟

* 前端先別急著跟進。元件測試多半用 MSW 在網路那層攔，替換服務那套優勢用不上，官方 Vue 綁定也還卡在還沒發正式版的 v4
* `@effect/platform` 不只是 HTTP，WebSocket、檔案系統、子行程、Worker 都在裡面，換平台等於換一顆 Layer
* 跟 NestJS 最大的差別在**什麼時候發現漏了依賴**，NestJS 要等啟動時容器組裝才噴錯，Effect 是編譯器直接紅
* 效能方面 Effect 的 HTTP 層沒想像中肥，但那份 benchmark 有一堆前提要看清楚，而且框架通常不是你的瓶頸
* 已經在用 oRPC 的話兩者不衝突，合約留給 oRPC、Effect 進 handler，Zod 契約一行都不用改

寫到這裡大概可以回答那個老問題了。

Effect 沒打算取代 TypeScript，也未必適合每個專案。但如果你也常常在翻「這函數到底會噴什麼錯、到底需要什麼」，它把答案寫進型別的做法，現在真的值得重新評估一次。%(ゝ∀・)b%

沒看過上篇的話，[來認識 Effect](/blog-program/getting-to-know-effect-ts)那篇有完整的概念說明，還有我兩年前棄坑又回鍋的心路歷程。%(´,,•ω•,,)%

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

---

---
url: /aquarium/enderbox.md
description: 我把 Minecraft 搬到網頁上了！不過這次是操作終界使者，一起來挖方塊、瞬間移動吧！
---


---

---
url: /aquarium/hexazen.md
description: 組合多種場景並產生不同的自然音效
---


---

---
url: /column-hexazen/01-origin.md
description: 同一個白噪音聽到快背起來了，來試試自己做一個 3D 白噪音混音器吧。◝(≧∀≦)◟
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP01：前言

平常上班時耳機常常都是放白噪音、雨聲等等自然聲音。

同一個聲音聽太多次，連下一個雷聲甚麼時候出現我都快背起來了。%(›´ω\`‹ )%

雖然有很多不錯的線上混音器網站，但是總感覺差了一點甚麼。

這次想嘗試用 Babylon.js 做一個 3D 白噪音混音器，聲音使用隨機播放的形式呈現。

## 說明

做一個有趣的白噪音網站，同時練習更複雜的 3D 應用

### 概念

每個聲音都是一個積木，積木可以任意組合，積木種類與規模會產生不同自然音效。

例如：

* 草：無
* 樹木：風吹過樹葉聲音
* 雲：下雨聲音
* 房子：咖啡廳聲音
* 河：流水聲

不同規模會產生生態系，例如樹木夠多會有蟲鳴、鳥叫等等。

地圖資訊會儲存在 URL 中，分享連結即可讓其他人聽到你的設計的自然音效。

### 素材

![kit](https://kenney.nl/media/pages/assets/hexagon-kit/7b13873307-1706007672/sample.png)

3D 積木則基於 kenney 大大設計的「[Hexagon Kit](https://kenney.nl/assets/hexagon-kit)」

感謝 kenney 大大提供如此優秀的素材！%(\*´∀\`)~♥%

## 開發

現在讓我們開始吧。%੭ ˙ᗜ˙ )੭%

第一步我打算先在此部落格做原型測試。

多虧 VitePress 強大的客製化能力，現在來建立完全客製化的頁面。

### 建立頁面

新增檔案。

`content\aquarium\hexazen\index.md`

```markdown
---
title: HexaZen
description: 組合多種場景並產生不同的自然音效
image: https://codlin.me/hexazen-cover.webp
layout: false
---
```

`layout` 設為 `false` 代表不使用預設的佈局，這樣就可以自由設計頁面了！%♪( ◜ω◝و(و%

::: tip
詳細說明可見文件：[VitePress：Layout](https://vitepress.dev/reference/default-theme-layout)
:::

現在導航到 `http://localhost:3000/aquarium/hexazen/` 應該會是一片空白。

接著在頁面中以 iframe 方式引入主元件，利用 [whyframe](https://whyframe.dev/) 隔離環境。

`content\aquarium\hexazen\index.md`

```markdown
---
title: HexaZen
description: 組合多種場景並產生不同的自然音效
image: https://codlin.me/hexazen-cover.webp
layout: false
---

<script setup>
import Hexazen from './hexazen.vue'
</script>

<iframe data-why class="fixed w-dvw h-dvh">
  <hexazen />
</iframe>
```

使用 iframe 隔離可以避免 VitePress 本身的樣式和狀態干擾，讓 HexaZen 擁有完全獨立的運行環境。

### 場景初始化

由於 Babylon.js 場景最基本構成是 `engine`、`scene`、`camera`、`light`。

所以我將相關邏輯直接獨立為 `use-babylon-scene` composable，簡化元件內容。

`content\aquarium\hexazen\composables\use-babylon-scene.ts`

```typescript
export function useBabylonScene(param?: UseBabylonSceneParam) {
  const canvasRef = ref<HTMLCanvasElement>()
  const engine = shallowRef<BabylonEngine>()
  const scene = shallowRef<Scene>()
  const camera = shallowRef<ArcRotateCamera>()

  onMounted(async () => {
    if (!canvasRef.value)
      return

    engine.value = await createEngine({
      canvas: canvasRef.value,
    })

    scene.value = createScene({
      canvas: canvasRef.value,
      engine: engine.value,
    })
    camera.value = createCamera({
      canvas: canvasRef.value,
      engine: engine.value,
      scene: scene.value,
    })

    engine.value.runRenderLoop(() => {
      scene.value?.render()
    })

    await init({ canvas, engine, scene, camera })
  })

  onBeforeUnmount(() => {
    engine.value?.dispose()
    scene.value?.dispose()
  })

  return { canvasRef, engine, scene, camera }
}
```

支援 WebGPU 優先、WebGL 降級的引擎建立策略，並提供預設的場景、攝影機、光源設定，同時允許 `init` callback 自定義初始化邏輯。

現在在 3D 場景元件中引用。

`content\aquarium\hexazen\main-scene.vue`

```vue
<template>
  <canvas v-once ref="canvasRef" class="w-full h-full outline-0" />
</template>

<script setup lang="ts">
import { useBabylonScene } from './composables/use-babylon-scene'

const { canvasRef, scene, camera } = useBabylonScene({
  async init({ scene, engine, camera }) {
    // 建立地板、陰影、粒子系統等
  },
})
</script>
```

接著產生地板。這裡使用 PBR 材質搭配 `MirrorTexture` 產生鏡面倒影效果。

```typescript
function createGround({ scene }: { scene: Scene }) {
  const ground = MeshBuilder.CreateGround(
    'ground',
    { width: 1000, height: 1000 },
    scene,
  )

  const pbr = new PBRMaterial('groundPBR', scene)
  pbr.albedoColor = new Color3(0.9, 0.9, 0.9)
  pbr.metallic = 0.2
  pbr.roughness = 0.2

  const mirrorTexture = new MirrorTexture('groundMirror', 512, scene, true)
  mirrorTexture.mirrorPlane = new Plane(0, -1, 0, 0)
  mirrorTexture.level = 0.5
  mirrorTexture.renderList = []
  pbr.reflectionTexture = mirrorTexture

  ground.material = pbr
  ground.receiveShadows = true

  return ground
}
```

現在場景中應該會有一個帶有鏡面反射的白色地板了。

### 資料驅動的積木定義

接著把模型放到靜態目錄中，[下載模型](https://kenney.nl/assets/hexagon-kit)並解壓縮。

`content\public\assets\kenny-hexagon-pack`

HexaZen 採用資料驅動的積木定義方式，所有積木的模型路徑、位置、旋轉、縮放等資訊都集中在 `data.ts` 中。

這裡的資料來自 [CodStack](/aquarium/codstack/) 工具的輸出。

`content\aquarium\hexazen\domains\block\builder\data.ts`

```typescript
interface BlockDefinition {
  /** 一個 block 可能會有多個特性，例如港口同時有 water、building */
  traitList: TraitTypeUnion[];
  content: {
    version: number;
    rootFolderName: string;
    partList: PartData[];
  };
}

export const blockDefinitions = {
  /** grass */
  g1: {
    traitList: ['grass'] as TraitTypeUnion[],
    content: {
      version: 1,
      rootFolderName: 'assets',
      partList: [
        {
          path: 'kenny-hexagon-pack/GLB format/grass.glb',
          position: [0, 0, 0],
          rotationQuaternion: [0, 1, 0, 0],
          scaling: [1, 1, 1],
          metadata: { name: '', mass: 0, restitution: 0.5, friction: 0 },
        },
      ],
    },
  },
  /** tree */
  t1: {
    traitList: ['tree'] as TraitTypeUnion[],
    content: {
      version: 1,
      rootFolderName: 'assets',
      partList: [
        {
          path: 'kenny-hexagon-pack/GLB format/grass-forest.glb',
          position: [0, 0, 0],
          rotationQuaternion: [0, 1, 0, 0],
          scaling: [1, 1, 1],
          metadata: { name: '', mass: 0, restitution: 0.5, friction: 0 },
        },
      ],
    },
  },
  // ... 共 30+ 種積木
} satisfies Record<string, BlockDefinition>
```

每個積木定義了 `traitList`（特性清單），這是聲景系統的判斷依據。例如港口（b6）同時擁有 `building` 和 `water` 兩個特性。

### 建立積木

統一的 `createBlock` function 負責載入模型、設定材質、掛載到場景上。

`content\aquarium\hexazen\domains\block\builder\index.ts`

```typescript
export async function createBlock({
  type,
  scene,
  shadowGenerator,
  hex,
  hexLayout,
  weather,
}: CreateBlockParams): Promise<Block> {
  const blockDefinition = blockDefinitions[type]

  const resultList = await Promise.all(
    blockDefinition.content.partList.map(
      async ({ path, position, rotationQuaternion, scaling, metadata }) => {
        const fullPath = `${blockDefinition.content.rootFolderName}/${path}`
        const model = await ImportMeshAsync(fullPath, scene)

        // 強制三線性過濾，避免旋轉時紋理閃爍
        model.meshes.forEach((mesh) => {
          if (mesh.material instanceof PBRMaterial) {
            mesh.material.metallic = 0
            mesh.material.roughness = 0.4
          }
        })

        return { model, position, rotationQuaternion, scaling }
      },
    ),
  )

  const rootNode = new TransformNode('block-root', scene)

  // 組裝所有部件到 rootNode
  resultList.forEach(({ model, position, rotationQuaternion, scaling }) => {
    const [rootMesh] = model.meshes
    if (!rootMesh)
      return

    rootMesh.receiveShadows = true
    rootMesh.position = new Vector3(...position)
    rootMesh.rotationQuaternion = new Quaternion(...rotationQuaternion)
    rootMesh.scaling = new Vector3(...scaling)
    rootMesh.parent = rootNode
  })

  // 放置到六角格世界座標
  rootNode.position.copyFrom(hexLayout.hexToWorld(hex))

  // 進入動畫：從下方彈出
  rootNode.position.y -= 1
  await animate(rootNode.position, {
    y: 0,
    duration: 1000,
    ease: 'outElastic(1,0.52)',
  }).then()

  return { type, rootNode, hex, dispose }
}
```

### 專案結構

目前的檔案結構如下：

```
hexazen/
├── hexazen.vue                # 應用根元件
├── main-scene.vue             # 3D 場景
├── index.md                   # VitePress 入口
├── components/                # UI 元件
├── composables/               # 共用邏輯
│   ├── use-babylon-scene.ts   # 引擎初始化
│   ├── use-simple-i18n.ts     # 輕量 i18n
│   ├── use-thumbnail-generator.ts
│   └── use-font-loader.ts
├── constants/
│   └── index.ts               # 版本號
├── types/
│   └── index.ts               # Trait、Weather 型別
└── domains/
    ├── block/                 # 積木系統
    │   ├── type.ts
    │   ├── block-picker.vue
    │   ├── builder/           # 建立積木
    │   └── trait-region/      # BFS 連通區域
    ├── hex-grid/              # 六角格數學
    ├── soundscape/            # 聲景系統
    │   ├── type.ts
    │   ├── soundscape-mixer.vue
    │   ├── player/            # 播放引擎
    │   └── resolver/          # 規則解析
    └── share/codec/           # URL 編碼
```

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* 建立 whyframe 隔離的 VitePress 客製化頁面
* 建立 WebGPU/WebGL 雙策略的 Babylon.js 場景
* PBR 材質地板搭配鏡面反射
* 資料驅動的積木定義系統
* 統一的積木建立函式與彈性動畫

下一章讓我們來看六角格座標系統與聲景規則的設計吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/02-hex-grid-and-soundscape.md
description: 如何讓六角積木組合出千變萬化的自然音效？讓我們從座標系統開始聊起。✧⁑｡٩(ˊᗜˋ*)و✧⁕｡
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP02：六角格與聲景系統

上一章讓我們可以建立積木，但只有積木沒辦法拚在一起

這次要來實作六角格座標系統，讓積木可以排列在六角網格上。

同時基於積木特性建立聲景（Soundscape）系統，讓不同的積木組合自動產生對應的自然音效！%◝( •ω• )◟%

## 六角格座標系統

六角格看似簡單，但座標計算其實有不少眉角。

### 三種座標系統

六角格常見的座標系統有 Offset、Axial、Cube 三種，各有優缺點。

#### Offset 座標

最直覺的方式：用 `(col, row)` 對應 2D 陣列索引。

看起來很簡單，但問題馬上出現，奇數行和偶數行的鄰居偏移不同：

```typescript
// Offset 座標找鄰居：需要判斷奇偶行 😵
function getNeighbors(col: number, row: number) {
  const isEvenRow = row % 2 === 0
  if (isEvenRow) {
    return [
      [col, row - 1],
      [col + 1, row - 1], // 上方兩格
      [col - 1, row],
      [col + 1, row], // 左右
      [col, row + 1],
      [col + 1, row + 1], // 下方兩格
    ]
  }
  else {
    return [
      [col - 1, row - 1],
      [col, row - 1], // 上方兩格
      [col - 1, row],
      [col + 1, row], // 左右
      [col - 1, row + 1],
      [col, row + 1], // 下方兩格
    ]
  }
}
```

距離計算也得分奇偶處理，旋轉更是噩夢。%(›´ω\`‹ )%

#### Axial 座標

把六角格攤在兩條斜軸 `(q, r)` 上：

鄰居偏移變得一致了，不用再判斷奇偶：

```typescript
// Axial 座標的六方向：固定偏移量，不分奇偶
const axialDirections = [
  [+1, 0],
  [+1, -1],
  [0, -1],
  [-1, 0],
  [-1, +1],
  [0, +1],
]
```

但距離計算仍然需要推導第三個隱含的座標：

```typescript
// Axial 距離：需要推算出 s
function axialDistance(a: [number, number], b: [number, number]) {
  const dq = a[0] - b[0]
  const dr = a[1] - b[1]
  const ds = -dq - dr // 隱含的第三軸
  return Math.max(Math.abs(dq), Math.abs(dr), Math.abs(ds))
}
```

#### Cube 座標

三軸 `(q, r, s)` 並且 **q + r + s = 0 恆成立**，這個約束讓所有運算都變得對稱且優雅。

對比三者的操作複雜度：

| 操作     | Offset     | Axial      | Cube                          |
| -------- | ---------- | ---------- | ----------------------------- |
| 找鄰居   | 判斷奇偶行 | 查表       | 向量加法                      |
| 算距離   | 分段公式   | 推導第三軸 | `max(\|dq\|, \|dr\|, \|ds\|)` |
| 旋轉     | 非常複雜   | 需要推導   | 排列 + 取反                   |
| 對稱性   | 無         | 部分       | 三軸完全對稱                  |
| 儲存空間 | 2 個值     | 2 個值     | 2 個值（s 可推算）            |

Cube 座標的距離就是向量在三軸上的最大分量：

```typescript
// Cube 距離：一行搞定
function cubeDistance(a: Hex, b: Hex) {
  return Math.max(
    Math.abs(a.q - b.q),
    Math.abs(a.r - b.r),
    Math.abs(a.s - b.s),
  )
}
```

旋轉 60° 也只需要排列三個值再取反：

```typescript
// Cube 旋轉：排列 + 取反，優雅到不行
function rotateRight(hex: Hex): Hex {
  return new Hex(-hex.r, -hex.s, -hex.q)
}
function rotateLeft(hex: Hex): Hex {
  return new Hex(-hex.s, -hex.q, -hex.r)
}
```

雖然儲存三個值看似冗餘，但 `s = -q - r` 隨時可以推算，實際只需要兩個值。

這種數學上的對稱性對後面的 BFS 連通偵測和座標轉換大有幫助。%( •̀ ω •́ )✧%

### Hex 類別

讓我們建立核心的 `Hex` 類別。

`content\aquarium\hexazen\domains\hex-grid\index.ts`

```typescript
export class Hex {
  public q: number
  public r: number
  public s: number

  constructor(q: number, r: number, s: number) {
    // 用 epsilon 容忍浮點誤差
    const sum = q + r + s
    if (Math.abs(sum) > 1e-6) {
      throw new Error('Hex invariant violated: q + r + s must be 0')
    }
    this.q = q
    this.r = r
    this.s = s
  }

  key() {
    return `${this.q},${this.r},${this.s}`
  }

  static fromAxial(q: number, r: number): Hex {
    return new Hex(q, r, -q - r)
  }

  add(b: Hex): Hex {
    return new Hex(this.q + b.q, this.r + b.r, this.s + b.s)
  }

  subtract(b: Hex): Hex {
    return new Hex(this.q - b.q, this.r - b.r, this.s - b.s)
  }
}
```

建構子中直接驗證 `q + r + s === 0`，如果違反就直接拋錯。

`fromAxial` 則是便利方法，只需要給 `q` 和 `r`，`s` 會自動推算。

### 找鄰居

六角格每格有 6 個共用邊的鄰居，定義方向向量後，找鄰居就是一次向量加法。

```typescript
// 六方向（cube）
static readonly directions: ReadonlyArray<Hex> = Object.freeze([
  new Hex(1, 0, -1),
  new Hex(1, -1, 0),
  new Hex(0, -1, 1),
  new Hex(-1, 0, 1),
  new Hex(-1, 1, 0),
  new Hex(0, 1, -1),
])

/** 取得共用邊的鄰居 */
neighbor(direction: number): Hex {
  return this.add(Hex.direction(direction))
}
```

另外還有 6 個對角鄰居（共用頂點、距離為 2），之後判斷蛙鳴等音效時會用到。

### 世界座標轉換

有了 Hex 座標後，需要 `HexLayout` 把 Hex 座標轉成 Babylon.js 的世界座標。

```typescript
export class HexLayout {
  constructor(
    public orientation: Orientation,
    public size: number,
    public origin: Vector3 = Vector3.Zero(),
  ) {}

  /** Hex -> 世界座標（X,Z） */
  hexToWorld(hex: Hex, yOverride?: number): Vector3 {
    const M = this.orientation
    const x = (M.f0 * hex.q + M.f1 * hex.r) * this.size + this.origin.x
    const z = (M.f2 * hex.q + M.f3 * hex.r) * this.size + this.origin.z
    const y = yOverride ?? this.origin.y
    return new Vector3(x, y, z)
  }

  /** 世界座標 -> 最近格 Hex（已 round） */
  worldToHexRounded(world: Vector3): Hex {
    return this.worldToHexFractional(world).round()
  }
}
```

這裡使用 pointy-topped（上下頂點朝上）的六角形方向，透過矩陣變換在 Hex 座標和世界座標之間轉換。

`worldToHexRounded` 把滑鼠點擊的世界座標轉回最近的 Hex 格，放置積木時非常有用。

::: tip
六角格的數學參考了 Red Blob Games 的 [Hexagonal Grids](https://www.redblobgames.com/grids/hexagons/) 文章

文章中有許多即時互動的範例，強力推薦！%ദ്ദി ˉ͈̀꒳ˉ͈́ )%
:::

## 積木與特性

有了六角格，接著需要定義各種積木與它們的「特性（Trait）」。

### 特性系統

```typescript
enum TraitTypeEnum {
  GRASS,
  TREE,
  CAMPFIRE,
  BUILDING,
  ALPINE,
  RIVER,
  WATER,
  SAND,
}
```

每個積木可以擁有一至多個特性，例如：

* 草地（g1～g6）：`grass`
* 樹木（t1～t3）：`tree`
* 港口（b6）：`building` + `water`
* 水車（r5）：`river` + `building`
* 山中小屋（b7）：`building` + `alpine`

這種多特性設計讓積木可以同時參與不同音效的判斷，例如港口既能觸發市集音效，也能貢獻海浪音效。%◝(≧∀≦)◟%

### 區域規模

光是計算單個積木不夠，還需要知道「有多少同類積木連在一起」，也就是「區域規模」。

這就需要 BFS（廣度優先搜尋）來找出連通區域。

`content\aquarium\hexazen\domains\block\trait-region\index.ts`

```typescript
export function calcTraitRegionList(
  blocks: Map<string, BlockSnapshot> | BlockSnapshot[],
): TraitRegion[] {
  const regionList: TraitRegion[] = []
  const traitToKeys = new Map<TraitType, Set<string>>()

  // 先將每個 block 的 trait 分類
  for (const [key, block] of blockMap) {
    for (const trait of blockDefinitions[block.type].traitList) {
      if (!traitToKeys.has(trait)) {
        traitToKeys.set(trait, new Set())
      }
      traitToKeys.get(trait)!.add(key)
    }
  }

  // 對每個 trait 獨立做 BFS 連通分量分析
  for (const [trait, keySet] of traitToKeys) {
    const unvisited = new Set(keySet)

    while (unvisited.size > 0) {
      const startKey = unvisited.values().next().value as string
      const startBlock = blockMap.get(startKey)!
      unvisited.delete(startKey)

      const hexMap = new Map<string, Hex>([[startKey, startBlock.hex]])
      const queue: Hex[] = [startBlock.hex]
      let head = 0

      while (head < queue.length) {
        const current = queue[head]!
        head++

        for (let direction = 0; direction < 6; direction++) {
          const neighbor = current.neighbor(direction)
          const neighborKey = neighbor.key()

          if (!unvisited.has(neighborKey))
            continue

          const neighborBlock = blockMap.get(neighborKey)!
          unvisited.delete(neighborKey)
          hexMap.set(neighborKey, neighborBlock.hex)
          queue.push(neighborBlock.hex)
        }
      }

      regionList.push({ trait, hexMap, size: hexMap.size })
    }
  }

  return regionList
}
```

幾個值得注意的細節：

* 使用 `head` 游標取代 `shift()`，避免破壞陣列記憶體連續性
* 以 `Map`（O(1)）取代 `Array`（O(n)）來查找鄰格
* 一個 block 若有多個 trait，會分別參與不同 trait 的連通分析

## 聲景系統

終於來到最有趣的部分了！%੭ ˙ᗜ˙ )੭%

### 規則驅動的音效生成

聲景系統的核心是一組「規則（Rule）」，每個規則包含：

* `predicate`：判斷是否觸發（依據積木組合與天氣）
* `transform`：產生對應的音效

```typescript
interface SoundscapeRule {
  type: SoundscapeType;
  predicate: (data: {
    traitRegionList: TraitRegion[];
    blockMap: Map<string, Block>;
    weather?: Weather;
  }) => boolean;
  transform: (soundscapeList: Soundscape[]) => Soundscape[];
}
```

### 生態系規則

這些規則設計出了一套小型生態系統，積木數量越多，音效越豐富：

| 條件             | 音效     | 說明             |
| ---------------- | -------- | ---------------- |
| 樹木 ≥ 3         | 風吹樹梢 | 林間基本的沙沙聲 |
| 草地 ≥ 4         | 蟲鳴     | 蟋蟀與蟈蟈的合唱 |
| 樹木 ≥ 6         | 鳥叫     | 黑鶇、交喙的歌聲 |
| 樹木 ≥ 10        | 獸鳴     | 鼠兔的叫聲       |
| 河流 ≥ 2         | 流水聲   | 潺潺水流         |
| 水域 ≥ 15        | 海浪     | 壯闊的海洋聲     |
| 水域 ≥ 15 + 有岸 | 潮汐     | 海浪拍打岸邊     |
| 高山 ≥ 10        | 高山風   | 凜冽的山風       |
| 建築 ≥ 5         | 市集     | 熙攘的人聲       |
| 有營火           | 營火     | 柴火劈啪聲       |

例如「風吹樹梢」的規則：

```typescript
{
  type: 'rustle',
  predicate: ({ traitRegionList, weather }) => {
    if (weather === 'rain') {
      return false
    }
    return traitRegionList.some(
      (region) => region.trait === 'tree' && region.size >= 3,
    )
  },
  transform: concat([{
    id: getId(),
    title: 'The Whisper of the Treetops',
    type: 'rustle',
    mode: { value: 'loop' },
    soundList: [{
      src: 'hexazen/sounds/rustle-tree.mp3',
      volume: 0.3,
    }],
  }]),
},
```

### 天氣影響

下雨時大部分自然聲音會受抑制，換成各種雨聲：

* 草地的雨聲（基礎）
* 森林的雨聲（樹木 ≥ 2）
* 屋頂的雨聲（建築 ≥ 5）
* 雷聲（隨機間隔 10～30 秒）

這讓同一個積木配置在晴天和雨天會有完全不同的聽覺體驗。%(\*´∀\`)~♥%

### 特殊規則

蛙鳴的觸發條件比較特別：需要一個水域格，且它的 6 個鄰格中至少有 5 個是非水域積木。

```typescript
predicate({ traitRegionList, blockMap }) {
  const waterRegionList = traitRegionList.filter(
    (region) => region.trait === 'water',
  )

  for (const waterRegion of waterRegionList) {
    for (const [, waterHex] of waterRegion.hexMap) {
      let nonWaterCount = 0

      for (let direction = 0; direction < 6; direction++) {
        const neighborHex = waterHex.neighbor(direction)
        const neighborBlock = blockMap.get(neighborHex.key())

        if (!neighborBlock) continue

        const isNotWater = !blockDefinitions[neighborBlock.type]
          .traitList.includes('water')

        if (isNotWater) {
          nonWaterCount++
          if (nonWaterCount >= 5) return true
        }
      }
    }
  }
  return false
},
```

也就是說，青蛙只會出現在「幾乎被陸地包圍的小池塘」旁邊！%ヾ(◍'౪\`◍)ﾉﾞ%

### 解析流程

最後，`resolveSoundscape` 將所有規則串接起來：

```typescript
export function resolveSoundscape(data: {
  traitRegionList: TraitRegion[];
  blockMap: Map<string, Block>;
  weather?: Weather;
}) {
  const validRuleList = soundscapeRuleList.filter((rule) =>
    rule.predicate(data),
  )

  const soundscapeList = pipe(
    validRuleList,
    reduce((acc, rule) => {
      return rule.transform(acc)
    }, [] as Soundscape[]),
  )

  return soundscapeList
}
```

流程很直覺：過濾出所有滿足條件的規則，然後依序呼叫 `transform` 將音效累加起來。

每次積木變動或天氣改變時，系統會重新計算連通區域、解析音效，自動更新播放中的聲景。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* 建立基於 Cube 座標的六角格系統
* 積木的多特性設計讓音效判斷更有彈性
* BFS 連通區域偵測讓「規模」成為音效觸發的關鍵因子
* 規則驅動的聲景系統，用簡單的 predicate + transform 組合出豐富的聽覺體驗
* 天氣系統為同一場景帶來截然不同的聲音氣氛

下一章讓我們來聊聊音效播放引擎與分享編碼的實作吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/03-soundscape-player.md
description: 怎麼讓白噪音不再重複？雙軌交叉淡入淡出加上隨機播放，讓耳朵不再疲勞。♪( ◜ω◝و(و
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP03：音效播放引擎

上一章我們設計了聲景規則系統，知道什麼時候該播放什麼音效，但是「播放音效」不是只有播放就好，有些小細節需要注意。%ԅ(´∀\` ԅ)%

例如 loop 音效循環到起點時，會有明顯的「接縫感」，這章就來解決這個問題！%◝( •ω• )◟
%

## 型別定義

先來看看 Soundscape 的資料結構。

`content\aquarium\hexazen\domains\soundscape\type.ts`

```typescript
export type SoundscapeType =
  | 'rustle'
  | 'insect'
  | 'bird'
  | 'frog'
  | 'beast'
  | 'river'
  | 'building'
  | 'ocean'
  | 'alpine'
  | 'rain'
  | 'campfire'

interface Sound {
  src: string;
  /** 0 ~ 1
   * @default 0.5
   */
  volume?: number;
}

export interface Soundscape {
  id: number;
  title: string;
  type: SoundscapeType;
  mode:
    | {
      value: 'loop';
    }
    | {
      value: 'interval';
      /** @default [5, 10] 秒 */
      range?: [number, number];
    };
  soundList: Sound[];
}
```

目前 `mode` 分為兩種播放模式：

* **loop**：適合持續性音效（風聲、流水、雨聲）
* **interval**：適合間歇性音效（鳥叫、蛙鳴、雷聲），會在隨機間隔後播放

## GainNode 串接架構

音效系統的核心是 `GainNode`，靠多個 Node 串接，達成方便、彈性的音效控制。

音量控制鏈如下：

```
trackGain → baseGain → globalGain → muteGain → destination
```

每一層各司其職：

| GainNode     | 控制者   | 用途                                 |
| ------------ | -------- | ------------------------------------ |
| `trackGain`  | 音效定義 | 單軌基礎音量（如鳥叫 0.5、雷聲 0.1） |
| `baseGain`   | 混音器   | 使用者在混音器 UI 中調整的乘數       |
| `globalGain` | 主控音量 | 左側滑桿的整體音量                   |
| `muteGain`   | 靜音按鈕 | 0 或 1，控制靜音                     |

```typescript
constructor(soundscape: Soundscape) {
  this.audioContext = getAudioContext()

  // 建立 GainNode 鏈
  this.baseGainNode = this.audioContext.createGain()
  this.globalGainNode = this.audioContext.createGain()
  this.muteGainNode = this.audioContext.createGain()

  this.baseGainNode.connect(this.globalGainNode)
  this.globalGainNode.connect(this.muteGainNode)
  this.muteGainNode.connect(this.audioContext.destination)
}
```

::: tip
所有 `SoundscapePlayer` 共用同一個 `AudioContext`，因為瀏覽器對 `AudioContext` 的數量有限制。
:::

## Loop 模式：雙軌交叉淡入淡出

Loop 模式的核心技巧是**雙軌交疊**（crossfade）。

建立兩個 `Audio` 元素播放同一段音檔，在 A 軌快結束前提早啟動 B 軌，兩軌重疊的期間自然過渡，就聽不到接縫了。

```typescript
private playLoop() {
  const soundData = this.soundscape.soundList[0]
  if (!soundData) return
  const baseVolume = soundData.volume ?? DEFAULT_BASE_VOLUME

  // 建立雙音軌
  const audioA = new Audio(soundData.src)
  audioA.crossOrigin = 'anonymous'
  audioA.loop = true
  const audioB = new Audio(soundData.src)
  audioB.crossOrigin = 'anonymous'
  audioB.loop = true

  const trackA = this.createTrack(audioA, baseVolume)
  const trackB = this.createTrack(audioB, baseVolume)

  let useTrackA = true

  const scheduleNext = (track: AudioTrack) => {
    if (this.isDestroying) return

    track.audio.currentTime = 0
    track.audio.play().catch((e) =>
      console.warn(`[${this.soundscape.type}] 播放被阻擋:`, e),
    )

    const setupOverlap = () => {
      // 確保交疊時間不會大於音檔本身長度的一半
      const overlap = Math.min(
        this.OVERLAP_SECONDS,
        track.audio.duration * 0.4,
      )
      const triggerTimeMs = (track.audio.duration - overlap) * 1000

      const timer = setTimeout(() => {
        this.timeoutIds.delete(timer)
        useTrackA = !useTrackA
        const nextTrack = useTrackA ? trackA : trackB
        scheduleNext(nextTrack)
      }, triggerTimeMs)

      this.timeoutIds.add(timer)
    }

    if (track.audio.readyState >= 1) {
      setupOverlap()
    } else {
      track.audio.onloadedmetadata = () => {
        setupOverlap()
        track.audio.onloadedmetadata = null
      }
    }
  }

  scheduleNext(trackA)
}
```

`OVERLAP_SECONDS` 預設為 4 秒，但不會超過音檔長度的 40%，避免短音檔出問題。%( •̀ ω •́ )✧%

## Interval 模式：隨機間隔播放

Interval 模式適合像鳥叫、蛙鳴這類間歇性聲音。

每次從 `soundList` 中隨機挑一個音效播放，播完後等待隨機秒數再播下一個。

```typescript
private playInterval() {
  if (this.isDestroying) return

  const [randomSound] = sample(this.soundscape.soundList, 1)
  if (!randomSound) return
  const baseVolume = randomSound.volume ?? DEFAULT_BASE_VOLUME

  const audio = new Audio(randomSound.src)
  audio.crossOrigin = 'anonymous'
  const track = this.createTrack(audio, baseVolume)

  audio.onended = () => {
    this.removeTrack(track)
    if (this.isDestroying) return

    const { mode } = this.soundscape
    const [min, max] = mode.value === 'interval' && mode.range
      ? [Math.min(...mode.range), Math.max(...mode.range)]
      : [5, 10]
    const waitSec = Math.random() * (max - min) + min

    const timer = setTimeout(() => {
      this.timeoutIds.delete(timer)
      this.playInterval()
    }, waitSec * 1000)

    this.timeoutIds.add(timer)
  }

  audio.play().catch((e) => {
    console.warn(`[${this.soundscape.type}] 播放被阻擋:`, e)
  })
}
```

預設等待時間為 5～10 秒的隨機區間，雷聲則特別設定為 10～30 秒，讓間隔更有真實感。

## 優雅地銷毀

當積木被移除或天氣變化導致音效不再需要時，不能突然靜音，會顯得相當突兀。

這裡用 `linearRampToValueAtTime` 做 2 秒的漸出：

```typescript
public async destroy(fadeOutDurationMs = 2000): Promise<void> {
  if (this.isDestroying) return
  this.isDestroying = true

  // 1. 清除所有等待中的計時器
  this.timeoutIds.forEach((timer) => clearTimeout(timer))
  this.timeoutIds.clear()

  // 2. 對所有正在播放的音軌執行漸出
  const currentTime = this.audioContext.currentTime
  const fadeEndTime = currentTime + fadeOutDurationMs / 1000

  for (const track of this.activeTracks) {
    track.trackGain.gain.setValueAtTime(
      track.trackGain.gain.value, currentTime,
    )
    track.trackGain.gain.linearRampToValueAtTime(0, fadeEndTime)
  }

  await new Promise<void>((resolve) => {
    const timer = setTimeout(resolve, fadeOutDurationMs)
    this.timeoutIds.add(timer)
  })

  // 3. 徹底清理回收資源
  for (const track of this.activeTracks) {
    track.audio.pause()
    track.audio.removeAttribute('src')
    track.audio.onloadedmetadata = null
    track.audio.onended = null
    track.trackGain.disconnect()
    track.source.disconnect()
  }
  this.activeTracks.clear()

  this.baseGainNode.disconnect()
  this.globalGainNode.disconnect()
  this.muteGainNode.disconnect()
}
```

三步驟：停止排程 → 漸出音量 → 徹底清理資源。乾淨利落。%( •̀ ω •́ )✧%

## Composable：管理播放器生命週期

最後用 `useSoundscapePlayer` composable 把所有播放器串起來。

`content\aquarium\hexazen\domains\soundscape\player\use-soundscape-player.ts`

```typescript
export function useSoundscapePlayer(
  blockMap: ShallowReactive<Map<string, Block>>,
  options: {
    muted?: Ref<boolean>;
    volume?: Ref<number>;
    weather?: Ref<Weather | undefined>;
  } = {},
) {
  const traitRegionList = computed(() => calcTraitRegionList(blockMap))
  const soundscapeList = computed(() =>
    resolveSoundscape({
      traitRegionList: traitRegionList.value,
      blockMap,
      weather: weather.value,
    }),
  )

  const activePlayerMap = shallowReactive(new Map<number, SoundscapePlayer>())

  watch(soundscapeList, (newList) => {
    const newIdSet = new Set(newList.map(prop('id')))

    // 不在新列表中的音效 → 靜音（保留音量設定）
    for (const [id, player] of activePlayerMap) {
      if (!newIdSet.has(id)) {
        player.muted()
      }
    }

    // 新列表中的音效 → 建立或解除靜音
    for (const scape of newList) {
      if (!activePlayerMap.has(scape.id)) {
        const player = new SoundscapePlayer(scape)
        player.setGlobalVolume(volume.value)
        player.play()
        if (muted.value) {
          player.muted()
        }
        activePlayerMap.set(scape.id, player)
      }
      else {
        const player = activePlayerMap.get(scape.id)!
        if (!muted.value) {
          player.unmuted()
        }
      }
    }
  })

  return { traitRegionList, soundscapeList, activePlayerMap }
}
```

幾個值得注意的設計：

* 不在新列表中的音效是**靜音**而非銷毀，保留使用者調整過的音量設定
* `watch` 自動響應 `blockMap` 變化，積木一放下，音效就跟著更新
* 全域音量與靜音狀態也透過 `watch` 即時同步

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen/domains/soundscape)

* 雙軌交叉淡入淡出消除 loop 接縫感
* Interval 模式隨機播放帶來自然變化
* GainNode 四層串接實現細緻的音量控制
* 漸出動畫 + 資源清理確保優雅銷毀
* Composable 自動管理播放器生命週期

下一章讓我們來看看 3D 場景中的互動機制吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/04-3d-scene-interaction.md
description: 讓積木可以放置、旋轉、移除，還有滑順的動畫與視覺效果。◝(≧∀≦)◟
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP04：3D 場景互動

有了六角格和音效系統，現在要讓使用者能在 3D 場景中實際操作積木。

點擊空格放置、點擊積木旋轉、切換鏟子模式移除。%੭ ˙ᗜ˙ )੭%

## 地板：PBR 材質與鏡面反射

首先讓地板看起來更有質感。使用 PBR 材質加上 `MirrorTexture` 產生鏡面倒影。

```typescript
function createGround({ scene }: { scene: Scene }) {
  const ground = MeshBuilder.CreateGround(
    'ground',
    { width: 1000, height: 1000 },
    scene,
  )

  const pbr = new PBRMaterial('groundPBR', scene)
  pbr.albedoColor = new Color3(0.9, 0.9, 0.9)
  pbr.metallic = 0.2
  pbr.roughness = 0.2

  const mirrorTexture = new MirrorTexture('groundMirror', 512, scene, true)
  mirrorTexture.mirrorPlane = new Plane(0, -1, 0, 0)
  mirrorTexture.level = 0.5
  mirrorTexture.renderList = []
  pbr.reflectionTexture = mirrorTexture

  ground.material = pbr
  ground.receiveShadows = true

  // 自動將新增的 mesh 加入倒影渲染清單
  scene.onNewMeshAddedObservable.add((mesh) => {
    if (mesh !== ground) {
      mirrorTexture.renderList?.push(mesh)
    }
  })

  return ground
}
```

`mirrorTexture.level = 0.5` 讓倒影若隱若現，不會太搶眼。

搭配 `onNewMeshAddedObservable`，後續新增的積木也會自動出現在倒影中。

## 候選格、選中格、Hover 狀態

六角格有三種視覺狀態：

| 狀態               | 透明度 | 顏色   | 可點擊 |
| ------------------ | ------ | ------ | ------ |
| 候選格 (Candidate) | 0.5    | 灰色   | 是     |
| 選中格 (Selected)  | 0.6    | 暗金色 | 否     |
| Hover              | 0.7    | 灰色   | 是     |

```typescript
const COLOR_SELECTED = new Color3(0.4, 0.3, 0.1)
const COLOR_CANDIDATE = new Color3(0.3, 0.3, 0.3)

const ALPHA_SELECTED = 0.6
const ALPHA_CANDIDATE = 0.5
const ALPHA_HOVER = 0.7
const ALPHA_HIDDEN = 0.0

const FADE_SPEED = 14
```

### 平滑過渡

狀態切換使用**指數平滑**做漸變動畫：

```typescript
scene.onBeforeRenderObservable.add(() => {
  const dt = engine.getDeltaTime() / 1000
  const t = 1 - Math.exp(-FADE_SPEED * dt)

  for (const [key, material] of tileMaterialMap) {
    const targetAlpha = targetTileAlphaMap.get(key) ?? ALPHA_HIDDEN
    const targetColor = targetTileColorMap.get(key)

    // 透明度漸變
    material.alpha = material.alpha + (targetAlpha - material.alpha) * t

    // 顏色漸變
    if (targetColor) {
      material.emissiveColor.r
        += (targetColor.r - material.emissiveColor.r) * t
      material.emissiveColor.g
        += (targetColor.g - material.emissiveColor.g) * t
      material.emissiveColor.b
        += (targetColor.b - material.emissiveColor.b) * t
      material.diffuseColor.copyFrom(material.emissiveColor)
    }
  }
})
```

`1 - Math.exp(-FADE_SPEED * dt)` 是一種與幀率無關的指數平滑公式。不管 60fps 還是 144fps，動畫速度都一致。%( •̀ ω •́ )✧%

## 候選格同步

每次放置或移除積木後，需要重新計算哪些格子是候選格。

```typescript
function syncAllCandidateTile() {
  // 移除沒有相鄰 placed block 的孤立候補格
  candidateTileMap.forEach((hex, key) => {
    const hasAdjacentBlock = Array.from({ length: 6 }, (_, d) =>
      hex.neighbor(d),).some((neighbor) => props.placedBlockMap.has(neighbor.key()))

    const hasSelfBlock = props.placedBlockMap.has(key)

    if (hasAdjacentBlock || hasSelfBlock)
      return
    removeCandidate(hex)
  })

  // 補上 placedBlock 鄰格中缺少的候補
  props.placedBlockMap.forEach((block) => {
    for (let d = 0; d < 6; d++) {
      addCandidate(block.hex.neighbor(d))
    }
  })

  // 若地圖為空，確保原點候補存在
  if (props.placedBlockMap.size === 0) {
    candidateTileMap.forEach((hex) => removeCandidate(hex))
    addCandidate(new Hex(0, 0, 0))
  }
}
```

另外 `addCandidate` 會檢查 `hex.len() > MAX_RADIUS`，限制最大放置半徑為 2 格。

## 積木放置與動畫

放置積木時使用彈性彈跳動畫，讓積木從下方彈出：

`content\aquarium\hexazen\domains\block\builder\index.ts`

```typescript
// 進入動畫
rootNode.position.y -= Z_OFFSET
await animate(rootNode.position, {
  y: 0,
  duration: 1000,
  ease: 'outElastic(1,0.52)',
}).then()
```

移除時則反向沉入地面：

```typescript
async function dispose() {
  await animate(rootNode.position, {
    y: -Z_OFFSET,
    duration: 600,
    ease: 'inBack',
  }).then()

  rootNode.dispose()
  smoothParticleSystem?.dispose()
  scope.stop()
}
```

`outElastic` 讓積木「咚」一聲彈出來，`inBack` 則讓積木稍微往上抬再沉下去，提供回饋感。%(・∀・)９%

## 旋轉互動

點擊已放置的積木可以旋轉 60°，搭配彈跳效果：

```typescript
// 旋轉
animatingBlockSet.add(pickedKey)
const duration = 800
animate(block.rootNode.rotation, {
  y: block.rootNode.rotation.y + Math.PI / 3,
  duration,
  ease: 'inOutCirc',
})

animate(block.rootNode.position, {
  y: [0, 0.2, 0],
  duration,
  ease: 'inOutBack(3)',
  onComplete() {
    animatingBlockSet.delete(pickedKey)
  },
})
```

旋轉的同時積木會稍微抬起再放下，`animatingBlockSet` 則防止動畫期間重複觸發。

## 滑鼠偵測與 Ray-casting

Babylon.js 的 `scene.pick` 方法透過射線投射來判斷滑鼠點到了哪個 mesh。

我們需要兩組偵測器：一組用於已放置的積木（旋轉/移除），一組用於候選格（放置）。

```typescript
// 偵測已放置的積木
scene.onPointerObservable.add(async (info) => {
  const pick = scene.pick(scene.pointerX, scene.pointerY, (mesh) => {
    const key = hexMeshMetadata(mesh)?.hex.key()
    return key ? props.placedBlockMap.has(key) : false
  })
  // ... 處理旋轉或移除
})

// 偵測候選格
scene.onPointerObservable.add((info) => {
  const pick = scene.pick(scene.pointerX, scene.pointerY, (mesh) => {
    const key = hexMeshMetadata(mesh)?.hex.key()
    if (!key || props.placedBlockMap.has(key))
      return false
    return candidateTileMap.has(key) || selectedTileSet.has(key)
  })
  // ... 處理 hover 和選取
})
```

透過 `pick` 的 filter callback 可以精確控制哪些 mesh 會被偵測到。

## 後製效果管線

讓畫面更有質感的最後一步：

```typescript
const pipeline = new DefaultRenderingPipeline('hexazenPipeline', true, scene, [
  camera,
])

pipeline.fxaaEnabled = true
pipeline.samples = 4

// 景深
pipeline.depthOfFieldEnabled = true
pipeline.depthOfFieldBlurLevel = DepthOfFieldEffectBlurLevel.High
pipeline.depthOfField.focalLength = 135
pipeline.depthOfField.fStop = DEFAULT_F_STOP

// 色調
pipeline.imageProcessingEnabled = true
pipeline.imageProcessing.contrast = 1.1
pipeline.imageProcessing.exposure = 1.1

// 暗角（vignette）
pipeline.imageProcessing.vignetteEnabled = true
pipeline.imageProcessing.vignetteWeight = DEFAULT_VIGNETTE_WEIGHT
```

景深的對焦距離會自動跟隨攝影機：

```typescript
scene.onBeforeRenderObservable.add(() => {
  if (pipeline.depthOfFieldEnabled && camera instanceof ArcRotateCamera) {
    pipeline.depthOfField.focusDistance = camera.radius * 1000
  }
})
```

### 暗角顏色隨主題變化

更有趣的是，暗角的顏色會根據場景中最多的特性類型動態變化：

```typescript
const traitVignetteColorMap: Record<TraitType, Color3> = {
  grass: new Color3(0, 0.2, 0),
  tree: new Color3(0, 0.2, 0),
  building: new Color3(0.4, 0.2, 0),
  alpine: new Color3(0, 0, 0),
  river: new Color3(0, 0.4, 0.4),
  water: new Color3(0, 0.4, 0.5),
  // ...
}
```

放滿樹木時暗角泛綠，放滿水域時暗角泛藍，整體視覺氣氛會跟著改變。%◝( •ω• )◟%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen/main-scene.vue)

* PBR 材質 + 鏡面反射打造質感地板
* 三態候選格搭配指數平滑漸變動畫
* 彈性進出動畫讓積木操作充滿回饋感
* Ray-casting 精確偵測滑鼠互動
* 後製效果管線 + 動態暗角色彩提升視覺氣氛

下一章讓我們來實作天氣系統與粒子特效吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/05-weather-and-particles.md
description: 下雨了！用 GPU 粒子系統撒下 5 萬顆雨滴，再搭配射線投射讓水花不會浮空。ˋ( ° ▽、° )
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP05：天氣與粒子系統

一片晴天固然美好，但如果能下場雨就更有感覺了。%ˋ( ° ▽、° )%

這章來實作天氣系統，GPU 粒子雨滴、射線投射水花、以及動態的光照與霧氣變化。%੭ ˙ᗜ˙ )੭%

## 天氣狀態機

天氣有三種模式，透過 `useCycleList` 循環切換：

```typescript
const { state: weatherMode, next: nextWeatherMode } = useCycleList<
  Weather | undefined | 'random-rain'
>([
  undefined, // 晴天
  'rain', // 雨天
  'random-rain', // 隨機（每 5 分鐘擲骰子）
])

useIntervalFn(
  () => {
    if (weatherMode.value === 'random-rain') {
      currentWeather.value = Math.random() < 0.5 ? 'rain' : undefined
    }
  },
  1000 * 60 * 5,
)
```

隨機降雨模式每 5 分鐘擲一次骰子，50% 機率下雨。

## GPU 粒子系統：雨滴

雨滴使用 `GPUParticleSystem`，容量 50,000 顆粒子，比 CPU 版本高效得多。

```typescript
function createRainSystem(scene: Scene) {
  if (!GPUParticleSystem.IsSupported) {
    console.warn('此裝置不支援 GPU 粒子系統')
    return
  }

  const particleSystem = new GPUParticleSystem(
    'rain_system', { capacity: 50000 }, scene,
  )

  // 動態繪製雨滴紋理：一條半透明的漸層直線
  const dropTexture = new DynamicTexture(
    'drop_tex', { width: 1, height: 20 }, scene, false,
  )
  const ctx = dropTexture.getContext()
  const gradient = ctx.createLinearGradient(0, 0, 0, 32)
  gradient.addColorStop(0, 'rgba(255, 255, 255, 0)')
  gradient.addColorStop(0.5, 'rgba(255, 255, 255, 0.6)')
  gradient.addColorStop(1, 'rgba(255, 255, 255, 0)')
  ctx.fillStyle = gradient
  ctx.fillRect(0, 0, 4, 32)
  dropTexture.update()

  particleSystem.particleTexture = dropTexture
```

紋理不是用圖片檔，而是用 `DynamicTexture` 動態繪製一條上下漸隱的白線，看起來就像細細的雨絲。

### 發射器設定

```typescript
const emitter = new BoxParticleEmitter()
emitter.direction1 = new Vector3(0, -1, 0)
emitter.direction2 = new Vector3(0, -1, 0)
emitter.minEmitBox = new Vector3(-5, 4, -5)
emitter.maxEmitBox = new Vector3(5, 4, 5)

particleSystem.particleEmitterType = emitter
particleSystem.emitter = Vector3.Zero()

particleSystem.billboardMode = ParticleSystem.BILLBOARDMODE_STRETCHED
particleSystem.color1 = new Color4(0.8, 0.8, 0.9, 0.2)
particleSystem.color2 = new Color4(0.6, 0.7, 0.8, 0.3)

particleSystem.minSize = 0.01
particleSystem.maxSize = 0.01
particleSystem.minScaleY = 5.0
particleSystem.maxScaleY = 5.0

particleSystem.emitRate = 2000
particleSystem.gravity = new Vector3(0, -1, 0)
```

重點：

* `BILLBOARDMODE_STRETCHED` 讓粒子沿移動方向拉伸，呈現雨絲效果
* `minScaleY = 5.0` 把每顆粒子拉成細長的雨滴形狀
* 從 10×10 的方形區域往下垂直降落

## CPU 粒子系統：水花

雨滴打到地面或積木上會濺起水花。這裡用 CPU 粒子系統，因為需要 ray-cast 來決定水花出生位置。

```typescript
function createSplashSystem(scene: Scene) {
  const splashSystem = new ParticleSystem(
    'splash_system', 10000, scene,
  )

  // 圓形水花紋理
  const splashTexture = new DynamicTexture(
    'splash_tex', { width: 32, height: 32 }, scene, false,
  )
  const ctx = splashTexture.getContext()
  const gradient = ctx.createRadialGradient(16, 16, 0, 16, 16, 16)
  gradient.addColorStop(0, 'rgba(200, 220, 240, 0.8)')
  gradient.addColorStop(1, 'rgba(200, 220, 240, 0)')
  ctx.fillStyle = gradient
  ctx.fillRect(0, 0, 32, 32)
  splashTexture.update()

  splashSystem.particleTexture = splashTexture
```

### 射線投射定位

這是水花系統最精巧的部分，用射線投射來找到地面或積木的表面位置。

```typescript
  splashSystem.startPositionFunction = (
    _worldMatrix, positionToUpdate,
  ) => {
    const randomX = Math.random() * 10 - 5
    const randomZ = Math.random() * 10 - 5

    // 從高空垂直向下發射射線
    const rayStart = new Vector3(randomX, 5, randomZ)
    const rayDir = new Vector3(0, -1, 0)
    const ray = new Ray(rayStart, rayDir, 30)

    // 偵測射線打到了場景中的哪個表面
    const hit = scene.pickWithRay(ray, (mesh) => {
      return mesh.isVisible && mesh.isPickable
    })

    if (hit && hit.hit && hit.pickedPoint) {
      positionToUpdate.copyFrom(hit.pickedPoint)
      positionToUpdate.y += 0.01  // 稍微抬高避免被模型吃掉
    } else {
      // 沒打到東西就藏到畫面外
      positionToUpdate.copyFromFloats(randomX, -100, randomZ)
    }
  }

  return splashSystem
}
```

`startPositionFunction` 覆寫了粒子的出生位置。每顆水花粒子出生前，先從空中往下射一條光線，打到什麼表面就在那裡濺起水花。

這樣水花就會精確地出現在積木頂部、地面上，而不會浮在空中。%ヽ(●\`∀´●)ﾉ%

## 天氣轉場

切換天氣時，光照和霧氣也要配合變化，使用 3 秒動畫做平滑過渡。

```typescript
watch(
  () => ({
    isRain: props.weather === 'rain',
    scene: scene.value,
  }),
  ({ isRain, scene: sceneValue }) => {
    if (!sceneValue)
      return

    // 粒子系統啟停（水花延遲 3 秒）
    if (isRain) {
      rainParticleSystem.value?.start()
      promiseTimeout(3000).then(() => {
        splashParticleSystem.value?.start()
      })
    }
    else {
      rainParticleSystem.value?.stop()
      promiseTimeout(3000).then(() => {
        splashParticleSystem.value?.stop()
      })
    }

    // 光照漸變
    const shadowLight = shadowGenerator.value?.getLight()
    if (shadowLight) {
      animate(shadowLight, {
        intensity: isRain ? 0.01 : 0.8,
        duration: 3000,
      })
    }

    // 霧氣漸變
    animate(sceneValue, {
      fogStart: isRain ? 1 : 10,
      fogEnd: isRain ? 30 : 100,
      duration: 3000,
    })
  },
)
```

下雨時的變化：

| 屬性     | 晴天 | 雨天 |
| -------- | ---- | ---- |
| 光照強度 | 0.8  | 0.01 |
| 霧氣起始 | 10   | 1    |
| 霧氣結束 | 100  | 30   |

光照幾乎關閉、霧氣逼近，整個場景瞬間變得昏暗朦朧。

水花延遲 3 秒才開始，因為雨滴需要時間「落下來」。%( •̀ ω •́ )✧%

## 營火煙霧：天氣連動

營火積木有煙霧粒子效果，但下雨時火被澆熄了，煙霧也要停止：

```typescript
const scope = effectScope()
scope.run(() => {
  watch(weather, (value) => {
    if (value === 'rain') {
      smoothParticleSystem?.stop()
    }
    else {
      smoothParticleSystem?.start()
    }
  })
})
```

使用 Vue 的 `effectScope` 確保清理時不會留下殘餘的 watcher，此概念源自[此文章](/blog-vue/vue-watch-may-cause-a-memory-leak)。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* GPU 粒子系統高效渲染 5 萬顆雨滴
* `DynamicTexture` 動態繪製紋理，不需額外圖片
* 射線投射讓水花精確定位在表面上
* 3 秒轉場動畫確保天氣切換流暢自然
* 營火煙霧與天氣連動，注重細節

下一章讓我們來看積木選擇器與縮圖生成機制吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/06-block-picker-and-thumbnail.md
description: 30 多種積木怎麼讓使用者挑選？用無頭 Babylon.js 場景產生即時縮圖吧！ヾ(◍'౪`◍)ﾉﾞ
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP06：積木選擇器與縮圖生成

HexaZen 有 30 多種積木，光靠文字名稱選擇太無趣了，這裡需要每個積木的 3D 預覽縮圖。

但 30 多張圖片手動截圖太累了，而且每次微調積木就要重做。%...(›´ω\`‹ )%

來做個自動縮圖產生器吧！%( ´ ▽ \` )ﾉ%

## 多執行緒縮圖生成器

核心概念是建立多個隱藏的 canvas，每個 canvas 都有獨立的 Babylon.js 引擎，像產線一樣平行生成縮圖。

### 決定並行數

首先根據裝置性能決定要啟動幾個「產線」：

`content\aquarium\hexazen\composables\use-thumbnail-generator.ts`

```typescript
function getOptimalConcurrency(): number {
  if (typeof window === 'undefined' || !window.navigator) {
    return 2
  }

  const cores = navigator.hardwareConcurrency || 4
  const memory = (navigator as any).deviceMemory || 4

  let optimal = 2
  if (cores >= 8 && memory >= 8) {
    optimal = 6
  }
  else if (cores >= 4 && memory >= 4) {
    optimal = 4
  }
  else {
    optimal = 2
  }

  return Math.min(optimal, 6)
}
```

8 核 + 8GB 記憶體以上開 6 個，4 核開 4 個，其他開 2 個。上限 6 個避免吃太多資源。

### 建立隱藏的產線

每個產線都是一個完整的 Babylon.js 場景：

```typescript
function createGenerator() {
  const queue = new PQueue({ concurrency: 1 })

  const canvas = document.createElement('canvas')
  canvas.style.visibility = 'hidden'
  canvas.width = 128
  canvas.height = 128
  document.body.appendChild(canvas)

  const engine = new Engine(canvas, true)
  const scene = new Scene(engine)
  scene.clearColor = new Color4(0, 0, 0, 0) // 透明背景

  const camera = new ArcRotateCamera(
    'camera',
    Math.PI / 4,
    Math.PI / 4,
    5,
    Vector3.Zero(),
    scene,
  )
  camera.useFramingBehavior = true
  if (camera.framingBehavior) {
    camera.framingBehavior.mode = FramingBehavior.FitFrustumSidesMode
    camera.framingBehavior.radiusScale = 1
    camera.framingBehavior.framingTime = 0
  }

  const light = new HemisphericLight('light', new Vector3(0, 1, 0), scene)
  // ...
}
```

128×128 的小 canvas，透明背景，`FramingBehavior` 會自動將模型置中並調整鏡頭距離。

### 縮圖生成流程

```typescript
function generateThumbnail(
  blockType: BlockType,
  options?: { signal?: AbortSignal },
) {
  return queue.add(
    async () => {
      const blockData = blockDefinitions[blockType]

      // 載入所有部件
      const tasks = blockData.content.partList.map(async (part) => {
        const modelPath = `${blockData.content.rootFolderName}/${part.path}`
        const model = await LoadAssetContainerAsync(modelPath, scene)
        const root = model.meshes[0]

        if (root) {
          root.position.copyFrom(Vector3.FromArray(part.position))
          root.rotationQuaternion?.copyFrom(
            Quaternion.FromArray(part.rotationQuaternion),
          )
          root.scaling.copyFrom(Vector3.FromArray(part.scaling))
        }

        return model
      })

      const containerList = await Promise.all(tasks)

      // 清除上一個模型，載入新模型
      clearLastContainer()
      lastContainerList = containerList
      containerList.forEach((c) => c.addAllToScene())

      // 自動調整鏡頭框住所有 mesh
      const meshes = containerList
        .flatMap((c) => c.meshes)
        .filter((m) => m.getTotalVertices() > 0)
      camera.framingBehavior?.zoomOnMeshesHierarchy(meshes, true)

      // 渲染一幀並截圖
      engine.runRenderLoop(() => scene.render())
      await scene.whenReadyAsync(true)

      camera.beta = Math.PI / 4
      camera.alpha = Math.PI / 4

      const base64 = await Tools.CreateScreenshotAsync(engine, camera, {
        width: 128,
        height: 128,
      })
      engine.stopRenderLoop()

      const res = await fetch(base64)
      return await res.blob()
    },
    { signal },
  )
}
```

流程為：載入模型 → 自動框住 → 渲染 → 截圖 → 轉 Blob。

這裡使用 [`p-queue`](https://www.npmjs.com/package/p-queue) 套件處理任務排隊，每個產線一次只處理一個任務（`concurrency: 1`），但多個產線可以同時工作。

### Round-Robin 分配

任務以輪詢方式分配給產線：

```typescript
function generateThumbnail(blockType: BlockType) {
  const generator = generatorList[index]
  index = (index + 1) % concurrency
  return generator.generateThumbnail(blockType)
}
```

## IndexedDB 快取

生成縮圖很耗時，不能每次開頁面都重新產生。用 IndexedDB 快取起來：

`content\aquarium\hexazen\domains\block\block-picker.vue`

```typescript
const blockThumbnailList = computedAsync(async () => {
  const tasks = blockTypeList.map(async (blockType) => {
    const key = `hexazen-${version}-block-thumbnail-${blockType}`

    // 先查快取
    const cache = await get(key)
    if (cache) {
      return {
        type: blockType,
        thumbnail: URL.createObjectURL(cache),
      }
    }

    // 快取沒有，即時生成
    const imgBlob = await generateThumbnail(blockType)
    await set(key, imgBlob)

    return {
      type: blockType,
      thumbnail: URL.createObjectURL(imgBlob),
    }
  })

  return Promise.all(tasks)
}, [])
```

快取的 key 包含 `version`，版本更新時自動失效重新生成。

離開頁面時也要記得清理 `ObjectURL`：

```typescript
onBeforeUnmount(() => {
  blockThumbnailList.value.forEach((item) => {
    URL.revokeObjectURL(item.thumbnail)
  })
})
```

## 積木選擇器 UI

有了縮圖，UI 就簡單了。使用輪播元件搭配倒角邊框風格：

```vue
<template>
  <div class="chamfer-4 p-1 bg-gray-200">
    <div class="bg-white chamfer-3.5 p-3">
      <u-carousel v-slot="{ item }" :items="blockThumbnailList" drag-free>
        <div
          class="size-22 chamfer-3 p-0.5 bg-gray-100
                 cursor-pointer select-none"
          @click="handleClick(item.type)"
        >
          <img
            :src="item.thumbnail"
            class="border-none! bg-white chamfer-2.5"
          >
        </div>
      </u-carousel>
    </div>
  </div>
</template>
```

`drag-free` 讓使用者可以自由拖拽瀏覽，手機上也很順暢。%◝(≧∀≦)◟%

## `createSharedComposable` 單例化

縮圖生成器在整個應用中只需要一個實例，使用 VueUse 的 `createSharedComposable`：

```typescript
export const useThumbnailGenerator = createSharedComposable(
  _useThumbnailGenerator,
)
```

不管幾個元件呼叫 `useThumbnailGenerator()`，都會拿到同一個實例，共享同一批產線。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* 多執行緒無頭 Babylon.js 場景自動產生 3D 縮圖
* 根據裝置性能動態調整並行數
* IndexedDB 快取避免重複生成
* `createSharedComposable` 確保全域單例
* 輪播 UI 支援拖拽瀏覽

下一章讓我們來看分享編碼與 URL 壓縮的實作吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/07-share-codec.md
description: 每個積木只佔 25 bits，用 Bit-packing 把整個場景塞進一條短短的 URL 裡。(/≧▽≦)/
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP07：分享編碼與 URL 壓縮

我希望分享連結即可讓他人聽到你設計的自然音效，但我不想登入也不想有後端，這代表場景資料要塞進 URL 裡了。%◝( •ω• )◟%

JSON 太長了，Base64 編碼 JSON 也不夠精簡，所以這裡採用位元打包（Bit-packing）格式。%੭ ˙ᗜ˙ )੭%

## 編碼格式設計

### 每個積木需要什麼資訊？

| 欄位     | 說明                      | 範圍            | 位元數  |
| -------- | ------------------------- | --------------- | ------- |
| type     | 積木種類（如 "g1"、"b7"） | 2 個 ASCII 字元 | 16 bits |
| q        | 六角格 q 座標             | \[-3, 4]         | 3 bits  |
| r        | 六角格 r 座標             | \[-3, 4]         | 3 bits  |
| rotation | 旋轉步數                  | \[0, 7]          | 3 bits  |

每個積木只需要 **25 bits**！

### 完整格式

```
[version: 4 bits][block₁: 25 bits][block₂: 25 bits]...
```

最前面 4 bits 是版本號，方便未來擴展。目前是 v2。

## BitWriter 與 BitReader

以 MSB-first 方式讀寫任意寬度的位元。

`content\aquarium\hexazen\domains\share\codec\index.ts`

```typescript
class BitWriter {
  private buffer: number[] = []
  private currentByte = 0
  private bitPosition = 0

  /** 寫入 width 個位元（MSB-first） */
  write(value: number, width: number): void {
    for (let i = width - 1; i >= 0; i--) {
      this.currentByte = (this.currentByte << 1) | ((value >> i) & 1)
      this.bitPosition++

      if (this.bitPosition === 8) {
        this.buffer.push(this.currentByte)
        this.currentByte = 0
        this.bitPosition = 0
      }
    }
  }

  /** 結束寫入，將剩餘位元補 0 後輸出 */
  finish(): Uint8Array {
    if (this.bitPosition > 0) {
      this.buffer.push(this.currentByte << (8 - this.bitPosition))
    }
    return new Uint8Array(this.buffer)
  }
}
```

`BitReader` 則是反向操作，從 `Uint8Array` 中逐位元讀取。

## 編碼：場景 → URL

```typescript
export function encodeBlocks(blocks: Iterable<SharedBlock>): string {
  const blockArray = [...blocks]
  if (blockArray.length === 0)
    return ''

  const writer = new BitWriter()

  // 版本號
  writer.write(FORMAT_VERSION, BITS_VERSION)

  for (const block of blockArray) {
    // type: 2 個 ASCII 字元，各 8 bits
    writer.write(block.type.charCodeAt(0), BITS_CHAR)
    writer.write(block.type.charCodeAt(1), BITS_CHAR)

    // 座標加偏移量，將 [-3, 3] 映射到 [0, 6]
    const encodedQ = block.hex.q + COORDINATE_OFFSET
    const encodedR = block.hex.r + COORDINATE_OFFSET
    writer.write(encodedQ, BITS_COORDINATE)
    writer.write(encodedR, BITS_COORDINATE)

    // 旋轉
    writer.write(block.rotation, BITS_ROTATION)
  }

  return uint8ArrayToBase64url(writer.finish())
}
```

座標使用固定偏移量，就可以避免資料出現負數，例如：`q + 3` 把 \[-3, 3] 轉成 \[0, 6]，剛好可以用 3 bits 表示。

最後透過 Base64url 編碼確保 URL 安全：

```typescript
function uint8ArrayToBase64url(bytes: Uint8Array): string {
  let binary = ''
  for (const byte of bytes) {
    binary += String.fromCharCode(byte)
  }
  return btoa(binary)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '')
}
```

標準 Base64 的 `+`、`/`、`=` 在 URL 中有特殊含義，替換成 `-`、`_` 並去掉 padding。

## 解碼：URL → 場景

```typescript
function decodeBinaryBlocks(encoded: string): SharedBlock[] {
  const bytes = base64urlToUint8Array(encoded)
  const reader = new BitReader(bytes)

  const version = reader.read(BITS_VERSION)
  if (version !== FORMAT_VERSION) {
    throw new TypeError(`不支援的版本號: ${version}`)
  }

  const totalBits = bytes.length * 8
  const dataBits = totalBits - BITS_VERSION
  const blockCount = Math.floor(dataBits / BITS_PER_BLOCK)

  const blocks: SharedBlock[] = []

  for (let i = 0; i < blockCount; i++) {
    const char1 = String.fromCharCode(reader.read(BITS_CHAR))
    const char2 = String.fromCharCode(reader.read(BITS_CHAR))
    const blockType = `${char1}${char2}` as BlockType

    if (!validBlockTypes.has(blockType)) {
      throw new TypeError(`無效的 BlockType: "${blockType}"`)
    }

    const q = reader.read(BITS_COORDINATE) - COORDINATE_OFFSET
    const r = reader.read(BITS_COORDINATE) - COORDINATE_OFFSET
    const rotation = reader.read(BITS_ROTATION)

    blocks.push({
      type: blockType,
      hex: Hex.fromAxial(q, r),
      rotation,
    })
  }

  return blocks
}
```

根據 `totalBits` 和 `BITS_PER_BLOCK` 可以推算出有幾個積木，不需要額外儲存數量。

## 分享與還原流程

### 分享：編碼 → 複製連結

```typescript
async function handleShare() {
  const sharedBlocks = Array.from(placedBlockMap.values()).map((block) => {
    const rotationStep = Math.round(block.rootNode.rotation.y / (Math.PI / 3))
    const rotation = ((rotationStep % 6) + 6) % 6

    return {
      type: block.type,
      hex: block.hex,
      rotation,
    }
  })

  const encoded = encodeBlocks(sharedBlocks)
  const url = new URL(window.parent.location.href)
  url.searchParams.set('view', encoded)

  await navigator.clipboard.writeText(url.toString())
  toast.add({
    title: t('linkCopied'),
    description: t('shareLinkDescription'),
  })
}
```

旋轉角度從弧度轉回步數（六角形嘛，轉 6 次就是一圈了，所以步數為 0~5），確保 `((step % 6) + 6) % 6` 處理負數旋轉。

### 還原：載入分享連結

```typescript
async function restoreSharedView() {
  if (!sharedViewEncodedData)
    return

  isRestoringView.value = true
  try {
    const sharedBlocks = decodeBlocks(sharedViewEncodedData)

    const tasks = sharedBlocks.map(({ type, hex, rotation }) => {
      return mainSceneRef.value!.spawnBlock(type, hex).then((block) => {
        block.rootNode.rotation.y = rotation * (Math.PI / 3)
      })
    })

    await Promise.all(tasks)
  }
  catch (error) {
    toast.add({
      title: t('restoreFailed'),
      description: t('linkInvalid'),
      color: 'error',
    })
  }
  finally {
    // 至少顯示 3 秒 loading 畫面
    await promiseTimeout(Math.max(3000, new Date().getTime() - startedAt))
    isRestoringView.value = false
  }
}
```

`promiseTimeout` 確保 loading 畫面至少顯示 3 秒，避免一閃而過造成使用者困惑。

還原後的檢視模式會自動開啟攝影機自動旋轉，讓使用者可以悠閒地欣賞音景。%(´,,•ω•,,)%

## 效率比較

假設放了 10 個積木：

| 格式                    | 大小       |
| ----------------------- | ---------- |
| JSON                    | ~500 bytes |
| Bit-packing + Base64url | ~43 bytes  |

壓縮率超過 90%！URL 短而美觀。%(/≧▽≦)/%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen/domains/share)

* Bit-packing 將每個積木壓縮至 25 bits
* Base64url 確保 URL 安全
* `BitWriter` / `BitReader` 實現任意位元寬度的讀寫
* 版本號機制方便未來擴展格式
* 分享連結包含完整場景資訊，不需後端

下一章讓我們來看 UI 設計與國際化的實作吧。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/08-ui-and-i18n.md
description: 倒角邊框、聲景混音器、還有不用 vue-i18n 的輕量國際化方案。੭ ˙ᗜ˙ )੭
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP08：UI 設計與國際化

3D 場景和音效引擎都搞定了，最後要讓整個應用的 UI 既好看又好用。

HexaZen 跑在 VitePress 的 whyframe iframe 裡，所以 `vue-i18n` 無法正常運作。

沒關係，那就自己做一個。%ᕕ( ﾟ ∀。)ᕗ%

## 倒角邊框元件

HexaZen 的 UI 風格不用圓角，而是用「倒角（chamfer）」，像寶石一樣的多邊形切割。

`content\aquarium\hexazen\components\chamfer-border-card.vue`

```vue
<template>
  <div class="chamfer-4 p-1" :style="frameStyle">
    <div class="bg-white chamfer-3.5 p-3" :class="props.contentClass">
      <slot />
    </div>
  </div>
</template>

<script setup lang="ts">
import type { CSSProperties } from 'vue'
import { computed } from 'vue'

interface Props {
  contentClass?: string;
  borderSize?: string;
  borderColor?: string;
}
const props = withDefaults(defineProps<Props>(), {
  contentClass: '',
  borderSize: '4px',
  borderColor: '#e5e7eb',
})

const frameStyle = computed<CSSProperties>(() => ({
  padding: props.borderSize,
  backgroundColor: props.borderColor,
}))
</script>
```

外層一個帶色的 chamfer 框，內層一個白色的 chamfer 框，用 padding 差異製造邊框效果。

### 倒角按鈕

按鈕也用 `clip-path` 做出八邊形倒角：

```typescript
const style = computed<CSSProperties>(() => {
  const size = height.value / 2
  const size2 = (size / 3) * 2

  return {
    paddingInline: `${size * 1.1}px`,
    clipPath: `polygon(
      ${size2}px 0,
      calc(100% - ${size2}px) 0,
      100% ${size}px,
      100% calc(100% - ${size}px),
      calc(100% - ${size2}px) 100%,
      ${size2}px 100%,
      0 calc(100% - ${size}px),
      0 ${size}px
    )`,
  }
})
```

用 `useElementSize` 動態取得按鈕高度，讓倒角比例自動適配不同大小的按鈕。%( •̀ ω •́ )✧%

## 聲景混音器

每個音效都可以獨立調整音量，透過 Modal 呈現：

```vue
<template>
  <div class="space-y-4 p-2">
    <div
      v-for="item in playerList"
      :key="item.id"
      class="flex items-center gap-3"
    >
      <u-icon
        :name="soundscapeIconMap[item.type] ?? 'i-mingcute:music-2-fill'"
        class="text-xl text-gray-500 shrink-0"
      />

      <span class="text-sm text-gray-600 flex-1 capitalize">
        {{ t(item.player.title as any) }}
      </span>

      <u-slider
        :model-value="volumeMap[item.id] ?? 1"
        :min="0"
        :max="2"
        :step="0.01"
        class="flex-1"
        @update:model-value="(value) => handleVolumeChange(item.id, value ?? 1)"
      />
    </div>
  </div>
</template>
```

每個音效類型都有專屬 icon：

```typescript
const soundscapeIconMap: Record<SoundscapeType, string> = {
  rustle: 'i-mingcute:leaf-fill',
  insect: 'i-mingcute:bug-fill',
  bird: 'i-material-symbols:raven',
  frog: 'i-fa7-solid:frog',
  beast: 'i-mingcute:cat-fill',
  river: 'i-material-symbols:water',
  building: 'i-solar:buildings-2-bold',
  ocean: 'i-lucide-lab:waves-birds',
  alpine: 'i-mynaui:mountain-snow-solid',
  rain: 'i-material-symbols:rainy',
  campfire: 'i-mingcute:campfire-fill',
}
```

音量範圍 0～2，也就是最大可以放大到原始音量的 2 倍。

只顯示目前正在播放（未被靜音）的音效，避免混亂。%ԅ(´∀\` ԅ)%

## 公告欄 Modal

首次開啟會顯示歡迎頁面，包含 Intro 和 Quick Start 兩個分頁。

Quick Start 使用輪播展示操作步驟，搭配影片和圖片：

```typescript
const quickStartItems = computed(() => {
  const descriptionList = t('start')
  const imgList = t('startImg')

  return descriptionList.map((text, index) => ({
    img: imgList[index] || '',
    description: text,
  }))
})
```

有趣的是文字內容和圖片路徑都放在 i18n 翻譯檔中，可以根據語言顯示不同的教學內容。

## 輕量 i18n：不用 vue-i18n 的方案

因為 whyframe 環境的限制，只好自己做了輕量版 i18n composable。

`content\aquarium\hexazen\composables\use-simple-i18n.ts`

```typescript
export function useSimpleI18n<
  Messages extends Record<DefaultLang, MessageSchema>,
  DefaultLang extends 'zh-hant' | 'en',
  Data = Messages[DefaultLang],
>(
  messages: Messages & StrictCheck<Messages>,
  options?: {
    defaultLocale?: DefaultLang;
  },
) {
  const currentLocale = ref(
    options?.defaultLocale ?? Object.keys(messages)[0],
  ) as Ref<DefaultLang>

  const languages = usePreferredLanguages()

  watch(
    languages,
    ([lang]) => {
      currentLocale.value = (
        lang?.includes('zh') ? 'zh-hant' : 'en'
      ) as DefaultLang
    },
    { immediate: true },
  )

  function t<Key extends keyof Data>(
    key: Key,
    params?: Record<string, string | number>,
  ): Data[Key] extends string[] ? string[] : string {
    const value = getMessage(key) as any

    if (Array.isArray(value))
      return value

    if (typeof value === 'string' && params) {
      let text = value
      Object.entries(params).forEach(([k, v]) => {
        text = text.replace(new RegExp(`{${k}}`, 'g'), String(v))
      })
      return text
    }

    return value
  }

  return { locale: currentLocale, setLocale, t }
}
```

### 型別安全的嚴格檢查

最精華的部分是 TypeScript 型別層面的檢查：

```typescript
type StrictCheck<Messages> = {
  [L in keyof Messages]: {
    [K in KeyUniverse<Messages>]: CommonType<Messages, K>;
  };
}
```

`StrictCheck` 確保**所有語言都必須有完全相同的 key 集合**。

如果中文多了一個 key 但英文沒有，TypeScript 編譯時就會報錯。不用等到運行時才發現遺漏翻譯。%╰(*´︶\`*)╯%

### 特色

* 自動偵測瀏覽器語言（`usePreferredLanguages`）
* 支援字串插值（`{name}` 參數替換）
* 支援字串陣列（用於教學步驟等清單）
* 編譯時期型別檢查，缺漏翻譯直接報錯
* 不到 100 行程式碼，零外部依賴

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* 倒角邊框風格統一整個應用的視覺語言
* 聲景混音器提供精細的個別音量控制
* 公告欄兼具歡迎頁和操作教學
* 自製輕量 i18n，編譯時期保證翻譯完整性
* 自動偵測瀏覽器語言，零設定

下一章是最後一篇，讓我們來聊聊 WebGPU 與效能優化。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /column-hexazen/09-webgpu-and-performance.md
description: 最終章！WebGPU 優先策略、智慧鏡頭限制、還有各種讓體驗更流暢的小細節。✧⁑｡٩(ˊᗜˋ*)و✧⁕｡
---

![hexazen-cover](/hexazen-cover.webp){.cover}

# HexaZen - EP09：WebGPU 與效能優化

最後一章，來聊聊那些讓 HexaZen 跑得更順暢的技術細節。

從渲染引擎的選擇到鏡頭限制，這些看似微小的優化加在一起，就是「流暢」和「卡頓」的差別。%੭ ˙ᗜ˙ )੭%

## WebGPU 優先，WebGL 降級

Babylon.js 支援 WebGPU，效能比 WebGL 好不少。優先使用 WebGPU，不支援的裝置自動降級。

`content\aquarium\hexazen\composables\use-babylon-scene.ts`

```typescript
async createEngine({ canvas }) {
  const webGPUSupported = await WebGPUEngine.IsSupportedAsync
  if (webGPUSupported) {
    const engine = new WebGPUEngine(canvas, {
      antialias: true,
      stencil: true,
    })
    await engine.initAsync()
    return engine
  }

  return new Engine(canvas, true, {
    antialias: true,
    alpha: false,
    stencil: true,
  })
},
```

`WebGPUEngine.IsSupportedAsync` 是非同步檢測，因為瀏覽器需要時間確認 GPU 支援狀態。

## 場景初始化

`useBabylonScene` composable 封裝了完整的場景生命週期：

```typescript
export function useBabylonScene(param?: UseBabylonSceneParam) {
  const canvasRef = ref<HTMLCanvasElement>()
  const engine = shallowRef<BabylonEngine>()
  const scene = shallowRef<Scene>()
  const camera = shallowRef<ArcRotateCamera>()

  onMounted(async () => {
    if (!canvasRef.value)
      return

    engine.value = await createEngine({
      canvas: canvasRef.value,
    })
    // 適配高 DPI 螢幕
    engine.value.setHardwareScalingLevel(1 / (window?.devicePixelRatio ?? 1))

    scene.value = createScene({
      canvas: canvasRef.value,
      engine: engine.value,
    })
    camera.value = createCamera({
      canvas: canvasRef.value,
      engine: engine.value,
      scene: scene.value,
    })

    window.addEventListener('resize', handleResize)

    engine.value.runRenderLoop(() => {
      scene.value?.render()
    })

    await init({ canvas, engine, scene, camera })
    setupSmartCameraLimits(engine, camera, scene)
  })

  onBeforeUnmount(() => {
    engine.value?.dispose()
    scene.value?.dispose()
    window.removeEventListener('resize', handleResize)
  })

  return { canvasRef, engine, scene, camera }
}
```

`setHardwareScalingLevel` 根據 `devicePixelRatio` 調整渲染解析度，Retina 螢幕上會更清晰。

### 預設光照與霧氣

```typescript
createScene({ engine }) {
  const scene = new Scene(engine)
  scene.createDefaultLight()

  const defaultLight = scene.lights.at(-1)
  if (defaultLight instanceof HemisphericLight) {
    defaultLight.diffuse = new Color3(1.0, 0.98, 0.95)
    defaultLight.direction = new Vector3(0.5, 1, 0)
    defaultLight.groundColor = new Color3(0.64, 0.56, 0.78)
  }

  scene.clearColor = new Color4(0.97, 0.97, 0.96, 1)

  scene.fogMode = Scene.FOGMODE_LINEAR
  scene.fogColor = new Color3(0.55, 0.6, 0.65)
  scene.fogStart = 10
  scene.fogEnd = 100

  return scene
},
```

暖色光源搭配偏紫的地面反射光，讓積木看起來有柔和的手繪感。

## 智慧鏡頭限制

鏡頭需要根據裝置螢幕比例自動調整：

```typescript
function setupSmartCameraLimits(
  engine: BabylonEngine,
  camera: ArcRotateCamera,
  scene: Scene,
) {
  const width = engine.getRenderWidth()
  const height = engine.getRenderHeight()

  // 直式螢幕使用垂直 FOV，橫式使用水平 FOV
  if (width < height) {
    camera.fovMode = Camera.FOVMODE_VERTICAL_FIXED
  }
  else {
    camera.fovMode = Camera.FOVMODE_HORIZONTAL_FIXED
  }

  const finalRadius = 4
  const safeDistance = finalRadius / Math.sin(camera.fov / 2)

  camera.lowerRadiusLimit = safeDistance * 0.2
  camera.upperRadiusLimit = safeDistance * 1
  camera.minZ = finalRadius * 0.1
}
```

手機直式螢幕和電腦橫式螢幕的 FOV 模式不同，這樣積木在任何裝置上都能完整顯示在畫面中。

### 鏡頭約束

```typescript
createCamera({ scene, canvas }) {
  const camera = new ArcRotateCamera(
    'camera', 0, Math.PI / 3 * 2, 5,
    new Vector3(0, 0, 0), scene,
  )
  camera.attachControl(canvas, true)

  // 禁止平移，只能旋轉和縮放
  camera.panningSensibility = 0
  camera.wheelDeltaPercentage = 0.01

  // 限制仰角，永遠從上方俯瞰
  camera.lowerBetaLimit = Math.PI / 3
  camera.upperBetaLimit = Math.PI / 3

  return camera
},
```

禁止平移（`panningSensibility = 0`）和固定仰角（`beta` 鎖定在 60°），讓使用者只能水平旋轉和縮放，保持最佳觀賞角度。

## 模型材質優化

載入 GLB 模型時，強制使用三線性過濾避免紋理閃爍：

```typescript
model.meshes.forEach((mesh) => {
  if (mesh.material instanceof PBRMaterial) {
    mesh.material.metallic = 0
    mesh.material.roughness = 0.4

    const texture = mesh.material.albedoTexture
    if (texture instanceof Texture) {
      texture.updateSamplingMode(Texture.TRILINEAR_SAMPLINGMODE)
    }
  }
})
```

`TRILINEAR_SAMPLINGMODE` 讓紋理邊緣被柔化，旋轉時不會有像素閃爍。

一開始看到的時候真的是快被閃瞎眼。%(◞‸◟ )%

## 陰影生成

```typescript
function createShadowGenerator(scene: Scene) {
  const light = new DirectionalLight('dir01', new Vector3(-3, -5, -2), scene)
  light.intensity = 0.8

  const shadowGenerator = new ShadowGenerator(2048, light)
  shadowGenerator.bias = 0.000001
  shadowGenerator.normalBias = 0.0001
  shadowGenerator.forceBackFacesOnly = true
  return shadowGenerator
}
```

2048×2048 的陰影貼圖確保陰影邊緣銳利。`forceBackFacesOnly = true` 防止自身陰影產生的瑕疵（shadow acne）。

## 整體架構回顧

經過 9 篇文章，HexaZen 的架構如下：

```
hexazen/
├── hexazen.vue              # 應用根元件（狀態管理、UI 佈局）
├── main-scene.vue           # 3D 場景（互動、粒子、後製）
├── composables/
│   ├── use-babylon-scene    # 引擎初始化與生命週期
│   ├── use-thumbnail-gen    # 多執行緒縮圖生成
│   ├── use-simple-i18n      # 輕量國際化
│   └── use-font-loader      # 字體動態載入
└── domains/
    ├── block/               # 積木定義、建立、縮圖
    ├── hex-grid/            # 六角格數學
    ├── soundscape/          # 聲景規則、播放引擎、混音器
    └── share/codec/         # URL 編碼/解碼
```

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/hexazen)

* WebGPU 優先、WebGL 自動降級
* 高 DPI 螢幕適配與智慧鏡頭限制
* 三線性過濾消除紋理閃爍
* 2048×2048 高品質陰影

感謝看到這裡的你！希望這系列文章能給你一些靈感。%ヾ(◍'౪\`◍)ﾉﾞ%

如果你也想體驗看看，歡迎到 [HexaZen](https://codlin.me/aquarium/hexazen/) 玩玩看，打造屬於你自己的音景吧！

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

---

---
url: /blog-vue/js-util-vs-vue-composable.md
description: Vue composable，比一般的 JS function 多了些約定，讓我們來看看吧。(´・ω・`)
---

![js-util-vs-vue-composable](/js-util-vs-vue-composable.webp){.cover}

# JS Utility Function 和 Vue Composable，傻傻分不清楚

熟悉 Vue 3 的朋友們應該都用過 Composition API 寫過 composable 吧？

之前聽過有人問：「為什麼我要寫個 `useXxx` 的 composable，而不是直接寫個普通的 util function？」

其實 utility function 和 composable 本質上的確都是 function，但 composable 有一些重要的約定。

今天就來聊聊這兩者的差異，這也是目前 AI 最常犯的錯誤。%ლ(╹ε╹ლ)%

## Utility Function 就是純 JS function

先來看最單純的情況。utility function 就是一般的 JavaScript function，負責做資料轉換、格式化、驗證等等純粹的運算。

例如：

```ts
export function formatDate(date: Date) {
  return new Intl.DateTimeFormat('zh-TW').format(date)
}

export function formatCurrency(amount: number) {
  return new Intl.NumberFormat('zh-TW', {
    style: 'currency',
    currency: 'TWD',
  }).format(amount)
}

export function validateEmail(email: string) {
  return /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(email)
}
```

這類 function 有幾個特點：

* **沒有狀態**：輸入相同，輸出一定相同
* **不依賴 Vue**：拿去 Node.js、React 裡面用也完全沒問題
* **隨時隨地都能呼叫**：在 `setup`、`onMounted`、`watch`、甚至 `setTimeout` 裡面呼叫都可以

## Composable 不只是 function

composable 雖然也是 function，但它會利用 Composition API（`ref`、`onMounted` 等）來封裝有狀態的邏輯。

例如以下是一個偵測視窗大小的 composable：

```ts
import { onMounted, onUnmounted, ref } from 'vue'

export function useWindowSize() {
  const width = ref(window.innerWidth)
  const height = ref(window.innerHeight)

  function update() {
    width.value = window.innerWidth
    height.value = window.innerHeight
  }

  onMounted(() => window.addEventListener('resize', update))
  onUnmounted(() => window.removeEventListener('resize', update))

  return { width, height }
}
```

這時候你可能會想問：「Vue 的響應式系統本來就可以獨立運作，就算不是 Vue 也可以用，所以分界線在哪？」

關鍵點是 composable 內部可能使用 `onMounted`、`onUnmounted` 等 lifecycle hook 或 `watch`、`computed` 等 effect，這些 API 必須在**元件實例的同步流程**中才能正確註冊並自動清除。

## Composable 必須在同步流程中呼叫

Vue 在執行 `<script setup>` 時，會將目前的元件實例設為 current instance。只要你還在這個同步的呼叫堆疊中，lifecycle hook 或 effect 就能正確註冊到元件上。

所以以下這些地方呼叫 composable 都是可以的：

```vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { useWindowSize } from './composables/use-window-size'

// ✓ script setup 頂層
const { width, height } = useWindowSize()

// ✓ onMounted callback（Vue 會設定 current instance）
onMounted(() => {
  const size = useWindowSize()
})
</script>
```

因為 `<script setup>` 頂層和 `onMounted` 等 lifecycle hook 的 callback 執行時，Vue 都會將元件實例設為 current instance，所以能正確註冊。%╰(*´︶\`*)╯%

但是，一旦脫離同步流程，元件實例就不再是 current instance 了：

```vue
<script setup lang="ts">
import { onMounted, ref, watch } from 'vue'
import { useWindowSize } from './composables/use-window-size'

const enabled = ref(false)

// ✗ watch callback 觸發時機不確定，可能不在同步流程中
watch(enabled, () => {
  const size = useWindowSize()
})

onMounted(() => {
  // ✗ setTimeout 是非同步，脫離了元件的同步流程
  setTimeout(() => {
    const size = useWindowSize()
  }, 100)

  // ✗ Promise.then 也是非同步
  fetch('/api').then(() => {
    const size = useWindowSize()
  })
})

// ✗ await 之後也是非同步
const data = await fetchSomething()
const size = useWindowSize()
</script>
```

`watch` callback、`setTimeout`、`Promise.then`、`await` 之後的程式碼，都不在元件實例的同步呼叫堆疊中，lifecycle hook 或 effect 無法正確註冊，自動清除機制就會壞掉。

意思就是在非同步流程中使用 composable 可能會導致 memory leak！%(́⊙◞౪◟⊙‵)%

## Utility Function 可以隨便放

相比之下，utility function 沒有這些限制，因為它們根本不碰 Vue 的響應式系統和生命週期。

```vue
<script setup lang="ts">
import { onMounted, ref, watch } from 'vue'
import { formatDate } from './utils/formatters'
import { validateEmail } from './utils/validators'

const email = ref('')
const today = ref('')

// ✓ 在頂層呼叫
today.value = formatDate(new Date())

// ✓ 在 onMounted 呼叫
onMounted(() => {
  console.log(formatDate(new Date()))
})

// ✓ 在 watch 呼叫
watch(email, (value) => {
  if (validateEmail(value)) {
    console.log('Email 合法')
  }
})

// ✓ 甚至在 setTimeout 呼叫
setTimeout(() => {
  console.log(formatDate(new Date()))
}, 1000)
</script>
```

畢竟就是普通的 function，沒有副作用，也不依賴 Vue 的元件實例。

## 不要把 Utility 包成 Composable

有時候會看到有人把明明是 utility 的東西，硬是包成 composable 的格式：

```ts
// ✗ 不需要這樣做
export function useFormatters() {
  const formatDate = (date: Date) => {
    return new Intl.DateTimeFormat('zh-TW').format(date)
  }

  const formatCurrency = (amount: number) => {
    return new Intl.NumberFormat('zh-TW', {
      style: 'currency',
      currency: 'TWD',
    }).format(amount)
  }

  return { formatDate, formatCurrency }
}
```

這樣做完全沒有好處，反而帶來壞處：

* 多了一層不必要的包裝
* `use` 前綴讓人誤以為裡面有響應式狀態
* 使用時多了解構的步驟

直接 export function 就好了，簡單明瞭。%◝( •ω• )◟%

## Composable 搭配 Utility 一起用

不過 composable 和 utility function 並非互斥。composable 裡面當然可以使用 utility function：

```ts
export function validateEmail(email: string) {
  return /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(email)
}
```

```ts
import { computed, ref } from 'vue'
import { validateEmail } from '../utils/validators'

export function useEmailInput(initialValue = '') {
  const email = ref(initialValue)
  const isValid = computed(() => validateEmail(email.value))
  const error = computed(() =>
    email.value && !isValid.value ? '無效的 Email 格式' : null
  )

  return { email, isValid, error }
}
```

`validateEmail` 是純粹的 util，`useEmailInput` 才是 composable。

各司其職，結構清晰。%( •̀ ω •́ )✧%

## 所以真的會怎麼樣嗎？

讓我們用實際的例子來感受可能會有甚麼問題，我們使用 VueUse 的 `useIntervalFn` 舉例。

這裡使用簡化過的 `useIntervalFn`，內容如下：

```ts
import { onScopeDispose, onUnmounted, ref } from 'vue'

/** 簡化版 useIntervalFn，用於示範 composable 的自動清除機制 */
export function useIntervalFnSimple(
  callback: () => void,
  interval: number,
) {
  let timerId: ReturnType<typeof setInterval> | null = null
  const isActive = ref(false)

  function stop() {
    if (timerId) {
      clearInterval(timerId)
      timerId = null
    }
    isActive.value = false
  }

  function start() {
    stop()
    timerId = setInterval(callback, interval)
    isActive.value = true
  }

  start()
  onScopeDispose(stop)

  return { isActive, start, stop }
}

```

重點在最後那行 `onScopeDispose(stop)`。它會在作用域銷毀時自動呼叫 `stop()`，interval 就會跟著被清除。

前提是 `onScopeDispose` 要在正確的時機被呼叫，也就是在元件實例的同步流程中。

接下來讓我們用實際的元件來對比看看。兩邊都是每秒 +1 的計數器，差別只在 composable 的呼叫位置。

`content\blog-vue\js-util-vs-vue-composable\interval-top-level.vue`

```vue
<template>
  <span class="text-xs opacity-50">
    interval-top-level 已安裝
  </span>
</template>

<script setup lang="ts">
import { syncCount } from './interval-store'
import { useIntervalFnSimple } from './use-interval-fn-simple'

// ✓ 在同步流程中呼叫，onUnmounted 綁定元件實例
useIntervalFnSimple(() => {
  syncCount.value++
}, 1000)
</script>

```

`content\blog-vue\js-util-vs-vue-composable\interval-in-timeout.vue`

```vue
<template>
  <span class="text-xs opacity-50">
    interval-in-timeout 已安裝
  </span>
</template>

<script setup lang="ts">
import { asyncCount } from './interval-store'
import { useIntervalFnSimple } from './use-interval-fn-simple'

// ✗ 模擬非同步操作（例如等待 API 回應）後才啟動 interval
// setTimeout callback 執行時，已經脫離元件的同步流程
// onUnmounted 無法正確註冊，元件銷毀後 interval 不會被清除
setTimeout(() => {
  useIntervalFnSimple(() => {
    asyncCount.value++
  }, 1000)
}, 1000)
</script>

```

點「銷毀元件」後觀察計數器的變化：

左邊在同步流程中呼叫，銷毀後計數停止。右邊在 `setTimeout`（非同步）中呼叫，銷毀後計數還在跑。

同樣的 composable，只是呼叫時機不同，結果天差地別。%( ˘•ω•˘ )%

這就是為什麼 composable 必須在元件的同步流程中呼叫，否則作用域無法正確與元件實例綁定，導致 memory leak。

不過其實 Vue 在 dev 模式下會貼心地給你一個警告：

```bash
[Vue warn]: onUnmounted is called when there is no active component
instance to be associated with.
Lifecycle injection APIs can only be used during execution of setup().
If you are using async setup(), make sure to register lifecycle hooks
before the first await statement.
```

所以如果你在 console 看到這段訊息，就表示有 composable 在非同步流程中被呼叫了，趕快檢查一下吧。%( •̀ ω •́ )✧%

## 用 Effect Scope 補救

雖然說最好的做法是把 composable 放在同步流程中呼叫，但如果真的遇到沒有辦法的情境，可以用 Vue 提供的 `effectScope` 來補救：

```vue
<template>
  <span class="text-xs opacity-50">
    interval-effect-scope 已安裝
  </span>
</template>

<script setup lang="ts">
import { effectScope } from 'vue'
import { scopeCount } from './interval-store'
import { useIntervalFnSimple } from './use-interval-fn-simple'

// 在同步流程中建立 scope，會自動成為元件 scope 的子 scope，除非將 detached 設為 true
const scope = effectScope()

// ✓ 雖然在 setTimeout（非同步）中呼叫，但用 effectScope 包住
// composable 內部的 onScopeDispose 會被收集到 scope 中
// 元件銷毀時 scope 自動停止，interval 也跟著被清除
setTimeout(() => scope.run(() => {
  useIntervalFnSimple(() => {
    scopeCount.value++
  }, 1000)
}), 1000)
</script>

```

`effectScope()` 在同步流程中建立時，會自動成為元件 scope 的子 scope。元件銷毀時，子 scope 也會跟著被停止，裡面收集的 `onScopeDispose`、`watch`、`computed` 等 effect 都會一起清除。

實際效果如下，同樣在 `setTimeout` 中呼叫，但用 `effectScope` 包住後，銷毀元件就能正確停止 interval：

不過要注意的是，`scope.run()` 只能收集基於 `onScopeDispose` 的清除邏輯。如果 composable 內部是用 `onUnmounted` 而不是 `onScopeDispose`，`scope.stop()` 管不到喔。%乁( ◔ ௰◔)「%

所以寫 composable 時，建議用 `onScopeDispose` 取代 `onUnmounted`，這樣使用者不管是在同步流程還是 `effectScope` 中呼叫，都能正確清除，可靠性更高。%( •̀ ω •́ )✧%

## 總結 🐟

* utility function 是純粹的 JavaScript function，不依賴 Vue，隨時隨地都能呼叫
* composable 利用 Composition API 封裝有狀態的邏輯，必須在**元件實例的同步流程**中呼叫
* `<script setup>` 頂層、`onMounted` 等 lifecycle hook callback 屬於同步流程，可以安全呼叫 composable
* `watch` callback、`setTimeout`、`Promise.then`、`await` 之後不在同步流程中，lifecycle hook 無法正確註冊，會導致 memory leak
* 非同步情境可以用 `effectScope` 補救，但 composable 內部必須使用 `onScopeDispose` 才能被正確收集
* 不要把純粹的 util function 包成 composable，`use` 前綴應該保留給有響應式狀態、生命週期管理的 function
* 寫 composable 時建議用 `onScopeDispose` 取代 `onUnmounted`，相容性更好

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

有錯誤或任何想法還請多多指教。%( ´∀\`)~♥%

---

---
url: /aquarium/minespace.md
description: 戴上耳機，在箱庭一隅聆聽。無盡白沙上散落二十二座木座箱庭，每座只收一種聲音的質地：連綿的風、稀疏的滴水、低頻的蛙鳴。
---


---

---
url: /column-minespace/01-voxel-world.md
description: 從一張空白的畫布開始，架起引擎、光與霧，再把幾十萬顆方塊塞進一個繪製呼叫裡。%(｢･ω･)｢✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP01：從零打造一個方塊世界

大家好，我是鱈魚。

Minespace 是一片無盡的白沙禪庭，十七座木頭底座的箱庭散落其間，每一座只收一種聲音的質地。戴上耳機走進去，走到哪裡就聽到哪裡的聲音。%( ˘ω˘ )%

這個系列會把裡面每一個特效拆開來講，一章一個。光暈、風、雲、陰影、雨雪，全部從最單純的原理開始做到專案裡實際跑的版本。

不過在講特效之前，得先有一個世界可以放特效。%੭ ˙ᗜ˙ )੭%

這一章就從一張空白的畫布開始，把方塊世界整個搭起來。

## 第一步：準備一塊畫布

先裝引擎。

```bash
npm install @babylonjs/core
```

再給它一塊畫布。

```html
<canvas ref="canvasRef" class="w-full h-full" />
```

Babylon 需要知道畫布實際有多大，所以樣式上要給它明確的尺寸，別讓它自己去猜。

## 第二步：引擎與場景

引擎負責跟 WebGL 講話，場景負責裝東西。

```ts
import { Engine, Scene } from '@babylonjs/core'

const engine = new Engine(canvas, false, {
  antialias: false,
  alpha: false,
  stencil: false,
  preserveDrawingBuffer: false,
})

const scene = new Scene(engine)

engine.runRenderLoop(() => scene.render())
window.addEventListener('resize', () => engine.resize())
```

Minespace 固定走 WebGL2，沒有開 WebGPU。WebGPU 在部分裝置上會出現難以重現的異常，而這個場景吃不到它的效能優勢，那就穩定優先。

第二個參數是抗鋸齒，這裡關掉。整個場景最後會畫進後製管線的離屏貼圖，canvas 那份多重取樣緩衝區只接得到最後那一張全螢幕方塊，上面沒有任何幾何邊緣可以抗鋸齒，等於白白配置一份記憶體與頻寬。%(›´ω\`‹ )%

`runRenderLoop` 交給引擎去接 `requestAnimationFrame`，中途要暫停就呼叫 `stopRenderLoop`。畫面捲出視窗、分頁切到背景，停掉算繪迴圈是最划算的一件事。

## 第三步：鏡頭

第一人稱漫遊用 `UniversalCamera`。

```ts
import { UniversalCamera, Vector3 } from '@babylonjs/core'

const camera = new UniversalCamera('roam-camera', new Vector3(0, 12, 0), scene)
camera.attachControl(canvas, true)

camera.minZ = 0.1
/** 要看得到延伸到天邊的沙地 */
camera.maxZ = 1600
camera.fov = 1.15
```

`fov` 預設是 0.8，那個視角很窄，走在箱庭之間像從管子裡看出去。一點一五大約是六十六度，寬到看得見兩側的木座，又還沒到廣角鏡那種邊緣拉長的程度。

`minZ` 與 `maxZ` 決定深度緩衝區的精度怎麼分配。近平面壓得太近，遠處會出現兩個面互相搶著顯示的閃爍，所以 0.1 是底線，不要再小。

## 第四步：兩盞燈

場景最少要有兩盞燈。

```ts
import { Color3, DirectionalLight, HemisphericLight } from '@babylonjs/core'

const ambientLight = new HemisphericLight('ambient', new Vector3(0, 1, 0), scene)
ambientLight.intensity = 0.82
/** 天空偏冷 */
ambientLight.diffuse = new Color3(0.78, 0.88, 1)
/** 地面反射偏暖 */
ambientLight.groundColor = new Color3(0.82, 0.77, 0.72)
ambientLight.specular = new Color3(0, 0, 0)

const sunLight = new DirectionalLight(
  'sun',
  new Vector3(0.666, -0.62, -0.416).normalize(),
  scene,
)
sunLight.intensity = 1.3
/** 午後的暖陽 */
sunLight.diffuse = new Color3(1, 0.93, 0.78)
/** 高光給滿，讓材質自己決定要反射多少 */
sunLight.specular = new Color3(1, 1, 1)
```

半球光是「由上往下一個顏色、由下往上另一個顏色」，方塊的頂面、側面、底面因此有三層不同的亮度。

色溫差是重點。陽光是暖的、補光是冷的，兩者拉開才會讓畫面活起來。全部用同一種白光，再多層次也只是灰階濃淡。%( •̀ ω •́ )✧%

先把平行光關掉，只剩半球光時最看得出那三層。木簷底下那一面完全照不到太陽，它的亮度全部來自「由下往上的地面反射色」。

再切「冷暖色溫差」，亮度層次一格都沒少，畫面卻立刻變成一張黑白照片。%(・∀・(・∀・(・∀・\*)%

平行光的 `specular` 給滿這件事，後面幾章會一直用到。`StandardMaterial` 裡漫射與自發光在乘上貼圖之前就被夾在 1.0，高光則加在那道 clamp 外面，所以高光是整套渲染裡唯一能真的超過純白的通道。光源這端給滿，「這個表面有多亮」就交還給各自的材質去決定。

## 第五步：霧

```ts
scene.fogMode = Scene.FOGMODE_LINEAR
scene.fogColor = new Color3(0.955, 0.95, 0.935)
scene.fogStart = 100
scene.fogEnd = 220
```

禪庭的霧色幾乎是純白，只帶一點點沙的暖。

背景色要跟霧色設成同一個顏色。

```ts
scene.clearColor = new Color4(0.955, 0.95, 0.935, 1)
```

天空若是另一塊顏色，兩者交界就會露出一條線，而那條線要靠霧藏起來。%( ˘•ω•˘ )%

## 第六步：第一顆方塊

場景有了，來畫第一顆方塊。

```ts
import { MeshBuilder, StandardMaterial } from '@babylonjs/core'

const block = MeshBuilder.CreateBox('stone', { size: 1 }, scene)

const material = new StandardMaterial('stone-material', scene)
material.diffuseTexture = createStoneTexture(scene)
material.specularColor = new Color3(0.02, 0.02, 0.02)
block.material = material
```

貼圖是十六格見方的像素畫，取樣方式要指定成最近鄰。

```ts
const texture = new Texture(url, scene, true, false, Texture.NEAREST_SAMPLINGMODE)
```

預設的雙線性取樣會把相鄰兩格的顏色混在一起，一顆方塊放大到滿螢幕時，看到的是一片糊掉的漸層。最近鄰取樣則是老老實實地放大每一格，硬邊完全保留，那才是這套美術要的樣子。%( ´ ▽ \` )ﾉ%

到這裡，畫面上有一顆帶著石頭紋理、吃得到光的方塊。

接下來要放第二顆、第三顆，以及剩下的幾十萬顆。

## 一顆一顆畫會怎樣

Minespace 的世界是 280 格見方、40 格高。

```ts
export const WORLD_SIZE = 280
export const WORLD_HEIGHT = 40
```

實際填出來的方塊有幾十萬顆。

鱈魚：「那就跑一個迴圈建幾十萬個 `CreateBox`，很快嘛。%(๑•̀ㅂ•́)و✧%」
路人：「你的瀏覽器會先跟你說再見。」
鱈魚：「⋯⋯好啦，這條路走不通。」

問題出在繪製呼叫（draw call）。CPU 每畫一個網格，就要跟 GPU 交代一次「用這份頂點、這份材質、這個矩陣，畫」。這趟溝通本身有固定成本，跟那顆方塊有幾個三角形幾乎無關。

換句話說，一萬顆方塊就是一萬趟。CPU 整幀的時間全花在講話上，GPU 反而閒著等。%(´థ‸థ)%

自己拉一下滑桿最快。

左邊的繪製呼叫跟著方塊數一路往上，右邊永遠停在個位數。%(⊙ o ⊙)%

## 第七步：換成 Thin Instance

右邊那條路叫 thin instance。

同一份頂點資料配上一整條變換矩陣的緩衝區，GPU 一次畫完幾萬顆，成本只有一個繪製呼叫。

```ts
const box = MeshBuilder.CreateBox('stone', { size: 1 }, scene)
box.material = material

const matrixBuffer = new Float32Array(positionList.length * 16)
positionList.forEach(([x, y, z], index) => {
  Matrix.Translation(x, y, z).copyToArray(matrixBuffer, index * 16)
})

box.thinInstanceSetBuffer('matrix', matrixBuffer, 16, true)
```

矩陣是 4×4，所以 stride 給 16。

第四個參數的意思是「這份緩衝區是靜態的」。Minespace 的世界不可編輯，這些矩陣算好之後就再也不動，這個旗標一定要給。傳 `false` 等於告訴 Babylon 之後還會改它，於是 GPU 緩衝區以 `DYNAMIC_DRAW` 配置，驅動層會另外做搬運與反交錯。官方論壇有一個兩百五十萬個面的實測，只改這個旗標就從 15 幀變成 60 幀。%(⊙ o ⊙)%

路人：「一個布林值差四倍？」
鱈魚：「一個布林值差四倍。%( ˘•ω•˘ )%」

### 兩個必須成對的旗標

緩衝區設完之後，還有兩行要一起下。

```ts
/** 邊界盒已經在設定緩衝區時算好了 */
box.doNotSyncBoundingInfo = true
box.alwaysSelectAsActiveMesh = true
```

這兩個必須一起出現。`doNotSyncBoundingInfo` 單獨用會讓網格整個消失，因為邊界盒不再更新，視錐剔除卻照樣拿它去判斷，判成「不在畫面裡」就整批不畫了。%(・∀・(・∀・(・∀・\*)%

而對 thin instance 來說，剔除本來就幫不上忙。一顆網格的邊界盒是它所有實例的聯集，在體素世界裡通常橫跨整座場景，永遠剔不掉，那幾百次測試全都白做。直接說「一律當成看得見」，省下測試也順便修掉消失的風險。

網格生成之後就再也不會動，所以世界矩陣也可以凍結。

```ts
box.freezeWorldMatrix()
box.isPickable = false
```

還有一行很容易忘。

```ts
/**
 * Babylon 預設每一次 pointermove 都會發一條射線去找游標下的網格
 * 這個場景用的是指標鎖定，游標下有什麼完全沒有意義
 */
scene.skipPointerMovePicking = true
```

## 第八步：只畫露得出來的面

繪製呼叫解決了，還有一件事沒解決。

一顆方塊有六個面。幾十萬顆方塊全部丟給 GPU，等於幾百萬個面，而其中絕大多數埋在土裡，誰也看不到。

所以生成矩陣的時候要順便問一句，這一面的鄰居是空的嗎。

```ts
const shouldDrawFace = (
  neighborX: number,
  neighborY: number,
  neighborZ: number,
): boolean => {
  /** 世界邊界外一律剔除，玩家走不出去，看不到外牆 */
  if (
    neighborX < 0 || neighborX >= worldSize
    || neighborZ < 0 || neighborZ >= worldSize
    || neighborY < 0
  ) {
    return false
  }
  if (neighborY >= worldHeight)
    return true

  const neighborId = worldState[coordinateToIndex(neighborX, neighborY, neighborZ)]!
  /** 鄰居是空氣，這一面看得到 */
  if (neighborId === 0)
    return true

  /** 相同方塊相鄰剔除，一整片湖水才不會把內部的面全畫出來 */
  if (neighborId === blockId)
    return false

  /** 鄰居是玻璃、水這類半透明的東西，這一面還是看得到 */
  return !!(blockFlags[neighborId]! & F_TRANSPARENT)
}
```

六個方向都問過之後，如果一個面都畫不出來，這顆方塊直接跳過。

```ts
const hasTop = shouldDrawFace(x, y + 1, z)
const hasBottom = shouldDrawFace(x, y - 1, z)
const hasFront = shouldDrawFace(x, y, z + 1)
const hasBack = shouldDrawFace(x, y, z - 1)
const hasLeft = shouldDrawFace(x - 1, y, z)
const hasRight = shouldDrawFace(x + 1, y, z)

if (!hasTop && !hasBottom && !hasFront && !hasBack && !hasLeft && !hasRight)
  continue
```

關掉剔除，畫面看起來一模一樣，面數卻是四倍多。切開一半就知道那些面躲在哪裡了。%(๑•̀ㅂ•́)و✧%

半透明的鄰居要特別處理。水面底下那格如果照著「鄰居不是空氣就剔掉」去做，隔著水看下去會是一片看得穿的黑。玻璃、冰、樹葉全都是同一件事。

## 第九步：把世界切成區塊

面剔除要掃過整個世界的每一格，一格要問六個鄰居。280 × 280 × 40 大約是三百一十萬格，乘六是一千八百多萬次查詢。

這件事在主執行緒上做，畫面會整個凍住。

路人：「不能直接算嗎？反正只算一次。」
鱈魚：「算得完，只是那幾秒鐘連滑鼠都動不了，讀者會以為當掉了。」

解法是切成區塊，丟給打工仔（Web Worker）。

```ts
export const CHUNK_SIZE = 56
export const CHUNKS_PER_AXIS = WORLD_SIZE / CHUNK_SIZE
export const TOTAL_CHUNKS = CHUNKS_PER_AXIS * CHUNKS_PER_AXIS
```

56 格見方一塊，整個世界切成 25 塊。

區塊刻意給得大。Minespace 的世界不可編輯，重建的粒度完全不重要，切得越碎只是讓每一塊的邊界處理成本越高。

Worker 這端用 `useWebWorkerFn` 包起來就好。

```ts
import { useWebWorkerFn } from '@vueuse/core'

const { workerFn, workerTerminate } = useWebWorkerFn(computeChunkMatricesInWorker)

const results = await workerFn(
  worldState,
  JSON.stringify(chunkList),
  blockFlags,
  lightEmissionList,
  CHUNK_SIZE,
  WORLD_HEIGHT,
  WORLD_SIZE,
)
```

這裡有個限制要記住。`computeChunkMatricesInWorker` 會先序列化，再丟進 Worker 執行，所以它必須完全自包含，不能引用任何外部模組或閉包變數。方塊的旗標、發光等級這些查表資料要一併當參數傳進去。

世界資料本身用 `Uint8Array` 存，一格一個位元組。

```ts
export function coordinateToIndex(x: number, y: number, z: number): number {
  return (x * WORLD_HEIGHT * WORLD_SIZE) + (y * WORLD_SIZE) + z
}
```

三百多萬顆方塊塞在一條連續的記憶體裡，只有三 MB 多，傳給 Worker 也快。

## 第十步：算完之後接成一條

各區塊算好了，接下來是最後一步。

切成區塊的唯一理由是讓計算能分頭跑，算完之後就沒有必要繼續分開。同一種石頭在世界各處若各留各的網格，二十五份網格每一幀主畫面與陰影各畫一次，繪製呼叫又回去了。%(´థ‸థ)%

所以把各區塊的矩陣接成一條，同一種方塊全世界共用一個網格。

```ts
/** 把一串緩衝區接成一條 */
function mergeBufferList(bufferList: Float32Array[] | undefined): Float32Array | null {
  if (!bufferList || bufferList.length === 0)
    return null

  const total = bufferList.reduce((sum, buffer) => sum + buffer.length, 0)
  if (total === 0)
    return null

  const merged = new Float32Array(total)
  let offset = 0
  for (const buffer of bufferList) {
    merged.set(buffer, offset)
    offset += buffer.length
  }

  return merged
}
```

把「接成一條」關掉，繪製呼叫立刻從一變成十六，畫面卻沒有任何差別。打開上色就看得出哪一塊是哪一塊。%ヽ(●\`∀´●)ﾉ%

代價是失去逐區塊的視錐剔除。但這個世界只有 280 格見方、霧又開到 220 格，本來就幾乎整片都在視野內，剔除省不到什麼。

接的時候要等全部到齊再一次接完。每收到一塊就重設一次緩衝區的話，等於把同一份資料上傳好幾遍。

```ts
this.receivedChunkCount++
if (this.receivedChunkCount >= TOTAL_CHUNKS) {
  this.flush()
}
```

## 第十一步：需要時才建網格

還有一個很容易踩到的地方。

直覺的寫法是在建構時就替「所有有貼圖的方塊」建好網格，一種都不漏。但一個區塊裡通常只出現十來種方塊，整個世界一百多種、二十五個區塊，算下來會建出七千三百多個網格，其中八成八一個實例都沒有。

空網格照樣要進每一幀的剔除與排序，白白吃掉大量時間。

改成等 Worker 算完、知道實際用到哪些方塊之後才建。

```ts
private ensureBlockMeshes(blockId: BlockId): void {
  if (this.builtBlockSet.has(blockId))
    return

  this.builtBlockSet.add(blockId)

  const blockDef = BLOCK_DEFS[blockId]
  if (!blockDef || blockDef.isHidden || !blockDef.textures)
    return

  this.initSingleMaterialMesh(blockId, blockDef, blockDef.textures)
}
```

網格數從 7300 降到 880。%( •̀ ω •́ )✧%

## 第十二步：順手把亮度烘進去

最後補一個之後會一直用到的機制。

Babylon 的 thin instance 除了矩陣，還支援每個實例一個顏色，著色器會拿它去乘上貼圖顏色。

```ts
mesh.thinInstanceSetBuffer('color', shadeBuffer, 4, true)
```

方塊的立體感有一半來自環境遮蔽，也就是角落比較暗那件事。這種明暗算一次就定案，而 Worker 反正已經在掃鄰居，順手算出來直接烘進緩衝區，執行期沒有任何額外成本。

上面那個區塊範例的顏色就是走這條路。燈火照亮的範圍也烘在同一份顏色裡，這件事講到晝夜循環時還會再出現一次。

## 世界搭好了

整理一下這一章做完的事。

1. 引擎、場景與算繪迴圈
2. 第一人稱鏡頭
3. 一冷一暖兩盞光，加上一片收住遠方的霧
4. 一顆用最近鄰取樣的像素方塊
5. 面剔除，只留露得出來的那些面
6. 世界切成 25 個區塊丟給打工仔算
7. 矩陣接成一條，一種方塊一個網格

現在畫面上是一整片吃得到光、遠處收在霧裡的方塊地景，幾十萬顆方塊只花掉幾百個繪製呼叫。

地基打好了，接下來每一章就往上疊一個特效。%( ´ ▽ \` )ﾉ%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 引擎固定 WebGL2，canvas 的多重取樣關掉，抗鋸齒交給後製管線
* 半球光的冷暖色溫差讓畫面活了起來，平行光的高光給滿讓材質自己決定
* 一顆一顆畫，繪製呼叫會先壓死你，thin instance 一次畫完幾萬顆
* 靜態緩衝區旗標是最便宜的四倍效能，`doNotSyncBoundingInfo` 與 `alwaysSelectAsActiveMesh` 必須成對出現
* 面剔除只留鄰居是空氣的那些面，範例裡的地形砍完只剩不到四分之一
* 切區塊是為了讓打工仔分頭算，算完就該接成一條

下一章從燈火的光暈開始。方塊的自發光只讓燈自己是亮的，要讓夜裡的石燈籠真的在發光，得在它前面掛一片會跟著鏡頭轉的圓盤。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/02-lamp-glow.md
description: 方塊的自發光只讓燈自己是亮的，光沒有溢出來。想讓夜裡的石燈籠真的在發光，得在它前面掛一片會跟著鏡頭轉的圓盤。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP02：燈火光暈

大家好，我是鱈魚。

這個系列會把 Minespace 裡每一個特效拆開來講，從最單純的原理開始，一路做到專案裡實際跑的版本。%( •̀ ω •́ )✧%

上一章把整個方塊世界蓋了起來，這一章從燈火的光暈開始，因為它不需要寫任何著色器，用現成的網格與材質就做得出來。

## 為什麼需要光暈

方塊世界裡的燈籠，材質上會給它自發光。

```ts
const material = new StandardMaterial('lantern', scene)
material.emissiveColor = new Color3(1, 0.86, 0.62)
```

自發光的意思是「這顆方塊自己會亮」，跟場景裡有沒有燈完全無關。

問題在於自發光只影響這顆方塊自己的像素。方塊的邊界一到，亮度就停在那裡，光完全沒有溢出去。%(´･\_･\`)%

現實裡的燈不是這樣。空氣裡有灰塵與水氣，光走過去會散射，所以我們看到燈的周圍有一團暈；眼睛本身也會散射，湊近看更明顯。

關掉光暈的時候，那顆方塊確實是亮的，卻怎麼看都像一塊會發光的貼紙。加上圓盤之後才有「這裡點著一盞燈」的感覺。%ヽ(●\`∀´●)ﾉ%

路人：「所以光暈就是在燈前面貼一張圖？」
鱈魚：「對，而且是一張永遠正對著你的圖。」

## 第一步：一片永遠面向鏡頭的圓盤

先把最小的版本做出來。

```ts
const halo = MeshBuilder.CreateDisc('halo', { radius: 1.8, tessellation: 32 }, scene)
halo.billboardMode = Mesh.BILLBOARDMODE_ALL
halo.position.copyFrom(lampPosition)
```

`BILLBOARDMODE_ALL` 讓這片網格永遠轉向鏡頭。走到燈的側面、繞到背後，看到的都是同一個正圓。

這裡用圓盤而不是方片，有兩個理由。

第一個是省。光暈的衰減是放射狀的，方片的四個角落在衰減曲線之外，那一圈永遠是白算的片元。

第二個理由更要緊。萬一邊界上還剩下任何一點亮度，方片露出來的會是一個方形；圓盤露出來的至少還是一圈圓。%( ˘•ω•˘ )%

## 第二步：把衰減畫進貼圖

接著要一張中心亮、往外化開的圖。用 `DynamicTexture` 開一張畫布，畫一圈放射狀漸層就好。

```ts
const texture = new DynamicTexture('glow', { width: 128, height: 128 }, scene, false)
const context = texture.getContext()

const center = 64
const gradient = context.createRadialGradient(center, center, 0, center, center, center)
```

這裡有個關鍵，衰減要畫在**顏色**上，不要畫在透明度上。

光暈走的是相加混合，透明度在那條路上不起作用，只有顏色會加到畫面上。所以把該有的透明度先乘進顏色裡，一路收到全黑就對了。黑色加上去等於沒加，暈開的效果自然就出來。

```ts
for (let index = 0; index <= 32; index++) {
  const ratio = index / 32
  const intensity = measureFalloff(ratio)

  gradient.addColorStop(
    ratio,
    `rgb(${255 * intensity}, ${220 * intensity}, ${160 * intensity})`,
  )
}
```

### 衰減曲線挑哪一條

最直覺的寫法是直線，從中心的 1 一路降到邊緣的 0。

```ts
function measureFalloff(ratio: number) {
  return 1 - ratio
}
```

這條線有個麻煩的地方在於它走到底會**突然**變成零。

人眼對亮度的轉折特別敏感，這個現象叫馬赫帶效應（Mach bands）。一條直線斜坡走到底忽然平掉，就算兩側只差一個色階，那道界線照樣看得一清二楚。

換成 `(1 - t²)^n` 這一族曲線就沒有這個問題，它在邊緣的值與斜率同時是零。

```ts
function measureFalloff(ratio: number) {
  const base = Math.max(0, 1 - ratio * ratio)

  return 0.55 * base ** 8 + 0.45 * base ** 3
}
```

兩項相加，次方高的那項是緊實的核心，次方低的那項鋪出長長的尾巴。

亮度拉到 1 以上，左邊那團的邊界就浮出來了，右邊那團則是一路化開到看不見。%(⊙ o ⊙)%

順帶一提，漸層停點要給得夠密。畫布的漸層在停點之間走的是直線，段數太少的話每個停點上都會留下一個折角，而我們要避開的就是這個。三十二段之後，每一段的轉折都小於一個色階。

## 第三步：相加混合

材質這邊有五個設定要一起下。

```ts
const material = new StandardMaterial('halo', scene)

material.diffuseTexture = texture
material.diffuseColor = new Color3(0, 0, 0)
material.emissiveColor = new Color3(1, 1, 1)
material.disableLighting = true

material.alphaMode = Constants.ALPHA_ADD
material.alpha = 0.999
material.disableDepthWrite = true
```

逐項來說。

**貼圖掛在 `diffuseTexture`**，不要掛在 `emissiveTexture`。Babylon 的自發光是「顏色加上貼圖」，掛在自發光上的話，顏色調黑貼圖照樣全亮。關掉光照之後走 diffuse 那條路才是我們要的乘法，自發光的顏色就成了乾淨的亮度乘數。

**`ALPHA_ADD`** 就是相加混合，把顏色直接加到已經畫好的畫面上。光本來就是相加的，兩盞燈照同一個地方會更亮。

**`alpha = 0.999`** 這行看起來很怪。Babylon 要材質走半透明那條路，相加混合才會生效，而 alpha 剛好等於 1 會被歸類成不透明。差那 0.001 就是為了讓它落到正確的那一邊。%(´,,•ω•,,)%

**`disableDepthWrite`** 是說「別留下深度」。暈是空氣裡的一團光，本來就擋不住東西。照常寫深度的話，燈後面的東西會被那片看不見的圓盤整齊地切掉。

路人：「那不寫深度，光暈會不會跑到牆前面？」
鱈魚：「它照樣要通過深度測試，只是不留下自己的深度。牆比它近的話還是擋得住。」

## 第四步：把圓盤挪出方塊之外

現在有個很實際的狀況要處理。

光源的座標是燈籠那顆方塊的中心，而方塊是不透明的、會寫深度。於是整團暈最亮的核心永遠埋在方塊裡面，只剩外圈那幾階近乎全黑的地方露得出來。

解法是每一幀把圓盤沿著「這盞燈往鏡頭看過去」的方向挪出來。

```ts
const toCamera = new Vector3()

scene.onBeforeRenderObservable.add(() => {
  toCamera.copyFrom(camera.position).subtractInPlace(origin)
  const distance = toCamera.length()

  const lift = Math.min(0.95, distance * 0.5)
  halo.position.copyFrom(origin).addInPlace(toCamera.scaleInPlace(lift / distance))
})
```

圓盤本來就永遠面向鏡頭，所以不論從哪個角度走過去，它都剛好浮在那顆方塊的前面。

偏移量給 0.95 是算出來的。一顆方塊的半對角線是 0.866，挪 0.95 剛好從任何角度都繞得出來，而它遠小於一堵牆的厚度，所以「隔著牆看不到燈」這件事仍然成立。%( •̀ ω •́ )✧%

`Math.min` 那一行是給貼很近的時候用的。人臉快要碰到燈的時候照樣挪 0.95，會把圓盤送到鏡頭背後，那盞燈反而在走近的最後一步憑空消失。

## 第五步：亮度隨晝夜走

夜裡的燈該搶眼，白天則要收斂。

```ts
const NIGHT_STRENGTH = 0.85
const DAY_STRENGTH_RATIO = 0.45

const dayRatio = getDayRatio()
const strength = NIGHT_STRENGTH * (1 - dayRatio * (1 - DAY_STRENGTH_RATIO))
```

白天保留四成五，而不是收到零。一盞點著的燈就算在正午也還是點著的。

這裡有個容易忽略的地方，白天要留的比例得給得比直覺高。畫面出去還要過一次 ACES 色調映射，而那條曲線在高處壓縮得很兇。夜裡加 0.17 是一團明顯的光，白天加同樣的 0.17 幾乎整個被壓掉。%(›´ω\`‹ )%

亮度寫在材質的自發光上，所以幾十盞燈只要改兩三個顏色物件。

```ts
for (const entry of materialMap.values()) {
  const [red, green, blue] = entry.color
  entry.material.emissiveColor.set(red * strength, green * strength, blue * strength)
}
```

材質依光色分組就好。整個世界的燈火其實只有兩種顏色，燈籠的暖黃與火的橘。

白天的保留比例拖到零，那盞燈就整個熄了，看起來像它壞掉而不是天亮了。%(´･\_･\`)%

## 第六步：靠近實體時化開

最後補一個細節。

光暈是一片平的圓盤，貼著牆或地面的時候，圓盤與那個平面會交出一條筆直的線。空氣裡的一團光不該有直邊。

處理方式是拿一張場景深度圖，比對這個片元與它背後實體的距離，靠得越近就越淡。

```glsl
float gap = max(sceneDepth - fragmentDepth, 0.0);
float fade = smoothstep(0.0, softDistance, gap);
```

打開除錯檢視，畫面就換成那個 `gap` 本身，越黑代表這個片元離背後的實體越近。光暈與地面交出來的那條線，在深度圖上是一片連續的漸層，所以只要拿它當淡出的依據，直邊自然就散掉了。%( •̀ ω •́ )✧%

這一段要寫進著色器，屬於材質外掛的範圍，之後講到大氣透視時會完整說明那套機制。

## 完整實作

把六個步驟組起來，就是專案裡 `lamp-glow.ts` 在做的事。

流程整理一次。

1. 世界生成完掃一次，收集所有夠亮的光源方塊
2. 依光色建立材質，一種顏色一份
3. 每盞燈給一片圓盤，半徑跟著亮度等級縮放
4. 每一幀把圓盤挪到方塊之外，並依晝夜更新亮度

```ts
const haloList = sourceList.map((source, index) => {
  const size = (source.isFire ? FIRE_SIZE : LAMP_SIZE) * source.level

  const mesh = MeshBuilder.CreateDisc(
    `lamp-halo-${index}`,
    { radius: size / 2, tessellation: 24 },
    scene,
  )
  mesh.material = getMaterial(source.color, source.isAreaLight)
  mesh.billboardMode = Mesh.BILLBOARDMODE_ALL
  mesh.isPickable = false

  return { mesh, origin: new Vector3(source.x, source.y, source.z) }
})
```

岩漿這種一整片的光源要另外處理。一池岩漿上灑十幾顆圓盤，相加混合疊起來會是一塊沒有層次的白，所以單片的濃度要壓到三成半，重疊處剛好回到一團火的亮度。

圓盤的邊數也留了餘裕。世界上每一盞燈都是一片這樣的圓盤，省下來的頂點是乘上燈數的，所以低畫質收到十邊，那時候它本來就糊成一團，看不出是幾邊形。%( ´ ▽ \` )ﾉ%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 自發光只讓方塊自己亮，光要溢出來得靠額外的網格
* 光暈是一片 `BILLBOARDMODE_ALL` 的圓盤，配上相加混合
* 衰減曲線在邊緣的斜率也要是零，`(1 - t²)^n` 這一族剛好
* 圓盤每一幀往鏡頭的方向挪 0.95，才不會埋在自己的方塊裡
* 白天保留四成五的亮度，色調映射會吃掉一大截

下一章講天上那兩顆。太陽與月亮的光暈用的是同一套機制，難處在於它們得跟著整片天色一起變。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/03-sky-glow.md
description: 天上那兩顆是方的。方形的太陽、有月海的月亮、一整片星空，全部共用同一套材質，差別只在那個自發光乘數。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP03：日月光暈

大家好，我是鱈魚。

上一章的燈火光暈是一片面向鏡頭的圓盤加上相加混合。這一章把同一套機制搬到天上，主角換成太陽、月亮與星空。%( •̀ ω •́ )✧%

難處在於它們不能只是掛在那裡。天色一整天都在變，這三樣東西得跟著進場、退場、被染色，而且彼此的時間點還不一樣。

## 天上要掛什麼

先講清楚天空與天體的分工。

天空那一層負責漸層與霞光，那是大氣散射算出來的，整片鋪滿視野。太陽與月亮則是另外掛上去的小東西，各自是一片有貼圖的網格。

路人：「散射不是連太陽都一起算出來了嗎？」
鱈魚：「算得出來，但它會是一顆帶著柔邊的圓球。」

方塊世界的天上不該有圓的東西。所以太陽本體改掛一張正方形的貼圖，該有的圓潤感交給外圈的光暈。%( ˘•ω•˘ )%

整套要做的東西列一下。

1. 方形的太陽，配一圈暖色的暈
2. 方形的月亮，表面有月海與坑，配一圈冷色的暈
3. 一整片星空
4. 一套讓三者隨太陽高度淡入淡出、順便染色的機制

## 第一步：一顆方形的太陽

太陽的貼圖只有十六格見方，而且整片填滿同一個白。

```ts
const size = 16
const texture = new DynamicTexture(
  'sun',
  { width: size, height: size },
  scene,
  false,
  Texture.NEAREST_SAMPLINGMODE,
)

const context = texture.getContext()
context.fillStyle = 'rgb(255, 250, 230)'
context.fillRect(0, 0, size, size)
texture.update()
```

`NEAREST_SAMPLINGMODE` 是這裡的重點。

十六格的圖要拉到畫面上好幾百個像素寬，預設的雙線性取樣會在每個相鄰的紋素之間內插，硬邊立刻化成一圈糊掉的漸層。最近鄰取樣則是直接取最靠近的那一格，放大幾倍都還是方的。

這一顆填滿的白看不出差別，等一下畫月亮就很明顯了。

第五個參數的 `false` 是關掉 mipmap。天體在畫面上永遠是被放大的，縮圖鏈那幾層一輩子用不到。%(´,,•ω•,,)%

## 第二步：天體共用的材質

太陽、月亮、兩圈暈與星空總共五樣東西，材質是同一套。

```ts
function createSkyBodyMaterial(name: string, texture: DynamicTexture, scene: Scene) {
  const material = new StandardMaterial(name, scene)

  material.diffuseTexture = texture
  material.diffuseColor = new Color3(0, 0, 0)
  material.specularColor = new Color3(0, 0, 0)
  material.emissiveColor = new Color3(1, 1, 1)
  material.disableLighting = true
  material.fogEnabled = false
  material.backFaceCulling = false

  material.alphaMode = Constants.ALPHA_ADD
  material.alpha = 0.999
  material.disableDepthWrite = true

  return material
}
```

相加混合、`alpha = 0.999`、不寫深度這三項與上一章的燈火光暈完全一樣，理由也一樣。

`fogEnabled` 要關掉。霧是給地面上的東西用的，天體離鏡頭好幾十格遠，照著霧的公式算會直接被霧色蓋滿。

### 貼圖為什麼掛在 diffuseTexture

這一項最關鍵，也最容易寫錯。

直覺上「會自己發亮的東西」該掛 `emissiveTexture`。但 Babylon 的著色器裡，自發光是這樣算的。

```glsl
vec3 emissiveColor = vEmissiveColor;
#ifdef EMISSIVE
  emissiveColor += texture2D(emissiveSampler, vEmissiveUV).rgb * vEmissiveInfos.y;
#endif
```

顏色與貼圖是**相加**的關係。

於是把顏色調成黑色，貼圖照樣全亮，大白天會有一顆月亮跟一整片星星掛在藍天上；調成白色則是整片再加上一層白，夜裡整個天空被灌成灰的。無論怎麼調，那張貼圖都收不掉。

改掛 `diffuseTexture` 之後，關掉光照，那一行就成了乘法。

```glsl
vec3 finalDiffuse = clamp(diffuseBase * diffuseColor + emissiveColor + vAmbientColor, 0.0, 1.0)
  * baseColor.rgb;
```

`diffuseBase` 因為關了光照是零，`diffuseColor` 也給了黑，`vAmbientColor` 是零，`baseColor.rgb` 正是那張貼圖。整條式子收成 `clamp(自發光) * 貼圖`。

自發光的顏色因此成了乾淨的亮度乘數。淡入淡出、染色，全部都靠它。%ヽ(●\`∀´●)ﾉ%

左邊那顆乘數歸零就整個淡出去了。右邊那顆歸零時貼圖還在原地發亮，拉到 1 反而糊成一片白。%(⊙ o ⊙)%

## 第三步：掛在天上

網格本身要設兩個屬性。

```ts
const disc = MeshBuilder.CreatePlane('sun', { size: 15 }, scene)
disc.material = material
disc.position = SUN_DIRECTION.scale(-110)
disc.infiniteDistance = true
disc.billboardMode = Mesh.BILLBOARDMODE_ALL
disc.isPickable = false
```

**`infiniteDistance`** 讓這片網格每一幀跟著鏡頭平移。人往前走一百格，太陽也往前挪一百格，於是它與鏡頭的相對位置永遠不變。

少了這一項，太陽就成了場景裡固定在某個座標的板子。走近它會變大，走遠會變小，繞過去還能看到它的背面。%(´･\_･\`)%

**`BILLBOARDMODE_ALL`** 讓網格永遠正對鏡頭。抬頭、低頭、轉身，看到的都是同一個正方形。

再補一項。

```ts
disc.alwaysSelectAsActiveMesh = true
```

`infiniteDistance` 的網格是每一幀跟著鏡頭跑的，拿它原本的包圍盒去判斷在不在視野裡會判錯。乾脆讓它跳過剔除那一步。

## 第四步：月亮的臉

月亮與太陽一樣是填滿的方形，差別在表面。

太陽是一片沒有細節的白，月亮則要有月海、坑與明暗。冷色調也與太陽的暖白分得開，同樣是方塊，一眼就認得出誰是誰。

底色先鋪滿。

```ts
context.fillStyle = 'rgb(226, 233, 250)'
context.fillRect(0, 0, size, size)
```

接著是月海，暗一階的幾塊斑。

```ts
context.fillStyle = 'rgb(196, 206, 231)'
const seaList: [number, number, number, number][] = [
  [2, 3, 5, 4],
  [8, 2, 3, 3],
  [10, 7, 4, 5],
  [1, 9, 3, 3],
  [5, 11, 4, 3],
  [12, 1, 2, 2],
]
for (const [x, y, width, height] of seaList) {
  context.fillRect(x, y, width, height)
}
```

這幾組座標刻意不規則，也刻意不對稱。

鱈魚：「來吧，用個雙層迴圈把斑均勻灑滿整張圖！」
路人：「那不就變成雜訊了嗎？」
鱈魚：「說得也是，還是手排吧。」

排得整齊會變成一顆骰子，均勻散開又會變成雜訊。幾塊大的湊在一邊、幾塊小的散在另一邊，那才像月面。%( ´ ▽ \` )ﾉ%

再暗一階的坑落在月海裡面，表面才有第三層深度。

```ts
context.fillStyle = 'rgb(170, 181, 209)'
const craterList: [number, number, number, number][] = [
  [3, 4, 2, 2],
  [11, 9, 2, 2],
  [6, 12, 2, 1],
  [2, 10, 1, 1],
]
```

最後把右下角壓暗一層。

```ts
context.fillStyle = 'rgba(120, 132, 164, 0.32)'
context.fillRect(9, 12, 7, 4)
context.fillRect(13, 8, 3, 4)
```

一整片同亮度的方塊看起來是平的。讓一角暗下去，月亮才有一點球的錯覺，卻又沒有真的把它畫成圓。

順手把取樣模式也放進去了。切成雙線性之後，十六格的圖拉大三十倍，剛才排了半天的月海整個化成一團霧。%(›´ω\`‹ )%

材質那邊給的自發光比太陽暗一階。

```ts
material.emissiveColor = new Color3(0.86, 0.88, 0.95)
```

月亮是反射的光，本來就沒有太陽亮。壓在泛光的門檻以下，月面就維持乾淨的硬邊像素，散開的工作交給外圈那圈暈。

## 第五步：星空

夜裡抬頭只有一片深藍的話，天空會像一塊布。

星空的做法是一張隨機點上星點的貼圖，貼在一個罩住鏡頭的盒子上。

```ts
const size = 512
const texture = new DynamicTexture('star', { width: size, height: size }, scene, true)
const context = texture.getContext()

context.fillStyle = '#000000'
context.fillRect(0, 0, size, size)

const random = createSeededRandom('minespace-star')
for (let index = 0; index < 460; index++) {
  const x = Math.floor(random() * size)
  const y = Math.floor(random() * size)

  const isBright = random() < 0.1
  const brightness = isBright ? 0.85 + random() * 0.15 : 0.25 + random() * 0.45
  const pixelSize = isBright ? 2 : 1

  context.fillStyle = `rgba(255, 252, 242, ${brightness})`
  context.fillRect(x, y, pixelSize, pixelSize)
}
```

底畫成全黑很重要。這張圖走的是相加混合，黑色加上去等於沒加，於是只有星點會浮出來。

一成的星點畫成兩格寬、亮度接近滿格，其餘的又小又暗。疏密有層次，抬頭才不會是一整片均勻的白點。

```ts
const dome = MeshBuilder.CreateBox('star', { size: 240 }, scene)
dome.material = material
dome.infiniteDistance = true
```

盒子六個面共用同一張圖，圖樣其實重複了六次。星點本來就是隨機散布、沒有結構，轉頭時看不出重複。%( ˘•ω•˘ )%

## 第六步：淡入淡出與染色

最後把三樣東西接上時間。

太陽沿著一個傾斜的圓在天球上繞一圈，月亮永遠在正對面。

```ts
const angle = (time - 0.25) * Math.PI * 2
const alongRise = Math.cos(angle)
const alongNoon = Math.sin(angle)

sunPosition.set(
  SUNRISE_AXIS.x * alongRise + NOON_AXIS.x * alongNoon,
  SUNRISE_AXIS.y * alongRise + NOON_AXIS.y * alongNoon,
  SUNRISE_AXIS.z * alongRise + NOON_AXIS.z * alongNoon,
)
moonPosition.copyFrom(sunPosition).scaleInPlace(-1)
```

兩根軸永遠互相垂直——這是路徑維持正圓（而非橢圓）的關鍵，垂直是結構保證的。傾角其實藏在 NOON\_AXIS 自己的仰角裡：它只抬到約 58 度，不是九十度，正午才不會落在正上方。

有了太陽的高度，三者各自的門檻就好訂了。

```ts
const sunHeight = sunPosition.y

sunVisibility = smoothRange(sunHeight, -0.05, 0.06)
moonVisibility = smoothRange(-sunHeight, -0.02, 0.14)
starVisibility = smoothRange(-sunHeight, 0.02, 0.24)
```

`smoothRange` 把一段區間換成兩端斜率為零的平滑曲線，天體進場退場才不會有突然的一跳。

```ts
function smoothRange(value: number, from: number, to: number) {
  const ratio = Math.min(1, Math.max(0, (value - from) / (to - from)))

  return ratio * ratio * (3 - 2 * ratio)
}
```

三個門檻刻意錯開。太陽從地平線下五度就開始亮，月亮要等太陽真的沉下去，星星則要再暗一階才敢出來。這樣黃昏才有那段「太陽剛走、星星還沒到」的空檔。%( •̀ ω •́ )✧%

### 越低的太陽越紅

天空的漸層是大氣散射算出來的，太陽本體卻是一張自己畫的貼圖。

兩邊各走各的，日落時就會有一顆慘白的方塊掛在一片橘紅的天上。所以要拿當下的光色回去染它。

```ts
const horizonRatio = 1 - smoothRange(sunHeight, 0.04, 0.42)
const sunFade = sunVisibility * skyBodyFade

for (const [index, material] of sunMaterialList.entries()) {
  const base = sunBaseList[index]

  material.emissiveColor.set(
    base.r * sunFade,
    base.g * lerp(1, lightColor.g, horizonRatio) * sunFade,
    base.b * lerp(1, lightColor.b, horizonRatio) * sunFade,
  )
}
```

紅色那一項不動，綠與藍往光色靠。太陽越低，`horizonRatio` 越接近 1，扣掉的綠藍越多，那顆方塊就越橘。

月亮與星空不需要染色，只要乘上各自的淡出比例。

```ts
material.emissiveColor.set(base.r * moonFade, base.g * moonFade, base.b * moonFade)
starMaterial.emissiveColor.set(starFade, starFade, starFade)
```

`skyBodyFade` 是另一件事。走到世界邊界時整片天要收乾淨，那個比例會把所有天體一起壓到零。

## 完整實作

把六個步驟組起來，就是專案裡 `use-babylon-scene.ts` 天空那一段在做的事。

流程整理一次。

1. 畫四張貼圖，太陽、月亮各一張，兩圈暈與星空各一張
2. 五份材質全部走 `createSkyBodyMaterial`，貼圖掛 `diffuseTexture`
3. 網格全部開 `infiniteDistance` 與 `BILLBOARDMODE_ALL`
4. 每一幀依太陽高度更新五份材質的自發光，順便把太陽染色

光暈那兩片沿用上一章的 `createGlowTexture`，只換峰值顏色。

```ts
const sunGlowTexture = createGlowTexture('sun-glow', scene, [130, 127, 109])
const moonGlowTexture = createGlowTexture('moon-glow', scene, [103, 112, 128])
```

太陽的暈偏暖，月亮的偏冷，夜裡那點空氣感就是這一圈冷色撐出來的。

### 峰值要壓在本體之下

太陽那圈原本我給的是 `[217, 211, 182]`，跟本體的白只差一點，想說這樣暈才夠亮。

結果太陽整顆不見了。%(´,,•ω•,,)%

鱈魚：「太陽被暈吃掉了，那就把暈也調亮，讓它們一起發光。」
路人：「你這是要把整片天燒了嗎？」
鱈魚：「開玩笑的啦，該調暗的是暈。」

本體跟光暈其實走同一套混合方式，都是相加混合，疊在本來就不暗的天色上。本體疊出一塊固定亮度的方形，光暈疊出一圈由亮到暗的漸層。峰值相當時，兩邊疊加的結果一起衝出顯示能接的上限，clamp 成同一片白，方形的邊界因此消失，跟本體透不透明沒有關係。

收到六成之後，太陽與貼邊的光暈差開二十五階，方形的輪廓回來了，暈的尾巴照樣鋪得出去。%( •̀ ω •́ )✧%

這個階數是在專案正式場景量出來的，那邊開了 ACES 色調映射，曝光給到 1.06、對比 1.05。底下兩支範例沒有套這層後製，同樣的峰值疊上去，太陽一樣會先溶進暈裡，六成之後才重新浮出來，但量到的階數會是另一組數字，沒辦法拿這兩支範例回頭對照「二十五階」這個數字。

暈的網格半徑要對應貼圖的內切圓。

```ts
function createGlowMesh(name: string, planeSize: number, scene: Scene): Mesh {
  const mesh = MeshBuilder.CreateDisc(
    name,
    { radius: planeSize / 2, tessellation: 48 },
    scene,
  )
  mesh.infiniteDistance = true
  mesh.billboardMode = Mesh.BILLBOARDMODE_ALL
  mesh.isPickable = false

  return mesh
}
```

圓盤的 UV 是「邊緣落在貼圖的內切圓上」，而放射狀漸層的外徑正是那個圓。所以半徑取原本方片邊長的一半，暈的大小才不會變。

最後，暈要掛得比本體再遠兩格。

```ts
sunDisc.position = sunDirection.scale(-110)
sunGlow.position = sunDirection.scale(-112)
```

兩片都不寫深度，誰先畫誰後畫由排序決定。差那兩格就是拿來穩住順序的。%(´,,•ω•,,)%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 方塊世界的太陽是方的，硬邊靠 `NEAREST_SAMPLINGMODE` 保住
* 天體的貼圖掛 `diffuseTexture`，自發光的顏色才會是乾淨的乘數
* `infiniteDistance` 讓天體跟著鏡頭平移，`billboardMode` 讓它永遠正對鏡頭
* 月面靠底色、月海、坑、暗角四階疊出來，座標刻意不規則
* 太陽、月亮、星星的門檻要錯開，黃昏才有那段空檔
* 光暈的峰值要壓在本體之下，相加混合疊在天色上很容易蓋過太陽

下一章換到地上，講陰影。從 `ShadowGenerator` 最基本的用法開始，一路做到影子會在物體的根部收緊的接觸硬化。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/04-contact-shadow.md
description: >-
  影子在柱腳要銳利、離遠了才化開，這樣柱子才是站在地上的。從 ShadowGenerator 最基本的用法一路做到 PCSS 與分層陰影。%( •̀ ω •́
  )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP04：接觸硬化陰影

大家好，我是鱈魚。

前兩章都在加光，這一章換個方向，來擋光。%( •̀ ω •́ )✧%

目標很具體。鳥居的柱子立在白沙上，柱腳那一段影子要是銳利的，往上到橫樑那一段才慢慢化開。這樣柱子才真的「站」在地上。

## 影子從哪裡來

陰影貼圖的原理只有一句話。

從光源的位置往場景看一次，把每個方向上「最近的東西有多遠」記下來。之後畫地面的時候，拿這一點到光源的距離跟那張表比對，比表上的數字遠就代表前面有東西擋著。

```text
1. 從光源的角度算繪一次，只留深度 → 陰影貼圖
2. 正常算繪時把每個片元換算到光源空間
3. 比對深度，較遠的就是在影子裡
```

Babylon 把這整套包成 `ShadowGenerator`，建起來只要兩行。

```ts
const shadowGenerator = new ShadowGenerator(1024, sunLight)
shadowGenerator.addShadowCaster(pillar)
```

再幫要接收影子的網格打開開關。

```ts
ground.receiveShadows = true
```

路人：「這樣就好了？」
鱈魚：「畫面上會有影子沒錯，但接下來六個設定每一個都會讓它變得完全不一樣。」

## 第一步：平行光與正交投影

太陽在一億五千萬公里外，射到這座庭園的光線可以當成互相平行。所以光源用 `DirectionalLight`。

```ts
const sunLight = new DirectionalLight('sun', new Vector3(0.58, -0.66, -0.48), scene)
```

平行光沒有「位置」的概念，只有方向。但投影用的鏡頭需要位置，所以要沿著光線的反方向退開一段。

```ts
sunLight.position = new Vector3(-0.58, 0.66, 0.48).scale(SHADOW_LIGHT_DISTANCE)
```

退多遠？退到把場景裡最高的東西整個含進去為止。這個世界最高的岩體大約四十格，光源退九十格綽綽有餘。

接著是投影範圍。平行光走的是正交投影，範圍由四個數字決定。

```ts
sunLight.autoUpdateExtends = false
sunLight.orthoLeft = -SHADOW_HALF_EXTENT
sunLight.orthoRight = SHADOW_HALF_EXTENT
sunLight.orthoTop = SHADOW_HALF_EXTENT
sunLight.orthoBottom = -SHADOW_HALF_EXTENT

sunLight.shadowMinZ = 10
sunLight.shadowMaxZ = SHADOW_LIGHT_DISTANCE + 80
```

`autoUpdateExtends` 要關掉。開著的話 Babylon 每幀會依所有投影者重算範圍，視野裡多一棵樹範圍就跳一次，影子邊緣跟著抖。

關掉之後 `autoCalcShadowZBounds` 也跟著失效，深度範圍得自己給。給法就是光源退開的距離加上世界的高度，前後各留一點餘裕。

投影範圍是這一章最重要的數字。一張 2048 的貼圖攤在八十格見方上，每一格地分到二十一個紋素；攤在三百五十格見方上，每一格只剩十一個。同樣的成本，影子的銳利度差了一倍。

## 第二步：darkness 與那道 clamp

`darkness` 是「影子裡還留多少光」，0 是全擋、1 等於沒有影子。

```ts
shadowGenerator.darkness = 0.05
```

直覺上給 0.5 很合理，影子淡一點才自然。但在這座白沙庭園上，0.5 會讓正午的影子**完全消失**。

原因在 `StandardMaterial` 算漫射的那一行。

```glsl
vec3 finalDiffuse = clamp(diffuseBase * diffuseColor + emissiveColor + vAmbientColor, 0.0, 1.0)
  * baseColor.rgb;
```

那道 `clamp` 是關鍵。

正午的白沙正對太陽，環境光 0.72 加上平行光 1.03，合計 1.75。影子裡擋掉一半也還有 1.24。兩個數字都超過 1，`clamp` 之後一律變成 1.00，亮處與影子完全相同。%(⊙ o ⊙)%

太陽很斜的凌晨黃昏，合計掉到 1 以下，影子就回來了。月光強度只有 0.3，整晚都遠在天花板以下，所以夜裡的投影一直都在。

把天光拉到頂、darkness 給 0.5，白沙上的影子就這樣消失了。改成全擋之後，影子裡只剩環境光的 0.72，與亮處的 1.00 就分得開。

留 0.05 是不讓它硬生生地黑掉。白沙上的影子該是柔和偏藍的一片。%( ˘•ω•˘ )%

## 第三步：bias 與 normalBias

陰影貼圖的深度是有解析度的，一格紋素涵蓋一小塊面積，裡面存的卻只有一個深度值。

於是一個平面自己比對自己的時候，會有一半的取樣點算出「我比表上的數字遠」，判成在影子裡。畫面上就是滿地黑白相間的條紋，術語叫做 shadow acne。

`bias` 是把比對的門檻往前推一點。

```ts
shadowGenerator.bias = 0.0005
```

這個數字是**正規化深度**，要換算成世界單位才有意義。深度範圍三百四十格，0.0005 大約是 0.17 格。

推太多會有另一個症狀。一格高的花草整株落在偏移量以內，投出來的影子被抹掉了，草看起來浮在地上。這叫 peter-panning，因為影子跟本體脫節了。%(´･\_･\`)%

`normalBias` 走的是另一條路。

```ts
shadowGenerator.normalBias = 0.08
```

它沿著法線的反方向把投影者推進去。對付平面的自我遮蔽特別有效，又不會像 `bias` 那樣連帶吃掉貼地的短影子。

這裡有個要注意的地方。這個世界的花草為了讓交叉的兩片立板亮度一致，法線統一改成朝上了，推的方向剛好是往地底下。值一大整株草就沉進地面，影子自然消失。所以 `normalBias` 只留剛好夠壓住條紋的量，其餘交給提高解析度。

把 bias 拉到零，矮牆與地面立刻浮出條紋；拉到底，貼地的小石頭連影子都不見了。投影半徑那條拖桿則是拿來看解析度的，範圍越大邊緣越粗。

## 第四步：PCF 與接觸硬化

直接比對深度只有兩種答案，在影子裡或不在。邊緣因此是一排硬梆梆的階梯。

**PCF**（Percentage Closer Filtering）的做法是在陰影貼圖上取好幾個點各比一次，算出「這一點有幾成在影子裡」。

```ts
shadowGenerator.usePercentageCloserFiltering = true
shadowGenerator.filteringQuality = ShadowGenerator.QUALITY_MEDIUM
```

邊緣因此有了漸層。麻煩的是那個模糊寬度從頭到尾都一樣，柱腳與橫樑的影子軟得一模一樣。

現實裡的影子沒有這回事。太陽有半度的張角，遮蔽物離地面越遠，半影就越寬。柱腳貼著地，影子幾乎是刀切的；橫樑在六格高，影子已經化開了。

**PCSS**（Percentage Closer Soft Shadows）就是在算這件事，Babylon 叫它接觸硬化。

```ts
shadowGenerator.useContactHardeningShadow = true
shadowGenerator.contactHardeningLightSizeUVRatio = 0.05
```

它分成兩步。先在陰影貼圖上搜一圈，找出擋在前面的東西平均離得多遠；再依那段距離決定模糊寬度。近的就硬，遠的就散。

`contactHardeningLightSizeUVRatio` 這個名字很長，意思其實只有一句，光源在陰影貼圖上佔多寬。

換句話說就是「太陽有多大」。給得太大，一根柱子離地兩格影子就散得看不出形狀；給得太小則與硬邊的 PCF 沒有分別。投影範圍是八十格見方時，0.05 換算下來大約是四格的光源直徑，貼著地的那一段仍然銳利，樹冠那一段已經化開。

代價要記著。中等品質是十六次遮蔽搜尋加三十二次比較，大約是 PCF 五乘五的兩倍，高等再翻一倍。這是整套渲染裡最貴的一項，所以最省的畫質等級直接走 PCF。

```ts
function applyShadowFiltering(shadowGenerator: ShadowGenerator, preset: QualityPreset) {
  if (preset.shadowFilter === 'pcf') {
    shadowGenerator.useContactHardeningShadow = false
    shadowGenerator.usePercentageCloserFiltering = true
    shadowGenerator.filteringQuality = SHADOW_FILTER_QUALITY_MAP[preset.shadowFilterQuality]
    return
  }

  shadowGenerator.useContactHardeningShadow = true
  shadowGenerator.contactHardeningLightSizeUVRatio = CONTACT_HARDENING_LIGHT_SIZE
  shadowGenerator.filteringQuality = SHADOW_FILTER_QUALITY_MAP[preset.shadowFilterQuality]
}
```

順帶一提，指數陰影（ESM）那條路在這裡走不通。投影範圍只罩住鏡頭附近，範圍外的地面照樣要決定自己有沒有被遮住。PCF 與接觸硬化的著色器對範圍外會直接回傳「全亮」，指數陰影那條路沒有這個判斷，範圍外會取到邊界的深度值，遠處的沙地於是浮出一圈莫名其妙的陰影。%(›´ω\`‹ )%

## 第五步：投影範圍跟著鏡頭走

投影範圍只有八十格見方，而世界有三百五十格寬。範圍當然要跟著人走。

```ts
light.position.set(
  center.x - forward.x * SHADOW_LIGHT_DISTANCE,
  center.y - forward.y * SHADOW_LIGHT_DISTANCE,
  center.z - forward.z * SHADOW_LIGHT_DISTANCE,
)
```

`center` 直接給鏡頭的位置就行了。走到哪，影子就跟到哪。

麻煩的是連續移動。投影矩陣一直在變，同一道邊緣每一幀落在不同的深度取樣點上，影子邊緣會沿著走路的方向不停爬動，術語叫 shadow shimmering。

解法是把投影中心對齊到貼圖的取樣格。只要人沒有跨過一格取樣格，整張陰影貼圖就是上一幀那一張，一個像素都不會變。

關鍵在於**對齊到哪個座標系**。

鱈魚：「簡單啊，把鏡頭的世界座標 X、Y、Z 各自四捨五入就好了。」
路人：「光源是斜的耶，那樣對得到嗎？」
鱈魚：「⋯⋯對不到。」

陰影貼圖的格子長在光源空間上。世界座標對齊之後投影到光源空間並不會落在整數格上，邊緣照樣每一幀重新取樣。%(´,,•ω•,,)%

正解是先把中心點投影到光源自己的三軸上，在那裡對齊，再轉回世界座標。

```ts
const texelSize = (SHADOW_HALF_EXTENT * 2) / mapSize

forward.copyFrom(light.direction).normalize()
Vector3.CrossToRef(Vector3.UpReadOnly, forward, right)
right.normalize()
Vector3.CrossToRef(forward, right, up)

const alongRight = Math.round(Vector3.Dot(camera.position, right) / texelSize) * texelSize
const alongUp = Math.round(Vector3.Dot(camera.position, up) / texelSize) * texelSize
const alongForward = Math.round(Vector3.Dot(camera.position, forward) / texelSize) * texelSize

center.set(
  right.x * alongRight + up.x * alongUp + forward.x * alongForward,
  right.y * alongRight + up.y * alongUp + forward.y * alongForward,
  right.z * alongRight + up.z * alongUp + forward.z * alongForward,
)
```

三軸的建法必須與 Babylon 算陰影視圖矩陣時完全一致，也就是 `LookAtLH` 以世界的上方為參考，否則對齊的還是另一組格子。

深度那一軸也要對齊。它不影響取樣格的位置，卻影響存進去的深度值。光源沿著光線連續前後移動時，同一個表面每一幀記下來的深度都差一點點，而比較深度是有門檻的。那些剛好卡在門檻上的取樣點會在「被擋住」與「沒被擋住」之間反覆翻面，看起來就是邊緣在閃。

還有一項要注意。`light.direction` 每一幀都在轉，白天從太陽射下、夜裡換成月亮，所以三軸要從光源當下的方向重算。照著固定的方向退開，投影範圍會歪到鏡頭以外的地方去。

## 第六步：分層陰影

單層的做法有個沒辦法解決的問題。

八十格見方罩得住鏡頭附近，而霧要到一百格才開始收。中間那一整圈看得一清二楚的景物完全沒有影子。

把範圍拉大到兩百格呢？那每一格地分到的紋素會少掉六倍多，近處的影子糊成一團。%(´･\_･\`)%

分層陰影（Cascaded Shadow Maps，CSM）就是為此而生。它把鏡頭前方依距離切成幾段，每一段各給一張貼圖。最近那一層罩得小，每格分到的像素最多；越遠的層罩得越大，但那裡的東西本來就小，看不出解析度掉了。

```ts
function createCascadedShadowGenerator(sunLight: DirectionalLight, preset: QualityPreset) {
  const shadowGenerator = new CascadedShadowGenerator(preset.shadowMapSize, sunLight)

  shadowGenerator.numCascades = preset.shadowCascadeCount
  shadowGenerator.stabilizeCascades = true
  shadowGenerator.lambda = 0.8
  shadowGenerator.shadowMaxZ = preset.shadowDistance
  shadowGenerator.autoCalcDepthBounds = false

  return shadowGenerator
}
```

逐項來說。

**`lambda`** 決定每一層的邊界怎麼切。0 是等距切，1 是照對數切，近處的層極窄、遠處的層極寬。0.8 偏向對數那一端，人眼對近處的影子解析度敏感得多，把像素往近處堆是划算的。

**`stabilizeCascades`** 必須開。關著的話每一層的投影範圍會隨鏡頭轉動重新貼合視錐，同一道邊緣每幀落在不同的取樣點上，邊緣會沿著轉頭的方向爬動。上一節花了一整段對付的問題，分層版由它自己處理。

**`autoCalcDepthBounds`** 這裡選擇關掉。它每幀要把深度圖縮到一個像素去讀最小與最大深度，換來的是更貼身的深度範圍。這個場景的高度只有四十格，範圍本來就很緊，那一趟縮圖換不到相稱的品質。

還有一件事要記得。切到分層之後，上一節那整套追蹤鏡頭的程式碼要**整個讓開**。

```ts
scene.onBeforeRenderObservable.add(() => {
  const generator = light.getShadowGenerator()
  if (generator instanceof CascadedShadowGenerator)
    return

  alignShadowCenter(light, camera)
})
```

分層自己會依鏡頭的視錐算出每一層的投影範圍與深度，光源的位置與正交範圍對它完全沒有意義。照著單層的做法去挪動光源，只會讓那幾層的計算基準每幀被推走一次。

影子一路鋪到霧裡，這是這座庭園望出去最明顯的一項改變。%ヽ(●\`∀´●)ﾉ%

## 完整實作

把六個步驟組起來。

```ts
function createShadowGenerator({ scene, existingLight }: {
  scene: Scene;
  existingLight?: DirectionalLight | null;
}) {
  const sunLight = existingLight
    ?? new DirectionalLight(SUN_LIGHT_NAME, SUN_DIRECTION, scene)
  sunLight.intensity = SUN_INTENSITY
  sunLight.diffuse = new Color3(1, 0.93, 0.78)
  sunLight.specular = new Color3(1, 1, 1)

  const { preset } = useGraphicsQuality()
  const isCascaded = preset.value.shadowCascadeCount > 1

  if (!isCascaded) {
    sunLight.autoUpdateExtends = false
    sunLight.orthoLeft = -SHADOW_HALF_EXTENT
    sunLight.orthoRight = SHADOW_HALF_EXTENT
    sunLight.orthoTop = SHADOW_HALF_EXTENT
    sunLight.orthoBottom = -SHADOW_HALF_EXTENT
    sunLight.shadowMinZ = 10
    sunLight.shadowMaxZ = SHADOW_LIGHT_DISTANCE + 80
  }

  const shadowGenerator = isCascaded
    ? createCascadedShadowGenerator(sunLight, preset.value)
    : new ShadowGenerator(preset.value.shadowMapSize, sunLight)

  shadowGenerator.bias = 0.0005
  shadowGenerator.normalBias = 0.08
  shadowGenerator.darkness = 0.05
  applyShadowFiltering(shadowGenerator, preset.value)
  shadowGenerator.frustumEdgeFalloff = 0.2

  return shadowGenerator
}
```

最後那一行是給投影範圍的邊緣用的。範圍外全亮、範圍內有影子，中間沒有過渡就會是一條筆直的分界線。讓陰影在接近邊緣時逐漸淡掉，那條線就融進去了。

換畫質時要整個重建，因為貼圖的邊長與分幾層都是建構時就決定的。重建時把原本那盞光傳進來，場景裡才不會多出第二顆太陽。日夜循環是按名字找光的，多一盞就會有一盞永遠不被更新。

另外，陰影貼圖必須每一幀重畫。

太陽十分鐘才走完一整天，慢得不得了，很容易想省下那一趟幾何重繪。但慢不等於不動。比對用的光源矩陣是每一幀從光源當下的位置與方向重算的，深度資料卻停在上一次重畫的時刻。太陽一移動，兩者就對不起來，整片地面會浮出自我遮蔽的髒污，下一幀重畫後又消失。%(›´ω\`‹ )%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 平行光走正交投影，投影範圍越小影子越銳利，所以範圍要跟著鏡頭走
* `darkness` 要全擋，`StandardMaterial` 那道 clamp 會把「擋一半」整個吃掉
* `bias` 壓自我遮蔽的條紋，`normalBias` 沿法線推開，兩者要一起調
* 接觸硬化依遮蔽物的距離決定模糊寬度，柱腳才站得住
* 投影中心要在**光源空間**對齊取樣格，世界座標對齊沒有用
* 單層只罩得住鏡頭附近，遠處的影子交給分層陰影

下一章講雲影。天上飄著一整片方塊雲，地上卻從早到晚是同一個亮度，這件事得補起來。順便會完整介紹材質外掛這套機制，往後好幾個效果都靠它。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/05-cloud-shadow.md
description: 天上飄著一整片方塊雲，地面卻從早到晚是同一個亮度。要把地上那塊暗補回來，得先認識材質外掛這套機制。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP05：雲影

大家好，我是鱈魚。

上一章把陰影做完了，鳥居與樹都好好地站在白沙上。抬頭看看，天上還飄著一整片方塊雲。%( •̀ ω •́ )✧%

低頭再看一次，地面從早到晚是同一個亮度。

一大片高明度的白沙，太陽角度一直在變，但「這一塊比較暗」這件事從來沒發生過，整座庭園平得像一張紙。這一章就是要把那塊暗補回來。

## 為什麼不能用上一章那套

直覺會想把雲層加進投影者，讓陰影貼圖順手把它畫進去。這條路走不通，原因在數字上。

投影用的鏡頭只沿著光線退開九十格，而雲在一百零四格高。沙面在六格，太陽仰角約三十八度時，遮住腳下這一點的那朵雲位在光線上游一百五十三格處，遠在投影鏡頭的近截面之外。太陽要爬到六十三度以上雲才進得了範圍，而這個世界的太陽從來沒那麼高。%(´･\_･\`)%

就算進得了範圍，也只罩得住鏡頭附近八十格見方那一塊。雲影該鋪滿整片視野，一路延伸到天邊。

路人：「那用光的投影貼圖呢？給太陽掛一張捲動的雲圖。」
鱈魚：「Babylon 的 `projectionTexture` 只有聚光燈有，平行光沒有這個東西。」

所以只剩一條路，在著色器裡自己算。地面上這一點，沿著光線往上走到雲層那一層，看那個位置有沒有雲。

## 第一步：可平鋪的值噪音

先做雲的形狀。

這個世界是循環的，走過邊界時位置會平移一整個世界的寬度。所以雲的圖樣必須剛好是一個世界寬，而且無縫接得起來。跨過邊界的那一瞬間整片天換一副樣子的話，整片天不吃霧氣，破綻藏都藏不住。

一般的連續噪音給不了這件事，simplex 那一類函式沒有週期，接縫上兩側的值對不起來。

值噪音就簡單多了。在稀疏的格點上灑亂數，再內插放大到要的解析度，讀格點時把座標繞回去。

```ts
function createTileableNoise(random: () => number, size: number, pointCount: number) {
  const pointList = Array.from({ length: pointCount * pointCount }, () => random())

  const readPoint = (x: number, z: number) => {
    const wrappedX = ((x % pointCount) + pointCount) % pointCount
    const wrappedZ = ((z % pointCount) + pointCount) % pointCount

    return pointList[wrappedZ * pointCount + wrappedX] ?? 0
  }

  const scale = pointCount / size

  return Array.from({ length: size * size }, (_, index) => {
    const x = (index % size) * scale
    const z = Math.floor(index / size) * scale
    const baseX = Math.floor(x)
    const baseZ = Math.floor(z)
    const ratioX = smoothRatio(x - baseX)
    const ratioZ = smoothRatio(z - baseZ)

    const top = readPoint(baseX, baseZ) * (1 - ratioX)
      + readPoint(baseX + 1, baseZ) * ratioX
    const bottom = readPoint(baseX, baseZ + 1) * (1 - ratioX)
      + readPoint(baseX + 1, baseZ + 1) * ratioX

    return top * (1 - ratioZ) + bottom * ratioZ
  })
}
```

繞回去那三行是整個機制的關鍵。最右邊那一格的右鄰居會是最左邊那一格，所以放大出來的結果本身就是無縫的。

內插的比例先過一次曲線。

```ts
function smoothRatio(ratio: number) {
  return ratio * ratio * (3 - 2 * ratio)
}
```

這條曲線兩端的斜率都是零，接起來的格點之間才看不出直線的痕跡。

把「邊界繞回去」關掉就知道差在哪裡了。每一塊拼接處都會浮出一條看得出來的界線。%(⊙ o ⊙)%

## 第二步：雲的圖樣

有了噪音，接著把它變成布林值的雲格。

兩層噪音疊起來，低頻那一層決定一朵雲多大，高頻那一層負責咬出邊緣的缺口。

```ts
const fieldList = Array.from({ length: size * size }, () => 0)

for (const octave of octaveList) {
  const noiseList = createTileableNoise(random, size, Math.round(size * octave.density))
  for (let index = 0; index < fieldList.length; index++) {
    fieldList[index] = (fieldList[index] ?? 0) + (noiseList[index] ?? 0) * octave.weight
  }
}
```

接著要決定門檻，超過就是雲。

鱈魚：「隨便挑個 0.6 應該就差不多了吧。」
路人：「權重一改分布就跑掉了，你要重新試一輪嗎？」
鱈魚：「⋯⋯好啦，改成排序。」

門檻取分位數，由大到小排完取第 N 名。

```ts
const sortedList = fieldList.slice().sort((a, b) => b - a)
const threshold = sortedList[Math.floor(sortedList.length * coverage)] ?? Infinity

return fieldList.map((value) => value > threshold)
```

這樣說覆蓋幾成就真的是幾成，權重怎麼調都不必回頭改門檻。%( •̀ ω •́ )✧%

圖樣的格數也不能隨便給。

```ts
const patternCount = Math.round(WORLD_SIZE / options.cellSize)
```

格數乘上格寬必須剛好等於世界寬度，理由就是上一節講的循環世界。直接由世界寬度除出來，這件事就不會再對不上。

## 第三步：方塊雲的網格

每一朵雲都是實際的方塊，所以看得到厚度與側面。整片雲做成一個網格，成本只有一次 draw call。

建網格的迴圈很單純，走過每一格，是雲就把六個面加上去。

```ts
for (let x = -halfCount; x < halfCount; x++) {
  for (let z = -halfCount; z < halfCount; z++) {
    if (!isFilled(x, z))
      continue

    const minX = x * options.cellSize
    const maxX = minX + options.cellSize
    const minZ = z * options.cellSize
    const maxZ = minZ + options.cellSize

    addQuad([
      [minX, halfThickness, minZ],
      [minX, halfThickness, maxZ],
      [maxX, halfThickness, maxZ],
      [maxX, halfThickness, minZ],
    ], [0, 1, 0])

    // ⋯ 其餘五個面
  }
}
```

上下兩面一定要畫，側面則要看鄰居。

```ts
if (!isFilled(x - 1, z)) {
  addQuad([
    [minX, halfThickness, minZ],
    [minX, -halfThickness, minZ],
    [minX, -halfThickness, maxZ],
    [minX, halfThickness, maxZ],
  ], [-1, 0, 0])
}
```

這就是方塊世界的面剔除，鄰居是空的才畫那一面。

少了這一步，相鄰兩格之間那兩片牆照樣畫出來。雲是半透明的，隔著雲面看過去就是一格一格的框線交錯在一起，看起來像用積木拼的。%(›´ω\`‹ )%

飄移的做法也很省。

```ts
const driftPeriod = patternCount * options.cellSize
cloudMesh.position.x = (elapsed * options.driftSpeed) % driftPeriod
```

圖樣每 `patternCount` 格重複一次，位移滿一個週期就回到完全相同的排列，直接取餘數歸零，看不出接縫。

## 第四步：材質外掛

現在要動著色器了。

Babylon 的 `StandardMaterial` 是一支寫死的著色器，想在裡面加東西又不想整份重寫的話，走的就是材質外掛（`MaterialPluginBase`）。這一章之後好幾個效果都靠它，所以這一節講完整。

### 一份外掛長什麼樣

```ts
class CloudShadowPlugin extends MaterialPluginBase {
  constructor(material: Material) {
    super(material, 'MinespaceCloudShadow', 210, {}, true, true)
  }

  getClassName(): string {
    return 'CloudShadowPlugin'
  }
}
```

建構子那六個參數依序是掛在哪份材質、外掛名稱、優先權、附加的 defines、是否已啟用、是否一律啟用。

優先權決定多個外掛之間的注入順序。最後那個「一律啟用」給 true 的話，這份外掛沒有開關屬性，掛上去就永遠生效。

### 宣告自己要用的資料

著色器需要的參數與貼圖要先報備。

```ts
getSamplers(samplers: string[]): void {
  samplers.push('cloudShadowSampler')
}

getUniforms() {
  return {
    ubo: [
      { name: 'cloudShadowParam', size: 4, type: 'vec4' },
      { name: 'cloudShadowProjection', size: 4, type: 'vec4' },
    ],
    fragment: `
      uniform vec4 cloudShadowParam;
      uniform vec4 cloudShadowProjection;
    `,
  }
}
```

`ubo` 那個陣列會被塞進材質的統一緩衝區。下面那段 `fragment` 字串只有在不支援統一緩衝區時才派得上用場，支援的時候那串字會靜靜地被丟掉。兩邊都寫，退路才在。

參數盡量湊成 `vec4`。統一緩衝區是按十六位元組對齊的，四個 float 湊一組不浪費空間，也少一次綁定。

### 每一幀把數字寫進去

```ts
bindForSubMesh(uniformBuffer: UniformBuffer): void {
  const state = cloudShadowState

  uniformBuffer.updateFloat4(
    'cloudShadowParam',
    state.strength,
    state.inverseSpan,
    COVER_START,
    COVER_FULL,
  )
  uniformBuffer.updateFloat4(
    'cloudShadowProjection',
    state.slopeX,
    state.slopeZ,
    state.height,
    state.driftX,
  )

  if (patternTexture) {
    uniformBuffer.setTexture('cloudShadowSampler', patternTexture)
  }
}
```

`cloudShadowState` 是所有材質共讀的一份物件。天氣系統每一幀寫一次，下一幀各材質綁定時自己來讀。

這個寫法很重要。這個世界有兩百多份材質，各存一套的話，改一次天氣就得走過每一份。%( ˘•ω•˘ )%

### 把程式碼注進去

`getCustomCode` 回傳的是「注入點 → 程式碼」的對照表，分成兩種。

**第一種是具名的注入點。** Babylon 在著色器裡預留了幾個位置，直接填就好。

```ts
'CUSTOM_FRAGMENT_DEFINITIONS': `
  uniform sampler2D cloudShadowSampler;

  float minespaceCloudCover() {
    // ⋯
  }
`,

'CUSTOM_FRAGMENT_BEFORE_LIGHTS': `
  float minespaceCloudCoverValue = minespaceCloudCover();
`,
```

常用的有 `CUSTOM_FRAGMENT_DEFINITIONS`（放函式與宣告）、`CUSTOM_FRAGMENT_BEFORE_LIGHTS`（光照之前）、`CUSTOM_FRAGMENT_BEFORE_FOG`（霧之前）、`CUSTOM_FRAGMENT_MAIN_END`（整支結束前）。

**第二種是正規式取代。** 鍵值開頭加一個 `!`，剩下的部分當成正規式去比對原本的著色器原始碼，比到的那一段換成你給的字串。

```ts
'!info=computeLighting\\(viewDirectionW,normalW,([^,]+),(diffuse(\\d+)\\.rgb),([^,]+),(diffuse\\3\\.a),glossiness\\);': `
  {
    float cloudShade = 1.0;
    #ifdef DIRLIGHT$3
      cloudShade = 1.0 - cloudShadowParam.x * minespaceCloudCoverValue;
    #endif

    info = computeLighting(viewDirectionW, normalW, $1, $2 * cloudShade, $4 * cloudShade, $5, glossiness);
  }
`,
```

這一招很強，Babylon 內建著色器的任何一行都改得動。三件事要記住。

**一、每個 `$n` 只准出現一次。** Babylon 代換捕獲群組用的是 `newCode.replace('$' + i, match[i])`，字串比對，一個編號只換掉最前面那一個。後面的原封不動留在著色器裡變成 `$` 字元，整支著色器編不過。寧可多切幾個群組，也不要重複用同一個編號。

**二、注入的 GLSL 裡不要寫註解。** Babylon 的前處理器用 `/(#ifdef)|(#else)|(#elif)|(#endif)|(#ifndef)|(#if)/` 掃每一行，沒有錨定行首，也不先把註解拿掉。註解裡提到條件編譯指令的名字，就會被當成真的指令，條件層數從此對不起來，游標一路跑到檔尾，後面整段著色器憑空消失。%(´,,•ω•,,)%

**三、找不到就靜靜地不做事。** 哪天 Babylon 改了那一行的寫法，正規式比不到，畫面會退回沒有雲影的樣子。不會壞掉，但也不會有人跳出來告訴你。

### 什麼時候掛上去

```ts
export function registerCloudShadow(): void {
  if (isRegistered)
    return

  isRegistered = true
  RegisterMaterialPlugin('MinespaceCloudShadow', (material) => {
    if (!(material instanceof StandardMaterial))
      return null

    return new CloudShadowPlugin(material)
  })
}
```

`RegisterMaterialPlugin` 註冊的是一個工廠函式，之後**每一份新建的材質**都會走一次這個函式。

所以它必須在任何材質建立之前呼叫。註冊之前就做好的材質不會回頭補掛，畫面上會出現一部分方塊有雲影、一部分沒有的怪狀況。

單獨掛在某一份材質上也可以，直接 `new` 就行。文章裡的範例走的正是這條路，因為那一頁只想影響自己那兩份材質。

```ts
const material = new StandardMaterial('ground', scene)
const cloudShadowPlugin = new CloudShadowPlugin(material)
```

## 第五步：沿著光線往上查圖樣

機制都有了，來寫真正在算雲影的那幾行。

```glsl
float minespaceCloudCover() {
  if (cloudShadowParam.x <= 0.0) {
    return 0.0;
  }

  vec2 cloudPoint = vPositionW.xz
    - (cloudShadowProjection.z - vPositionW.y) * cloudShadowProjection.xy
    - vec2(cloudShadowProjection.w, 0.0);

  float cover = texture2D(cloudShadowSampler, cloudPoint * cloudShadowParam.y).r;

  return smoothstep(cloudShadowParam.z, cloudShadowParam.w, cover);
}
```

逐行來說。

`cloudShadowProjection.z` 是雲層高度，減掉這一點的高度就是要往上走多遠。乘上 `.xy` 那組斜率，得到水平方向要退多少。斜率是太陽方向的水平分量除以仰角，仰角越低退得越遠。

再扣掉 `.w`，那是雲此刻往 +X 飄了多遠。扣掉之後才回得到原始圖樣裡的位置。

取樣器用重複定址，座標推到圖樣外面會自己繞回來，這與循環世界是同一件事。

最後那個 `smoothstep` 把覆蓋率換成遮蔽比例。兩個門檻決定雲影的邊緣有多硬，拉近是輪廓分明的積雲影，拉遠是糊成一片的高層雲。

### 圖樣要先糊過

著色器讀的那張圖不是原本的布林值。直接雙線性取樣一張全有全無的圖會拉出菱形的塊，得先糊一糊。

```ts
const shadowCount = patternCount * SHADOW_TEXEL_PER_CELL
const coverList = blurPattern(
  upsamplePattern(cellList, patternCount, SHADOW_TEXEL_PER_CELL),
  shadowCount,
)
```

先把每一格雲切成四個紋素，再糊兩輪。

切細這一步是有原因的。一格雲有十四格寬，直接在原本的解析度上糊兩輪等於糊掉二十八格，而一朵雲的影子總共才五十來格寬，半影吃掉了將近一半。切成四份之後每個紋素是三點五格，同樣糊兩輪，半影收到四格。貼圖從 1.6 KB 長到 25 KB，換得回來。

邊緣清楚之後看得出雲的方格輪廓，那是對的。天上那朵雲本來就是方塊堆的，影子理當跟著有稜有角。%ヽ(●\`∀´●)ﾉ%

糊完還要把最濃的一格拉回滿格。

```ts
const peak = Math.max(...valueList)
if (peak <= 0) {
  return valueList
}

return valueList.map((value) => value / peak)
```

三乘三取平均只有在「一朵雲寬到中心那格的鄰居全是雲」時才留得住 1.0，兩輪之後那要五格寬。多數雲不到那麼大，最濃的地方只剩零點七幾。門檻卻是照著 0 到 1 訂的，不正規化的話最深的雲影也永遠踩不到滿格。

拉回去之後，「雲最厚的地方」對上的就是「影子最深的程度」，這兩個數字本來就該是同一件事。

### 圖樣從哪來

雲影拿的就是雲層那份圖樣。

```ts
if (options.castsShadow) {
  setCloudShadowPattern(scene, cellList, patternCount, options.cellSize, options.height)
}
```

在著色器裡另外鋪一張噪聲當然也做得到，那會是另一副雲。地上那塊暗要與頭頂這朵雲是同一朵，何況這個世界是循環的，雲影的週期非得與雲一樣不可。

順帶一提，兩層雲只有一層投影。兩層都投的話，地面會疊出兩種週期的暗塊，糊成看不出形狀的雜訊。

## 第六步：平行光與天光各收多少

最後是兩個數字。

```ts
const SHADE_DEPTH = 0.72
const SKY_SHADE_DEPTH = 0.42
```

平行光收七成二，天光收四成二。

天光那一項一開始很容易寫成零，理由聽起來很篤定，雲擋住的是太陽，關天空什麼事。那句話只對了一半。一朵積雲罩在頭頂時，它擋掉的除了那顆太陽，還有頭頂那一大塊天空，站在雲底下天光確實也少了一截。

而真正逼著這一項長出來的，是色調映射。

這座庭園的地是白沙。正午時平行光加天光加上環境色，線性亮度是 1.75，早就衝過 ACES 的膝點，整片地貼在天花板上。量過的數字擺出來就很清楚（白沙／一般方塊，數字是最深處與無雲處）。

| 平行光 / 天光 | 白沙 | 一般方塊 |
|---|---|---|
| 0.60 / 0.30 | 204..209 | 142..209 |
| 0.72 / 0.42 | 174..209 | 108..209 |
| 0.82 / 0.55 | 130..209 | 75..209 |

第一組在白沙上只差五階，等於看不見。雲影一直都算對了，只是全部被壓在那道天花板底下。第三組又太深，像雲飄過去整個世界暗一下。

所以這兩個數字是照著這座場景的曝光配的。哪天 pipeline 的曝光或日夜的光強調低、畫面離開了膝點，這兩個數字就該一起往回收。%( ˘•ω•˘ )%

高光那一項也要一起乘。少了那一行，一朵雲飄過水鏡池的時候池面照樣閃著一道刺眼的反光，而那道光的來源明明正被遮著。

洞裡那幾盞燈則完全不該跟著暗，所以那一段包在 `#ifdef DIRLIGHT$3` 裡面。整個場景裡只有日月那一盞是平行光，其餘的燈條件編譯整段會被拿掉，`cloudShade` 就是常數 1.0，乘法會被編譯器摺掉，不花錢。

### 太陽太低就收掉

```ts
const SUN_HEIGHT_FADE_START = 0.1
const SUN_HEIGHT_FADE_FULL = 0.32
```

兩個理由。

物理上，太陽貼著地平線時光要橫穿一百多格的空氣才到得了地面，雲影早就散得沒有形狀了。

投影法本身也撐不住。投影點要沿著光線往回推「(雲高 − 腳下高度) ÷ 太陽仰角」，仰角趨近零時那個距離會爆掉，整片地會被一格雲的顏色蓋滿。與其加保護，不如在還看得出形狀時就淡出。

```ts
const sunHeight = -sunDirection.y

if (!isEnabled || sunHeight <= SUN_HEIGHT_FADE_START) {
  cloudShadowState.strength = 0
  return
}

const heightRatio = Math.min(
  1,
  (sunHeight - SUN_HEIGHT_FADE_START) / (SUN_HEIGHT_FADE_FULL - SUN_HEIGHT_FADE_START),
)

cloudShadowState.strength = SHADE_DEPTH * heightRatio * Math.min(1, Math.max(0, clarity))
cloudShadowState.slopeX = sunDirection.x / sunHeight
cloudShadowState.slopeZ = sunDirection.z / sunHeight
```

`clarity` 是「直射陽光還剩幾成」。陰天與洞裡都要收掉，沒有太陽的時候當然也沒有雲影。

## 完整實作

整套的資料流整理一次。

1. `createCloudPattern` 用兩層可平鋪的噪音算出布林值的雲格
2. `createCloudLayer` 拿那份雲格建網格，順手把同一份交給雲影
3. `setCloudShadowPattern` 把雲格切細、糊過、正規化，烘成一張 RawTexture
4. `registerCloudShadow` 在任何材質建立之前掛上外掛
5. 每一幀，天氣系統寫一次 `cloudShadowState`，雲層寫一次 `driftX`
6. 每一份材質綁定時讀那份狀態，著色器沿著光線往上查一次圖樣

整個效果的代價是一次貼圖取樣，換到的是「地上那塊暗確實是頭頂那朵雲的」。%( •̀ ω •́ )✧%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 循環世界的噪音必須可平鋪，值噪音讀格點時繞回去就有了
* 雲的門檻取分位數，說覆蓋幾成就真的是幾成
* 方塊雲照方塊世界的面剔除做，鄰居是空的才畫那一面
* 材質外掛靠 `getUniforms`、`bindForSubMesh`、`getCustomCode` 三件事運作，註冊要趕在所有材質之前
* 正規式注入時每個 `$n` 只准出現一次，注入的 GLSL 裡不要寫註解
* 雲影要連天光一起收，不然整片地會卡在色調映射的天花板上

下一章講葉片透光。陽光從樹葉背面穿過來的時候，那片葉子會亮起來，而這件事同樣是在材質外掛裡做的。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/06-leaf-translucency.md
description: >-
  太陽在樹後面的時候，真實的葉子會透光，整棵樹在逆光裡是發亮的。方塊世界裡的樹卻剛好相反，背光那一側最暗。這一章用一次點積加一次次方把它換過來。%( •̀ ω
  •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP06：葉片透光

大家好，我是鱈魚。

黃昏的時候站在樹下往太陽的方向看，整棵樹會亮起來。葉子的邊緣透出黃綠，樹冠像一盞燈。

方塊世界裡的樹在同一個時刻剛好相反。背對太陽那一側只吃得到環境光，於是逆光時整團最暗，那是它最不像樹的一刻。%(´･\_･\`)%

這一章把它換過來。

## 為什麼葉子在逆光裡會亮

光打到不透明的東西上就停在表面，反彈回來的那一部分就是我們看到的顏色。葉子不一樣，它薄到光可以直接穿過去。

穿的過程裡，光會在葉肉的細胞之間反覆彈跳，出來的時候方向已經散開了，顏色也被葉綠素吃掉一部分。這件事有個名字叫**次表面散射**（subsurface scattering），皮膚、蠟燭、牛奶、玉，全部靠它。

關掉的時候那團樹冠只是一塊深綠。打開之後才有「太陽在它背後」的感覺。%ヽ(●\`∀´●)ﾉ%

鱈魚：「知道了，那就把整棵樹改成半透明！」
路人：「那會變成一叢塑膠花吧！%(´・ω・\`)%」
鱈魚：「開玩笑的啦，只要讓背光那一面多加一道光就好。」

## 正經做法有多貴

真的要算次表面散射，得先知道兩件事。

第一件是光在葉子裡走了多遠。這要量「光從哪一點進去、從哪一點出來」，中間隔著多少材質。

第二件是那段路上被吃掉多少。不同波長被吃掉的比例不同，所以出來的光會偏色。

即時繪圖裡通常拿一張厚度圖來逼近第一件事，那張圖要另外烘。而一顆一格見方的樹葉方塊沒有厚度圖，它只是一顆方塊。%( ˘•ω•˘ )%

所以這裡走另一條路。

## 第一步：用「視線與光線多接近」當近似

觀察一件事，光穿過薄的東西之後，大致還是順著原本的方向繼續走。散射會讓它偏一點，但主要的能量還在原方向上。

那麼「我看得到多少透過來的光」就約等於「我的視線與那道光線有多接近」。

一次點積就量得出來。

```glsl
float forward = max(dot(viewDirection, sunDirection), 0.0);
```

`viewDirection` 是從表面指向眼睛的方向，`sunDirection` 是光線前進的方向。太陽正在樹的另一頭、光直直朝著我走過來的時候，兩者重合，點積是一。

問題是點積給出來的曲線太胖。它要到夾角九十度才歸零，也就是站在樹的側面照樣看得到透光，那不合理。

加一次次方就收得起來。

```glsl
float forward = pow(max(dot(viewDirection, sunDirection), 0.0), 3.5);
```

次方給到 1 的時候整棵樹不管從哪個方向看都在發光，那已經是自發光了。給到 16 則只剩太陽正後方那一點，走過去根本遇不上。%(⊙ o ⊙)%

三點五大約是「視線與光線夾角三十度以內看得出來」，一天裡剛好接得住清晨與黃昏那兩段。

## 第二步：把亮區化開

上一步的式子有個地方要修。

純粹順著光線走的話，亮的只有「視線與光線完全重合」那一條線。玻璃走的正是那條路，光進去多少方向、出來就多少方向。

葉子則已經把光散開了，該亮的是一整片。

做法是把出射方向往法線的反面偏一點。

```glsl
vec3 throughDirection = normalize(sunDirection - surfaceNormal * distortion);
float forward = pow(max(dot(viewDirection, throughDirection), 0.0), 3.5);
```

法線指向葉子的外側，減掉它就是往內側扳。每一片葉子的法線方向都不一樣，於是每一片透出來的方向也各自偏一點，整團樹冠的亮區自然就化開了。

偏移量拉到 0.35 左右，鏡頭繞過太陽背後的那一段路上，整片樹冠會一直亮著。%( •̀ ω •́ )✧%

## 第三步：只加在背光面

現在有件很要緊的事。

正對太陽的那一面已經被直射光照亮了。在那一面上再加一次透光，等於同一道光算了兩遍。

會透光的是背著太陽的那一側，那正是原本最暗的地方。

```glsl
float backFacing = 1.0 - max(dot(surfaceNormal, -sunDirection), 0.0);
```

`-sunDirection` 是「往太陽看過去」的方向。法線與它同向代表這一面朝著太陽，那個點積接近一，減完之後剩下零，透光整個收掉。

關掉這道限制之後，向光側整片過曝。%(›´ω\`‹ )%

路人：「這一行是為了省效能嗎？」
鱈魚：「它擋掉的是一份本來就不該存在的光，效能只是順便。」

## 第四步：乘上葉子自己的顏色

透過來的光帶著葉子本身的顏色。綠葉透出來的是黃綠，楓葉透出來的是橘紅。

要為每一種葉子各調一組顏色嗎？不必。方塊的顏色本來就在貼圖裡，把透光乘上去就對了。

```glsl
color.rgb += leafTranslucency(viewDirectionW, normalW) * baseColor.rgb;
```

`baseColor` 是貼圖取樣出來的結果，這件事有兩層意思。

**一是顏色**。綠葉透綠、楓葉透橘，一份程式碼吃下所有葉子。

**二是遮蔽**。方塊的環境遮蔽與燈火都烘在這個顏色裡，所以樹冠深處那幾片本來就照不到光的葉子，透光也會跟著弱下去。

這裡要乘的是 `baseColor`。Babylon 的 `diffuseColor` 只是材質上那個色票，貼圖的內容進不去，所以葉子的顏色一定要畫進貼圖裡。範例的 `createLeafTexture` 做的就是這件事。

## 第五步：加在霧之前

注入點挑 `CUSTOM_FRAGMENT_BEFORE_FOG`。

```ts
class LeafTranslucencyPlugin extends MaterialPluginBase {
  getCustomCode(shaderType: string) {
    if (shaderType !== 'fragment')
      return null

    return {
      CUSTOM_FRAGMENT_BEFORE_FOG: `
        color.rgb += minespaceLeafTranslucency(viewDirectionW, normalW) * baseColor.rgb;
      `,
    }
  }
}
```

遠處的樹冠與近處的一樣會透光，但那道光也要跟著被霧吃掉。加在霧之後的話，霧裡會浮出一片發亮的葉子，遠山糊成一團而樹葉還亮著。

這個位置還有兩個好處。

一是 `viewDirectionW` 與 `normalW` 到這裡都算好了，直接拿來用。

二是它落在 Babylon 夾住漫射亮度那道 clamp 的外面。逆光的樹冠因此可以真的超過一，後面的色調映射會把它收回畫面裡。

## 第六步：只掛在該掛的材質上

石頭不會透光。

材質外掛的完整機制在 EP05 雲影那一章講過，這裡只用到它的開關。外掛建立時把「預設啟用」那一格傳 `false`，材質工廠依配方再打開。

```ts
class LeafTranslucencyPlugin extends MaterialPluginBase {
  private amount = 0

  constructor(material: Material) {
    /** 倒數第二個參數是「預設不啟用」 */
    super(material, PLUGIN_NAME, 220, {}, true, false)
  }

  setAmount(amount: number): void {
    if (this.amount === amount)
      return

    this.amount = amount
    this._enable(amount > 0)
  }
}
```

`_enable(false)` 的意思是這段程式碼連編都不會編進著色器。石頭、泥土、木頭那兩百多份材質，著色器裡一個字都不會多。

這與「算完再乘上零」差很多。乘零的版本照樣要跑那一次點積、那一次次方、那一次正規化。

打開的那幾份只有樹葉與花草。

```ts
export function setLeafTranslucency(material: StandardMaterial, amount: number): void {
  const plugin = material.pluginManager?.getPlugin<LeafTranslucencyPlugin>(PLUGIN_NAME)
  plugin?.setAmount(amount)
}
```

## 第七步：兩種植物給不一樣的量

樹葉 0.8，花草 1。

```ts
export const LEAF_TRANSLUCENCY = 0.8
export const PLANT_TRANSLUCENCY = 1
```

地上的草與花瓣只有一層細胞那麼薄，逆光時幾乎是半透明的。樹冠那一團則是好幾片葉子疊在一起，光要穿過去會被吃掉更多。

## 第八步：跟著這一刻的陽光走

透光的量與顏色每一幀寫一次，材質綁定時自己來讀。

```ts
export function updateLeafTranslucency(
  sunDirection: Vector3,
  sunColor: Color3,
  strength: number,
  isEnabled = true,
): void {
  const length = Math.hypot(sunDirection.x, sunDirection.y, sunDirection.z) || 1
  sunState.directionX = sunDirection.x / length
  sunState.directionY = sunDirection.y / length
  sunState.directionZ = sunDirection.z / length

  const ratio = isEnabled ? Math.min(1, Math.max(0, strength)) : 0
  sunState.red = sunColor.r * ratio
  sunState.green = sunColor.g * ratio
  sunState.blue = sunColor.b * ratio
}
```

方向一定要正規化過。出射方向是拿它與視線做點積算出來的，長度不等於一的話那個夾角就錯了，而日夜循環寫進來的方向不保證是單位向量。%(´,,•ω•,,)%

`strength` 吃的是「直射陽光還剩幾成」。雲層把太陽打散之後，天空整片還是亮的，但沒有一道明確的方向可以透，葉子也就不再發亮。專案裡直接拿大氣參數的 `specularRatio` 來用，那個值量的正是同一件事。

夜裡換成月光時光源強度掉到很低，葉子跟著暗下去。月光確實透不過一片葉子。

## 完整實作

整章整理成一次。

1. 註冊外掛，預設關著
2. 材質工廠依配方打開樹葉與花草那幾份
3. 每一幀寫入太陽的方向、顏色與此刻的強度
4. 片元著色器裡算出透光量，乘上貼圖顏色，加在霧之前

核心那幾行放在一起是這樣。

```glsl
vec3 minespaceLeafTranslucency(vec3 viewDirection, vec3 surfaceNormal) {
  float backFacing = 1.0 - max(dot(surfaceNormal, -leafTranslucencySun.xyz), 0.0);

  vec3 throughDirection = normalize(
    leafTranslucencySun.xyz - surfaceNormal * leafTranslucencyColor.a
  );
  float forward = pow(
    max(dot(viewDirection, throughDirection), 0.0),
    leafTranslucencySun.w
  );

  return leafTranslucencyColor.rgb * forward * backFacing;
}
```

一次點積、一次次方、一次正規化，換來一天裡最好看的兩段。%♪( ◜ω◝و(و%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 葉子在逆光裡會亮是次表面散射，而算它要知道厚度，方塊沒有那張圖
* 光穿過薄物之後大致順著原方向走，所以「視線與光線多接近」就約等於透出來多少
* 點積太胖，加一次次方收緊；出射方向往法線反面偏一點，亮區才化得開
* 只加在背光面，向光面已經被直射光照亮了
* 乘上 `baseColor`，綠葉透綠、楓葉透橘，順便吃到方塊的環境遮蔽
* 加在霧之前，遠處的透光才會跟著被霧收掉

下一章講大氣透視。內建的霧只有一個顏色，那條路走到底會出現一種現實裡不存在的畫面。%( •̀ ω •́ )✧%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/07-aerial-perspective.md
description: >-
  場景內建的霧只有一個顏色，走到底會出現遠山比天空還淡這種現實裡不存在的畫面。這一章用正規式把 Babylon 內建的霧那一行整段換掉。%( •̀ ω •́
  )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP07：大氣透視

大家好，我是鱈魚。

引擎附的霧只要三行就打開了。

```ts
scene.fogMode = Scene.FOGMODE_LINEAR
scene.fogStart = 20
scene.fogEnd = 220
scene.fogColor = new Color3(0.9, 0.92, 0.94)
```

很好用，遠處的東西會慢慢化開，世界的邊界也順便藏起來了。

只是它只有一個顏色。%(´･\_･\`)%

## 一個顏色會出什麼事

不管多遠，一律往那個顏色收。走到底會出現一種現實裡不存在的畫面，遠處的山比它背後的天空還要淡。

霧的終點拉近之後，最遠那道山脊整片浮在天空前面，像貼上去的一張紙。天不可能比空氣本身更暗，這件事眼睛認得出來，只是說不上來哪裡怪。%(⊙ o ⊙)%

鱈魚：「那把霧色調暗一點就好啦。」
路人：「那近處的東西不就整片發灰？%(´・ω・\`)%」
鱈魚：「說得也是，一個顏色本來就不夠用。」

## 真實的空氣是分段的

站在山上往遠處看，眼前那一段是透明的，中間那一段偏藍，再遠才近乎白。

藍色來自大氣的散射。空氣分子把短波長的光散得比長波長的多，所以隔著一段空氣看東西，那段空氣自己會發藍。天空之所以是藍的，也是同一件事。

白色則是散射早已飽和之後的結果。空氣再厚，該散的都散完了，剩下的就是一片均勻的亮。

所以霧要拆成兩層。中距離往當下的天色偏，遠距離才收進霧色。

## 第一步：找到 Babylon 那一行

霧的實作在 `fogFragment` 這段 include 裡，總共四行。

```glsl
#ifdef FOG
float fog = CalcFogFactor();
color.rgb = mix(vFogColor, color.rgb, fog);
#endif
```

`fog` 是「還剩幾成原本的顏色」，一代表完全清楚，零代表整片讓霧蓋掉。那一行就是拿它去混。

我們要換掉的正是這一行。

路人：「材質外掛不是只能在幾個指定的位置插程式碼嗎？」
鱈魚：「還有另一種寫法，它可以把既有的程式碼整段換掉。」

## 第二步：`!` 開頭的注入點

`getCustomCode` 回傳的是一張表，鍵是注入點的名字。名字以驚嘆號開頭的時候，Babylon 會把後面那一段當成**正規式**，掃過整份著色器，把每一處符合的地方換成你給的程式碼。

```ts
class AerialPerspectivePlugin extends MaterialPluginBase {
  getCustomCode(shaderType: string) {
    if (shaderType !== 'fragment')
      return null

    return {
      '!color\\.rgb\\s*=\\s*mix\\(\\s*vFogColor\\s*,\\s*color\\.rgb\\s*,\\s*fog\\s*\\);': `
        // 換上去的新程式碼
      `,
    }
  }
}
```

有幾件事要知道。

**空白要自己吞掉。** 著色器進到 `ShaderStore` 之前會壓縮過，實際上那一行長這樣。

```glsl
color.rgb=mix(vFogColor,color.rgb,fog);
```

寫死成有空白的版本會對不上，所以每個縫都補一個 `\s*`。

**替換發生在 include 展開之後。** Babylon 走的是 `processCodeAfterIncludes` 那條路，所以霧那一行雖然是 include 進來的，正規式照樣找得到。

**旗標可以自己指定。** 預設帶 `g`，也就是整份著色器裡每一處都換。想指定別的就寫成 `!gi!...`，想完全不帶旗標就用 `!!` 開頭。

**捕獲群組的 `$n` 每個只准出現一次。** Babylon 代換捕獲群組用的是 `newCode.replace('$' + i, match[i])`，那是字串比對，同一個編號只換掉最前面那一個。後面那些會原封不動留在著色器裡變成 `$` 字元，整支著色器編不過。寧可多切幾個群組，也不要重複用同一個編號。

**注入的那段 GLSL 裡不要寫註解。** Babylon 的前處理器掃條件編譯指令時沒有先把註解拿掉，註解裡只要提到 `#ifdef` 這幾個字，它就當成真的指令，條件層數從此對不起來，後面整段著色器會憑空消失。要解釋就寫在外面的 TypeScript 註解裡。%(›´ω\`‹ )%

還有一個很重要的性質。哪天 Babylon 改了那一行的寫法，正規式找不到就靜靜地不做事，畫面退回原本的單色霧。它不會壞掉，只會少一個效果。

```mermaid
---
title: 材質建立時，這個注入點在做什麼
---
flowchart TD
    A[材質建立] --> B[外掛掃過壓縮後的 fragment 原始碼]
    B --> C{符合那段正規式？}
    C -- 符合 --> D["整段換成兩層混色的 GLSL"]
    C -- 不符合 --> E["原本那一行 mix 照舊<br/>退回單色霧"]
```

## 第三步：兩層混色

換上去的程式碼是這樣。

```glsl
float aerialAmount = clamp(1.0 - fog, 0.0, 1.0);
color.rgb = mix(color.rgb, mix(aerialMidColor, vFogColor, aerialAmount), aerialAmount);
```

`aerialAmount` 就是「這裡被空氣蓋掉幾成」，剛好是 `fog` 的反面。

裡面那個 `mix` 先調出這一段空氣該是什麼顏色。蓋得少的地方靠近 `aerialMidColor`（帶著天色的那一層），蓋得多的地方靠近 `vFogColor`（遠處那片白）。

外面那個 `mix` 再拿同一個量決定蓋多濃。

同一個變數用兩次，一次選顏色、一次定濃度，兩層空氣就出來了。%( •̀ ω •́ )✧%

偏移量為零時與內建的單色霧完全相同。這一點很有用，除錯開關要關掉這個效果的時候，著色器裡那段程式碼已經編進去拆不掉了，但把中距離的空氣色設成與霧色相同，兩層混出來的結果就跟原本那一行一模一樣。

## 第四步：中距離的顏色從哪裡來

不必另外調。日夜循環已經算好中空的天色了，直接拿來用。

```ts
export function updateAerialAir(
  fogColor: Color3,
  skyMidColor: Color3,
  clearRatio: number,
): void {
  const strength = MID_AIR_STRENGTH * Math.min(1, Math.max(0, clearRatio))

  airState.red = fogColor.r + (skyMidColor.r - fogColor.r) * strength
  airState.green = fogColor.g + (skyMidColor.g - fogColor.g) * strength
  airState.blue = fogColor.b + (skyMidColor.b - fogColor.b) * strength
}
```

中午是藍、清晨是丁香紫、黃昏是橘，這一層跟著天色一起走，一行色票都不必寫。%ヽ(●\`∀´●)ﾉ%

`MID_AIR_STRENGTH` 給 0.75。一往上就會出現「遠山比它背後的天空還白」那種假，七成五剛好讓內圈明顯帶藍，外圈仍然收在霧色裡。

`clearRatio` 是洞裡與雨中要收掉的量。岩壁之間沒有天空可以散射，下雨時天本來就已經是一片鉛灰，兩種情況都該退回純霧色。

## 第五步：高度霧

空氣是有重量的，濁的那一層積在低處。從山上往下看，山谷總是比山脊模糊。

做法是拿這個片元的高度去算一個額外的濃度。

```glsl
float aerialLow = clamp((aerialGround.x - vPositionW.y) * aerialGround.y, 0.0, 1.0);
aerialAmount = clamp(aerialAmount * (1.0 + aerialLow * aerialGround.z), 0.0, 1.0);
```

`aerialGround` 三個分量分別是濁氣的頂、往下加厚的速度，以及要濃多少。

這裡有個關鍵，濃度走的是**乘法**。

近處的東西 `aerialAmount` 本來就接近零，乘上任何數字還是零，完全不受影響。只有本來就有點遠的東西才會再糊一點。改成直接相加的話，腳邊的方塊會憑空罩上一層灰。%( ˘•ω•˘ )%

往下加厚的速度給十二格的倒數。從樹冠到地面是一段連續的漸變，不會出現一條水平的界線。

濁氣的頂抓在沙面上十格。木座、鳥居與矮松都泡在裡面，樹冠與山頭則露在上面，那正是清晨從高處往下看時整片庭園浮在一層薄濁上的樣子。

## 第六步：晨昏加濃

太陽貼著地平線的那段時間，貼地的水氣最看得出來。逆光穿過一層薄霧是晨昏辨識度最高的畫面之一。

```ts
const GROUND_HAZE_BOOST_BASE = 0.6
const GROUND_HAZE_BOOST_DAWN_DUSK = 1.15

function computeGroundHazeBoost(sunHeight: number): number {
  const ratio = (sunHeight - GROUND_HAZE_LOW_SUN_HEIGHT)
    / (GROUND_HAZE_HIGH_SUN_HEIGHT - GROUND_HAZE_LOW_SUN_HEIGHT)
  const clamped = Math.min(1, Math.max(0, ratio))
  const smooth = clamped * clamped * (3 - 2 * clamped)

  return GROUND_HAZE_BOOST_DAWN_DUSK
    + (GROUND_HAZE_BOOST_BASE - GROUND_HAZE_BOOST_DAWN_DUSK) * smooth
}
```

太陽的仰角直接拿平行光的方向來量，`-sunLight.direction.y` 就是。低於 0.12 時濃度給滿，高過 0.55 收回基準值，中間那段用 `smoothstep` 的多項式接起來，太陽爬升的過程才不會看出一道分界。

## 第七步：掛在哪些材質上

這個外掛沒有任何開關屬性，所以建立時就要一律啟用。

```ts
class AerialPerspectivePlugin extends MaterialPluginBase {
  constructor(material: Material) {
    /** 第六個參數是「一律啟用」 */
    super(material, 'MinespaceAerialPerspective', 200, {}, true, true)
  }
}
```

註冊要在任何材質建立之前。外掛是靠「材質建立」這個事件自己接上去的，晚了的話先建好的那些材質收不到。

```ts
export function registerAerialPerspective(): void {
  RegisterMaterialPlugin('MinespaceAerialPerspective', (material) => {
    if (!(material instanceof StandardMaterial))
      return null

    return new AerialPerspectivePlugin(material)
  })
}
```

工廠只認 `StandardMaterial`。天空與雲用的是自己寫的著色器材質，裡面沒有那條霧的程式碼可以換，也本來就不該有霧。

至於吃霧的那兩百多份材質，注入的整段都在 `#ifdef FOG` 裡面，所以關掉霧的材質一個字都不會被動到。

## 完整實作

整章串起來。

1. 註冊外掛，在任何材質建立之前
2. 每一幀由天氣與日夜循環寫入霧色、中空天色與太陽仰角
3. 材質綁定時把兩個 uniform 送進去
4. 片元著色器裡，正規式換掉的那一段依距離與高度算出兩層空氣

換上去的四行放在一起是這樣。

```glsl
float aerialAmount = clamp(1.0 - fog, 0.0, 1.0);
float aerialLow = clamp((aerialGround.x - vPositionW.y) * aerialGround.y, 0.0, 1.0);
aerialAmount = clamp(aerialAmount * (1.0 + aerialLow * aerialGround.z), 0.0, 1.0);
color.rgb = mix(color.rgb, mix(aerialMidColor, vFogColor, aerialAmount), aerialAmount);
```

四行 GLSL 換掉一行，遠山有了層次，山谷積起了濁氣。%♪( ◜ω◝و(و%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 內建的霧只有一個顏色，走到底會讓遠處比天空還淡
* 真實的空氣近透明、中段偏藍、遠處近白，所以霧要拆成兩層
* `getCustomCode` 的鍵以 `!` 開頭就是正規式，能把 Babylon 既有的程式碼整段換掉
* 那一行被壓縮過，記得每個縫都補 `\s*`；`$n` 每個編號只准用一次
* 找不到就靜靜地不做事，畫面退回單色霧，不會壞掉
* 高度霧的濃度是倍率，腳邊的方塊才不會憑空罩上一層灰

下一章講水面高光。整套渲染裡只有一個通道能突破亮度上限，正午的池面能不能真的刺眼，全靠它。%( •̀ ω •́ )✧%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/08-water-glint.md
description: >-
  靜水最有說服力的東西是太陽反在上面那一道光。這一章從 Blinn-Phong 講到法線擾動，順便講整套渲染裡唯一能突破亮度上限的那個通道。%( •̀ ω
  •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP08：水面高光

大家好，我是鱈魚。

一池不會動的水要怎麼看起來像水？

答案是太陽反在上面那一道光。人走一步，那個亮點就跟著移一步，比任何波紋貼圖都有效。%( •̀ ω •́ )✧%

這一章把那道光從頭做起來。

## 高光是怎麼算出來的

表面反射光分兩種。

一種是**漫射**（diffuse），光打進表面之後往四面八方彈出去，所以不管站在哪裡看，那塊地的顏色都一樣。磚牆、泥土、木頭都走這條路。

另一種是**高光**（specular），光幾乎照著入射角反出去，所以只有站在特定角度才看得到。鏡子、金屬、水面走的是這一條。

Babylon 的 `StandardMaterial` 用的是 Blinn-Phong 模型，式子很短。

```glsl
vec3 halfDirection = normalize(lightDirection + viewDirection);
float specular = pow(max(dot(normal, halfDirection), 0.0), glossiness);
```

`halfDirection` 是「往光源看」與「往眼睛看」這兩個方向的中間值。表面的法線剛好指在那個中間值上的時候，光就正好反進眼睛裡，那個點積等於一。

法線稍微歪一點，點積就掉下來。掉得多快由後面那個次方決定。

路人：「為什麼要繞一個中間值？直接算反射方向不行嗎？」
鱈魚：「行，那是原版的 Phong。半向量省掉一次反射計算，而且能量分布更接近真實的表面。」

## 第一步：specularColor 與 specularPower

材質上有兩個旋鈕。

**`specularColor`** 是這個表面有多亮，也就是反射率。它會乘在算好的高光上，決定那道光的強度與顏色。

**`specularPower`** 就是上面式子裡那個次方，決定高光收得多緊。

指數給到個位數，那道反光散成一整片，看起來像磨砂玻璃。給到一百六才收得緊，才是水面該有的一小點。%(⊙ o ⊙)%

專案裡水的配方是這樣。

```ts
material.specularColor = new Color3(0.8, 0.82, 0.85)
material.specularPower = 160
```

藍綠通道略高一點，反出來的那道光帶著一點水色。

## 第二步：光源端給滿，材質決定亮度

高光的最終亮度是兩個值相乘，光源的 `specular` 乘上材質的 `specularColor`。

這裡有個很容易踩到的配置。光源端給 0.1、材質端給 0.08，相乘之後只剩 0.008，整個場景實質上沒有高光這回事。%(´･\_･\`)%

乾方塊看不出差別，石頭本來就是霧面的。麻煩的是水面，材質那一端已經沒有空間可以往上調。

兩個旋鈕控制同一件事的時候，要留一個當作真正的旋鈕。所以光源這一端給滿。

```ts
sunLight.specular = new Color3(1, 1, 1)
```

「這個表面有多亮」交還給各自的材質。

```ts
/** 乾方塊，幾乎是霧面 */
material.specularColor = new Color3(0.02, 0.02, 0.02)
/** 淋濕的表面 */
material.specularColor = new Color3(0.42, 0.42, 0.42)
/** 水面 */
material.specularColor = new Color3(0.8, 0.82, 0.85)
```

光源這一端只有一個值，收掉它等於整個場景一起沒有高光。這個性質後面講天氣時會派上用場。

高光也會跟著光源強度縮放，所以夜裡換成月光的時候，池面只留下很淡的一道。

## 高光是唯一能突破亮度上限的通道

這一節是整章最要緊的地方。

看一下 Babylon 把顏色組起來的那幾行。

```glsl
vec3 finalDiffuse = clamp(diffuseBase * diffuseColor + emissiveColor + vAmbientColor, 0.0, 1.0) * baseColor.rgb;
vec3 finalSpecular = specularBase * specularColor;

vec4 color = vec4(finalDiffuse * baseAmbientColor + finalSpecular, alpha);
```

漫射與自發光在乘上貼圖**之前**就先夾在 1.0 了。光再強，那一項也只能亮到貼圖本身的顏色，之後就停在那裡。

高光則加在那道 clamp 外面。

左邊那顆亮到一個程度就不動了，右邊那顆一路亮下去。%(⊙ o ⊙)%

所以正午的池面真的會刺眼。整套渲染裡能做到這件事的只有高光這一條路，濕掉的木板與水面能不能反出一道真正的光，全靠它。

鱈魚：「那把漫射那一行的 clamp 拿掉不就好了！」
路人：「你要改人家引擎的著色器喔？%(´・ω・\`)%」
鱈魚：「說得也是，而且拿掉之後陰影裡的地面也會一起爆掉。」

## 第三步：讓法線碎掉

現在的水面已經有一道很有說服力的反光了，但整池水從岸邊到湖心是同一個樣子。

水的法線統一改成朝上（材質配方裡的 `flatShaded`），整池水因此是一個光學上的平面。平面上只反得出一個點。

真正的水面是有起伏的，每一小塊的法線都朝著不同方向，於是太陽在上面碎成一整片會閃的亮片。

要重現這件事，該動的是法線。

沒有畫上任何一個白點。那一整片閃爍是同一道陽光落在被推歪的法線上算出來的。%ヽ(●\`∀´●)ﾉ%

做法是先定一個高度場，再從高度場取斜率。

```glsl
float waterHeight(vec2 point, float time) {
  return sin(point.x * 1.7 + time * 1.3) * 0.5
    + sin(point.y * 2.3 - time * 1.1) * 0.35
    + sin((point.x + point.y) * 3.1 + time * 1.9) * 0.22
    + sin((point.x - point.y * 1.4) * 4.7 - time * 2.3) * 0.14;
}
```

四道波的波長刻意不成整數倍，相位永遠對不齊，圖樣不會在幾秒後整片重複。速度也各自不同，長浪會慢慢追過短浪，疊出一段特別亮的再錯開。

斜率用差分取。

```glsl
float step = 0.08;
float center = waterHeight(point, time);
float slopeX = waterHeight(point + vec2(step, 0.0), time) - center;
float slopeZ = waterHeight(point + vec2(0.0, step), time) - center;

normalW = normalize(normalW + vec3(-slopeX, 0.0, -slopeZ) * strength);
```

高度往哪邊上升，法線就往哪邊的反面倒，所以兩個斜率都取負號。

注入點挑 `CUSTOM_FRAGMENT_BEFORE_LIGHTS`。這個位置 `normalW` 已經算好、還沒有人用過它，換掉之後漫射與高光吃到的都是新的那一根。

## 第四步：對齊到像素格

這套美術是十六格見方的像素畫，貼圖用最近鄰、法線用最近鄰、刻意不開 FXAA。

一片平滑起伏的水面疊上去，全場就只有它帶著平滑曲線，像在一幅點陣圖上蓋了一層向量圖形。

把取樣座標先對齊到貼圖的像素格再送進高度場就好。

```glsl
vec2 point = worldPosition.xz * scale;
point = floor(point * 16.0) / 16.0;
```

同一個貼圖像素裡的每一個片元共用同一根法線，於是那些亮片是一格一格的，與方塊表面上那些方方正正的像素同一個節奏。%( ˘•ω•˘ )%

範例裡那個「對齊像素格」的開關就是這一行的開關，關掉之後亮片會化成平滑的一團。

## 第五步：陰天要把高光單獨收掉

Babylon 只用 `intensity` 同時縮放漫射與高光，但這兩件事在天氣上的反應完全不同。

雲層把太陽打散之後，天空整片還是亮的，漫射只是變柔。高光需要一顆又小又亮的太陽，而雲最先抹掉的就是那一顆。

所以要分開收。

```ts
sunLight.intensity = atmosphere.lightIntensity * weatherRatio * (1 - caveRatio)

const specular = atmosphere.specularRatio * (1 - caveRatio)
sunLight.specular.set(specular, specular, specular)
```

把「高光另外收」關掉之後，暴雨裡的水面照樣閃著一道刺眼的反光，而抬頭連太陽在哪都看不出來。%(›´ω\`‹ )%

每種天氣各有一個 `specularRatio`。

```ts
CLEAR_ATMOSPHERE.specularRatio = 1
SWAMP_ATMOSPHERE.specularRatio = 0.45
RAIN_ATMOSPHERE.specularRatio = 0.05
SNOW_ATMOSPHERE.specularRatio = 0.04
```

這個值好用的地方在於它量的正是「天上有沒有一顆又小又亮的太陽」，所以雲影與葉片透光也拿它來當強度。三件事要的是同一個東西。%( •̀ ω •́ )✧%

## 完整實作

整章整理成一次。

1. 光源端的 `specular` 給滿，讓材質自己決定要反射多少
2. 水的材質給 `specularColor` 0.8、`specularPower` 160
3. 水面的法線統一朝上，整池水先變成一個光學上的平面
4. 材質外掛在光照之前把法線推歪，那道光自己碎成一片
5. 取樣座標對齊到十六分之一格，亮片跟著像素走
6. 天氣與洞穴用 `specularRatio` 把高光單獨收掉

最後補一件實作上的事。

水的最上層另外開了一份材質（理由留到下一章講），但那一份與水底下那些滿格的水必須是同一種水。高光的強度、透明度與混合方式差一點，岸邊就會看到一條界線。

所以這兩件事抽成同一個函式，兩份材質都走它。

```ts
class VoxelRenderer {
  private applyLiquidLook(material: StandardMaterial, blockDef: BlockDef): void {
    if (blockDef.isLiquid) {
      material.specularColor = new Color3(0.8, 0.82, 0.85)
      material.specularPower = 160
      this.liquidMaterialList.push(material)
    }

    if (blockDef.alpha !== undefined && blockDef.alpha < 1) {
      material.alpha = blockDef.alpha
      material.transparencyMode = Material.MATERIAL_ALPHABLEND
      material.backFaceCulling = true
      material.needDepthPrePass = true
    }
  }
}
```

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 高光走 Blinn-Phong，法線與半向量的點積再加一次次方
* `specularColor` 管有多亮，`specularPower` 管收得多緊，水面是 0.8 配 160
* 光源端給滿，材質那一端才有空間分辨乾方塊、濕木板與水面
* 漫射在乘上貼圖之前就夾在 1.0，高光加在那道 clamp 外面，正午的池面才真的會刺眼
* 讓法線隨波起伏，高光自己會碎成一片，畫面上不必灑任何白點
* 取樣座標對齊到像素格，亮片才與方塊表面同一個節奏
* 陰天要用 `specularRatio` 把高光單獨收掉，`intensity` 一起縮是不夠的

下一章講岸線與漣漪。拿一張場景深度圖比對「我背後那塊實體有多近」，岸邊、睡蓮的莖、棧道的柱子，交界處全部自己浮出一圈白沫，而這件事完全不必知道那裡有什麼東西。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/09-water-shoreline.md
description: 湖心與腳邊的淺灘長得一模一樣，那片水就只是一塊藍色的蓋子。想讓水在岸邊自己浮出一圈白沫，得先自己再畫一趟深度。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP09：岸線與漣漪

大家好，我是鱈魚。

一片水最容易露餡的地方在岸邊。

方塊世界的水面是一整片同樣的藍，湖心與腳邊的淺灘長得一模一樣。少了那圈白沫，那片水在畫面上只是一塊藍色的半透明蓋子。%(´･\_･\`)%

這一章做兩件事。一是岸線，水淺的地方浮出一圈白沫；二是漣漪，雨滴與腳步各打出一圈往外擴的環。

第一件事得先知道「水底下那塊沙地離我多遠」，所以從深度圖講起。

## 第一步：畫一張場景深度圖

深度圖是一張與畫面同樣大小的圖，每個像素存著「這個方向上最近的實體有多遠」。

近的白、遠的黑，一整片地形被壓成一張灰階圖。%(⊙ o ⊙)%

範例裡有個地方值得停一下。那片水完全不在圖上。

深度算繪預設只畫不透明與 alpha test 的網格，半透明的東西整批跳過。水面因此不在自己這張圖上，它問到的才會是水底下那塊沙地。

### 為什麼要自己再畫一趟

鱈魚：「畫面本來就有一份深度緩衝區，直接拿來讀不就好了？」
路人：「WebGL 拿不到那個東西。」
鱈魚：「⋯⋯好吧，那就自己再畫一趟。」

這是這套機制最貴的地方。整個場景要多跑一次，雖然深度著色器只寫一個數字、幾乎不吃填充率，但繪製呼叫是實打實的一倍。

Babylon 這邊開一張圖只要一行。

```ts
const depthRenderer = scene.enableDepthRenderer(
  camera,
  false,
  false,
  Texture.NEAREST_SAMPLINGMODE,
  /** 直接存視空間的 Z */
  true,
)
```

最後那個參數要打開。另一條路存的是正規化過的深度，要用就得把近遠平面再乘回去，而那組數字散在相機上，日後有人動了 `maxZ`，這裡會靜靜地算錯。存原始的 Z 值，比對時一個字都不必換算。%( ˘•ω•˘ )%

取樣模式挑最近鄰也是有原因的。浮點深度圖的雙線性取樣不是每張顯卡都支援，而我們只要那一格的值。

### 沒有東西的地方要當成無限遠

開完之後還有一行不能漏。

```ts
depthRenderer.clearColor = new Color4(camera.maxZ, 0, 0, 1)
```

存視空間 Z 時的預設底色是零，零的意思是「實體就貼在鏡頭上」。天空那一片於是變成全世界最近的一層，望向湖心的水會整片判成貼著岸。改成遠平面之後，那一片回到乾淨的水。

## 第二步：把深度差換成岸線

有了深度圖，岸線的原理短得像一句話。

拿水面這個片元自己的深度，減掉深度圖裡同一個位置的深度，差多少就是「光要穿過多少水才碰到底」。差得少的地方就是淺灘。

先在頂點那邊把自己的深度算出來。

```glsl
varying float vShoreViewZ;

// CUSTOM_VERTEX_MAIN_END
vShoreViewZ = (view * worldPos).z;
```

這一行與 Babylon 深度著色器裡的那一行完全相同，兩邊比的才會是同一個量。

片段那邊照著螢幕座標去查圖。

```glsl
float sceneZ = texture2D(shoreDepthSampler, gl_FragCoord.xy * shoreScreen.xy).r;
float gap = max(sceneZ - vShoreViewZ, 0.0);
```

`shoreScreen.xy` 是畫面寬高的倒數。深度圖與場景畫在同一個尺寸上，所以像素座標除以畫面大小就是取樣座標，每一幀重讀一次，換視窗大小時才不會錯開。

`max` 那一刀是給水面前方的東西用的。有東西站在鏡頭與水之間時，兩者相減會是負的，夾成零之後那一段就只是滿版的白沫。

接著把距離換成濃度。

```glsl
float line = 1.0 - smoothstep(0.0, SHORELINE_WIDTH, gap);
float halo = exp(-gap / SHORELINE_GLOW_WIDTH) * 0.55;
float foam = max(line, halo) * strength;
```

兩項相加是不行的，那會讓亮線的核心過曝。取最大值之後，`line` 負責岸邊那道實心的亮帶，`halo` 鋪出外面那圈慢慢化開的暈。暈的寬度給到亮線的一倍多，白沫才有散開的樣子。

石頭與水的交界也自己浮出一圈。這是整套做法最好用的地方，睡蓮的莖、棧道的柱子、從水裡站起來的枯木，全部不必登記，深度差自己會算。%ヽ(●\`∀´●)ﾉ%

### 白沫平視過去會拉長

把範例的鏡頭壓到接近水平，同一片淺灘的白沫會整片變寬。

這是對的。

深度差量的是「沿著視線」的距離，垂直的水深只是它在正上方看的特例。斜著看過去，同樣一格深的水，光要走的路變長了，白沫自然跟著攤開。

路人：「所以低頭看是一圈細線，平視是一整片？」
鱈魚：「對，光本來就是這樣穿過水的。」

## 第三步：白沫要量化

現在的白沫是一圈平滑的漸層。

這件事在別的專案裡很好，在這裡不行。整套美術是十六格見方的像素畫，貼圖用最近鄰、法線用最近鄰、連 FXAA 都刻意關掉，全場就只有那圈漸層沒有階梯。

一行就收得回來。

```glsl
foam = floor(foam * STEP_COUNT) / STEP_COUNT;
```

階數給零是原本的漸層，切成三四階之後白沫是一階一階退開的，與貼圖上的像素同一個節奏。階數再往上加就慢慢退回漸層。%( ´ ▽ \` )ﾉ%

### 白沫疊在哪一層

顏色要疊在漫射色上，別等到最後的成品那一層。

```glsl
// CUSTOM_FRAGMENT_UPDATE_DIFFUSE
baseColor.rgb = mix(baseColor.rgb, FOAM_COLOR, foam);
```

這個位置的顏色還沒乘上光照，所以白沫會跟著天色走。夜裡的沫是暗的、黃昏是橘的、霧裡是灰的。疊在成品上的話，那圈白會在半夜的湖面上自己發亮。

順帶一提，那個 `FOAM_COLOR` 看起來超出範圍。

```ts
const FOAM_COLOR: [number, number, number] = [1.7, 1.25, 1.05]
```

紅與綠都拉高是刻意的。這個顏色會乘上光照，而水的材質色調把光照先染成了藍，給純白出來會是一圈淡藍色的沫。把紅與綠先乘回去，落到畫面上才是白的。著色器最後有 clamp，不會過曝。

最後補一刀透明度。

```glsl
// CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR
color.a = min(1.0, color.a + foam * 0.4);
```

水本身是七成二的半透明，白沫跟著半透明的話，水底的沙石會從那圈沫裡透出來。那看起來就像一池漂白過的水。%(´,,•ω•,,)%

## 第四步：漣漪是幾個槽位

岸線是靜態的，水面還缺會動的東西。

漣漪的資料結構很單純，一組固定長度的槽位，每一圈四個數字。

```ts
const RIPPLE_SLOT_COUNT = 8

/** 每四個數字一圈：世界 X、世界 Z、已經過幾秒、濃度。濃度為零代表空槽 */
const rippleList = new Float32Array(RIPPLE_SLOT_COUNT * 4)
```

丟一圈進去的時候，先找空槽，全滿就擠掉最老的那一圈。

```ts
export function emitWaterRipple(x: number, z: number, strength: number): void {
  let slotIndex = 0
  let oldestAge = -1

  for (let index = 0; index < RIPPLE_SLOT_COUNT; index++) {
    const offset = index * 4
    if (rippleList[offset + 3] === 0) {
      slotIndex = offset
      break
    }

    const age = rippleList[offset + 2]!
    if (age > oldestAge) {
      oldestAge = age
      slotIndex = offset
    }
  }

  rippleList[slotIndex] = x
  rippleList[slotIndex + 1] = z
  rippleList[slotIndex + 2] = 0
  rippleList[slotIndex + 3] = strength
}
```

擠掉最老的那一圈很安全，它本來就快淡光了。

每一幀替所有槽位加上年齡，過了壽命就把位子讓出來。

```ts
const age = rippleList[offset + 2]! + deltaSecond
rippleList[offset + 2] = age
if (age > RIPPLE_LIFETIME) {
  rippleList[offset + 3] = 0
}
```

著色器那邊每個片元走一遍八個槽位。

```glsl
float ripple = 0.0;

for (int rippleIndex = 0; rippleIndex < 8; rippleIndex++) {
  vec4 rippleEvent = rippleList[rippleIndex];
  if (rippleEvent.w <= 0.0) continue;

  float rippleDistance = length(vPositionW.xz - rippleEvent.xy);
  float ringRadius = rippleEvent.z * RIPPLE_SPEED;
  float ring = 1.0 - smoothstep(0.0, RIPPLE_WIDTH, abs(rippleDistance - ringRadius));

  ripple = max(ripple, ring * rippleEvent.w * exp(-rippleEvent.z * RIPPLE_DECAY));
}
```

`abs(距離 - 半徑)` 是「離這一圈的環有多遠」，所以環是空心的，半徑則單純隨時間長大。

這裡同樣取最大值。兩圈相加會在交會處爆出一塊白，而水面上兩道波交會時本來就只是「比較亮的那一道」。

## 第五步：誰來打圈

有了 `emitWaterRipple`，剩下的是決定誰去呼叫它。

**雨**每一幀會算出二十幾個落點，站在池邊時那些落點多半都在水上。照單全收的話，八個槽位每一幀被覆寫一遍，每一圈都停在剛出生的那個半徑上，畫面看到的是一池不會擴散的白點。

隔三分之一秒放一圈就好。配上兩秒多的壽命，水面上同時有六七圈大小不同的環。

```ts
if (waterState.time - lastRainRippleTime < RAIN_RIPPLE_INTERVAL)
  return false

const level = getWaterLevel(waterMap, x, z)
if (level === null || Math.abs(impactY - level) > SURFACE_TOLERANCE)
  return false
```

第二刀擋掉的是「水面上方有東西」。池上的屋頂、棧道與樹冠都會擋雨，那些地方的雨滴不該讓底下的水起波。

**腳步**看的則是距離，走多遠才濺一次。

```ts
const wadeDistance = Math.hypot(
  camera.position.x - lastWadeX,
  camera.position.z - lastWadeZ,
)
if (wadeDistance < WADE_RIPPLE_DISTANCE)
  return
```

站著不動的人不該在自己腳邊持續打出一圈一圈的水波。%(´,,•ω•,,)%

判斷條件也要看高度，而且看的是「腳踩在水面附近」。整個人沉下去之後水面在頭頂，那時該有的是頭頂的波紋。

```ts
const footY = camera.position.y - PLAYER_EYE_HEIGHT
const level = getWaterLevel(waterMap, camera.position.x, camera.position.z)
if (level === null || footY > level + 0.2 || footY < level - 1.4)
  return
```

兩條路各自把關兩件事，整理起來是同一種邏輯，先問「夠不夠格觸發」，再問「位置對不對」。

```mermaid
---
title: 這個事件要不要打一圈漣漪
---
flowchart TD
    A[雨滴 / 腳步事件] --> B{是雨滴嗎？}
    B -- 是 --> C{距上一圈超過間隔？}
    C -- 否 --> X1["跳過<br/>不然雨會把八槽洗成靜止的白點"]
    C -- 是 --> D{落點在水面上？}
    D -- 否 --> X2["跳過<br/>屋簷、棧道底下不該起波"]
    D -- 是 --> E["打一圈"]
    B -- 否，是腳步 --> F{移動夠遠？}
    F -- 否 --> X3["跳過<br/>站著不動不該一直冒圈"]
    F -- 是 --> G{腳踩在水面附近？}
    G -- 否 --> X4["跳過<br/>沉進水裡該換頭頂起波"]
    G -- 是 --> H["打一圈"]
```

## 完整實作

專案裡的 `water-surface.ts` 是一個 `MaterialPluginBase`，只掛在水面那一層的材質上。材質外掛的完整機制見 EP05，這裡只用它的四個切入點。

1. `getSamplers` 報上深度圖的取樣器名字
2. `getUniforms` 開一組 `vec4`，時間、強弱、螢幕大小與漣漪陣列都在裡面
3. `bindForSubMesh` 每一幀把 `waterState` 的內容寫進去
4. `getCustomCode` 注入頂點與片段那幾段

有一件事跟這篇的示範不一樣。專案裡的水面是一顆一顆的方塊，六個面都在，而岸線與漣漪都照世界的 XZ 座標算，畫到側面上會變成一條條垂直的抹痕。

法線幫不上忙，水是 flat shaded 的，六個面的法線都被改成朝上。所以改看頂點的區域座標。

```glsl
// 頂點
vWaterTopFace = step(TOP_FACE_THRESHOLD, position.y);

// 片段
if (vWaterTopFace > 0.9) {
  // 岸線與漣漪都在這裡面
}
```

門檻要算出來，別寫死。水面那一層的網格是一顆矮掉八分之一格的方塊，建好之後又往下烘了半個落差，而那個落差是與碰撞共用的常數。寫死的話，哪天有人調了它，這裡會靜靜地失效，失效的樣子是「岸線整片不見」，不會有任何錯誤訊息。%(›´ω\`‹ )%

最後是畫質。低畫質整套收掉，強度歸零之後著色器裡那幾段全部跳過，等於這個外掛不存在。

```ts
const isEnabled = devToggle.waterShoreline && preset.value.waterShoreline
waterState.shorelineStrength = isEnabled ? SHORELINE_STRENGTH : 0
```

深度預繪那一趟在低畫質本來就沒開，沒有圖可以查，岸線自然也留不住。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* WebGL 讀不到主畫面的深度緩衝區，深度圖只能自己再畫一趟
* 深度算繪不畫半透明的東西，水面因此問得到自己背後那塊沙地
* 深度差是沿著視線量的，同一片淺灘平視過去會整片拉長
* 白沫要量化成幾階，才跟得上像素風的節奏
* 漣漪是幾個固定的槽位，滿了就擠掉最老的那一圈

下一章講水底下那張晃動的亮網。陽光穿過皺起來的水面會被聚成一條條光斑打在水底，而那個效果只需要一張細胞紋，加上一張烘好的水位圖。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/10-water-caustics.md
description: 少了水底那張晃動的亮網，一片水在視覺上就只剩「藍色的半透明蓋子」這一個作用。而重現它只要一張細胞紋，加上一張烘好的水位圖。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP10：水下焦散

大家好，我是鱈魚。

上一章讓水在岸邊浮出一圈白沫，這一章要處理水底下那張晃動的亮網。

夏天在泳池邊看過的那個東西就是焦散。水面被風吹皺，每一小片水面都是一面歪掉的透鏡，陽光穿過去之後被聚成一條條光斑打在池底，那些光斑還會隨著水面起伏慢慢流動。%( ˘•ω•˘ )%

少了它，水底的沙石與水面以外的沙石是同一個樣子，那片水在視覺上只剩「藍色的半透明蓋子」這一個作用。

## 老實算是不可能的

焦散的正解要追光線。從太陽出發、在水面折射、打到水底、統計每一塊池底收到多少能量。那是離線算圖在做的事，片段著色器沒有那個預算。

鱈魚：「那就每一幀把水面的法線算出來，一條一條光線折射過去。」
路人：「你在一個方塊世界裡要追幾百萬條光線？」
鱈魚：「⋯⋯好啦，畫一張看起來很像的圖就好。」

「看起來很像」在這裡很好定義。焦散的圖樣是一張細細的亮網，網眼的形狀不規則，網線會隨時間蠕動。

有一種雜訊天生就長這樣。

## 第一步：Voronoi 與它的邊界

Voronoi 的做法是在平面上灑一堆種子點，每一個位置去問「離我最近的種子有多遠」。畫出來是一片碗接著一片碗，種子的位置是碗底。

問題在於我們要的是網線，也就是碗與碗相接的那一圈。而那個相接處在數值上並不特別，只是「最近距離」這條曲線上的一道轉折，挑不出一條線來。

訣竅是再算一次同樣的東西，只是把 `min` 換成平滑的 `min`。

```glsl
float waterSmoothMin(float left, float right, float blend) {
  float weight = max(blend - abs(left - right), 0.0) / blend;
  return min(left, right) - weight * weight * weight * blend / 6.0;
}
```

平滑版在細胞中心與原版完全一致，那裡只有一個碗，沒得平滑。到了兩碗相接處才被抹掉一角。

兩者相減，中心是零、邊界是正值，一條沿著細胞邊界的脊線就浮出來了。%(⊙ o ⊙)%

```glsl
float waterCellEdge(vec2 point, float time, float blend) {
  vec2 cell = floor(point);
  vec2 offset = fract(point);

  float nearest = 8.0;
  float smoothNearest = 8.0;

  for (int y = -1; y <= 1; y++) {
    for (int x = -1; x <= 1; x++) {
      vec2 neighbor = vec2(float(x), float(y));
      float cellDistance = length(
        neighbor + waterCellPoint(waterHash2(cell + neighbor), time) - offset
      );

      nearest = min(nearest, cellDistance);
      smoothNearest = waterSmoothMin(smoothNearest, cellDistance, blend);
    }
  }

  return nearest - smoothNearest;
}
```

平滑係數給零的時候整張圖是全黑，因為那時兩趟算的是同一件事，相減當然什麼都不剩。%(´,,•ω•,,)%

### 網怎麼會動

動的是細胞中心。

```glsl
vec2 waterCellPoint(vec2 seed, float time) {
  return 0.5 + 0.5 * sin(time + 6.2831 * seed);
}
```

每個中心在自己的格子裡繞圈，繞的相位由那個格子的雜湊決定，所以每個中心各走各的。中心一動，邊界就跟著蠕動。

這裡有個地方不能省。兩趟取樣必須用同一個式子算中心，否則相減出來的只會是一片雜訊。

### 三乘三的鄰居

迴圈跑的是自己這一格加上周圍八格，共九個中心。

一個位置的最近種子有可能落在隔壁格，所以九格是最小的安全範圍。九個中心、兩趟、每趟一次雜湊，一個片元十八次雜湊，這是整個效果最貴的地方。

### 座標要先量化

還有一刀不能忘。

```glsl
vec2 waterQuantize(vec2 worldPoint) {
  return floor(worldPoint * 16.0) / 16.0;
}
```

這套美術是十六格見方的像素畫，貼圖用最近鄰、法線用最近鄰、刻意不開 FXAA。一張平滑的細胞圖疊上去，全場就只有它帶著平滑曲線，像在一幅點陣圖上蓋了一層向量圖形。

把世界座標先對齊到貼圖的像素格再送進雜湊，出來的紋路就只能沿著格線轉折，與方塊表面那些方方正正的像素同一個節奏。

## 第二步：兩層疊起來才會流動

單層的網已經會蠕動，看久了卻不太對勁。整片水底是同一個尺度、同一個節奏，比較像一張在抖的網子。

真正的水面是好幾組不同尺度的波疊在一起，所以再疊一層。第二層的細胞小一點、速度快一點，時間給負的讓它往反方向走。

```glsl
float caustic = smoothstep(threshold - softness, threshold + softness, edge);

float edgeSecond = waterCellEdge(point * scale * 0.63, time * speed * -1.7, blend);
caustic = max(caustic, smoothstep(threshold - softness, threshold + softness, edgeSecond) * ratio);
```

這裡取最大值。兩層的亮線相加會在交會處爆出一塊白，而焦散的亮線交會時本來就只是「比較亮的那一條」。

門檻與柔邊也在這裡定。柔邊要給得很窄，焦散是一張細細的亮網，門檻放低會變成水底整片發光。%(›´ω\`‹ )%

```ts
const CAUSTIC_EDGE_THRESHOLD = 0.075
const CAUSTIC_EDGE_SOFTNESS = 0.02
```

網的疏密則抓一格約一個半的細胞。焦散比水面本身的紋路細，粗了會變成水底鋪著幾塊亮斑。

## 第三步：只在水面下才算

現在有一張很好看的亮網，而它鋪滿整個世界。

原因很單純，片段著色器問不到世界資料，它只知道自己在哪裡。「這個點在不在水下」對它來說是個無解的問題。

所以答案要先算好送進去。

### 一張烘好的水位圖

地形生成之後水就不再變動，所以整份資料掃一次烘成一張貼圖就好，每一格柱一個像素。

通道這樣分。

* **R、G**：水面高度，兩個位元組湊十六位元
* **B**：這一格有沒有水
* **A**：留給別的用途

高度要用兩個通道。只用一個通道的話一階是四分之一格，而深度門檻本身只有 0.05 格，那個精度會讓岸邊一階一階地跳。

```ts
const encoded = Math.round(level / WATER_LEVEL_ENCODE_RANGE * 65535)

data[texel] = encoded >> 8
data[texel + 1] = encoded & 255
data[texel + 2] = 255
data[texel + 3] = 255
```

`WATER_LEVEL_ENCODE_RANGE` 給六十四。世界只有四十格高，除以六十四一定落在零到一之間，而六十四是二的冪，除下去不會有浮點數的零頭。

藍色通道也不能省。用「高度是零」代表沒有水是不行的，世界的最底層本來就在零附近。

取樣一律用最近鄰。相鄰兩格若一格有水一格沒有，內插出來的是「半有水」，藍色通道會落在門檻附近，岸邊那一圈於是時有時無；而高度是拆成兩個位元組存的，內插高位元組更是毫無意義。%(´థ‸థ)%

```ts
const texture = RawTexture.CreateRGBATexture(
  createWaterLevelTextureData(waterMap),
  WORLD_SIZE,
  WORLD_SIZE,
  scene,
  false,
  false,
  Texture.NEAREST_SAMPLINGMODE,
)
```

### 著色器那邊查一次

```glsl
vec4 causticWater = texture2D(causticWaterSampler, vPositionW.xz * INV_WORLD_SIZE);

if (causticWater.b > 0.5) {
  float causticSurfaceY = (causticWater.r * 65280.0 + causticWater.g * 255.0)
    / 65535.0 * 64.0;
  float causticDepth = causticSurfaceY - vPositionW.y;
  ...
}
```

`65280` 是 `255 * 256`，把高位元組乘回它該有的位置。

關掉水位圖之後，判斷條件只剩「比水面矮」，於是水池旁邊那個乾的坑整片亮起了水底才有的網。%(・∀・)%

### 三層條件由外往內收

細胞紋很貴，所以最貴的那一段要排在最裡面。

```glsl
if (causticParam.y > 0.0 && vPositionW.y < causticParam.w) {
  // 查圖

  if (causticWater.b > 0.5) {
    // 算深度

    if (causticDepth > 0.05) {
      // 細胞紋在這裡
    }
  }
}
```

第一道刷掉沒開這個效果的時候。第二道刷掉「比全世界最高的水面還高」的片元，那是整個世界絕大多數的片元，而且不必查圖。撐到第三道才真的去問那張水位圖。

```mermaid
---
title: 這個片元要不要算細胞紋
---
flowchart TD
    A[這個片元] --> B{有開效果，<br/>且沒比最高水位高？}
    B -- 否 --> Z1[跳過<br/>不查任何資料]
    B -- 是 --> C[查水位圖]
    C --> D{這一格有水？}
    D -- 否 --> Z2[跳過<br/>沒算細胞紋]
    D -- 是 --> E{比水面深 0.05 以上？}
    E -- 否 --> Z3[跳過<br/>沒算細胞紋]
    E -- 是 --> F[算細胞紋<br/>疊上焦散]
```

```ts
causticState.maxSurfaceY = getMaxWaterLevel(waterMap) + 0.5
```

那個 0.5 是留給水面本身那一格的餘裕，門檻剛好卡在水面上會讓最淺的一層閃掉。

## 第四步：深了要淡，夜裡要收

兩項收尾，兩項都只有一行。

光穿過水會被吸收，所以深處的光斑本來就淡。

```glsl
baseColor.rgb += CAUSTIC_COLOR * caustic * exp(-causticDepth * falloff) * strength;
```

指數衰減這一項還順手解掉一個實務問題。淺灘的焦散最清楚，而淺灘正是人看得最清楚的地方。

日照則是把整張網一起收放。

```ts
const dayRatio = Math.min(1, Math.max(0, getDayRatio()))
const isEnabled = devToggle.waterCaustics && preset.value.waterCaustics && dayRatio > 0.01

causticState.strength = isEnabled ? CAUSTIC_STRENGTH * dayRatio : 0
```

陽光穿過水才有焦散，夜裡沒有東西可以聚。強度歸零之後著色器第一道條件就出去了，等於這個外掛不存在。

顏色挑偏青的白。

```ts
const CAUSTIC_COLOR: [number, number, number] = [0.72, 0.95, 1]
```

這一段是加法而不是混合，所以不必像上一章的白沫那樣先把水的藍色調乘回去。而它疊在漫射色上，所以亮網一樣會跟著天色走，那是第二道保險。

## 完整實作

專案裡的 `water-caustics.ts` 同樣是 `MaterialPluginBase`（機制見 EP05），由材質工廠替每一份方塊材質掛上。

有一份材質是例外，液體自己不掛。

水面那一份已經有上一章的 `water-surface`，而兩者共用同一段細胞紋的 GLSL。同時掛上去等於把同一個函式宣告兩次，整份材質會編譯失敗，而失敗的樣子是那一批方塊整個不畫。%(・\_・;)%

低畫質也整套不做。一片元十八次雜湊，而這個外掛掛在每一份方塊材質上，就算多數片元在前兩道條件就出去了，那一檔本來就在跟填充率計較。

順帶一提，水位圖那張是共用的。潮汐磯的湧浪要問「這一格離岸邊多遠」，焦散要問「我頭頂上有沒有水」，兩者都是逐格柱、都不會變、都是同一份掃描結果，各烘一張只是把三十萬個位元組算兩遍再存兩份。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 焦散是陽光穿過皺起來的水面聚成的亮網，追光線是不可能的，用細胞紋近似就好
* Voronoi 的邊界要靠「平滑的 min 減掉一般的 min」才挑得出來
* 取樣座標先量化到貼圖的像素格，紋路才跟得上像素風
* 「哪裡有水、水面多高」烘成一張最近鄰的貼圖，著色器查一次就知道
* 三層條件由外往內收，最貴的細胞紋排在最裡面

下一章講水面上那一半。倒影的做法是把整個場景以水面為鏡面再畫一次，而那件事貴得驚人，所以還得決定什麼時候才畫。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/11-water-mirror.md
description: 只映天空的話，池面上看得到雲飄過去，岸邊那圈石燈籠卻不在水裡，那片水面就成了一塊開在地上的天窗。%( ˘•ω•˘ )%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP11：水面倒影

大家好，我是鱈魚。

前兩章都在處理水面以下，白沫、光網、水有多淺。這一章換到水面以上。

一方靜水最有說服力的東西是倒影。岸邊的石燈籠、頭上的雲、黃昏的天色，全部在水裡再來一次，而且是上下顛倒的。%( •̀ ω •́ )✧%

## 鏡子的原理

倒影的做法比想像中直白，把整個場景以水面為鏡面再畫一次，畫到一張圖上，然後把那張圖貼回水面。

鱈魚：「所以是把每個東西複製一份，翻過來擺在水底下？」
路人：「那你有幾百顆方塊要複製？」
鱈魚：「⋯⋯好啦，翻的是鏡頭，東西一顆都不動。」

真正翻過去的是視點。把鏡頭對著水面鏡射一次，從那個位置再畫一趟，畫出來的就是水裡該看到的樣子。

Babylon 把這件事包成 `MirrorTexture`，用起來像一張普通的算繪目標。

```ts
const texture = new MirrorTexture('water-mirror', 512, scene, true)
texture.mirrorPlane = new Plane(0, -1, 0, surfaceY)
texture.renderList = renderList
```

三行，一行一件事。第一行決定圖多大，第二行決定鏡面在哪，第三行決定要映什麼。

## 第一步：鏡面方程式

平面在 Babylon 裡是四個數字，前三個是法線、第四個是位移，滿足 `法線 · 位置 + 位移 = 0` 的點就在平面上。

水面是一片水平的面，位置在 `y = surfaceY`。代進去。

```ts
new Plane(0, -1, 0, surfaceY)
```

法線給朝下的 `(0, -1, 0)`，方程式展開是 `-y + surfaceY = 0`，也就是 `y = surfaceY`。%( ˘•ω•˘ )%

法線翻成朝上會怎樣，範例裡試一次就知道。整個倒影會映到水面上方去，鳥居倒插在天上。

位移這個數字也不能隨便給。水是液體，最上層那一格會矮掉八分之一格；冰是實心方塊，頂面就是格子的頂面。差的那一點點會讓倒影浮在冰面上方或沉進冰裡。

```ts
surfaceY: topLayerY + 0.5 - (surface === 'water' ? LIQUID_SURFACE_DROP : 0)
```

## 第二步：反射清單

`renderList` 決定鏡子裡有什麼。沒進清單的東西在水裡不存在。

只映天空的話，池面上看得到雲飄過去，岸邊那圈石燈籠卻不在水裡。那看起來就像一塊開在地上的天窗。%(´థ‸థ)%

所以兩邊都要進來。

```ts
const skyMeshList = [
  SKYBOX_NAME,
  STAR_FIELD_NAME,
  SUN_DISC_NAME,
  SUN_GLOW_NAME,
  MOON_DISC_NAME,
  MOON_GLOW_NAME,
  CLOUD_LAYER_NAME,
  OVERCAST_NAME,
]
  .map((name) => scene.getMeshByName(name))
  .filter((mesh) => !!mesh)

const blockMeshList = scene.meshes.filter((mesh) => mesh.name.startsWith(BLOCK_MESH_PREFIX))

texture.renderList = [...skyMeshList, ...blockMeshList]
```

天空那一組要逐個指名，因為天空是好幾個網格湊出來的。太陽、月亮、它們各自的光暈、星空、雲層、陰天那一片罩子，少一個就是水裡少一樣東西。

地景這邊撈的是方塊網格。這個世界是逐方塊類型一個網格配 thin instance 畫的（見 EP02），所以加進來的成本是「每種方塊多一次繪製呼叫」，每一顆方塊並不會各記一筆。

路人：「那植物、粒子、光暈那些呢？」
鱈魚：「都沒進去。倒影是要付錢的，貴的東西先不放。」

## 第三步：材質只留倒影

倒影面是一片獨立的網格，貼著水面浮在上頭。它的材質只有一個任務，所以其他通道全部關掉。

```ts
const material = new StandardMaterial('water-mirror-material', scene)

material.diffuseColor = new Color3(0, 0, 0)
material.specularColor = new Color3(0, 0, 0)
material.emissiveColor = new Color3(0, 0, 0)
material.disableLighting = true
material.reflectionTexture = texture
material.reflectionTexture.level = 1
```

反射在 `StandardMaterial` 裡是加在最後的一項。漫射與自發光留著的話，會在倒影上疊一層灰。

濃度用 `alpha` 給。

```ts
material.alpha = 0.5
material.transparencyMode = Material.MATERIAL_ALPHABLEND
```

倒影疊在水上，水自己的顏色與流動都還要看得見。給到滿就成了一面真的鏡子，那時水的存在感反而不見了。

還有一項要記得關。

```ts
material.fogEnabled = false
```

倒影裡的東西已經是從場景取來的顏色，各自吃過自己那一份霧了。這裡再套一次會讓水面比它映的東西更灰。

### 抬高兩公分

倒影面與水面幾乎同高，而兩片幾乎同高的半透明面會互相爭深度，畫面上是一片閃爍的雜訊。

```ts
const SURFACE_LIFT = 0.02

mesh.position.set(centerX, surfaceY + SURFACE_LIFT, centerZ)
```

抬高兩公分，深度就分得開了，而兩公分在畫面上量不出來。%(´,,•ω•,,)%

## 第四步：邊緣要淡出

倒影面是一片方形的板子，水池的形狀則各不相同。

沒有處理的話，水池的四個角會露出筆直的邊，看起來像鋪了一塊玻璃。做法是給材質一張透明度貼圖，中心是滿的、往外收到全透明。

```ts
const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2)
gradient.addColorStop(0, 'rgba(255, 255, 255, 1)')
gradient.addColorStop(0.62, 'rgba(255, 255, 255, 1)')
gradient.addColorStop(1, 'rgba(255, 255, 255, 0)')
```

內圈六成二維持全滿，最後那三成八化開。%( ´ ▽ \` )ﾉ%

倒影面本身也要比水真正的範圍再收窄一點。岸線是吃噪音生成的，凹凸不定，量出來的半徑是最外那一格的距離，照著鋪會讓倒影漫到岸上的草地。收掉三分之一格再讓邊緣淡出剛好。

### 解析度可以放心砍

範例裡那條解析度的滑桿一路往下拉，其實掉得很慢。

倒影本來就不該比實景銳利。水面在晃、倒影在抖，那是水的本性，一方水池用二五六完全看不出差別。

但這個數字得跟著範圍走。蛙聲澤那片水量出來半徑將近二十格，同一張圖攤在四十格見方的面上只剩每格六個像素，倒影會糊成一片色塊。

```ts
const textureSize = surface.radius > LARGE_MIRROR_RADIUS ? mirrorSizeLarge : mirrorSizeSmall
```

兩個尺寸住在畫質設定表裡，每一級各有一組，最省的那一級給零就是整個不做。走到水邊掉幀的話，這是第一個該減半的數字。

## 第五步：什麼時候才畫

一面鏡子等於那一帶的地景多畫一趟。這是這個效果唯一的成本，也是全部的成本。

所以要省，而且要省得徹底。

### 只給特定水景

第一刀是一份刻意的名單。

```ts
const MIRROR_TARGET_LIST: MirrorTarget[] = [
  { garden: 'pond', surface: 'water' },
  { garden: 'swamp', surface: 'water' },
  { garden: 'cave', surface: 'water' },
  { garden: 'rainvale', surface: 'water' },
  /** 山腳下那窪凍住的融雪池 */
  { garden: 'alpine', surface: 'ice' },
]
```

世界上零星的水窪、湯屋的岩池、海岸那片淺灘都有水，但「有水就映」是付不起的。值得付錢的是那幾座「反光本身就是主題」的箱庭。

再加一道下限，一兩格的水缽給了鏡子也看不出來。

```ts
const MIN_WATER_COLUMN_COUNT = 9
```

### 走近才畫

第二刀更有效。

```ts
const ACTIVE_DISTANCE = 30
const CHECK_INTERVAL = 0.3
```

超過三十格就把整張圖從算繪清單裡拿掉。四座箱庭彼此相距數十格，所以同一刻至多只有一面鏡子在畫。

距離檢查每三分之一秒做一次就好，這件事不必每一幀算。

關掉的時候有個地方容易漏。

```ts
function setActive(mirror: Mirror, nextActive: boolean): void {
  mirror.mesh.setEnabled(nextActive)
  mirror.texture.refreshRate = nextActive
    ? RenderTargetTexture.REFRESHRATE_RENDER_ONEVERYFRAME
    : 0
}
```

只把網格關掉是不夠的。算繪目標是掛在場景上的，網格看不看得見它都照畫，於是那一趟地景照樣走完，只是畫給沒人看的一張圖。頻率歸零才是真的不畫。%(・\_・;)%

### 人在水面以下也關掉

最後補一個狀況。

```ts
const isAbove = camera.position.y > mirror.surfaceY
```

從水裡往上看不會看到倒影，那時該看到的是水面本身。而倒影面是單面的，從底下看過去只會是一片空白。

## 完整實作

倒影面要鋪多大，這件事最好從世界資料量出來。

專案裡原本是寫死的，四座箱庭的水各有各的高度與形狀，岩響窟的水在洞裡、聽雨亭的是一方淺池，照著抄四組座標，只要地形生成改一次就全錯，而且錯的樣子是「倒影浮在半空中」。

改成掃。逐格柱找最上層的水，照高度分組，取格數最多的那一層。

分組這一步是必要的。一座箱庭可能同時有主池與岸邊的小水窪，兩者高度不同，混在一起算出來的中心會落在兩池之間的岸上。

量範圍則用外接矩形。

```ts
const halfWidth = Math.max(1, (waterMaxX - waterMinX) / 2 + 0.5 - RADIUS_INSET)
const halfDepth = Math.max(1, (waterMaxZ - waterMinZ) / 2 + 0.5 - RADIUS_INSET)
```

另一種算法是「重心加上最遠一格的距離」，那會把面積灌水，而且水愈散愈嚴重。蛙聲澤的水鋪滿整座箱庭，重心落在正中央、最遠的是四個角，量出來的半徑是 14 × √2 ≈ 19.8，於是鋪出一面四十格見方的鏡子，而那座箱庭的木座只有三十二格寬。

多出來的那四格會從台座邊緣探出去，懸在外圈的石板路上方。%(›´ω\`‹ )%

中心也要跟著改成矩形的中心。水池偏在箱庭一角時，重心與外接矩形的中心是兩個位置，用錯了鏡子會歪一邊。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* `MirrorTexture` 是把鏡頭對著水面鏡射一次，從那裡再畫一趟
* 鏡面方程式的法線朝下、位移等於水面高度
* 天空與地景都要進反射清單，少一邊就成了地上的天窗
* 倒影面抬高兩公分免得爭深度，邊緣用一張徑向遮罩淡出
* 成本是「那一帶的地景多畫一趟」，所以只給特定水景，而且走近才畫

下一章講雨停之後那段地還是濕的時間。濕的表面在物理上會同時變暗與變亮，兩件事要一起做才成立。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/12-wetness.md
description: 濕的表面在物理上會同時變暗與變亮。只壓暗會變成髒，只加高光會變成上了一層蠟，兩件事得一起做。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP12：雨後濕潤

大家好，我是鱈魚。

雨本身只是幾千條掉下來的線，落地就沒了。真正讓人相信剛下過雨的，是雨停之後那段地還是濕的時間。

少了它，走出聽雨亭的那一步，整個世界會在一瞬間乾透。%(´･\_･\`)%

## 濕的表面在物理上發生了什麼

這件事有兩個方向相反的效果，而且必須同時發生。

**第一件是變暗。**

石頭、木頭、泥土這類表面都有孔隙。下雨之後水填進那些孔隙，光射進去以後在裡面來回反射好幾次才出得來，每一次反射都被吸收掉一點。走出來的光就少了，於是我們看到的是一片更深、更飽和的顏色。

濕掉的沙灘顏色比乾沙深好幾階，就是這個原因。

**第二件是變亮。**

乾的表面很粗糙，法線東倒西歪，照進來的光散到各個方向。水在上面鋪成一層平滑的膜之後，那些散開的反射全部聚回同一個方向，高光因此暴增。

雨後的柏油路在斜射的陽光下會亮到刺眼，那道亮本來就該在那裡。

鱈魚：「所以濕就是把顏色調暗嘛，一行搞定。」
路人：「那看起來只是髒而已。」
鱈魚：「⋯⋯好啦，還要把高光一起拉起來。」

範例裡把兩個開關分開試一次就很清楚。只壓暗是髒，只加高光是上了一層蠟，兩個一起才是濕的。%( •̀ ω •́ )✧%

## 第一步：先把原色記下來

實作之前有一件事要先做對。

濕度會連續變化，每一幀都可能重算，所以絕對不能在材質的現值上再乘一次。那樣調個幾次就會越調越黑，再也回不來。

```ts
const backupList = materialList.map((material) => ({
  material,
  diffuse: [material.diffuseColor.r, material.diffuseColor.g, material.diffuseColor.b],
  specular: [material.specularColor.r, material.specularColor.g, material.specularColor.b],
  specularPower: material.specularPower,
}))
```

之後每次都拿這份原色去算。

## 第二步：漫射壓暗

```ts
const WET_DIFFUSE_RATIO = 0.68

const diffuseRatio = lerp(1, WET_DIFFUSE_RATIO, wet)

material.diffuseColor.set(
  diffuse[0] * diffuseRatio,
  diffuse[1] * diffuseRatio,
  diffuse[2] * diffuseRatio,
)
```

業界對柏油這類多孔材質會壓到剩下一兩成，方塊世界不必那麼極端。這裡的木頭與石頭本來就是低飽和的手繪色，壓太多會整片發黑，留六成八剛好。

## 第三步：高光提亮並散開

高光要往同一個目標值收。

```ts
const WET_SPECULAR = 0.42

material.specularColor.set(
  lerp(specular[0], WET_SPECULAR, wet),
  lerp(specular[1], WET_SPECULAR, wet),
  lerp(specular[2], WET_SPECULAR, wet),
)
```

照原值放大的話會有一個很難發現的漏洞。原本的高光是每種方塊各自調過的，有的很低、有的乾脆是零，而零乘上任何倍率都還是零，那幾種方塊永遠濕不起來。

水膜是蓋在表面上的一層，底下是什麼材質並不影響它有多亮。%( ˘•ω•˘ )%

範圍也要一起放寬。

```ts
const WET_SPECULAR_POWER = 20

material.specularPower = lerp(backup.specularPower, WET_SPECULAR_POWER, wet)
```

指數越低、高光的範圍越寬。乾的方塊用預設的六十四，那是幾乎看不見的小亮點；濕的地面該是一整片順著光的方向鋪開的亮，收到二十才是水膜該有的樣子。

順帶一提，高光這一項在 `StandardMaterial` 裡加在漫射的 clamp 外面，也就是全場唯一能真的超過純白的通道。雨後那道刺眼的反光正是從那裡來的。

六成八、零點四二、二十，這三個數字都是可以調的目標值。拉一拉滑桿，看看它們各自決定了什麼。

## 第四步：讓地面反射天色

到這裡已經很像了，還缺最後一樣東西。

真正的濕地面會反射天空。斜看出去的那一段路面會泛起一層天色，那是雨後最容易辨認的畫面。

正統的做法是螢幕空間反射，把場景多畫一次去找每個像素該反射什麼。而那個成本，跟這片禪庭濕地能佔到的畫面完全不成比例。%(´థ‸థ)%

所以走另一條路，反射一張等距柱狀投影的貼圖。

```ts
const texture = new DynamicTexture(
  'wet-sky-reflection',
  { width: 4, height: 64 },
  scene,
  false,
)
texture.coordinatesMode = Texture.FIXED_EQUIRECTANGULAR_MODE
texture.level = 0
```

寬度只給四像素，因為等距柱狀投影的顏色只跟視線的垂直角度有關，水平朝哪看都一樣。高度給六十四，漸層夠細看不出色階。

`FIXED` 那個變體是固定在世界座標上的，不隨鏡頭旋轉重新取樣。反光的是天空本身的顏色，鏡頭朝哪看都該一樣。

貼圖的內容跟著天色重畫。

```ts
const gradient = context.createLinearGradient(0, 0, 0, half)
gradient.addColorStop(0, colorToCss(atmosphere.skyZenithColor))
gradient.addColorStop(0.6, colorToCss(atmosphere.skyMidColor))
gradient.addColorStop(1, colorToCss(atmosphere.baseFogColor))
```

上半段是抬頭方向，天頂到地平線的漸層，中間插一階中空色，晨昏那種丁香紫與洋紅才有地方待。下半段是低頭方向，沒有真的地面資料，填地平線色至少不會顯得突兀。

天色變化很慢，半秒重畫一次就夠了。

這張圖不負責「反光的到底是不是眼前那棵樹」，它只負責「濕地在斜視角會泛起一層天光」。%(´,,•ω•,,)%

## 第五步：Fresnel 把反光趕到掠射角

只掛上反射貼圖的話，整片草地會泛白。

原因很直接，雨天的天空是一片亮灰，以那個強度反射到每一個像素上，等於在整個世界蓋一層灰白。濕潤該有的那道壓暗，被自己的反光完全蓋過去了。

真實的反射有角度。越貼近掠射角，反射越強，正對著看則幾乎沒有。這叫 Fresnel。

```ts
const fresnelParameters = new FresnelParameters()
fresnelParameters.bias = 0.02
fresnelParameters.power = 4
```

`bias` 是「正對時還留多少」，`power` 是「往掠射角集中得多快」。

`bias` 給高一點，低頭看到的地面也會蒙上一層天色。收到近乎零、`power` 拉高，反光就縮回它該在的地方，也就是斜看出去的那一段遠景。

強度也要一起收。

```ts
const WET_REFLECTION_LEVEL = 0.22

reflectionTexture.level = lerp(0, WET_REFLECTION_LEVEL, wet)
```

兩成二配上收窄的 Fresnel，濕地才會顯得更深、更飽和，而只在掠射角泛起一道白。

貼圖只有一張、Fresnel 參數只有一份，所有濕的材質共用，所以調這一個 `level` 就等於整個世界的濕地反光一起淡入淡出。

## 第六步：乾的時候要把貼圖整個拆掉

這一步很容易做成「把強度調成零就好」，那樣行不通。

```ts
function setReflectionAttached(nextAttached: boolean): void {
  for (const backup of backupList) {
    backup.material.reflectionTexture = nextAttached ? reflectionTexture : null
    backup.material.reflectionFresnelParameters = fresnelParameters
  }
}
```

兩個理由。

\*\*一是浪費。\*\*九成九的時間地面是乾的，卻讓兩百多份材質都常駐帶著一張反射貼圖，每一次繪製都多綁一個取樣器。

**二是會出事。**`StandardMaterial` 的反射在著色器裡有 `samplerCube` 與 `sampler2D` 兩份宣告，靠條件編譯二選一。掛著一張 2D 的等距柱狀投影貼圖時，另一份宣告仍然存在卻永遠不會被綁，於是它退回材質單元零，而那一格綁的是別的 2D 貼圖。

WebGL 對這種情況會丟出這一行。

```text
GL_INVALID_OPERATION: Two textures of different types use the same sampler location
```

整個繪製呼叫作廢。%(・\_・;)%

只在真的濕的時候掛上去，乾了就拆掉，兩個問題一起沒有。

順帶一提，Fresnel 參數留著就好，不必跟著拆。那組參數單獨存在時不做任何事，反射那一段整個掛在有沒有貼圖上。

## 第七步：雨停之後慢慢乾

最後把濕度接上天氣。

淋濕要快、變乾要慢，兩者差好幾倍。一場雨幾秒就把地面打濕，而雨停之後那段慢慢乾的過程才是這個效果存在的理由。

寫進材質之前記得加一道門檻。

```ts
const APPLY_STEP = 0.01

setRatio(ratio: number) {
  const wet = Math.min(1, Math.max(0, ratio))
  if (Math.abs(wet - appliedRatio) < APPLY_STEP)
    return

  appliedRatio = wet
  // 兩百多份材質從這裡開始改
}
```

這是每一幀都會走的路徑，而濕度在一秒內的變化遠小於眼睛看得出來的差別。差得夠多才動手，多數幀就整個跳過。

## 完整實作

專案裡的濕潤是一件全域的事，因為材質本來就全世界共用，同一種石頭只有一份。

這件事在這個場景裡剛好說得過去。雨勢滿檔時能見度只有二十六格，看得到的就只有腳邊這一塊；而走出雨區之後那段慢慢乾的過程，本來就該跟著人一起離開。

低畫質則不給反射貼圖。`createWetness` 的第二個參數是選用的，沒給的話就只做原本的漫射壓暗與高光散開，那兩件事本來就不花錢。

```ts
export function createWetness(
  materialList: StandardMaterial[],
  reflectionTexture?: Texture,
): Wetness
```

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 濕的表面更暗，因為水填進孔隙，光在裡面多反射幾次才出得來
* 濕的表面高光暴增，因為水膜把散開的反射聚回同一個方向
* 高光要往同一個目標值收，原本是零的材質才濕得起來
* 反射一張等距柱狀投影的天色貼圖，配上收窄的 Fresnel，反光只留在掠射角
* 乾的時候要把反射貼圖整個拆掉，只把強度調成零會踩到取樣器型別衝突

下一章講空氣裡那些浮著的顆粒。陽光斜射進林子的時候，空氣本身也該看得見。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/13-air-motes.md
description: 霧是一層數學，光束是一道後製，兩者之間什麼都沒有。要讓空氣看起來真的存在，得在裡面撒一把看得見的東西。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP13：空氣顆粒

大家好，我是鱈魚。

前幾章把天色、雲影、霧氣都做完了，畫面該有的東西看起來都有了。可是走進去晃一圈，總覺得哪裡怪怪的。%(´･\_･\`)%

怪在空氣。

## 為什麼空氣裡要有東西

這個世界的空氣一直是空的。霧是一層跟著距離算出來的數學，光束是一道後製的後處理，兩者之間什麼都沒有。

於是方塊與方塊之間那段距離，畫面上是完全透明的。人的眼睛拿不到任何線索，只好把它讀成真空。

現實裡的空氣從來不是這樣。花粉、灰塵、水氣一直懸在裡面，陽光斜進來的時候整條光路都看得見。人之所以「看得見陽光」，正是因為空氣裡有東西擋在光的路上。

關掉顆粒的時候，柱子與柱子之間只有一片乾淨的透明。撒上一把之後，那段距離忽然量得出來了。%ヽ(●\`∀´●)ﾉ%

鱈魚：「所以只要在空中隨便灑一堆白點就好了嘛。」
路人：「隨便灑會變成雜訊好嗎。%(´・ω・\`)%」
鱈魚：「好啦，數量、大小與速度都有講究。」

## 第一步：一組最小的粒子系統

Babylon 的 `ParticleSystem` 是現成的，開一份出來就能跑。

```ts
const emitter = new Vector3(0, 2, 0)

const moteSystem = new ParticleSystem('air-mote', 240, scene)
moteSystem.emitter = emitter
moteSystem.start()
```

建構子的第二個參數是這組系統最多養幾顆。這個數字一開就吃掉一份頂點緩衝，之後改不了，所以它是上限而不是目標值。

`emitter` 可以給網格，也可以給一個座標。這裡給座標，因為浮塵不從任何東西上噴出來，它就是散在空中。

### 顆粒生在哪裡

`emitter` 只決定中心點，範圍要另外給。

```ts
moteSystem.minEmitBox = new Vector3(-11, -2.5, -11)
moteSystem.maxEmitBox = new Vector3(11, 4, 11)
```

這兩個角落是**相對於發射器**的偏移，夾出來的長方體就是顆粒出生的範圍。

上下不對稱是刻意的。發射器等一下要綁在鏡頭上，而鏡頭的高度是眼睛，往下兩格半是腳邊、往上四格是頭頂。蹲著看與站著看都要有東西飄。

### 一顆顆粒的一生

每顆顆粒出生時領到一份隨機的參數，之後就照著它自己走完。

```ts
moteSystem.minSize = 0.04
moteSystem.maxSize = 0.08
moteSystem.minLifeTime = 6
moteSystem.maxLifeTime = 13
moteSystem.minEmitPower = 0.04
moteSystem.maxEmitPower = 0.16
```

大小給到將近一個像素就好。再大一點就成了雪，這個尺寸在畫面上只佔幾個像素，看得見卻不搶戲。空氣感本來就該讓人察覺不到自己在看什麼。%( ˘•ω•˘ )%

壽命給六到十三秒是配著發射率算的。同時飄在空中的數量大約是「發射率乘上平均壽命」，一秒二十六顆配上十秒的壽命，畫面上長期維持在兩百多顆。

### 顏色的三個欄位

```ts
moteSystem.color1 = new Color4(1, 0.94, 0.72, 0.5)
moteSystem.color2 = new Color4(0.94, 0.9, 0.78, 0.28)
moteSystem.colorDead = new Color4(1, 0.94, 0.72, 0)
```

`color1` 與 `color2` 是出生時隨機挑的兩端，每顆在兩者之間取一個值，一群顆粒因此不會整齊得像同一批貨。

`colorDead` 是壽命走完時的顏色。透明度收到零，顆粒才會慢慢淡掉。少了這一行，十三秒一到就是一顆白點憑空消失，那一下非常醒目。

### 怎麼飄

```ts
moteSystem.gravity = new Vector3(0, 0.012, 0)
moteSystem.direction1 = new Vector3(-0.06, 0.02, -0.06)
moteSystem.direction2 = new Vector3(0.06, 0.09, 0.06)
```

重力給了一個往**上**的極小值。灰塵在靜止的空氣裡是懸著的，幾乎不會落下，讓它慢慢往上飄一點點，再配上左右的微幅擾動，「空氣本身在動」的感覺才出得來。

`direction1` 與 `direction2` 同樣是隨機的兩端，配上 `emitPower` 就是每顆的初速。

### 混合模式

```ts
moteSystem.blendMode = ParticleSystem.BLENDMODE_STANDARD
```

浮塵走標準的半透明混合。它自己不發光，看得見是因為有光照在上面，所以該有的行為是蓋在背景上而不是加上去。

三個滑桿一起玩就看得出關係。範圍拉大而發射率不動，密度立刻稀掉；壽命拉長則是同一批顆粒撐得更久，畫面上的總數跟著上升。%(⊙ o ⊙)%

順帶一提，拉動滑桿之後畫面要過幾秒才整批換過來。發射盒與壽命只影響還沒生出來的那些，已經在空中的顆粒照著自己出生時那一份設定走完。

## 第二步：顆粒要跟著鏡頭走

現在有個很實際的狀況。

顆粒撒在世界原點周圍那一圈，人往前走十幾格就走出去了，身邊立刻乾乾淨淨。而整個世界撒滿顆粒是不可能的，遠處那些在畫面上小到看不見，卻照樣要進每一幀的更新與排序。

解法是把發射點綁在鏡頭上，只在身邊十來格內撒。

```ts
moteSystem.emitter = emitter

scene.onBeforeRenderObservable.add(() => {
  emitter.copyFrom(camera.position)
})
```

關鍵在於**只有發射點跟著走**。顆粒撒出去之後就留在世界座標上，人往前走，它們自然落在身後，幾秒之後壽命到了再從新的位置生出來。

於是走到哪裡身邊都有東西在飄，卻不會有「一團顆粒黏著鏡頭跑」那種假。

### 不必每一幀對齊

```ts
const RECENTER_INTERVAL = 0.25

recenterElapsed += deltaTime
if (recenterElapsed >= RECENTER_INTERVAL) {
  recenterElapsed = 0
  emitter.copyFrom(camera.position)
}
```

發射盒有二十二格見方，走路一秒也才五六格。四分之一秒對齊一次，畫面上完全看不出落差，省下來的是每一幀那幾次向量複製。

鏡頭沿著那排柱子來回。發射點釘在原地時，走到底就只剩一片空曠；跟著鏡頭走則是整段路上都有東西在飄。%( •̀ ω •́ )✧%

路人：「顆粒不會在世界邊界那裡穿幫嗎？」
鱈魚：「會，所以另外給了一個能見度的參數，貼近邊界時發射率直接收到零。」

## 第三步：白天的灰塵與夜裡的螢火

同一組骨架換一套參數，就長成完全不同的兩種。

夜裡的空氣不該有浮塵。浮塵之所以看得見是因為有光照在它身上，天黑了那道光就沒了，一群還在發亮的顆粒只會像浮在畫面上的雜訊。

夜裡該有的是螢火。

```ts
const fireflySystem = new ParticleSystem('air-firefly', 64, scene)

fireflySystem.blendMode = ParticleSystem.BLENDMODE_ADD
fireflySystem.minEmitBox = new Vector3(-8.8, -2.5, -8.8)
fireflySystem.maxEmitBox = new Vector3(8.8, 1.2, 8.8)
```

差別有三個。

**混合模式改成相加**。螢火自己會發光，顏色要加到畫面上。它也就這樣繞開了材質那道亮度上限，加上去的顏色不吃任何 clamp，一點螢火在深夜的草間才真的會亮。

**範圍收窄、也不往高處去**。螢火貼著草叢飛，上界只給到一格二。

**亮度用漸層走完一生**。

```ts
fireflySystem.addColorGradient(0, FIREFLY_COLOR_DIM, FIREFLY_COLOR_DIM)
fireflySystem.addColorGradient(0.25, FIREFLY_COLOR, FIREFLY_COLOR)
fireflySystem.addColorGradient(0.6, FIREFLY_COLOR, FIREFLY_COLOR)
fireflySystem.addColorGradient(1, FIREFLY_COLOR_DIM, FIREFLY_COLOR_DIM)
```

`addColorGradient` 的第一個參數是壽命走到幾成，後兩個是那一刻的顏色範圍。四個停點畫出「亮起、撐住、熄掉」的曲線，一整條壽命剛好走完一次明滅。

一群螢火各自的壽命又不一樣，整片看過去就是此起彼落地閃。%(๑´ㅂ\`๑)%

### 兩邊怎麼交班

發射率各自跟著白晝的程度走。

```ts
const FIREFLY_DAY_THRESHOLD = 0.35

moteSystem.emitRate = MOTE_EMIT_RATE * dayRatio

const nightRatio = Math.max(0, 1 - dayRatio / FIREFLY_DAY_THRESHOLD)
fireflySystem.emitRate = FIREFLY_EMIT_RATE * nightRatio
```

浮塵直接乘上白晝的程度，天亮就有、天黑就沒有。

螢火反過來拿 `1 - dayRatio` 推，而且除上一個門檻。天要暗到三成五以下牠們才開始現身，黃昏那段時間並不會一邊還有夕陽一邊已經滿天螢火。

把滑桿從右拉到左，浮塵先收乾淨，天再暗一點草間才亮起幾點綠光。

洞穴裡則是第三種空氣。那裡永遠是暗的，但有燈火，所以塵照樣看得見；顏色換成冷灰，一點暖都不留。

```ts
const litRatio = Math.max(dayRatio, caveRatio * 0.7)
moteSystem.emitRate = MOTE_EMIT_RATE * litRatio

Color4.LerpToRef(POLLEN_COLOR, CAVE_COLOR, caveRatio, moteSystem.color1)
```

顏色就地插值，不重建系統。連已經活著的顆粒都會跟著換色，走進洞口那幾步是連續的。

洞穴程度拉到底，發射率也只到日間滿檔的七成。塵靠燈火撐場面，亮度本來就到不了太陽那個等級。%(・ω・)%

## 第四步：數量跟著畫質分級

粒子是逐顆更新的，數量直接乘在每一幀的成本上。

```ts
function scaleParticleCount(baseCount: number) {
  return Math.max(1, Math.round(baseCount * preset.value.particleRatio))
}

airMotes = createAirMotes({
  scene,
  moteCount: scaleParticleCount(220),
  fireflyCount: scaleParticleCount(48),
})
```

每一種粒子的基準值都照著「最高畫質該有多密」調，各級之間的差別只是密度，所以這裡統一乘上一個倍率。等級增減時這一段完全不必動。

低畫質給零點三六倍，兩百二十顆收成八十顆。空氣感淡了一點，畫面照樣成立。

還有一件事要記得。

```ts
moteSystem.applyFog = true
```

平常那個距離連最濃的霧都還沒開始作用，這一項確實換不到任何看得出來的差別。世界邊界那道白幕是例外，它半格外就起霧、六格外全白，顆粒整片都落在裡面。

不吃霧的話，四周白成一片時這些顆粒依然清清楚楚地浮在白幕前面，跨過邊界就整批換了一組。停止發射只管得到還沒生出來的那些，已經飄在空中的要等壽命走完，而那段時間人早就走到邊界了。%(›´ω\`‹ )%

## 完整實作

專案裡 `air-motes.ts` 做的就是這幾件事。

1. 開兩組系統，浮塵走標準混合、螢火走相加混合
2. 發射點每四分之一秒對齊一次鏡頭
3. 依白晝程度與洞穴程度算出兩邊各自的發射率
4. 顏色隨洞穴程度插值，走進洞口是連續的

```ts
export function createAirMotes({ scene, moteCount, fireflyCount }: CreateAirMotesParams) {
  const moteEmitter = new Vector3()
  const fireflyEmitter = new Vector3()

  // ...兩組系統的設定

  return {
    update(camera, dayRatio, caveRatio, visibleRatio) {
      // 對齊發射點、更新顏色與發射率
    },
    dispose() {
      moteSystem.dispose()
      fireflySystem.dispose()
    },
  }
}
```

`visibleRatio` 自己一個參數，不折進 `dayRatio` 裡。螢火是拿 `1 - dayRatio` 反推的，把「此刻不該看見」折進白晝的程度，對浮塵是關掉、對螢火卻是開到最大。大白天走到世界邊界會召出一群螢火。%(๑•́ ₃ •̀๑)%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 空氣裡沒有東西的時候，眼睛只能把那段距離讀成真空
* `emitBox` 是相對於發射器的偏移，上下不對稱是為了配合眼睛的高度
* 只讓發射點跟著鏡頭走，顆粒留在世界座標上，才不會有一團東西黏著人跑
* 浮塵走標準混合、螢火走相加混合，同一套骨架換參數就是兩種空氣
* 數量統一乘上畫質的倍率，等級增減時這段程式碼不必動

下一章繼續在空氣裡動手腳。天亮前那一段時間，地面上會積一層霧，而它得貼著地形的高低起伏走。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/14-ground-mist.md
description: 天亮前的那一段，地面上會積一層白。做這件事要兩套東西，近處的體積感靠粒子，遠處的層次靠一行霧的公式。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP14：貼地晨霧

大家好，我是鱈魚。

上一章在空氣裡撒了一把顆粒。這一章要在同一片空氣裡再鋪一層東西，只是這次它貼在地上，而且只在一天當中很短的一段時間出現。%( ˘•ω•˘ )%

## 第一步：算出這一刻該有多濃

霧會積在地面，是因為夜裡地表放熱降溫，貼著地面那一層空氣先冷下來，水氣就凝在那裡。

所以晨霧的時間點很固定。天還沒亮的時候它已經積在那裡，太陽一升起就開始曬散。

專案裡的一天是零到一的循環，破曉在 0.18、日出在 0.24。晨霧的四個節點照著這兩個數字抓。

```ts
const MIST_RISE_FROM = 0.09
const MIST_RISE_TO = 0.18
const MIST_FADE_FROM = 0.27
const MIST_FADE_TO = 0.41
```

淡入九分之一天、淡出十四分之一天，出來的時間比散掉的時間短。太陽把霧曬散的那一段是晨霧最好看的地方，值得拖久一點。

### 濃度曲線

```ts
export function getDawnMistRatio(timeOfDay: number): number {
  if (timeOfDay <= MIST_RISE_FROM || timeOfDay >= MIST_FADE_TO)
    return 0

  if (timeOfDay < MIST_RISE_TO)
    return smoothRange(timeOfDay, MIST_RISE_FROM, MIST_RISE_TO)

  if (timeOfDay > MIST_FADE_FROM)
    return 1 - smoothRange(timeOfDay, MIST_FADE_FROM, MIST_FADE_TO)

  return 1
}
```

四個節點把一天切成五段，中間那段給滿，兩側各走一條 smoothstep。

```ts
function smoothRange(value: number, from: number, to: number): number {
  const ratio = Math.min(1, Math.max(0, (value - from) / (to - from)))

  return ratio * ratio * (3 - 2 * ratio)
}
```

`t²(3 - 2t)` 這條曲線在兩端的斜率都是零，所以霧開始出現與完全散掉的那一刻不會有轉折。直線的話，那兩個時間點上會看到濃度突然開始變化。

算出來的比例直接乘在發射率上。

```ts
const fullEmitRate = maxParticleCount / 14

particleSystem.emitRate = fullEmitRate * getDawnMistRatio(timeOfDay)
```

滿檔的發射率照容量除以平均壽命算。同時活著的數量大約是「發射率乘上平均壽命」，除以十四剛好把容量填滿而不撞到上限。

把滑桿從左推到右，霧先浮起來、撐一陣子，再慢慢化掉。%(´,,•ω•,,)%

路人：「發射率歸零之後，已經在那裡的霧片呢？」
鱈魚：「照自己的壽命走完，十幾秒剛好是天亮那段時間，看起來就是被曬散的。」

## 第二步：霧片要貼著地面長出來

粒子系統預設用 `minEmitBox` 與 `maxEmitBox` 夾出一個長方體，顆粒隨機生在裡面。

這對貼地的霧不夠用。庭園是一座座抬高的木座加上木座之間的白沙，高低差有好幾格，一個固定的高度只會得到一片橫穿所有東西的白板。

霧要積在低處、繞著木座的邊緣走，就得先知道每一個位置的地面有多高。

### 用射線問世界

```ts
particleSystem.startPositionFunction = (_worldMatrix, positionToUpdate) => {
  const radius = Math.random() ** 0.7 * MIST_RADIUS
  const angle = Math.random() * Math.PI * 2
  const x = emitter.x + Math.cos(angle) * radius
  const z = emitter.z + Math.sin(angle) * radius
  const surfaceY = castRainRay(Math.floor(x + 0.5), Math.floor(z + 0.5)) ?? 0

  positionToUpdate.set(
    x,
    surfaceY + MIST_MIN_HEIGHT + Math.random() * (MIST_MAX_HEIGHT - MIST_MIN_HEIGHT),
    z,
  )
}
```

`startPositionFunction` 一給，那兩個發射盒就不算數了，每一片霧生在哪裡完全由這個函式決定。

`castRainRay` 是從天空往下打的一道射線，回傳它撞到的第一個實心頂面。這道射線本來是給雨滴用的，晨霧、沼澤霧與落葉後來都接到同一支。

```ts
export function castRainRay(state: Uint8Array, x: number, z: number): number | null {
  for (let y = WORLD_HEIGHT - 1; y >= 0; y--) {
    const blockId = getBlock(state, x, y, z)
    if (blockId === BlockId.AIR)
      continue
    if (isPassableBlock(blockId) && !isWaterBlock(blockId))
      continue

    return y - 0.5 + getCollisionHeight(blockId)
  }

  return null
}
```

方塊世界的好處在這裡看得很清楚。射線不必真的做幾何相交，從天空那一格往下數，遇到第一個擋得住的就停。花草這類穿得過去的方塊直接跳過，半磚只有半格高，水面則擋在水的頂面。

### 半徑的取樣要偏向中心

```ts
const radius = Math.random() ** 0.7 * MIST_RADIUS
```

`Math.random()` 均勻散在零到一之間，直接乘上半徑的話，外圈那一圈會比內圈稀薄很多。圓的面積跟半徑平方走，同樣的角度區間在外圈涵蓋的面積大得多。

開零點七次方把取樣往中心壓一點。腳邊的霧最密，越往外越疏，邊緣自然就散開了。%(๑´ㅂ\`๑)%

### 高度給到過腰而不過肩

```ts
const MIST_MIN_HEIGHT = 0.1
const MIST_MAX_HEIGHT = 1.9
```

上界壓在一格九，也就是人的胸口。晨霧的辨識度全在「它比人矮」這件事上，一旦漫過頭頂，畫面上就只剩一片白，看起來像走進雲裡。

關掉貼地之後那片白板非常明顯，木座整個泡在裡面，霧與地形完全沒有關係。%(⊙ o ⊙)%

## 第三步：遠景交給高度霧

粒子只鋪在身邊三十幾格。再遠的地方，一片霧在畫面上只剩幾個像素，撒再多也堆不出厚度，卻照樣要進每一幀的更新與排序。

遠處那一層要用另一種做法。

場景內建的霧只看距離，不管在什麼高度，一律照離鏡頭多遠往霧色收。真實的空氣是有重量的，濁的那一層積在低處，這是為什麼從山上往下看，山谷總是比山脊模糊。

所以在霧的濃度上再乘一個看高度的倍率。

```glsl
float fogAmount = clamp(1.0 - fog, 0.0, 1.0);
float lowRatio = clamp((groundHaze.x - vPositionW.y) * groundHaze.y, 0.0, 1.0);
fogAmount = clamp(fogAmount * (1.0 + lowRatio * groundHaze.z), 0.0, 1.0);
color.rgb = mix(color.rgb, vFogColor, fogAmount);
```

`groundHaze` 那三個分量分別是濁氣的頂、往下加厚的速度，以及貼著地面時要濃多少。

```ts
const GROUND_HAZE_TOP = SAND_LEVEL + 10
const GROUND_HAZE_FALLOFF = 1 / 12
const GROUND_HAZE_BOOST_BASE = 0.6
```

頂抓在沙面上十格，木座、鳥居與矮松都泡在裡面，樹冠與山頭則露在上面。清晨從高處往下看時，整片庭園浮在一層薄濁上，就是這個高度切出來的。

加厚的速度給十二格的倒數。從樹冠到地面是一段連續的漸變，不會出現一條水平的界線。

第三個是**倍率**。近處的東西完全不受影響，乘上零還是零，只有本來就有點遠的東西會再糊一點。直接相加的話，腳邊的方塊會憑空罩上一層灰。

這一段程式碼要換進 `StandardMaterial` 的片段著色器裡，走的是材質外掛。那套機制在 EP05 講雲影時已經完整介紹過，這裡只用到它的兩件事，登記幾個 uniform 與換掉霧的那一行。

把加厚拉到零就退回原本的單色霧，柱子從底到頂糊得一樣多。拉起來之後，同一根柱子的下半截先沉進霧裡，頂端還留在外面。

## 第四步：濃度隨太陽仰角變化

貼地水氣最看得出來的時候，是太陽貼著地平線那一段。逆光穿過一層薄霧，是晨昏辨識度最高的畫面之一。

所以那個倍率不是固定的，它跟著太陽的仰角走。

```ts
const GROUND_HAZE_BOOST_DAWN_DUSK = 1.15
const GROUND_HAZE_LOW_SUN_HEIGHT = 0.12
const GROUND_HAZE_HIGH_SUN_HEIGHT = 0.55

function computeGroundHazeBoost(sunHeight: number): number {
  const ratio = (sunHeight - GROUND_HAZE_LOW_SUN_HEIGHT)
    / (GROUND_HAZE_HIGH_SUN_HEIGHT - GROUND_HAZE_LOW_SUN_HEIGHT)
  const clamped = Math.min(1, Math.max(0, ratio))
  const smooth = clamped * clamped * (3 - 2 * clamped)

  return GROUND_HAZE_BOOST_DAWN_DUSK
    + (GROUND_HAZE_BOOST_BASE - GROUND_HAZE_BOOST_DAWN_DUSK) * smooth
}
```

仰角低的時候給到 1.15，正午收回基準的 0.6，中間一樣用平滑曲線接起來。太陽爬升的過程因此看不出任何一道分界。

太陽仰角直接拿平行光的方向來算。

```ts
updateAerialAir(fogColor, skyMidColor, clearRatio, -sunLight.direction.y)
```

光往下照的時候 `direction.y` 是負的，取負號就成了「太陽在天上多高」。零是貼著地平線、一是正上方。

這個量法整個專案共用，雲影判斷太陽高度用的也是同一個數字。

鱈魚：「那乾脆晚上也開到最大，霧越多越有氣氛。」
路人：「晚上根本看不到霧啊，那只會整片變灰。ლ（´ 口\`ლ）」
鱈魚：「好啦，夜裡本來就收在天色裡了，不必額外加。」

## 第五步：兩層的分工

現在手上有兩套東西，該怎麼分配。

\*\*粒子給近景。\*\*它一片一片真的存在於世界上，會被木座擋住、會繞著邊緣走、會隨著人前進而慢慢補上。近處那種「霧是有厚度的」感覺只有它做得出來。

\*\*高度霧給遠景。\*\*它是一行公式，成本與距離無關，而且天涯海角都有效。遠處那一整片的層次交給它。

兩者的接手點靠半徑決定。

```ts
const MIST_RADIUS = 34
```

粒子的半徑抓得比場景霧開始作用的距離再遠一點。走在裡面時前方那一片是連續的，再遠的地方交給場景霧接手，兩者之間沒有一條看得出來的界線。

只留粒子的時候，遠處是一片平的白，沒有層次；只留高度霧的時候，腳邊乾乾淨淨，霧從幾十格外才開始。兩層疊起來才是從腳邊一路連到天邊的一片霧。%ヽ(●\`∀´●)ﾉ%

### 發射點同樣跟著鏡頭走

```ts
const RECENTER_INTERVAL = 0.4

recenterElapsed += deltaTime
if (recenterElapsed < RECENTER_INTERVAL)
  return

recenterElapsed = 0
emitter.copyFrom(camera.position)
```

與上一章的浮塵是同一招。已經生出來的霧片留在原地，只有新的那些照著現在的位置撒，於是走過的路上霧會慢慢散掉，前方則慢慢補上。

間隔比浮塵的四分之一秒再放寬到零點四秒。霧片的半徑有三十四格，位置差個一兩格完全看不出來。

## 完整實作

`ground-mist.ts` 整支就是這幾件事。

1. 依時刻算出這一刻該有多濃
2. `startPositionFunction` 打一道射線，把霧片貼著地表生出來
3. 發射點每零點四秒對齊一次鏡頭
4. 高度霧那一層由大氣透視的外掛順手做掉

呼叫端還要再乘幾個條件。

```ts
const dawnRatio = getDawnMistRatio(getTimeOfDay())

groundMist.update(
  camera,
  dawnRatio * (1 - caveRatio) * (1 - rainRatio) * (1 - swampMistRatio) * edgeHideRatio,
)
```

洞裡沒有晨霧，那裡照不到太陽；下雨時也沒有，天已經是一片鉛灰；沼澤上更不必，那裡本來就有一片更濃的。

這幾個條件全部寫成零到一的比例再相乘，好處是走進洞口、雨勢轉大、踏進沼澤這幾件事都是連續的，沒有任何一個瞬間會看到霧整批消失。%( •̀ ω •́ )✧%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 晨霧的濃度只看時刻，四個節點配上 smoothstep 就是一條完整的曲線
* 霧片要貼著地形長出來，得先從天空往下打一道射線問地面有多高
* 半徑取樣開零點七次方，腳邊最密、越往外越疏
* 近景的體積感靠粒子，遠景的層次靠片段著色器裡那一行高度霧
* 貼地水氣的濃度跟著太陽仰角走，晨昏最濃、正午收回基準值

下一章離開天氣，回到地上。人走過草叢時草要讓開，走遠了再慢慢站回來，而這件事得在頂點著色器裡做。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/15-grass-trample.md
description: 前面幾章的外掛都在改顏色，這一章改的是頂點的位置。風把草吹彎，人走過去草讓開，走遠了再慢慢站回來。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP15：草叢踩踏

大家好，我是鱈魚。

這個系列到目前為止，材質外掛都用在同一件事上，改片元最後的顏色。雲影是把顏色調暗，大氣透視是把顏色往霧色收，晨霧的高度加厚也是。

這一章換一邊。改的是頂點的位置本身。%( •̀ ω •́ )✧%

## 為什麼只能在著色器裡做

世界上的花草有上萬株，全部是 thin instance，共用同一份頂點資料。

這件事的意思是，CPU 這邊連「單獨移動其中一株」的餘地都沒有。手上只有一份網格與一大包矩陣，改網格等於整片草一起改，改矩陣則是整株平移。

要讓每一株各自彎腰，就只能在頂點著色器裡做。GPU 跑那支程式的時候，每一個頂點都知道自己屬於哪一株、在那一株的哪個高度。

```ts
class WindSwayPlugin extends MaterialPluginBase {
  getCustomCode(shaderType: string) {
    if (shaderType !== 'vertex')
      return null

    return {
      CUSTOM_VERTEX_DEFINITIONS: VERTEX_DEFINITIONS,
      CUSTOM_VERTEX_UPDATE_POSITION: VERTEX_UPDATE_POSITION,
    }
  }
}
```

材質外掛的完整機制在 EP05 講雲影時已經說過。這裡只有兩個地方不一樣。

\*\*`shaderType` 要認 `vertex`。\*\*片段那支回傳 `null`，一個字都不必動。

**注入點換成頂點著色器的那兩個。**`CUSTOM_VERTEX_DEFINITIONS` 在函式區，用來放自己寫的 GLSL 函式；`CUSTOM_VERTEX_UPDATE_POSITION` 在 `vec3 positionUpdated = position;` 之後、`instancesVertex` 展開之前。

那個順序很要緊。世界矩陣還沒乘上去，所以這裡動的是**區域座標**。一株草的區域座標是負零點五到正零點五，加上零點五剛好就是「離地多高」。

### 這一株長在哪裡

區域座標問不出「這一株站在世界的什麼位置」，可是風的強弱要看位置。

```glsl
#ifdef INSTANCES
  vec3 plantOrigin = world3.xyz;
#else
  vec3 plantOrigin = vec3(0.0);
#endif
```

`world0` 到 `world3` 是 Babylon 給實例的四個頂點屬性，湊起來就是那一株的世界矩陣。矩陣的第四行是平移，所以 `world3.xyz` 直接就是它的世界座標。

實例的矩陣要是純平移加上等比縮放。一旦帶了旋轉，區域座標上的位移會跟著轉，整片草就各自往不同的方向倒了。

### uniform 只登記一次

```ts
class WindSwayPlugin extends MaterialPluginBase {
  getUniforms() {
    return {
      ubo: [
        { name: 'windTime', size: 1, type: 'float' },
        { name: 'windAmplitude', size: 1, type: 'float' },
        { name: 'windTrampleList', size: 4, type: 'vec4', arraySize: TRAIL_MARK_COUNT },
      ],
    }
  }
}
```

登記在 `ubo` 裡的名字，Babylon 會自己把宣告注入材質的 uniform 區塊，頂點與片段兩支都拿得到。

所以 `VERTEX_DEFINITIONS` 那個字串裡千萬不要再寫一次 `uniform float windTime`。同一個名字宣告兩次，著色器編譯直接失敗，而編譯失敗的材質不會報錯，只會整批不畫。畫面上看到的就是所有的草突然消失。%(´･\_･\`)%

鱈魚：「我還以為是草自己害羞躲起來了。」
路人：「草哪有那種功能啦。ლ（´ 口\`ლ）」

把幅度拉到零就是一片站得筆直的草。往右推，每一株各自彎起來，而它們共用的是同一份網格。%(๑´ㅂ\`๑)%

風由三層疊起來，各管一件事。

## 第一步：柏林噪聲的陣風

這一層決定「這一帶此刻風多大」。

```glsl
vec2 samplePoint = plantOrigin.xz * 0.09 - windDirection * windTime * 0.09 * 2.6;
float gust = windNoise(samplePoint) * 0.68 + windNoise(samplePoint * 2.3 + 17.0) * 0.32;
float gustStrength = clamp(0.7 + gust * 0.45, 0.35, 1.15);
```

取樣點隨時間往風的方向退，噪聲場因此像一陣風掃過草原。

用的是梯度噪聲，格點上存的是一個方向。內插出來的場沒有格子的痕跡，這是「像風」的關鍵。換成存高度的值噪聲，格線就會露出來。

```glsl
vec2 windHash(vec2 point) {
  point = vec2(dot(point, vec2(127.1, 311.7)), dot(point, vec2(269.5, 183.3)));
  return -1.0 + 2.0 * fract(sin(point) * 43758.5453123);
}
```

疊兩層，大的那層是一陣一陣的強弱，小的那層讓陣與陣之間不會是同一個形狀。

`clamp` 壓成一個恆正的包絡。風會忽強忽弱，但不會反過來吹，下限留一點，草地永遠有一絲微風。

`0.09` 這個疏密約是十一格一個起伏，差不多一座箱庭的三分之一。看得出「一陣」的形狀，又不會整座木座同進同出。

## 第二步：沿著風向前進的行進波

問題來了。十一格才一個起伏，相鄰兩株在噪聲場上只差零點零九，取到的值幾乎一模一樣。整片草看起來是同時動的。

陣風管得了範圍，管不了順序。

```glsl
float rippleTravel = dot(plantOrigin.xz, windDirection) - windTime * 2.6;
float ripple = sin(windRippleFrequency * rippleTravel);
```

相位只看「這一株在風向上站得多前面」，減去時間就成了一道往下游跑的行進波。

波長給六格，隔壁那一株就差六十度的相位。這一株彎到底時下一株才剛開始傾，一排草因此是接力倒下去的。%ヽ(●\`∀´●)ﾉ%

它與陣風用同一個速度前進，所以看到的是「一陣風掃過來，草一株接一株倒下去」，兩者不會各走各的。

樹葉的波長則要拉到二十四格。樹冠是一團互相緊貼的方塊，波長若與草一樣短，相鄰兩塊葉子會往不同方向偏，塊與塊之間就裂出縫來。拉長之後同一棵樹幾乎整團同進同出，波的作用只剩「這棵樹與那棵樹不同步」。

關掉行進波，整片草變成同步擺動，看起來像一塊在抖的地毯。打開之後那股「掃過去」的感覺立刻回來。波長拉到二十幾格則會慢慢變回同步。%(⊙ o ⊙)%

## 第三步：每一株自己的顫動

```glsl
float plantPhase = plantOrigin.x * 1.7 + plantOrigin.z * 2.3;
float flutter = sin(windFlutterPhase + plantPhase);
```

只有前兩層的話，同一小塊裡的草會整齊得像一塊布。疊一層又快又小的擾動，每一株的相位由它自己的座標決定，葉尖那種細碎的顫動就出來了。

幅度寫成佔主擺幅的比例，這樣調整主擺幅時顫動會跟著等比縮放。

這裡的相位用的是 CPU 累積好的數字。

```ts
flutterPhase += deltaSecond * FLUTTER_SPEED * (0.55 + squall * 0.5)
```

在著色器裡寫「時間乘上當下的速度」會出事。速度是會變的，而那個乘積的變化率還帶著時間本身，跑了十分鐘之後速度稍微一動就會把相位甩出去好幾圈。畫面上是整片草莫名其妙抽動一下。

每一幀只加上「這一幀該轉多少」就沒有這個問題。

## 第四步：高度槓桿

三層算出一個幅度，接下來要決定這個幅度怎麼分配到一株草的上下。

```glsl
float height = clamp(positionUpdated.y + 0.5, 0.0, 1.0);
float leverage = mix(1.0, height * height, windHeightLeverage);

vec2 sway = windDirection * amplitude * leverage;
```

`height` 是「離地多高」，零在根部、一在頂端。再平方一次，根部幾乎釘在地上，只有頂端在動。

草是從土裡長出來的，底邊不該移動。而立板只有上下兩排頂點，`leverage` 在根部是零，所以底邊在數學上不可能動，這是一個保證而不是一個調參。

`windHeightLeverage` 給零的時候，`mix` 直接回傳 1.0，整株一起平移。那是樹葉要的擺法。

樹冠是一團互相緊貼的方塊，各自彎腰的話塊與塊之間會裂開，整團同進同出才是一棵樹被風推的樣子。

槓桿拉到零，草底邊跟著跑，看起來像浮在地上的一塊布。拉到一，根就釘住了。%( ˘•ω•˘ )%

順帶一提，樹葉的幅度只給花草的三分之一，還有另一個理由。樹葉會投影子，而陰影貼圖走的是另一支著色器，影子不會跟著擺。差零點零五格看不出來，差零點一五就對不上了。

## 踩踏：記住人走過哪裡

風是整片一起晃的，那是背景。接下來這一項是「因為我在這裡」，世界對人有反應，那是走進去與看著它的差別。

## 第五步：一組腳印存成 uniform 陣列

```ts
const TRAIL_MARK_COUNT = 12

const trailState = {
  /** 每四個數字一個腳印：世界 XYZ 與此刻的強度 */
  markList: new Float32Array(TRAIL_MARK_COUNT * 4),
  ageList: new Float32Array(TRAIL_MARK_COUNT),
  nextMarkIndex: 1,
}
```

十二個腳印，每個佔一個 `vec4`。前三個分量是它蓋在哪裡，第四個是此刻還壓著多重。強度為零代表這是空位。

送進著色器就是一整包。

```ts
uniformBuffer.updateFloatArray('windTrampleList', trailState.markList)
```

第零個位置是活的，每一幀覆寫成人此刻站在哪裡。所以站著不動時，腳邊那一圈會一直伏著。

其餘十一個是走過留下的腳印，各自照自己的年齡恢復。

## 第六步：著色器這邊怎麼算

衰減曲線長這樣。

十二個腳印一一查過去，逐株算出這一株此刻承受的推力。

```glsl
for (int markIndex = 0; markIndex < 12; markIndex++) {
  vec4 trampleMark = windTrampleList[markIndex];
  if (trampleMark.w <= 0.0) continue;

  float trampleDistance = length(plantOrigin.xz - trampleMark.xz);

  float trampleFalloff = 1.0 - smoothstep(0.6, 1.5, trampleDistance);
  trampleFalloff *= 1.0 - smoothstep(0.0, 2.2, abs(plantOrigin.y - trampleMark.y));

  trampleAmount = max(trampleAmount, trampleMark.w * trampleFalloff);
}
```

**外圈給一格半**，差不多是一個人張開手臂。走過去時貼著身體的那一圈草讓開，再遠一點的維持原狀。這個數字放到四格半的話，整片草地會以人為中心攤平成一個大圓，那看起來像有一台壓路機開過去。

\*\*裡面還有一個滿檔的核心。\*\*衰減若從距離零就開始算，力道最強的地方永遠是腳底下那一株，而那一株在畫面上根本看不到，看得到的那些全落在曲線的尾巴上。核心之內一律滿檔，草才是整片一起讓開。

這兩個數字是 `smoothstep` 的上下界，顛倒過來在 GLSL 是未定義行為，畫面上會變成整片草莫名其妙地抽動。

\*\*高度差也要算。\*\*沒有這一項的話，站在木橋上、坐在屋頂上、跳起來的那一刻，底下的草都會跟著往外倒，那看起來像有一團看不見的東西在飄。

\*\*十二個腳印取最重的那一個。\*\*相加會出事。人走過去之後那一株草的前後都有腳印，兩邊方向相反、互相抵銷，合力歸零，草在人還站在旁邊時就站了起來，下一個腳印蓋下去又倒回去。

取最大值則永遠不會抵銷。而最大值是連續的，每一項都連續，逐項取 `max` 出來的包絡也連續，換誰當最大的那一刻兩者剛好相等，接得上。

## 第七步：推開的同時要壓下去

```glsl
float tramplePush = trampleAmount * windHeightLeverage * leverage;
sway += windTrampleFlow.xy * tramplePush;

positionUpdated.x += sway.x;
positionUpdated.z += sway.y;
positionUpdated.y -= tramplePush * 0.55;
```

只有橫推的話，草是整株往旁邊挪，高度卻一點沒變。人的重量要看得出來，頂端就得同時矮下去一截。

五成五配上零點七五的推開量，草尖大約從一格高沉到六成，同時橫移四分之三格。那是伏倒的樣子。

推開量給到風的五倍多也是刻意的。風是整片草一起晃，看的是節奏；踩踏是「這幾株被讓開了」，看的是對比，推得不夠明顯就等於沒做。

下壓與橫推同樣乘在 `leverage` 上，而 `leverage` 在根部是零，所以壓下去的永遠是上半截，草的根不會沉進土裡。

三個滑桿一起看最清楚。下壓比例歸零時草只是平移，畫面上完全沒有重量。%(๑•́ ₃ •̀๑)%

## 第八步：倒向哪一邊

方向全場共用一個，存成角度。

```ts
const targetAngle = Math.atan2(moveZ, moveX)
let deltaAngle = (targetAngle - trailState.flowAngle) % (Math.PI * 2)
if (deltaAngle > Math.PI)
  deltaAngle -= Math.PI * 2
if (deltaAngle < -Math.PI)
  deltaAngle += Math.PI * 2

const turnLimit = TRAIL_FLOW_TURN_RATE * deltaSecond
trailState.flowAngle += Math.min(turnLimit, Math.max(-turnLimit, deltaAngle))
```

每個腳印各記一個方向的話，一條走過又走回來的路上會出現方向相反的腳印，加起來同樣是互相抵銷。共用一個方向就不會，代價是轉彎時身後那條舊的痕會跟著轉過來。

這裡存的是角度，理由是轉向要能限速。兩個相反的單位向量做內插，中途會經過零向量，而零向量正規化出來的方向是跳的。原地前後走的時候，每一次改變方向都會踩到這件事。

改成每一幀往目標角度轉一小段，一百八十度的迴轉要花大半秒，中間會經過側面。那正是「草被掃過去」的樣子。

## 第九步：恢復曲線

腳印蓋下來之後要慢慢站回原狀。

```ts
function measureRecovery(age: number): number {
  const ratio = Math.min(1, Math.max(0, age / TRAIL_RECOVER_SECOND))

  return 1 - ratio * ratio * (3 - 2 * ratio)
}
```

一樣是 smoothstep 反過來用，一是全倒、零是站直。平滑收尾很重要，草不該在恢復的最後一刻啪地彈回去。

恢復時間給一秒。這是「回頭還看得到」與「草是活的」之間的那個點。真正的草只需要一兩秒就撐回去了，給到六秒的話身後那條徑遲遲不闔上，看起來像地上留著一條被踩出來的凹痕。

關掉記憶就只剩人此刻站的那一圈，走開的瞬間草整片彈起來，看起來像草在躲人。%( ´ ▽ \` )ﾉ%

## 第十步：腳印數量有限，所以要輪流覆寫

```ts
trailState.nextMarkIndex = trailState.nextMarkIndex + 1 >= TRAIL_MARK_COUNT
  ? 1
  : trailState.nextMarkIndex + 1
```

繞回一而不是零。第零個位置是活的，不參與輪替。

這裡有個要處理的狀況。十二個位置蓋滿之後，最舊的那一個會被新的覆寫掉，而它當時往往還壓著八成。被覆寫的那一刻，它壓著的那片草是**瞬間**站回原狀的。

這件事有多快發生，取決於蓋腳印的速度。間距固定零點八五格、人走五點二格每秒，一秒六個，十一個位置一點八秒就繞完一圈。恢復要走完一秒的話還好，要是給到六秒，每一秒多都有一片草無聲地彈起來。「慢慢站回來」寫在恢復曲線裡，畫面上卻永遠看不到，因為沒有一個腳印活得到那個時候。

解法是讓一圈的長度追上恢復的時間。

```ts
function measureStampDistance(speed: number): number {
  const span = speed * TRAIL_RECOVER_SECOND / (TRAIL_MARK_COUNT - 1)

  return Math.min(TRAIL_STAMP_DISTANCE_MAX, Math.max(TRAIL_STAMP_DISTANCE_MIN, span))
}
```

一圈涵蓋的路是「間距乘上位置數」，走完它要「那段路除以速度」秒。要它不短於恢復時間，間距就得跟著速度走。跑起來時腳印散開，慢慢晃時腳印變密。

於是最舊的那一個總是在恢復完之後才被回收，覆寫掉的永遠是已經站直的那一處。

上下限也各有用途。下限管的是慢慢晃過去時不要蓋得太密，上限管的是兩個腳印之間不能脫節，間距超過核心的直徑，走過的路就會斷成一串圓點。

## 第十一步：速度要自己量

```ts
const frameSpeed = deltaSecond > 0
  ? Math.hypot(footX - trailState.lastFootX, footZ - trailState.lastFootZ) / deltaSecond
  : 0

trailState.speed += (Math.min(TRAIL_SPEED_MAX, frameSpeed) - trailState.speed)
  * Math.min(1, deltaSecond * TRAIL_SPEED_FOLLOW)
```

直接拿這一幀的位移除以時間會抖得很厲害。撞到方塊、跳起來、掉幀都會讓某一幀的瞬時速度暴衝，而腳印的間距跟著暴衝就會在路上開一個洞，所以要先夾住上限再平滑。

夾子那個上限是給瞬移用的。快速前往那一幀的位移有幾十格，不夾的話平滑後的速度會被那一下推高好幾秒。

為什麼不去跟漫遊控制器要一個常數？那個常數改了，這裡不會知道，而位移是量得到的。

## 完整實作

`wind-sway.ts` 整支做的事排一次。

1. 場景每一幀推進時間、整場風的強弱與顫動的相位
2. 依人的位移更新軌跡，蓋新腳印、讓舊腳印恢復
3. 每一份材質綁定時把這些數字寫進 uniform buffer
4. 頂點著色器逐頂點算出風的位移與踩踏的位移，一起加到區域座標上

```ts
export function createWindSway(scene: Scene): WindSway {
  const pluginList: WindSwayPlugin[] = []

  scene.onBeforeRenderObservable.add(() => {
    const deltaSecond = scene.getEngine().getDeltaTime() / 1000
    elapsedSecond += deltaSecond
    squall = measureSquall(elapsedSecond)
    flutterPhase += deltaSecond * FLUTTER_SPEED * (0.55 + squall * 0.5)

    updateTrail(scene, deltaSecond, devToggle.grassTrample)

    for (const plugin of pluginList) {
      plugin.setWindState(elapsedSecond, squall, flutterPhase)
    }
  })

  return { attach, dispose }
}
```

還有一個小最佳化值得提。

```glsl
if (windHeightLeverage > 0.0) {
  // 跑那十二個腳印
}
```

樹葉的 `windHeightLeverage` 是零，跑完十二個腳印算出來的結果最後也會被乘成零。而樹冠的頂點數遠多於地上的花草，這一個分支省下的是全場最大一批頂點的迴圈。%( •̀ ω •́ )✧%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 上萬株草共用一份頂點資料，要各自彎腰就只能寫在頂點著色器裡
* 注入點在世界矩陣之前，所以動的是區域座標，`world3.xyz` 才是那一株的世界座標
* 柏林噪聲管「這一帶風多大」，行進波管「一株接一株倒下去」
* `leverage` 在根部是零，所以底邊在數學上不可能移動
* 腳印取最重的那一個，相加會在來回走的路上互相抵銷
* 腳印的間距跟著速度算，最舊的那一個才會在恢復完之後才被回收

下一章回到畫面本身。方塊的邊緣在斜線上會露出鋸齒，而這個世界的解析度本來就刻意壓得很低，處理起來要格外小心。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/16-multisampling.md
description: 方塊的斜稜線上永遠有一排階梯。抹開它有兩條路，而其中一條會順手把整片像素貼圖也一起抹掉。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP16：多重取樣

大家好，我是鱈魚。

這一章講抗鋸齒。%( •̀ ω •́ )✧%

方塊世界的東西幾乎全是盒子，而盒子只要轉過一點角度，稜線上就會出現一排階梯。走路的時候那排階梯還會沿著邊緣爬，特別搶眼。

## 鋸齒是怎麼來的

畫面上的一個像素，其實是一小塊有面積的方格。而光柵化在決定這個方格該塗什麼顏色時，只問了一次，問的是方格正中心那一點落在誰身上。

三角形蓋住這一格的九成也好、一成也好，只要中心點在裡面，整格就是三角形的顏色；中心點在外面，整格就是背景色。中間那些「蓋了一半」的情況完全沒有地方可以表達。

把像素放大之後就看得很清楚了。斜邊只能在整數格之間跳，於是排成一道階梯。%(´･\_･\`)%

鱈魚：「那把解析度開到無限大不就好了？」
路人：「你的顯卡會先跟你分手。」

## 兩條路

抹開那排階梯有兩種完全不同的做法。

**FXAA** 是一道後製。等整張畫面畫完之後，它掃過每一個像素，找出亮度落差大的地方，判斷那裡大概是一條邊，再沿著邊的方向把兩側的顏色混一混。它很便宜，只要一趟全螢幕的取樣。

**MSAA**（多重取樣）發生在光柵化的當下。同一個像素裡擺好幾個取樣點，逐點去問「這一點在三角形裡面嗎」，最後按照中了幾點決定這一格要混多少三角形的顏色。片元著色器仍然只跑一次，多出來的只有覆蓋率的判定。

兩者的差別在於**它們手上有多少資訊**。

## 為什麼這個專案選 MSAA

FXAA 看到的只有一張畫好的圖。它分不出眼前這條亮度落差是幾何的邊緣，還是貼圖上本來就該有的兩格不同顏色的像素。

而 Minespace 的貼圖是十六格見方的像素畫，滿滿都是後者。

```mermaid
---
title: 這一格的亮度落差，FXAA 要不要抹開
---
flowchart TD
    A[方塊稜線的幾何邊緣] --> C{兩側亮度落差夠大？}
    B[貼圖上石縫的色塊交界] --> C
    C -- 否 --> D[維持原樣]
    C -- 是 --> E[往邊的方向混合兩側顏色]
    E --> F1[稜線確實平順了]
    E --> F2[石縫顆粒也跟著糊成一片]
```

FXAA 只認得到那個判斷式，兩種完全不同的來源走到它面前，都會觸發同一次混合。

開著 FXAA 的時候，牆面上那些石縫與顆粒被輕輕糊掉一層。而這套美術最不該失去的就是那些。%(´,,•ω•,,)%

MSAA 拿到的是光柵化階段的覆蓋率，它知道哪裡才是真正的三角形邊界。方塊的稜線平順了，貼圖一個像素都沒被動到。

路人：「所以像素風遊戲一律不能用 FXAA？」
鱈魚：「硬邊的美術風格都得小心。它的判斷依據就是亮度落差，而硬邊本來就是落差。」

代價是 MSAA 要配置一份多重取樣的緩衝區，每一幀還要多一次解析。這是頻寬的成本，跑不動的機器就兩個都不開。

## 第一步：把管線建起來

Babylon 的 `DefaultRenderingPipeline` 會把場景畫進離屏貼圖，再一路做完色調映射、暗角這些後製。

```ts
const pipeline = new DefaultRenderingPipeline('minespace-pipeline', false, scene, [camera])

pipeline.imageProcessingEnabled = true
pipeline.imageProcessing.toneMappingEnabled = true
pipeline.imageProcessing.toneMappingType = ImageProcessingConfiguration.TONEMAPPING_ACES
```

抗鋸齒的兩個開關就掛在這個管線上。

```ts
/** 幾何邊緣交給多重取樣 */
pipeline.samples = 4
/** 後製的那一種關掉，它會連貼圖一起抹 */
pipeline.fxaaEnabled = false
```

`samples` 給 1 等於關閉。

## 第二步：canvas 的多重取樣要關掉

這一步很容易漏。

建立引擎時有個 `antialias` 選項，那開的是 canvas 預設緩衝區的多重取樣。

```ts
return new Engine(canvas, false, {
  antialias: false,
  alpha: false,
  stencil: false,
  preserveDrawingBuffer: false,
})
```

之所以要關掉，是因為場景根本不是畫在那份緩衝區上。

有了 `DefaultRenderingPipeline` 之後，整個世界會先畫進管線自己的離屏貼圖，後製跑完才把結果貼回 canvas。而貼回去的那一步只畫一片鋪滿螢幕的方塊，上面沒有任何幾何邊緣。

canvas 那份多重取樣緩衝區於是接到一片沒有邊的畫面，抗鋸齒無從發揮，白配置一份記憶體與頻寬。真正在做事的是管線上的 `samples`。%( ˘•ω•˘ )%

## 第三步：取樣數給到幾

一到二那一階差最多，二到四還看得出來，四以上就只剩下帳單。

理由是覆蓋率的表達能力。一個像素四個樣本，邊緣能表達的是「四分之零到四分之四」共五階；八個樣本變成九階，而人眼在一條邊上分不出這兩者的差別。頻寬卻是線性成長。

所以專案裡最高的兩級都停在四倍。

```ts
export const QUALITY_PRESET_MAP = {
  high: {
    sampleCount: 4,
    // ...
  },
  ultra: {
    sampleCount: 4,
    // ...
  },
}
```

最省的那一級給 1，也就是整個不開。那一級本來就在跟頻寬計較。

## 第四步：解析度倍率

抗鋸齒還有第三條路，直接畫更多的像素。

倍率調到 2 的時候，實際畫布的邊長是螢幕的兩倍。縮回去顯示的那一步，每個螢幕像素等於收了四個樣本，邊緣自然就平了。這叫超取樣，效果最好，成本也最兇。

Babylon 這邊的旋鈕叫硬體縮放，它與倍率互為倒數。

```ts
export function getHardwareScalingLevel(preset: QualityPreset, devicePixelRatio: number): number {
  return 1 / Math.min(devicePixelRatio, preset.pixelRatioLimit)
}
```

`Math.min` 那一段是關鍵。在兩倍的螢幕上照著裝置像素比走，代表要畫四倍的像素。

而幀率一低，轉動視角就會一段一段跳。視角轉多少是由滑鼠位移決定的，與幀率無關；幀率低下來，同樣的角度就被切成更少、更大的步進。

所以每一級各有一個像素上限。

```ts
export const QUALITY_PRESET_MAP = {
  low: { pixelRatioLimit: 1 / 3 },
  medium: { pixelRatioLimit: 1 },
  high: { pixelRatioLimit: 1.5 },
  ultra: { pixelRatioLimit: 1.5 },
}
```

最奢的那一級原本給 2，後來收回一點五。那多出來的像素換到的是幾乎看不出的銳利度，卻讓最貴的三項（四層陰影、遮擋視差、光線行進）各自多付兩倍多的錢。

極致該奢在效果。%( •̀ ω •́ )✧%

## 第五步：接上畫質分級

兩個數字都放進設定表，切換畫質時一起套用。

```ts
watch(quality, () => {
  const devicePixelRatio = window?.devicePixelRatio ?? 1
  engine.value?.setHardwareScalingLevel(
    getHardwareScalingLevel(preset.value, devicePixelRatio),
  )

  if (pipeline.value) {
    pipeline.value.samples = preset.value.sampleCount
  }
})
```

這兩項都是設一個屬性就生效的，用 `watch` 接就好。陰影就沒這麼幸運，貼圖邊長是建構時決定的，換等級得整個重建。

除錯開關那邊也接一份，方便隨時把兩種抗鋸齒對著比。

```ts
pipeline.value.samples = devToggle.multiSample ? preset.value.sampleCount : 1
/** 關掉多重取樣時補回 FXAA，才比較得出兩者的差別 */
pipeline.value.fxaaEnabled = !devToggle.multiSample && preset.value.sampleCount > 1
```

## 完整實作

整理一次流程。

1. 建引擎時 `antialias: false`，場景不畫在 canvas 的緩衝區上
2. 建 `DefaultRenderingPipeline`，`fxaaEnabled = false`
3. `pipeline.samples` 由畫質設定表決定，最高給 4
4. `setHardwareScalingLevel` 由同一張表的像素上限算出來
5. 切換畫質時兩項一起更新

最後補一件事。抗鋸齒從 FXAA 換成多重取樣之後，會少掉一個原本沒人注意到的副作用。

FXAA 在抹平邊緣的同時，順手也把色階的邊界抹開了。那些一圈一圈的等高線落差雖小，在它眼裡照樣是落差。

換掉它之後，那件事得由別人正面處理。下一章講的就是這個。%(๑•̀ㅂ•́)و✧%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 鋸齒的根源在於一個像素只問一次「中心點落在誰身上」
* FXAA 手上只有畫好的成品，硬邊的像素貼圖會整片被抹糊
* 多重取樣發生在光柵化當下，只動真正的幾何邊緣
* 場景畫進離屏貼圖之後，canvas 自己那份多重取樣接不到邊緣，要關掉
* 解析度倍率也在抗鋸齒，但成本按平方成長，壓在一點五就好

下一章講打散色階，也就是被 FXAA 順手蓋掉的那個問題。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/17-dithering.md
description: 一整片藍天上浮出一圈一圈的等高線。八位元只有 256 階，而一條從天頂鋪到天邊的漸層剛好吃得下這麼多階。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP17：打散色階

大家好，我是鱈魚。

上一章把抗鋸齒從 FXAA 換成多重取樣，畫面上的貼圖總算不再被抹糊。

換完之後抬頭看天，一整片漸層上浮出了一圈一圈的等高線。%(⊙ o ⊙)%

鱈魚：「顯卡壞了？」
路人：「你自己把幫你遮住的東西拆了啊。」

## 色階環是什麼

畫面最後要寫進一份八位元的緩衝區，每個通道只有 0 到 255 這 256 個整數可以用。

著色器算出來的顏色是連續的浮點數，寫進去的那一刻得挑一個最近的整數。這一步叫量化，而量化的誤差本身很小，一個色階而已，人眼在一般的畫面上根本看不出來。

麻煩的是**平滑而漫長的漸層**。

想像一條從天頂的深藍走到天邊的白，走完整個畫面高度。這條路上只能踩 256 級台階，於是每一級都佔了好幾十列像素。同一級之內是完全相同的顏色，級與級之間是一次乾淨俐落的跳躍。

那就是一條看得見的界線。

漸層越長，每一階佔的螢幕就越寬，界線也就越明顯。%(´･\_･\`)%

而人眼對這種轉折特別敏感，這現象叫馬赫帶效應（Mach bands）。就算兩側只差一個色階，只要那條界線是筆直而連續的，眼睛就會自己把它強調出來。

路人：「所以改成十位元的緩衝區就好了？」
鱈魚：「WebGL 給不了，而且顯示器多半也吃不到。」

## 加半個色階的雜訊

治法出乎意料地便宜。在量化之前，替每個像素加上一點隨機的偏移就好。

```glsl
float noise = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
color += (noise - 0.5) / 255.0;
```

`fract(sin(...))` 是著色器裡最省的亂數。拿片元座標做一次高頻的正弦再取小數，出來的值在 0 到 1 之間，而且相鄰像素之間毫無關聯。

減 0.5 讓它變成正負半個色階，除以 255 換算成八位元的一階。

### 為什麼這樣就看不出來了

關鍵在於**界線消失了，誤差還在**。

想像漸層走到某一段，理想值剛好落在第 100 階與第 101 階之間，偏第 100 階那側三成。

沒有雜訊的時候，這一整段的每個像素都會乖乖地選 100，直到理想值越過中點才整排一起跳到 101。那個「一起跳」畫出來就是一條線。

加了雜訊之後，每個像素拿到的偏移都不一樣。理想值偏 100 那側三成的地方，大約七成的像素選 100、三成選 101，而且是隨機散布的。再往前走一點，選 101 的比例慢慢升到四成、五成。

於是**這一整片的平均亮度是連續的**，眼睛看到的是平滑的過渡。原本集中在界線上的誤差被攤成滿版的細顆粒，而顆粒的振幅只有一個色階，肉眼看不見。%( •̀ ω •́ )✧%

雜訊的幅度給到一個色階寬就夠。再往上加只是把畫面弄髒，界線早就散掉了。

## 每一道後製都是一次重排

事情還沒完。

畫面畫進緩衝區之後，還要經過色調映射、對比、色調曲線，最後才寫進螢幕。而每一道處理都在重新排列色階。

ACES 這條曲線在亮部壓縮得很兇、在暗部拉開得很兇。壓縮的那一段，好幾個輸入階會被擠成同一個輸出階；拉開的那一段剛好相反，原本相鄰的兩階被推得老遠，中間空出一段沒有東西的區間。

再量化一次，那段空隙就成了更寬的一條帶。

所以打散色階要做兩次，一次在畫面出去之前，一次在來源那一層。

## 第一步：管線這一道

Babylon 的影像處理本身就有這個開關。

```ts
pipeline.imageProcessing.ditheringEnabled = true
```

它會在色調映射與色調曲線之後、寫進畫面之前加上一份雜訊，預設強度剛好是 1/255。

成本是每個像素一次亂數，換來的是肉眼看不見的顆粒取代看得見的圈。這筆帳怎麼算都划算。%(´,,•ω•,,)%

順帶一提，專案裡最後拿掉色彩分級的查找表，也是同樣的道理。

查找表的取樣走三線性內插，等於把一條平滑的曲線換成幾十段折線，而每個節點上斜率會跳一下。天空的漸層加上光暈那層放射狀的亮度都極為平滑，兩者相加之後，某一圈等亮度線壓在節點上就會浮出一道看得見的輪廓。

實測那張查找表最大只改變 8/255，多數落在 1 到 5 之間。一個看不太出來的效果，換一個看得很清楚的瑕疵。%(›´ω\`‹ )%

## 第二步：天空那一層自己再加一次

管線那一道處理的是最後那次量化。而天空是自己算出顏色、自己寫進緩衝區的，它那一層的量化在更早之前就發生了。

而全場漸層最長的又剛好是天空。從天頂到天邊、從太陽那一側到背光那一側，兩條路都鋪滿整個畫面。

所以 `sky-gradient` 的片元著色器在最後一行自己加了一次。

```glsl
/**
 * 打散色階
 *
 * 整片天是一條很長的漸層，八位元的色階在上面會顯出一圈圈的等高線。
 * 加上半個色階的雜訊就看不出來了，代價是肉眼看不見的顆粒
 */
float noise = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
color += (noise - 0.5) / 255.0;

gl_FragColor = vec4(color, 1.0);
```

就這兩行，接在混完霞光之後。

把著色器內的雜訊關掉，天邊那一圈暖光的外緣會清清楚楚地畫出好幾道弧。那正是它們最容易出現的位置，因為那裡的漸層走得最慢。

路人：「兩層都加，雜訊會不會疊起來？」
鱈魚：「會，變成大約一點四個色階。還是遠低於看得見的門檻。」

## 為什麼抗鋸齒換掉之後才要處理

回到開頭那個問題。

FXAA 的判斷依據是亮度落差。而色階的界線本身就是一道落差，正好落在它的守備範圍裡，於是它在抹平幾何邊緣的同時，順手也把那些等高線抹開了。

那是免費的，也是不受控的。它決定要抹哪裡的依據跟色階完全無關，而且會連貼圖的硬邊一起帶走（上一章那件事）。

多重取樣不碰這件事。它只對真正的幾何邊緣多取幾個樣本，色階的界線在它眼裡什麼都不是。

所以換過去之後，這一項得由自己正面處理。%( ˘•ω•˘ )%

## 完整實作

整理一次。

1. 管線開 `ditheringEnabled`，收拾色調映射與色調曲線重排之後的那次量化
2. 天空著色器在寫出顏色前自己加一次，收拾它自己那一層的量化
3. 雜訊幅度都是正負半個色階，也就是 `1/255`
4. 亂數用 `fract(sin(dot(gl_FragCoord.xy, ...)))`，一次乘法一次正弦

判斷「這裡該不該加」的標準只有一條，**這一層有沒有長而平滑的漸層**。

天空有，光暈有，霧的過渡有。方塊的表面沒有，那上面滿滿都是貼圖的硬邊，本來就不存在連續的漸層。

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 色階環來自八位元只有 256 階，而長漸層讓每一階佔了好幾十列像素
* 加上正負半個色階的雜訊，界線會散成看不見的顆粒，平均亮度反而變連續
* 雜訊要加在量化之前，加在之後只是灑顆粒
* 色調映射與分級會重排色階，重新量化之後色階環更明顯，所以管線那一道要開
* 天空自己也加一次，因為它那一層的漸層最長、而且它自己就會量化一次

下一章換個題目，講體素全局光。牆角會泛著鄰居的顏色，那道光要怎麼在瀏覽器裡即時算出來。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/18-voxel-gi.md
description: 紅牆旁邊的地板該泛著一點紅。要在瀏覽器裡即時算出這道間接光，得先把整個世界壓成一份很粗的格子。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP18：體素全局光

大家好，我是鱈魚。

一般的即時光照只算直射光。太陽照到這個面，這個面就亮；沒照到，就交給環境光補一個固定的值。

現實裡不是這樣。光打在紅牆上會彈開，彈出去的光帶著紅牆的顏色，落在旁邊的地板上。所以牆角永遠泛著鄰居的顏色，而環境光那個固定的值給不了這件事。%( ˘•ω•˘ )%

這一章講怎麼把那道間接光算出來。

## 完整的做法有多貴

正規的全局光要沿著每一條光路追蹤反彈，那是離線算圖的規格，一幀幾秒到幾分鐘。

即時的做法一律在偷工，差別只在偷哪裡。這裡選的是**把空間切粗**。

世界是二百八十格見方、四十格高，一格一格算根本不用想。但如果水平四格、垂直兩格併成一個單元呢？格數瞬間掉到三千分之一，而間接光本來就很鬆，粗到這個地步在畫面上幾乎看不出來。

鱈魚：「那再粗一點不是更省？」
路人：「粗到整個庭園只剩一格，你就得到一顆環境光了。」

說得對，那就是這條路的兩個端點。這一章要做的就是在中間找一個位置。

## 第一步：把世界降採樣成粗網格

第一步是掃過整個世界，把每一粗格裡的方塊收成兩個數字。

```ts
export interface VoxelGiGrid {
  gridX: number;
  gridY: number;
  gridZ: number;
  /** 1 為這格大致是實心的（擋光、也反光），0 為大致開放（光在裡面流動） */
  solidList: Uint8Array;
  /** 每格的概略反照色，長度是格數乘三 */
  albedoList: Float32Array;
  /** 每格能看到多少天空 */
  skyVisibilityList: Float32Array;
}
```

掃法很單純，數這一格裡有幾個實心方塊、把它們的反照色加起來。

```ts
const blockId = worldState[coordinateToIndex(x, y, z)] as BlockId
if (blockId === BlockId.AIR || isPassableBlock(blockId))
  continue

solidCountList[cellIndex]! += 1

const albedo = getBlockAlbedo(blockId)
albedoSumList[cellIndex * 3]! += albedo[0]
albedoSumList[cellIndex * 3 + 1]! += albedo[1]
albedoSumList[cellIndex * 3 + 2]! += albedo[2]
```

掃完之後，實心與否取多數決。

```ts
/** 過半是實心才算實心，邊界格常常一半空氣一半石頭 */
solidList[i] = solidCount * 2 > totalCountList[i]! ? 1 : 0
```

### 水平粗、垂直細

格距那兩個數字刻意不一樣。

```ts
export const QUALITY_PRESET_MAP = {
  high: {
    giCellSizeXZ: 4,
    giCellSizeY: 2,
  },
}
```

世界只有四十格高。等向的粗細會讓垂直方向只剩十格解析度，而洞穴口與林冠交界那種地方，一兩格內就從露天變成陰暗。垂直切細一倍才抓得住這種變化，而且總格數也還不會爆。

### 反照色從哪裡來

這裡有個現實的問題，這個世界沒有一張「方塊到顏色」的對照表，顏色只活在貼圖的 PNG 裡。

真要準的話得逐張貼圖取平均色。但全局光要的只是「附近有沒有綠色的草、紅色的花」這種粗略提示，沒必要做到貼圖等級。

```ts
export function getBlockAlbedo(blockId: BlockId): [number, number, number] {
  if (isWaterBlock(blockId))
    return WATER_ALBEDO
  if (isLavaBlock(blockId))
    return LAVA_ALBEDO

  const tint = BLOCK_DEFS[blockId]?.textures?.tint
  return tint ?? NEUTRAL_ALBEDO
}
```

方塊定義裡本來就有一組 `tint`，那是給灰階貼圖上色用的，草地、花朵、樹葉都有。沒有 tint 的多半是石頭、木頭、沙，那些反光本來就偏中性灰，退回一個灰階即可。

液體另外給。水會把大半的光吸收掉，反彈出去的偏藍綠而且偏暗；岩漿自己在燒，反彈出去的是橘紅。

## 第二步：天空可見度

傳播要有起點，而起點是陽光。

問題是「這一格曬得到太陽嗎」。正規的答案要沿著太陽方向做一次三維射線行進，那很貴。這裡換一個近似，只看**頭頂壓了幾層實心**。

```ts
for (let cx = 0; cx < gridX; cx++) {
  for (let cz = 0; cz < gridZ; cz++) {
    let solidAbove = 0
    for (let cy = gridY - 1; cy >= 0; cy--) {
      const index = (cx * gridY + cy) * gridZ + cz
      skyVisibilityList[index] = Math.max(0, 1 - solidAbove * SKY_BLOCK_FACTOR)
      if (solidList[index] === 1) {
        solidAbove++
      }
    }
  }
}
```

由上往下走一趟，每過一層實心就把可見度收掉三成。三到四層粗格（也就是六到八格方塊）之後歸零。

這一步少算了「西曬的牆比東邊亮」這種方向性。全局光本來就只是個提示，這個簡化在畫面上幾乎看不出來，換到的是一整趟三維射線行進。%(´,,•ω•,,)%

## 第三步：光線傳播

接下來是這套機制的核心。

規則只有一條，**只有開放格存光，實心格不存**。實心格在每一輪裡負責反射，把開放鄰居送過來的光乘上自己的反照色再吐回去。

一輪分成兩趟。

第一趟，每個實心格收集六個開放鄰居目前的光，取平均，再加上自己的發光量（如果那格有燈）。

```ts
for (const [dx, dy, dz] of NEIGHBOR_OFFSET_LIST) {
  const neighborIndex = cellIndex(x + dx, y + dy, z + dz)
  if (solidList[neighborIndex] === 1)
    continue

  sumR += light[neighborIndex * 3]!
  openNeighborCount++
}

incident[index * 3] = (openNeighborCount > 0 ? sumR / openNeighborCount : 0)
  + emissiveIncidentList[index * 3]!
```

第二趟反過來，每個開放格收集六個實心鄰居反射回來的光，疊到自己身上。

```ts
addR += incident[neighborIndex * 3]! * albedoR * BOUNCE_STRENGTH
```

**乘上的是接收方那格的反照色**，顏色就是從這一步開始往外滲。紅牆吐出來的光帶著紅牆的紅，貼著紅牆的空氣於是泛紅，那團泛紅的空氣再照到地板上。%(๑•̀ㅂ•́)و✧%

這種「每一輪從鄰居收一次，直到收斂」的解法叫 Jacobi 迭代，是解擴散方程最直白的一種。

### 每一輪要折損多少

```ts
const BOUNCE_STRENGTH = 0.35
```

現實裡牆面不會把打在它身上的光原封不動吐回去。給太高會越滾越亮，因為每一輪都在疊加；給太低則四輪跑完幾乎沒有效果。

輪數也由畫質設定表決定，從兩輪到六輪。輪數越多，光滲得越遠。

### 最後要扣掉種子

烘完之後有一件很容易忘的事。

一開始種下去的直射光種子，是為了讓傳播有東西可以擴散。但直射光早就由既有的光照處理過了，全局光只該補上「從鄰居傳播過來」的那一份。

```ts
/** 只留傳播進來的那一份，扣掉一開始種下去的直射光種子 */
const r = Math.min(1, Math.max(0, light[index * 3]! - directLight[index * 3]!))
```

不扣的話，被太陽照到的地方會亮兩次。

## 第四步：交給打工仔

這一整套是純粹的陣列運算，跟畫面完全無關，正好丟給 Web Worker。

```ts
const worker = new Worker(
  new URL('./voxel-gi-worker.ts', import.meta.url),
  { type: 'module' },
)
```

送資料的時候有個關鍵，**世界只送一次**。

```ts
function init(param: Omit<VoxelGiInitMessage, 'type'>): void {
  const message: VoxelGiInitMessage = { type: 'init', ...param }
  worker.postMessage(message, [
    message.solidList.buffer,
    message.albedoList.buffer,
    message.skyVisibilityList.buffer,
  ])
}
```

`postMessage` 的第二個參數是轉移清單。列在裡面的 `ArrayBuffer` 會整個把所有權交出去，不複製，原本那一側從此讀不到。這叫 transferable，幾十萬格的陣列因此是零拷貝送過去的。

之所以敢這樣送，是因為世界生成完之後主執行緒不會再讀這份降採樣資料。所有權交出去反而更乾淨。

之後每次重烘只送三個數字。

```ts
worker.bake({
  sunColor: [sunColor.r, sunColor.g, sunColor.b],
  sunStrength,
  bouncePassCount: preset.value.giBouncePassCount,
})
```

回來的那一份也是轉移的。

```ts
workerSelf.postMessage(response, [textureData.buffer])
```

## 第五步：什麼時候該重烘

這個世界不可編輯。方塊的位置、顏色、燈火的位置從頭到尾不會變。

會變的只有太陽。

而太陽在一天裡幾乎每一刻都在動一點點，逐幀重烘不必要也跑不動。所以做法是每半秒檢查一次，只有太陽的方向偏移夠多才真的送出請求。

```ts
const REBAKE_ANGLE_THRESHOLD = 0.018

function update(sunDirection: Vector3) {
  const hasMovedEnough = !lastBakedDirection
    || Vector3.Distance(lastBakedDirection, sunDirection) > REBAKE_ANGLE_THRESHOLD
  if (!hasMovedEnough)
    return

  requestBake(sunDirection)
}
```

門檻大約是一度。日夜循環正常速度下每幾秒才會踩到一次，時間加速時自然烘得更勤。

還要記得擋住重入。

```ts
/** 上一次請求還沒回來，這一輪先跳過，別把 worker 的信箱塞爆 */
if (isBaking)
  return

isBaking = true
```

路人：「烘到一半太陽轉走了怎麼辦？」
鱈魚：「那一份照樣收下，反正下一次檢查很快就到。」

## 第六步：攤平成一張二維的圖集

烘出來的是三維資料，最自然的結構是 3D 貼圖。

不過這份程式碼裡所有既有的烘焙資料（雲影的圖樣、水位圖）用的都是 2D 貼圖，而新引入的 `sampler3D` 會與那些取樣器撞在同一個材質單元上，整批繪製呼叫作廢。既然攤成 2D 圖集本來就是光影包的標準做法，那就走已經驗證過的路。

排法是**每一層 Y 切片一塊磚，磚並排成一張二維的圖**。磚內的兩軸是 X 與 Z，跨磚才是 Y。

```ts
const tilesPerRow = Math.ceil(Math.sqrt(grid.gridY))
const tileRowCount = Math.ceil(grid.gridY / tilesPerRow)
const atlasWidth = tilesPerRow * grid.gridX
const atlasHeight = tileRowCount * grid.gridZ
```

開平方根是為了讓整張圖接近正方形。排成一長條也能用，只是那會做出一張又寬又扁的貼圖，容易撞上顯卡的單邊尺寸上限。

寫出去的時候要照圖集的像素順序走，格子原本的順序在這一步派不上用場。

```ts
for (let y = 0; y < gridY; y++) {
  const tileX = y % tilesPerRow
  const tileY = Math.floor(y / tilesPerRow)

  for (let z = 0; z < gridZ; z++) {
    const atlasX = tileX * gridX + x
    const atlasY = tileY * gridZ + z
    const pixel = (atlasY * atlasWidth + atlasX) * 4
    // ...
  }
}
```

### 水平雙線性，垂直自己來

貼圖的取樣模式給雙線性。

```ts
giTexture = RawTexture.CreateRGBATexture(
  new Uint8Array(atlasWidth * atlasHeight * 4),
  atlasWidth,
  atlasHeight,
  scene,
  false,
  false,
  Texture.BILINEAR_SAMPLINGMODE,
)
```

直覺上這裡會怕，磚與磚在圖上是相鄰的，但在世界裡卻是不同的 Y 層，雙線性會不會把兩層混在一起？

不會。取樣座標是 `tileOrigin + cell + 0.5`，而 `cell` 已經夾在 `[0, gridX - 1]`，換算成紋素中心正好是 `[0.5, gridX - 0.5]`。雙線性的取樣範圍剛好貼齊磚的邊界，一格都不會跨出去。%( •̀ ω •́ )✧%

而最近鄰的代價是實打實的。同一個粗格內（水平四格見方）的間接光完全一樣、格與格之間硬切，地面上因此浮出一塊一塊的矩形。白沙是高明度的平面，最藏不住這種階梯。

垂直方向就得自己來了，因為只有著色器那一份知道哪兩塊磚才是真的相鄰。

```glsl
/** 上下兩層各取一次再內插，垂直方向才不會一階一階跳 */
float slice0 = floor(cell.y);
float slice1 = min(slice0 + 1.0, voxelGiGrid.y - 1.0);

return mix(
  minespaceSampleVoxelSlice(cell.xz, slice0),
  minespaceSampleVoxelSlice(cell.xz, slice1),
  cell.y - slice0
);
```

代價是一次取樣變兩次。

## 第七步：讀回來

整段裡最容易寫錯的就是取樣函式的第一行。

```glsl
vec4 minespaceSampleVoxelGi(vec3 worldPosition) {
  /**
   * 減掉半格，整數點才落在格子中心
   */
  vec3 cell = worldPosition / voxelGiCellSize - 0.5;
  cell = clamp(cell, vec3(0.0), voxelGiGrid - 1.0);
  // ...
}
```

世界座標除以格距得到的座標，整數點落在格子的**邊界**上；而紋素的整數點落在紋素**中心**。兩者差半格。

少了 `- 0.5`，內插的重心整份偏移了半個粗格，也就是兩格方塊。牆角的間接光會固定偏向某一側。

取樣的結果加在霧之前，乘上表面自己的顏色。

```glsl
CUSTOM_FRAGMENT_BEFORE_FOG: `
  color.rgb += minespaceVoxelGi(vPositionW) * baseColor.rgb;
`,
```

乘 `baseColor` 是為了讓這道光帶著表面自己的顏色，而不是憑空疊一層純白。加在霧之前則是因為它補的是間接漫射光，理當跟直射光一樣被霧吃掉。

這一段掛進 `StandardMaterial` 的機制是材質外掛，完整說明見 EP05。這裡只補一件事，取樣的那段 GLSL 是一份匯出的字串，材質外掛與光束的後製都貼同一份。

```ts
export const VOXEL_GI_SAMPLE_GLSL = `...`
```

兩邊讀的是同一張圖，磚的排法一旦對不上就會取到別層的資料，而那種錯在畫面上是看不出來的，只會覺得「顏色怪怪的」。共用一份就不存在對不上這回事。%( ˘•ω•˘ )%

## 完整實作

流程整理一次。

1. 世界生成完，掃一次降採樣成粗網格，順便算天空可見度
2. 三份陣列用 transferable 送進 Worker，只送這一次
3. 每半秒檢查太陽方向，偏移超過一度才送出重烘請求
4. Worker 跑幾輪 Jacobi 傳播，扣掉直射光種子，照圖集順序寫成 RGBA
5. 主執行緒收到就 `giTexture.update(data)`
6. 材質外掛每個片元取樣一次，乘上表面顏色，加在霧之前

最後那道總量開關。

```ts
const GI_INTENSITY = 0.22
```

這個數字原本是 0.5，那讓白沙庭園在正午整片浮起來。這座場景的地是高明度的白沙，正午的線性亮度本來就已經頂在 ACES 的膝點上，貼著天花板的地方再加東西只會把周圍一起推過去，亮部之間的層次全被壓平。

間接光要看得出來的是暗處。%(´,,•ω•,,)%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)

* 間接光的本質是「牆角會反射鄰居的顏色」，環境光那個固定值給不了
* 把世界降採樣成粗網格，每格只記實心與否與概略反照色，格數掉到三千分之一
* 傳播是 Jacobi 式的擴散，實心格收鄰居的光、乘上自己的反照色再吐回去
* 烘焙丟給 Web Worker，世界用 transferable 零拷貝送一次，之後只送太陽
* 世界不可編輯，所以只有太陽角度變夠多時才重烘
* 三維資料攤平成 2D 圖集，水平走雙線性、垂直自己取兩層內插
* 取樣座標要減半格，整數點才落在格子中心

下一章講體積光束，也就是空氣裡看得見的那道光。%♪( ◜ω◝و(و%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /column-minespace/19-volumetric-light.md
description: 背對夕陽站在鳥居底下，光從身後穿過柱子與松枝灑進來。要看得到那一幕，得沿著每一條視線走一遍，還得問空氣願不願意把光散進眼睛。%( •̀ ω •́ )✧%
---

![minespace-cover](/minespace-cover.webp){.cover}

# Minespace - EP19：體積光束

大家好，我是鱈魚。

系列的最後一章，講那道從樹縫裡灑下來的光。%( •̀ ω •́ )✧%

## 光束是什麼

真空裡的光看不見。眼睛能看到東西，是因為光打在那個東西上再彈進眼睛。

空氣不是真空。裡面有水氣、灰塵、分子，光走過去會被它們散開，其中一小部分剛好散進眼睛。所以望向陽光的時候，那一整段空氣本身就是亮的。

而只要有東西擋住陽光，被擋住的那一段空氣就不會亮。亮與不亮的交界畫出來，就是一道光束。%(๑•̀ㅂ•́)و✧%

換句話說，畫光束要回答的問題只有一個，**視線經過的那一段空氣，有多少曬得到太陽**。

## 便宜的那條路

最省的做法是螢幕空間的放射狀模糊。先找出太陽在畫面上的位置，再從每個像素往那個點一路取樣疊加，亮的地方會被拖出一條尾巴。

效果不錯，成本也低。麻煩在於**它需要太陽在畫面裡**。

太陽一轉到背後，投影出來的原點落在畫面之外，那個「往太陽的方向」就沒有意義了，整個效果只能關掉。

於是這座庭園裡最想看到的那一幕反而看不到。站在鳥居底下背對夕陽，光從身後穿過柱子與松枝灑進來，那正是太陽不在畫面裡的時候。

鱈魚：「那就規定玩家一定要看著太陽。」
路人：「你要不要順便規定他幾點上線。」

## 沿著視線行進

換一條路。從鏡頭往每一個像素射一條線，沿路一步一步走，每一步問「這一點的空氣曬得到太陽嗎」，曬得到就累加一點亮度。

太陽在哪個方向完全不影響這個做法成不成立。被遮住的地方自然就暗下來，光束因此是從真的幾何縫隙裡透出來的。

一條線上的空氣有無限多段，沒辦法真的一段一段算，所以改成抽樣。

接下來的三步就是把這張圖翻成程式碼。

## 第一步：算出這條視線指向哪裡

後製拿到的是螢幕座標，要先反推回世界空間的方向。

```glsl
vec4 farPoint = inverseViewProjection * vec4(vUV * 2.0 - 1.0, 1.0, 1.0);
vec3 rayDirection = normalize(farPoint.xyz / farPoint.w - cameraPosition);
```

把畫面座標推到遠平面，轉回世界座標，減掉鏡頭位置就是方向。反矩陣由 CPU 每幀算一次送進來。

```ts
scene.getTransformMatrix().invertToRef(inverseViewProjection)
```

## 第二步：走到撞上實體為止

行進不能穿過牆壁，所以要先知道這條線走多遠會撞到東西。答案在場景深度圖裡。

```glsl
float viewZ = texture2D(depthSampler, vUV).r;
float forwardRatio = max(dot(rayDirection, cameraForward), 0.001);
float rayLength = min(viewZ / forwardRatio, maxDistance);
```

那個除法是必要的。深度圖存的是視空間的 Z，也就是「沿著鏡頭正前方多遠」，而這條射線是斜的。除以兩者的夾角才換算得回沿著射線的距離，少了這一步，越靠畫面邊緣的光束會越早被截斷。

上限給九十格。給太遠的話，同樣的步數會被攤得很稀，光束糊成一片平均的霧；何況霧本來在一百格就開始收，再遠的光束也早就被吃掉了。

## 第三步：起點要抖動

每個像素都從同一個位置起步的話，取樣點會在空間裡排成一層一層等距的殼，畫面上就是一圈一圈的同心紋。

```glsl
float jitter = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
float travelled = stepLength * jitter;
```

加半步以內的隨機位移之後，那些紋被打散成雜訊，而雜訊在這種糊開的效果裡看不出來。與上一章打散色階是同一招。%( ˘•ω•˘ )%

把步數壓到最低最看得出來。

## 第四步：問「這一點曬得到太陽嗎」

這是整套機制最花工夫的地方。

場景本來就有一張陰影圖，但那張在高畫質以上是分層的（CSM）。貼圖是一疊圖層，每一層有自己的矩陣，要在著色器裡挑層、算各層的邊界，那是一整套獨立的機制。而光束只需要「這一點照不照得到太陽」這個最單純的問題。

體素全局光那張粗網格也不行。一格粗格是水平四格、垂直兩格，一叢五格寬的樹冠只佔一到兩格，而且葉子稀疏，擋不出任何邊界分明的陰影體積。量出來的數字很直接，地表往上每一層四千九百格裡有四千八百格以上照得到太陽。可見度處處都是一，光束就沒有東西可以顯現。

所以光束自己畫一張。

### 一台不參與算繪的鏡頭

```ts
const shadowCamera = new TargetCamera('volumetric-shadow-camera', Vector3.Zero(), scene, false)
shadowCamera.mode = Camera.ORTHOGRAPHIC_CAMERA
shadowCamera.orthoLeft = -SHADOW_HALF_EXTENT
shadowCamera.orthoRight = SHADOW_HALF_EXTENT
shadowCamera.orthoTop = SHADOW_HALF_EXTENT
shadowCamera.orthoBottom = -SHADOW_HALF_EXTENT
```

太陽是平行光，投影必須是正交的，透視投影會讓影子近大遠小。

這台鏡頭不會被加進 `scene.activeCameras`，所以它不會真的畫到畫面上，只是拿來定義「從太陽看過去是什麼樣子」。

範圍給五十六格，略大於光束行進的上限。行進走到一半出了圖的話，後半段會突然全部變成「照得到」。

### 存視空間的 Z

```ts
const depthRenderer = new DepthRenderer(
  scene,
  Constants.TEXTURETYPE_FLOAT,
  shadowCamera,
  false,
  Texture.NEAREST_SAMPLINGMODE,
  true,
  'volumetric-shadow-depth',
)
```

最後那個 `true` 是「存視空間的 Z」。另一條路存的是零到一的正規化深度，比較時得把近遠平面再乘回來，而那組數字散在鏡頭上，日後有人動了範圍這裡會靜靜地算錯。存原始的距離，著色器那邊拿同一個視矩陣算一次就比得了。

底色也要改。

```ts
/**
 * 沒有東西的地方要當成無限遠
 */
depthMap.clearColor = new Color4(shadowCamera.maxZ, 0, 0, 1)
```

預設底色是零，那等於「實體就貼在太陽上」，整片天空會被判成遮住了自己，空氣因此全部落在陰影裡。

還有一行很容易漏。

```ts
/** 這張圖不跟著主鏡頭走 */
depthRenderer.useOnlyInActiveCamera = false
scene.customRenderTargets.push(depthMap)
```

預設只有在「正在算繪的就是它綁的那台鏡頭」時才畫，而這台鏡頭永遠不會是主鏡頭。

### 投影中心對齊取樣格

這張圖每幀要跟著鏡頭挪，而怎麼挪決定光束的邊界會不會抖。

```ts
forward.copyFrom(sunDirection).normalize()
Vector3.CrossToRef(Vector3.UpReadOnly, forward, right)
right.normalize()
Vector3.CrossToRef(forward, right, up)

const alongRight = Math.round(Vector3.Dot(position, right) / texelSize) * texelSize
const alongUp = Math.round(Vector3.Dot(position, up) / texelSize) * texelSize
const alongForward = Math.round(Vector3.Dot(position, forward) / texelSize) * texelSize
```

連續跟著走的話，投影矩陣一直在變，同一道邊緣每一幀落在不同的取樣點上，空氣裡的光束邊界會沿著走路的方向不停爬動。

關鍵在於**對齊的座標系必須是光源自己的三軸**。世界座標對齊之後投影到光源空間並不會落在整數格上，而光源是斜的。三軸都對齊之後，只要人沒有跨過一格取樣格，整張圖就是上一幀那一張。

這與地面陰影對齊取樣格是同一件事，講陰影那一章有更完整的說明。

### 查表

```glsl
float minespaceSunVisibility(vec3 worldPosition) {
  vec4 clipPosition = volumetricShadowViewProjection * vec4(worldPosition, 1.0);
  vec2 uv = (clipPosition.xy / clipPosition.w) * 0.5 + 0.5;

  /** 走出這張圖就當作照得到 */
  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
    return 1.0;
  }

  float occluderDistance = texture2D(volumetricShadowSampler, uv).r;
  float sampleDistance = (volumetricShadowView * vec4(worldPosition, 1.0)).z;

  return sampleDistance <= occluderDistance + volumetricShadowBias ? 1.0 : 0.0;
}
```

出了圖的地方判成照得到。判成陰影的話，遠處會憑空冒出一片方形的暗。

容差給半格多一點。這張圖的取樣點本來就在空氣裡、不貼著任何表面，所以可以給得比一般的地面陰影寬鬆。

## 第五步：乘上相位函數

到這裡東西都齊了，但直接加上去的話，正午整片畫面會泛白。

原因不在給得太強，而在**加上去的東西不分方向**。戶外滿視野的空氣都曬得到太陽，於是每一個像素都被加上差不多的亮度。那是一層白幕。

真實的空氣散射是強烈前向的。光束看得見，是因為視線朝著光源看過去，那些光才散得進眼睛；背對太陽時空氣裡照樣有光在散射，只是散射的方向不朝著你。

描述這件事的東西叫相位函數，這裡用的是 Henyey-Greenstein。

```glsl
float scatterPhase(float cosAngle) {
  float g = SCATTER_ANISOTROPY;
  float gg = g * g;
  float denominator = 1.0 + gg - 2.0 * g * cosAngle;

  return (1.0 - gg) / (4.0 * 3.14159265 * pow(max(denominator, 0.0001), 1.5));
}
```

參數 `g` 是不對稱係數。零代表各個方向散得一樣多，趨近一則是幾乎只往原方向繼續走。

加上這一項之後，亮度自己就集中到太陽那一側，正午背對太陽的畫面幾乎不受影響。於是它不必再靠「只在晨昏開啟」來避免泛白，全天候都成立。**這一項一拿掉，整個效果就不成立。**%( •̀ ω •́ )✧%

### 還要補一個底

純粹的前向散射集中得很兇。以 0.45 的不對稱係數算，視線與光線垂直時就已經剩不到一成。

空氣裡本來就有一部分是各向同性的散射，那是多次散射的結果。所以補一個底。

```glsl
const float SCATTER_BASE = 0.18;

float forwardLobe = scatterPhase(cosAngle) / scatterPhase(1.0);
float phaseValue = SCATTER_BASE + (1.0 - SCATTER_BASE) * forwardLobe;
```

除以正對時的值是為了正規化，讓最強的那個方向大約是一，強度那個常數才是說得準的「最亮到什麼程度」。

## 第六步：取沿路的平均

累積完之後怎麼收尾，這裡有個選擇。

散射的量正比於路徑長度，那是物理上對的。看著腳邊的地面只穿過兩三格空氣，望向遠處的松林才穿過幾十格。

但這座場景裡有樹。

樹葉是鏤空的，葉片本身很近、而縫隙後面的東西很遠。同一片樹冠上相鄰兩個像素的行進距離可能差上三倍，跟著距離走的話那道落差會整條印在縫上，樹冠看起來像被吃掉。

而且那條隨距離增長的曲線本來就是重複工，霧與大氣透視已經在做「越遠越濁」這件事了。體積光真正只有它做得到的，是「這一段空氣在不在陰影裡」，而那一項與距離無關。

```glsl
float rawVisibility = accumulated / stepCount;

float nearFade = smoothstep(0.0, NEAR_FADE_DISTANCE, rayLength);
accumulated = rawVisibility * nearFade;
```

改取平均之後，跨過深度邊界時前半段的取樣是共用的，平均值幾乎連續，落差自然就沒了。

只留一段很短的近距離淡入，免得貼著鏡頭的表面也蒙上一層。貼著鏡頭的表面前面幾乎沒有空氣，本來就不該有散射。

## 第七步：亮部保護

還有兩個地方會被推爆。

**天空**。太陽貼近地平線時，望向它的視線幾乎是平的，行進的九十格全是照得到太陽的空氣，累積值頂到滿檔。而那一塊的天色早就貼在色調映射的上限上。

天色本身在那一層就已經調過霞光了，光束再疊上去是同一件事做兩遍。

**被曬到的白沙**。它在 ACES 的膝點上，加什麼都會把周圍一起推過去、把亮部的層次壓平。

判斷方式很重要。拿深度來猜「這是不是天空」會出事，因為深度圖裡有沒有這個網格，會變成畫面的一部分。所以改成直接問亮度。

```glsl
float sceneLuma = dot(sceneColor, vec3(0.2126, 0.7152, 0.0722));
float brightRatio = smoothstep(BRIGHT_START, BRIGHT_FULL, sceneLuma);

/** 「又遠又亮」才算天空，兩個條件缺一不可 */
float farRatio = smoothstep(maxDistance * 0.95, maxDistance * 1.05, viewZ);
float skyRatio = farRatio * brightRatio;

float headroom = mix(1.0, SKY_FLOOR, skyRatio) * mix(1.0, BRIGHT_FLOOR, brightRatio);
```

兩個條件各自擋住一種爆掉的方式。

```mermaid
---
title: 這個像素要不要少加一點光束
---
flowchart TD
    A[這個像素] --> B{比行進上限還遠？}
    B -- 是 --> C{畫面亮度夠高？}
    B -- 否 --> D{畫面亮度夠高？}
    C -- 是 --> E["天空<br/>兩層相乘剩 2.5%"]
    C -- 否 --> F["遠處的暗面（第七步）<br/>照常加<br/>第八步後剩不到四成"]
    D -- 是 --> G["曬到的白沙<br/>收到剩一半"]
    D -- 否 --> H["樹蔭、陰影處<br/>照常加"]
```

天空要「又遠又亮」兩個條件同時成立，兩層保護一起生效，相乘之後只剩 2.5%。只看亮度的話，曬到太陽的白沙一樣很亮，收得夠兇到能壓住天空時，地面上的光束會一起消失。

亮面那一項與距離無關，只收一半，光束打在沙地上仍然看得見。

關掉這一項，望向太陽那一塊會整個爆掉。

## 第八步：天空的保護要留一個底

上面那個寫法我用了一陣子，直到某天注意到太陽外圍鑲著一圈又藍又暗的邊。

鱈魚：「一定是天色的漸層畫錯了，我去把霞光調暖一點。」
路人：「那圈藍就在太陽旁邊，霞光也在太陽旁邊，你調得開嗎？」
鱈魚：「⋯⋯好像調不開。%(´･ω･\`)%」

把整條管線從天色一路算到色調映射，答案在 `brightRatio` 上。

它讀的是已經合成好的畫面亮度，而那份亮度裡含著太陽的光暈。於是光暈每加一分亮度，`headroom` 就扣掉一分光束，兩者互相咬著，形成回授。

這道回授的增益是「相位 × 強度 × 亮度曲線的斜率」，整份跟著亮度走時大約是一點九。大於一的意思是，光暈每加一分，畫面反而暗零點九分。

光暈從亮到零的路上必然要穿過那一段，穿過的那一圈就凹下去，露出光束還沒洗白的原始天色。太陽外圍因此鑲了一道藍邊。

最有趣的是，這件事調光暈完全救不了。

| 光暈強度 | 凹陷深度 | 位置 |
|---|---|---|
| ×1.0 | 14 階 | 6° |
| ×1.5 | 14 階 | 7° |
| ×2.5 | 14 階 | 7.5° |
| ×4.0 | 14 階 | 8.5° |

加強光暈會等比放大回授的兩邊，增益不動，凹陷一階都沒變淺，只是往外移。%(´,,•ω•,,)%

要拿掉它只有一條路，把增益壓到一以下。

```glsl
/** 不管亮不亮，天空至少先吃到六成五的保護 */
const float SKY_GUARD_BASE = 0.65;

float skyRatio = farRatio * mix(SKY_GUARD_BASE, 1.0, brightRatio); // [!code ++]
```

天空還是乘上亮度，只是先墊一層底，跟著亮度走的部分縮到三成五。增益因此掉到一以下，剖面單調，藍邊消失。

順帶還修好另一件事。正午藍天的亮度只有零點五三，落在亮度曲線的起點附近，原本的 `brightRatio` 只剩零點一，`SKY_FLOOR` 幾乎沒生效。整片天多了將近半個單位的暖光，太陽整個糊在裡面看不清楚。

這個常數就是「天要白到什麼程度」的旋鈕。往一調是天空一律保護、光束完全不上天，往零調則回到原本那套。

把它拉到零，那道藍邊就會自己浮出來。%( •̀ ω •́ )✧%

## 幾個工程上的細節

### 迴圈上限必須是編譯期常數

GLSL 的迴圈次數不能是 uniform，所以步數得走兩層。

```ts
const postProcess = new PostProcess(
  'minespace-volumetric-light',
  SHADER_NAME,
  // ...
  `#define MAX_STEP_COUNT ${stepCount}`,
)
```

define 決定「最多幾步」，uniform 決定「這一刻實際走幾步」。

```glsl
for (int index = 0; index < MAX_STEP_COUNT; index++) {
  if (float(index) >= stepCount) {
    break;
  }
  // ...
}
```

步數給三十二。這是全螢幕逐像素的迴圈，成本與步數成正比；而光束的結果沿路平均過，本來就是糊的，從四十八收到三十二看不出差別，省下的卻是三分之一的取樣。

### 不需要的時候要整個卸下來

```ts
setAttached(
  devToggle.volumetricLight
  && currentStrength > 0.001
  && !!sceneDepthState.texture,
)
```

留著而不綁貼圖是會出事的。著色器裡引用了兩個取樣器，只要那兩個材質單元是不完整的，整個繪製呼叫就無效，畫面上剩下的是清除色。

驅動看的是「這支著色器用到了那個取樣器」，不管它有沒有真的執行到。所以只有兩種狀態，要嘛掛上去而且每一幀把該綁的都綁齊，要嘛整個拿掉。

### 插在後製鏈的最前面

```ts
camera.attachPostProcess(postProcess, 0)
```

後製鏈的順序就是套用的順序。光束要在色調映射之前疊上去，才會跟著整個畫面一起被曝光曲線壓過；擺在後面則是疊在成品上，亮部會直接爆掉。

## 完整實作

流程整理一次。

1. 另開一台正交鏡頭對準太陽，每幀畫一張逐方塊解析度的深度圖
2. 投影中心對齊到光源三軸上的取樣格，光束邊界才不會爬動
3. 後製反推每個像素的視線方向，用場景深度圖決定走多遠
4. 起點抖動半步以內，取樣殼打散成雜訊
5. 沿路每一步查那張陰影圖，累積可見度
6. 除以步數取平均，乘上相位函數，乘上亮部保護，乘上強度
7. 加在原本的畫面上，插在後製鏈的第一個位置

這一整套只有最奢的那一級才跑得起來。其餘各級要嘛不做，要嘛用便宜的螢幕空間版本。

## 系列收束

Minespace 從第一章的方塊寫到這裡，十九章。

回頭看，這些效果用的其實是同一批招式。

**造假**。法線改成朝上、陰影量化到像素格、全局光壓成粗網格、散射用一條經驗公式近似。沒有一項是物理正確的，但看起來對。

**注入**。`MaterialPluginBase` 讓你在 `StandardMaterial` 的著色器裡加東西，不必重寫整套光照。雲影、葉片透光、大氣透視、體素全局光都走這條路。

**收邊**。霧、深度、混合模式、繪製順序、取樣器綁不綁得齊，畫面上那些「怪怪的」幾乎都出在這幾件事上。

**量測**。幀率只告訴你慢，不告訴你慢在哪。而「看不到」有兩種，一種是沒算，一種是算了但被色調映射壓平了，這兩種要查的地方完全不同。

**節流**。世界不可編輯，所以全局光只在太陽轉夠多的時候重烘；陰影圖對齊取樣格，所以人沒跨格就整張沿用。省下來的都是每一幀的錢。

而最花時間的往往藏在預設值裡，效果本身反而做得快。%( ˘•ω˘ )%

## 總結 🐟

以上程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/main/content/aquarium/minespace)，場景本身在[這裡](/aquarium/minespace/)。

* 光束是空氣裡的散射，畫它就是回答「視線經過的空氣有多少曬得到太陽」
* 螢幕空間的放射狀模糊很便宜，但太陽一出畫面就沒了
* 沿著視線行進，每一步查一張專用的陰影圖，太陽在哪都成立
* 那張圖是另一台正交鏡頭畫的，逐方塊解析度，投影中心對齊取樣格
* 相位函數讓亮度集中到望向太陽的那一側，少了它整個效果就不成立
* 取沿路平均而不是積分，深度不連續的地方才不會裂開
* 又遠又亮才算天空，亮部保護要看亮度而不是深度
* 天空那道保護要留一個底，整份跟著亮度走會與光暈形成回授，鑲出一圈藍邊
* 迴圈上限是編譯期常數，所以步數走 define 與 uniform 兩層

寫到這裡，這個專欄就告一段落了。

如果這十九章能讓大家在自己的專案裡少繞幾圈，那就值得了。%(\*´∀\`)~♥%

::: tip
因為篇幅問題，某些部分簡單帶過。

若想看到更詳細的解釋，請不吝留言或寫信給我喔！%(\*´∀\`)~♥%
:::

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。有錯誤還請多多指教。%(´,,•ω•,,)♡%

---

---
url: /blog-program/remeda-piped-references-problem.md
description: 使用 remeda piped 時，不小心給自己埋了地雷，來筆記一下。(。-`ω´-)
---

![remeda-piped-references-problem](/remeda-piped-references-problem.webp){.cover}

# remeda piped 之 reference 問題

remeda 提供了一個 [`piped`](https://remedajs.com/docs/#piped) function，可以更方便的組織函數，不過我在使用時遇到了一個問題。

::: tip 甚麼是 Remeda
不知道甚麼是 Remeda 的朋友，可以參考我之前的文章：[好 pipe 不用嗎？藉由 remeda 讓程式碼更簡潔彈性吧！](https://codlin.me/blog-program/remeda-pipe)
:::

考慮以下程式：

```ts
const getList1 = R.piped(
  R.reduce((acc, item) => acc, [])
)

function getList2(list) {
  return R.pipe(
    list,
    R.reduce((acc, item) => acc, [])
  )
}
```

乍看之下，這兩個函數效果相同，但實際上 `getList1` 有一個大坑。

大家猜猜看是甚麼坑？

提示：不是 `remeda` 的問題，是 JS 本身的特性。

還沒看出問題的朋友不用擔心，[實際跑跑看就知道](https://stackblitz.com/edit/piped-reference-issue?file=index.js)了。%( ´ ▽ \` )ﾉ%

## 結果

`getList1` 回傳的結果都是同一個記憶體位置，也就是說，每次呼叫 `getList1` 都會得到同一個陣列。%Σ(ˊДˋ;)%

至於為甚麼，讓我們換個寫法就能理解了，`getList1` 的寫法等校於：

```ts
const initValue = []
const getList1 = R.piped(
  R.reduce((acc, item) => acc, initValue)
)
```

問題在於 `getList1` 的初始值變成一個全域變數，所以每次呼叫 `getList1` 都會得到同一個陣列。

`getList2` 由於初始值的 `[]` 在 function 呼叫時才初始化，所以沒有此問題。

大家在使用 `piped` 時，要特別注意這個問題，以免埋了一個巨大的地雷喔。%(´,,•ω•,,)%

::: tip
補充一個 `remeda` 開發者的[討論](https://github.com/remeda/remeda/issues/1030)，有興趣的人可以一起參與討論。%੭ ˙ᗜ˙ )੭%
:::

## 總結 🐟

* 使用 `piped` 要特別注意可能的 reference 問題。
* 這個不是 `remeda` 的問題，而是 JS 本身的特性。

---

---
url: /blog-ocean-world/test-independent-review-skill.md
description: 快樂的設計了一個審查型 skill，怎麼知道它真的有用？沒有欺騙你的感情？
---

![test-independent-review-skill](/test-independent-review-skill.webp){.cover}

# Skill 寫得很開心，但它真的有用嗎？來嘗試健檢看看

大家好，我是鱈魚 🐟

現在 coding 基本上都使用 AI 了，但如果直接請 AI 審查剛寫完的程式碼，它很常就回一句「整體看起來不錯」結案，然後下一秒程式碼就壞了 %╭(°A ,°\`)╮%

在同一個對話裡審查自己的產出，AI 很容易老王賣瓜，是不是~~像極了某個同事~~。

整個 context 都是它「為什麼這樣寫」的理由，自然會自動護航、繞過自己埋下的地雷。%(´\_ゝ\`)%

於是腦筋一轉，召喚另一個打工仔，改由**子代理人審查**。%( ‧ω‧)ノ╰(‧ω‧ )%

子代理人的 context 沒有你跟主 AI 之前的討論，不知道這段是自己人，可以六親不認的審查。%(⌐■\_■)✧%

試了幾次效果不錯，所以再**讓兩位代理人從不同視角分工**（正確性 + 測試覆蓋率、可行性 + 排程合理性...），互補性又更高 %( •̀ ω •́ )✧%

最後乾脆把整套流程封裝成 skill，取名 `independent-review`，每次寫完東西就審查一下。

你說為甚麼不要開另外一個 AI 工具審查？抱歉我鈔能力不足。%(´；ω；\`)%

不過寫 skill 是一回事，**它到底有沒有用又是另一回事**。

skill 本質上就是一段 prompt 規範，說不定一切都是 AI 幻覺。

就像人生三大錯覺：「手機震動、我能反殺、她喜歡我」，假的，都是假的。%ლ(´•̥̥̥ ω •̥̥̥\` ლ)%

於是試著設計了一套**健檢方法**：預埋蟲蟲、乾淨對照組、黑盒、加上**同題目跑三種審查方式互相對照**，順便試試看不同模型表現差異。

本文就是這場健檢的紀錄。%ヾ(◍'౪\`◍)ﾉﾞ%

## 這個 Skill 在做什麼？

`independent-review` 的核心流程是：

1. 判定產出類型（程式碼 / 計畫 / 規格 / 報告 / 架構）
2. 依類型決定**兩個代理人的正交視角**（例如程式碼配「正確性 + 測試完整性」，計畫配「可行性 + 排程合理性」）
3. 並行啟動兩位 `general-purpose` 代理人
4. 主 AI 整合兩份報告成三層清單
5. 不主動修，給使用者選擇與確認

重點是「**並行**」、「**正交視角**」、「**強制嚴重度標籤與位置**」這三件事。

```md
---
name: independent-review
description: 並行啟動兩個獨立代理人對目前產出（程式碼、計畫、報告、文件、設計）做批判性審查，整合後給出優先順序行動清單
---

# Independent Review

當你完成一輪產出（不論是程式碼、設計計畫、技術報告、規格文件、PR 描述、需求評估）想避免自己的盲點時呼叫本 skill。它用**兩個獨立代理人並行**從不同角度審視同一份產出，最後由 Claude 整合為「必修 / 應補 / 延後」三層清單。

兩個代理人的視角**依產出類型動態決定**（見下方 §3），不硬綁「程式碼 + 測試覆蓋率」。

## 步驟

1. **判定產出類型**（這步決定後續兩個代理人的任務設計，不能省略）：

   先根據使用者參數或現況推論下列類別之一；不清楚就**先問使用者一個簡短問題**確認。

   | 類別 | 典型觸發 |
   |------|---------|
   | 程式碼變更 | 目前在 git 分支、有 commit diff、使用者剛完成 bug fix / feature |
   | 實作計畫 | 使用者剛寫完設計文件、plan-mode 產出的步驟列表、schema migration 規劃 |
   | 技術報告 / 分析 | 調查性文件、A/B 結果、效能分析、事故回顧 |
   | 規格 / 需求 | 功能需求文件、API 契約、使用者故事 |
   | 架構 / 設計 | 系統流程圖、元件劃分、資料流設計 |
   | 其他 / 邊界情境 | DB migration、CI/CD 設定、config 變更、純測試碼、跨類別混合——直接詢問使用者要從哪兩個視角審查 |

2. **收集審查材料**：
   - 程式碼：`git log --oneline -20` + `git diff --stat` 取得變更概觀，並將 `git diff` 全文或關鍵檔案完整內容放入 prompt（不要只給路徑讓 agent 自找，會錯讀片段）。
   - 計畫 / 報告 / 文件：取得完整檔案路徑 + 相關依賴（引用的 spec、先前版本、相關程式碼位置）。
   - 如果有**上一輪審查的結論**，整理成 checklist 傳給代理人，要求逐項驗證。

3. **依類別設計兩個代理人的視角**（原則：兩個代理人要**正交互補**，不是重疊）：

   | 類別 | 代理人 A | 代理人 B |
   |------|---------|---------|
   | 程式碼變更 | 正確性審查：驗證修復是否到位、邊界、有無新問題、API 對齊 | 測試完整性：先確認 coverage 工具可跑，可跑則實測找 0% 方法；否則檢查測試是否涵蓋新行為與邊界、品質如何 |
   | 實作計畫 | 可行性 / 技術風險：架構合理性、依賴、rollback、向後相容 | 排程 / 拆解合理性：步驟粒度、並行機會、遺漏前置條件、估工時 |
   | 技術報告 | 資料正確性 / 論證嚴謹：數據來源、推論鏈、對立假設 | 完整性 / 受眾適配：缺哪些角度、讀者能否看懂、可執行結論 |
   | 規格 / 需求 | 一致性 / 歧義：條款衝突、未定義術語、邊界行為 | 可測試性 / 驗收條件：能否寫出驗收測試、成功標準量化 |
   | 架構 / 設計 | 耦合 / 擴展性：單一職責、模組邊界、未來變動代價 | 故障模式 / 可觀察性：失敗場景、監控、性能瓶頸 |

   若情境混合（例如 PR 同時含程式碼+規格文件），**擇主要產出類型**，在另一代理人的 prompt 裡補上次要角度的檢查項。

   對於 A、B 視角天生重疊較高的類別（如「實作計畫」的可行性與排程），在每位代理人的 prompt 末段明確列出「對方負責的範圍」，要求避開重疊區、聚焦自己的視角。

4. **並行啟動兩個 `general-purpose` 代理人**（同一個 tool-use 訊息發兩個 `Agent` 呼叫 + `run_in_background: true`）。每個 prompt 應包含：

   - **背景段**：產出位置、範圍、最近的決策脈絡、上一輪結論（如有）
   - **角色段**：明確說明此代理人負責的審查視角（見 §3 表）
   - **逐項檢查清單**：把關鍵檢查點列成題目要求代理人逐一回答
   - **產出格式要求**：
     - 每項發現標示**嚴重度**（Critical / High / Medium / Low / Nitpick）
     - 每項附具體位置（file:line、段落標題、表格行）
     - 分開列出「新發現」vs「已在上一輪提出」
     - 對於 known-issue 與真正 bug 明確分辨
   - **反客套指示**：「不要說整體看起來不錯、直接指出問題」「若此項確實通過，明確標 pass」

   Prompt 應足以涵蓋背景脈絡、角色定義、5–8 條具體檢查項與產出格式；越精確產出越可用。

5. **等代理人完成**（背景任務完成會自動通知；不要主動 poll / sleep）。

6. **整合報告**（由 Claude 自己做，不要再開第三個彙整代理人）：
   - 開表格比對兩個代理人的發現是否相互印證、矛盾、或互補。
   - 將所有 action 分成三層並給明確位置：
     - **必修** — 合併 / 送出前應處理的真實 bug、破壞性變動、嚴重遺漏
     - **應補** — 短期內應追加的測試、文件段落、計畫拆解細節
     - **延後** — 另開 issue / ticket 追蹤的大型改進（架構重構、抽換 logging / 監控、共用模組拆分）
   - 每項附難度標籤（trivial / medium / hard）或預估改動規模（單行 / 單檔 / 跨檔），不要強行估時數——AI 估時普遍不準。

7. **請使用者決策**：提供明確選項（全做 / 只做必修 / 補某類別 / 僅報告）讓使用者挑，**不要擅自動手**。

## 注意事項

- **兩個代理人都用 `general-purpose` subagent_type**（需要完整讀檔與跨檔分析）；不要用 `Explore`，它只適合定位搜尋、會錯過讀取視窗外的內容，不適合批判性審查。
- **務必並行**：同一訊息裡發兩個 `Agent` 呼叫並 `run_in_background: true`，避免序列浪費時間。
- **視角要正交**：兩個代理人不能做一樣的事。程式碼是「正確性 + 覆蓋率」；計畫是「可行性 + 排程」；報告是「正確性 + 完整性」……依 §3 表選。
- **產出格式強制**：嚴重度標籤、具體位置、pass/fail 標記是必填；不符合的回報要求代理人補齊或自己標註。
- **前後端 / 跨 repo 情境**：在 prompt 中明確告知兄弟目錄路徑（例如 `../<sibling-repo>/`），讓代理人能搜相依。
- **整合階段由 Claude 親自做**：兩份報告都在脈絡裡，直接比對更準確；開第三個代理人會失真。
- **此 skill 不自動動手修復**：即使找到 Critical bug，也先呈報後等使用者指示。
- **規劃初期（從零開始）**請用 `brainstorming`；本 skill 只做「已有產出」階段的批判審查。

```

## 我書讀得不多，你不要騙我 QQ

驗證一個審查型 skill 有沒有效，最容易出現的盲點就是 AI 說的頭頭是道，實則胡說八道。%(。-\`ω´-)%

尤其沒有足夠的背景知識可以判斷時，就很容易被 AI 拐著走。%(◓Д◒)%

就像「幾乎百分之百的癌症患者體內都含有大量的『[氫氧基酸](https://zh.wikipedia.org/zh-tw/%E4%B8%80%E6%B0%A7%E5%8C%96%E4%BA%8C%E6%B0%A2%E6%81%B6%E4%BD%9C%E5%89%A7)』，這種物質也是酸雨的主要成分，若吸入肺部甚至會導致窒息死亡，與其固體形式長時間接觸會導致嚴重的組織損傷，我們應該嚴格管制！」，聽起來很合理，但完全經不起推敲 %( ´\_ゝ\`)%

甚麼？你說上面這段話聽起來很正確？...我敬你一杯氫氧基酸。%(◐‿◑)%

反之如果不用 skill、直接拋一句「請審查」也能找到相同等級的問題，此 skill 就毫無價值，徒耗 token 而已。%(◞‸◟ )%

於是定了四條原則：

1. **預埋蟲蟲**：每個案例事先寫好「我植入了哪些 bug、什麼嚴重度、位置在哪」當成考古題答案。代理人能不能找到，可量化打分。
2. **加入乾淨對照組**：刻意做一個沒 bug 的小案例，看代理人會不會**捏造**問題（誤報率）。
3. **黑盒設計**：寫一行 `禁讀 GROUND_TRUTH.txt` 在 prompt 裡，避免代理人偷看答案。
4. **三組對照**：對每個 case 同時跑 skill、詳細 prompt、籠統 prompt 三種審查方式，比命中率與誤報率，證明 skill 真的帶來增量價值。

評分維度三層：

* **結構面**：skill 有沒有並行起兩個代理人？有沒有用 `general-purpose`？視角是不是依表格選的？
* **發現面**：預埋蟲蟲抓到幾個？有沒有瞎掰不存在的 Critical？
* **流程面**：最後有沒有照三層清單整合？有沒有越權自動修復？

### 三組 prompt 對照怎麼設計？

對每個 case 跑三組：

| 組別 | Agent 數 | Prompt 設計 | 對標目的 |
| ---- | -------- | ----------- | -------- |
| **Skill** | 2 位並行 | 完整檢查清單 + 正交視角分工 | 實驗組 |
| **詳細 prompt** | 1 位 | 完整檢查清單 + 雙視角合一 | 測「並行設計是否必要」 |
| **籠統 prompt** | 1 位 | 「請審查這個」一句話 + 防污染條款 | 測「skill 是否必要」 |

::: info 「防污染條款」是哪兩條？

1. 禁讀同資料夾 `GROUND_TRUTH.txt`（評分用標準答案）
2. 禁讀 `.claude/skills/` 與任何 `SKILL.md`（避免代理人直接抄 skill 結構）

第 1 條是黑盒測試的常識，第 2 條則是確保「籠統」這個對照組真的籠統。否則強模型會自己 ls 專案結構找到既有 skill 模板，讓對照失準 %(꒪ཀ꒪)%
:::

跑完一次可同時回答兩個問題：

1. **不用 skill 也能達到效果嗎？**（籠統 vs skill）
2. **「並行 + 正交」真的必要嗎？**（詳細單 agent vs skill 並行兩位）

## 4 個案例設計

技術堆疊使用我熟悉的 Vue 3。%(´,,•ω•,,)%

### Case A：Vue Composable 程式碼變更

寫了一個 `usePagedList<T>` composable，做陣列分頁。預埋 4 個 bug：

```ts
const items = computed(() => {
  const start = (page.value - 1) * pageSize
  const end = page.value * pageSize
  return source.value.slice(start, end + 1) // [!code error] // ← Critical：多取一筆
})

function next() {
  if (page.value <= pageCount.value) { // [!code error] // ← High：應為 <
    page.value += 1
  }
}
```

另外還有 `pageSize = 0` 無防呆、空陣列邊界沒處理。測試檔則刻意只測快樂路徑，邊界全缺。

### Case B：Vue 列表分頁 composable 重構計畫

寫了一份「把三個列表頁重複的分頁邏輯抽成 `usePagedList` composable」的 3 天計畫。預埋：

* **沒有 rollback 計畫**
* **Step 3 依賴 Step 5 才建立的 `PAGE_SIZE_KEY` provide token**（依賴順序錯誤）
* **`usePagedList` 測試擺在 Step 4 而非緊接 Step 2**（TDD 順序錯誤）
* 用字串 `'PAGE_SIZE_KEY'` 當 provide key（應改 `InjectionKey<number>`）
* 估時無拆解依據（順便埋了個計算錯誤，逐項加總 4 天卻寫「合計 3 天」%(´∀\`)%）

### Case C：`<BaseDialog>` 元件 API 規格

寫了一份共用對話框元件的 API 規格，預埋：

* §2「不可關閉時不應允許點背景關閉」與 §5「重要訊息時點背景仍應允許關閉」**直接衝突**
* 「不可關閉」、「重要訊息」、「背景」全部沒對應 prop 或定義
* §4「動畫應流暢」沒有量化（ms / FPS / easing 都沒）
* 焦點管理（focus trap、return focus、aria-\*）整個沒提
* 「QA 跑過即可上線」不可驗收

### Case D：對照組（無預埋）

刻意寫了一個乾淨的 `useDebouncedRef`（customRef 版 debounced ref），測試也涵蓋了初始值、延遲、連續寫入、依賴重跑、預設值。

預期：所有代理人**不應**標 Critical / High，至多 Nitpick / Low。

鱈魚：「對照組相當重要，以免 AI 湊字數，硬是瞎掰一堆問題 %( ・ิω・ิ)%」

路人：「就像你期末考明明一題都不會，還是要硬湊幾個字那樣嗎？%(´・ω・\`)%」

鱈魚：「說好不提這個的...%(╥ω╥\`)%」

## 代理人開工

4 case × 3 組（skill 2 位 + 詳細 1 位 + 籠統 1 位）× **3 種模型（Opus 4.7、Sonnet 4.6、Haiku 4.5）** = **48 位代理人**，全部用 `Agent` + `run_in_background: true` 開工 %( •̀ ω •́ )✧%

每位代理人的 prompt 都一致（只差 `model` 參數），包含：

* **背景段**：產出位置（絕對路徑）、範圍
* **角色段**：明確視角（如「你只負責程式碼正確性，不要評論測試覆蓋率」），籠統 prompt 組則略過
* **檢查清單**：5–8 條要求逐條 pass / fail，籠統 prompt 組不給
* **產出格式**：嚴重度標籤、檔案行號、通過項目分開列
* **反客套**：「禁說『整體看起來不錯』」、「沒問題就明確標 pass」、「不要捏造，標 Critical 必須能描述觸發路徑」
* **禁讀 GROUND\_TRUTH.txt**：黑盒測試的關鍵

## 結果摘要

三種模型對同一份 fixture 跑同樣 prompt，光看「能不能找到蟲」差異不大，但**會不會亂標 Critical / High 差很多**。%ԅ(´∀\` ԅ)%

### Case A~C 預埋命中率（任一嚴重度提及該蟲蟲表示找到）

| 案例 | 模型 | Skill | 詳細 prompt | 籠統 prompt |
| ---- | ---- | ----- | ------------ | ------------ |
| A 程式碼 | Opus 4.7 | 9 / 9 | 9 / 9 | 7 / 9 |
| A 程式碼 | Sonnet 4.6 | 9 / 9 | 9 / 9 | 6 / 9 |
| A 程式碼 | Haiku 4.5 | 9 / 9 | 9 / 9 | 6 / 9 |
| B 計畫 | Opus 4.7 | 9 / 9 | 9 / 9 | 7 / 9 |
| B 計畫 | Sonnet 4.6 | 9 / 9 | 9 / 9 | 4 / 9 |
| B 計畫 | Haiku 4.5 | 8 / 9 | 8 / 9 | 5 / 9 |
| C 規格 | Opus 4.7 | 10 / 10 | 10 / 10 | 10 / 10 |
| C 規格 | Sonnet 4.6 | 10 / 10 | 10 / 10 | 8 / 10 |
| C 規格 | Haiku 4.5 | 10 / 10 | 10 / 10 | 6 / 10 |

### Case D 對照組誤報率（預期 0 Critical / 0 High）

| 模型 | Skill 視角 A | Skill 視角 B | 詳細 prompt | 籠統 prompt |
| ---- | ----------- | ----------- | ------------ | ------------ |
| Opus 4.7 | 0C / 3H | 0C / 1H | 0C / 4H | **2C** / 0H |
| Sonnet 4.6 | **0C / 0H** ✓ | 0C / 1H | 1C / 3H | **0C / 0H** ✓ |
| Haiku 4.5 | **1C** / 1H | **1C** / 0H | **1C** / 2H | 0C / 0H ✓ |

其中：

* C = Critical
* H = High

整體看起來：

* **命中率**：三種模型在 skill / 詳細 prompt 都接近滿分；籠統 prompt 下 Opus 還能撐到 86%，Sonnet 跟 Haiku 都掉到 6 成
* **Case D 誤報**：Haiku 在 skill / 詳細都標 Critical，三種模型裡最愛找蟲湊字數；Opus 籠統也標了 2 個 Critical，是 正式環境等級 議題（onScopeDispose 缺失、timer 變數位置），但對小型 refactor 來說標太用力 %(´\_ゝ\`)%
* **Sonnet 4.6 最貼近標準答案**：Case D skill 視角 A 與籠統 prompt 都給出 0 Critical / 0 High，跟預期一致
* **Opus 4.7 標 High 標得重，還常常把正式環境等級議題當 Critical**：對 Case D 的 unmount cleanup、SSR、delayMs 動態調整都標 High 或 Critical，其實是設計取捨而非 bug

## Case A 三種模型完整報告對照

全部例子都列出來太多了，這裡只舉 Case A 作為代表。%乁( ◔ ௰◔)「%

同一份 `usePagedList.ts` + `usePagedList.spec.ts`，丟給三種模型的 skill 流程（兩位代理人並行：A 視角正確性、B 視角測試完整性），三份結果濃縮如下：

::: details Opus 4.7
**視角 A（正確性）：**

* \[Critical] `usePagedList.ts:32` → `next()` 守衛 `<=` 應為 `<`，連續 next 會讓 page 超過 pageCount（觸發路徑：source 長度 10、pageSize 5，連按 next 兩次 page=3 → items=空）
* \[Critical] `usePagedList.ts:22` → pageSize=0 時 pageCount=Infinity、items 切片仍回 1 筆，next 可無限累加；pageSize 負數時守衛立即失效
* \[High] `usePagedList.ts:28` → `slice(start, end + 1)` 每頁多取 1 筆
* \[High] `usePagedList.ts:21-23` → 空 source 時 pageCount=0 但 page=1，「第 1 頁／共 0 頁」不一致
* \[High] `usePagedList.ts:47` → `watch(source)` 預設淺層，原地 push/splice 不會重置 page
* \[High] `usePagedList.ts:3-6` → `source` / `pageSize` 不符 Vue 3 慣例（應為 `MaybeRefOrGetter`）
* \[Medium] `pageSize` 解構為純值，失去 reactivity
* \[Medium] 回傳型別宣告為 `Ref<number>` 但實際是 `ComputedRef`，誤導呼叫端
* \[Low] `Math.ceil` 不擋非整數 pageSize
* **Passed**：`prev` 守衛、`reset` 行為、泛型 `<T>` 簽章

**視角 B（測試完整性）：**

* \[Critical] `usePagedList.spec.ts:9` → 「回傳第一頁資料」斷言 `[1,2,3]`，但實作回 `[1,2,3,4]`，**這代表測試從未實際 run 過**
* \[Critical] `usePagedList.spec.ts:17` → 「next 切換到下一頁」斷言 `[4,5,6]` 表面通過，是 source 邊界剛好掩蓋 bug 的巧合
* \[Critical] 未測 next 在末頁（漏掉 A2 守衛）
* \[Critical] 未測 `source.value = [...]` 變動時 page 是否重置
* \[High] 未測空陣列 / source 少於 pageSize
* \[High] 未測 pageSize = 0 / 負數
* \[High] 未測 prev 在第一頁
* \[High] `reset()` 整個函式零覆蓋
* \[Medium] `next` 後寫 `await nextTick()` 多餘
* \[Medium] 缺泛型 / 物件型別測試
  :::

::: details Sonnet 4.6
**視角 A（正確性）：**

* \[Critical] `usePagedList.ts:28` → `slice(start, end + 1)` 應為 `slice(start, end)`（觸發路徑：pageSize=3、source=\[A,B,C,D,E,F]，第 1 頁期望 \[A,B,C] 實際 \[A,B,C,D]）
* \[High] `usePagedList.ts:32` → `next()` 守衛 `<=` 允許 page 超出 pageCount
* \[High] `usePagedList.ts:21-23` → pageSize=0 → pageCount=Infinity；pageSize 負數 → pageCount 為負
* \[Medium] `usePagedList.ts:4` → source 型別限縮為 `Ref<T[]>`，不接受 Getter / Reactive
* \[Medium] `usePagedList.ts:47-49` → `watch(source)` 僅 lazy，原地 push/splice 不觸發
* **Passed**：`prev` 守衛、`reset`、`pageCount` computed、`page` 型別、回傳介面完整

**視角 B（測試完整性）：**

* \[Critical] `usePagedList.ts:31-35` → 未覆蓋 next 在末頁，無法暴露 `<=` bug
* \[Critical] `usePagedList.ts:28` → 第一個測試斷言應 fail 但表面通過，**強烈懷疑測試套件從未成功執行**
* \[High] 缺空陣列 / source 少於 pageSize
* \[High] 缺 pageSize=0 / 負數
* \[High] 缺 source 變動 page 是否重置（watch 行為）
* \[High] 完全沒有 prev 測試
* \[Low] 只測 `number[]`，未測物件陣列
  :::

::: details Haiku 4.5
**視角 A（正確性）：**

* \[Critical] `usePagedList.ts:28` → `slice(start, end + 1)` 邏輯錯誤，每頁多取一筆
* \[Critical] `usePagedList.ts:32` → `next()` 守衛 `<=` 會讓 page 超過上限（觸發路徑：source=50 筆、pageSize=10，第 5 頁呼叫 next() → page=6）
* \[High] `usePagedList.ts:22` → pageSize=0 / 負數無防禦，會 Infinity 或負無窮
* \[High] `usePagedList.ts:4-5` → source / pageSize 型別過嚴格，應接受 MaybeRefOrGetter
* \[Medium] 空陣列時 pageCount 與 page 不一致
* \[Medium] pageCount 變化未觸發 items 邊界檢查
* \[Low] `watch` 缺 `{ deep: true }` 選項

**視角 B（測試完整性）：**

* \[Critical] `usePagedList.spec.ts:6-10` → 第一個測試 assertion 錯誤，slice(0, 4) 應返回 \[1,2,3,4] 但 expect \[1,2,3]，**測試應該會失敗，表示測試沒實際執行過**
* \[High] 未測 next 末頁（暴露 `<=` bug）
* \[High] 未測 prev、source 變動、空陣列
* \[Medium] 未測 pageSize ≤ 0 防呆
* \[Medium] 未測物件陣列型別
  :::

### 報告差異

三種模型都抓到 A1（slice +1）、A2（next 守衛）這兩個核心 bug，也都從「斷言對不上」反推到「這份測試根本沒跑過」這層更深的結論，連 Haiku 都看出來了。%(｢･ω･)｢%

Haiku：「說好的尊重呢？%(°A ,°\`)%」

**Opus 4.7**：條目最多最細，Critical 給最多。把 A4（空陣列）、`watch` 淺層、`MaybeRefOrGetter` 全列，甚至延伸到 `ComputedRef` 型別宣告、`Math.ceil` 不擋小數。整合者要做的工作最多。

**Sonnet 4.6**：嚴重度最克制，只給一個 Critical（A1）。A2 只給 High，乍看保守，但 A2 標準答案就是 High，**反而 Sonnet 校準到位**。報告結構完整，passed 段最清楚。

**Haiku 4.5**：條目精煉，重點都中但描述偏淺。對 Vue 慣例（MaybeRefOrGetter、watch deep）有提到但不深入。速度則是三種模型中最快（多數 < 20s）。

簡單說就是 Haiku 愛碎碎念、Sonnet 腦子打結、Opus 有點激動。%(◜௰◝)%

## 所以此 Skill 效果如何？

### 1. vs 籠統 prompt：提高命中率

籠統 prompt（「請審查這個」一句話 + 防污染條款）在不同模型下命中率差距很大，但 skill 可以填平差距。

| 模型 | 籠統 prompt 平均命中率（A+B+C） | skill 平均命中率 | 提升 |
| ---- | --------------------- | --------------- | ---- |
| Opus 4.7 | 86%（24/28） | 100%（28/28） | +14 |
| Sonnet 4.6 | 64%（18/28） | 100%（28/28） | +36 |
| Haiku 4.5 | 61%（17/28） | 96%（27/28） | +35 |

**Opus 自己就能撐到 86%**，籠統 prompt 都吃得下；**Sonnet 跟 Haiku 都掉到 6 成上下**，少了 skill 的視角分工 Sonnet 表現幾乎跟 Haiku 一樣。

skill 把不同模型拉到接近滿分，**對 Sonnet 提升最大**（+36），等於把它從「會漏掉三成多」拉到「幾乎不漏」%( •̀ ω •́ )✧%

### 2. vs 詳細 prompt：標記比較冷靜

詳細 prompt（單 agent + 完整檢查清單）命中率跟 skill 平手（都接近 100%），差異在 Case D 對照組標多重：

| 組別 | 三種模型 Critical 誤報合計 | 三種模型 High 誤報合計 |
| ---- | --------------------- | ------------------ |
| Skill（兩位 agent 並行） | 2 | 6 |
| 詳細 prompt（一位 agent + 雙視角合一） | 2 | 9 |

Critical 持平，但 skill 標的 High 比詳細 prompt 少 1/3（6 vs 9）。

原因是兩個 agent 各管一個視角，**每個 agent 不需要硬找超出自己範圍的問題**，自然就不會標太重。%(*´ω`)人(´ω`*)%

### 3. 誰是瞎掰王

Case D 是乾淨案例，用來挖洞給模型跳，正常不該標出 Critical、High。%ԅ(´∀\` ԅ)%

| 模型 | Critical 誤報 | High 誤報 |
| ---- | ----------- | -------- |
| Opus 4.7 | 0 | 8 |
| Sonnet 4.6 | 1 | 5 |
| Haiku 4.5 | **3** | 3 |

* **Haiku**：對 unmount cleanup、SSR setTimeout、scope dispose 標 Critical，是真實 production 議題沒錯，但用在小型 refactor 上太用力
* **Sonnet**：唯一 Critical 出在「timer 跨 instance 共享」，標完又自己澄清「實務上不會發生」
* **Opus**：零 Critical 誤報，但 High 標得很重，立場偏向「正式環境就該處理」

## 小筆記

### Claude Code 的 Explore 與 general-purpose

代理人類型可選 `Explore` 或 `general-purpose`。

`Explore` 速度快、占用 context 也少，乍看像審查的不二之選。

不過 Claude Code 官方文件提到：

> Fast read-only search agent for locating code. Use it to find files by pattern, grep for symbols or keywords, or answer "where is X defined / which files reference Y." **Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window.**

意思是 `Explore` 適合定位、搜尋，**不適合 code review、設計文件審查、跨檔一致性檢查**，因為它只讀片段不讀完整檔案，視窗外的內容會直接被略過。

口說無憑，我們把 Case A 丟給 `Explore` 跟 `general-purpose` 並用籠統 prompt 實驗看看。

| 模型 | general-purpose | Explore |
| ---- | ------------------ | ------ |
| Opus 4.7 | 7/9 | 8/9 |
| Sonnet 4.6 | 6/9 | 6/9 |
| Haiku 4.5 | 6/9 | **4/9** |

Case A 不到 100 行，Opus 跟 Sonnet 差距吃不太出來，**Haiku 倒是少抓 2 個**。

文件警告的「漏看內容」風險主要在「弱模型 + 大檔案 + 跨檔分析」這種情境才會放大，小檔案上很難看出來。

審查需要完整脈絡，所以用 `general-purpose`，雖然慢一點、貴一點，至少不會發生「有看但是不多」這種事 %( ・ิω・ิ)%

## 總結 🐟

* **Skill 可以填平模型差距**：強模型（Opus）光看一句「請審查」就能撐到 86% 命中率，但弱模型（Sonnet、Haiku）會掉到 6 成左右。套上 skill 後三種模型都拉到 99%，所以 skill 對弱模型補強最大。

* **計畫類審查效果良好**：Case B 計畫類在籠統 prompt 下 Sonnet 只剩 4/9、Opus 7/9，skill 把這兩個視角強制拆給兩位代理人後，弱模型也能做得不錯 %( •̀ ω •́ )✧%

* **不同模型有不同毛病**：Haiku 快但常亂標 Critical（瞎掰王是你）；Sonnet 嚴重度標籤最貼近實際；Opus 立場像資深 PM，所有正式環境議題都標 High。

* **Skill 對弱模型有副作用**：逐項清單會逼 Haiku「每項都要回答」，沒問題也硬塞 Critical。skill 改進一下應該可以解決，有機會再來試試。

目前看來，可以試試模型混搭，Haiku 海撈、Sonnet 整合、Opus 最後把關，下次再來試試吧。%∠( ᐛ 」∠)\_%

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去 %(\*´∀\`)~♥%

有錯誤或不周全之處，還請多多指教 %( ´ ▽ \` )ﾉ%

---

---
url: /blog-ocean-world/orpc-vs-ts-rest.md
description: ts-rest 作者人間蒸發，許久沒更新，來試試看 oRPC 吧
---

![orpc-vs-ts-rest](/orpc-vs-ts-rest.webp){.cover}

# ts-rest 躺得很安詳，決定來認識認識 oRPC

大家好，我是鱈魚 🐟

前陣子回頭翻自己寫的 [ts-rest 實務篇](/blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest-practical-experience)，順手到 npm 上看了眼版本。

`@ts-rest/core` 停在 `3.52.1`，最後更新是 2025 年 6 月。

我一直在等的 `3.53.0`（支援 Standard Schema 的版本）呢？躺在 `rc` 標籤裡，相當安詳。%(´・ω・\`)%

不管是 GitHub 還是 Discord 都找不到作者，作者人間蒸發惹 %( ´•̥̥̥ ω •̥̥̥\` )%

反正 AI 改很快，來試試看 oRPC 吧。%ԅ( ˘ω˘ԅ)%

說是這麼說，別衝動改舊專案，新專案或實驗專案再來試試看。%( ´ ▽ \` )ﾉ%

相關套件版本如下：

* @orpc/server、@orpc/client、@orpc/contract：`1.14.14`
* @ts-rest/core：`3.52.1`（`3.53.0-rc.1` 尚未轉正）

## 甚麼是 oRPC？

[oRPC](https://orpc.dev/) 全名為 OpenAPI Remote Procedure Call，同樣是端到端型別安全的 TypeScript 工具。

名字其實已經把重點講完了，它是 RPC 風格，但同時相容 OpenAPI 規範。

### 最短的範例

先定義一個 procedure，這是 oRPC 的最小單位。

`server/router.ts`

```ts
import { os } from '@orpc/server'
import * as z from 'zod'

export const findPlanet = os
  .input(z.object({ id: z.string() }))
  .handler(async ({ input }) => ({
    id: input.id,
    name: '地球',
  }))

export const router = {
  planet: { find: findPlanet },
}
```

前端拿到的東西長這樣。

`web/api.ts`

```ts
import type { RouterClient } from '@orpc/server'
// 就是上面那包 router，用 import type 拿進來
import type { router } from '../server/router' // [!code highlight]
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'

const link = new RPCLink({ url: 'http://localhost:3000/rpc' })
const client: RouterClient<typeof router> = createORPCClient(link)

const planet = await client.planet.find({ id: '1' })
```

沒有 method、沒有 path、沒有 status code，就是呼叫一個函式，回傳值直接就是資料。

### 想要 REST 也可以

剛才那個範例走的是 oRPC 自家的 RPC 協定，那想變成 REST 呢？

router 一個字都不用改，換掉伺服器上的 handler 就好。

```ts
// 走 oRPC 自家協定
import { RPCHandler } from '@orpc/server/fetch'

const handler = new RPCHandler(router)
```

```ts
// 走標準 REST
import { OpenAPIHandler } from '@orpc/openapi/fetch'

const handler = new OpenAPIHandler(router)
```

兩者的 `handle()` 介面完全相同，所以接線的程式碼也不用動。

```ts
export default async function fetch(request: Request) {
  const { matched, response } = await handler.handle(request, {
    prefix: '/api',
    context: {},
  })

  return matched ? response : new Response('Not Found', { status: 404 })
}
```

所謂「換一種協定」，其實就只是換掉 `new` 後面那個字而已。%ヾ(◍'౪\`◍)ﾉﾞ%

那端點路徑會長怎樣？沒特別指定的話，oRPC 會給一組預設值。

* method 是 `POST`
* path 由 router 的 key 用 `/` 串起來
* 成功狀態碼是 `200`

以剛才的 `planet.find` 為例，端點就是 `POST /api/planet/find`，能跑，但很 RPC 味。%(  ˙꒳​˙)%

想要像樣的 RESTful 端點，就要自行補上 `.route()`。

```ts
export const findPlanet = os
  .route({
    method: 'GET',
    path: '/planets/{id}',
    successStatus: 200,
  })
  .input(z.object({ id: z.string() }))
  .handler(async ({ input }) => ({ id: input.id, name: '地球' }))
```

端點就變成 `GET /api/planets/{id}` 惹。路徑參數用大括號 `{id}`，不是 ts-rest 的 `:id`，這點要習慣一下。

::: tip `.route()` 只對 OpenAPIHandler 有意義
走 `RPCHandler` 時，路徑一律由 router 的 key 決定，`.route()` 標的 method 與 path 完全用不到。

換句話說 `.route()` 不是必填，除非你在意端點好不好看，或是要接 `@orpc/nest`（後面會聊到，那邊強制要求）。%(´,,•ω•,,)%
:::

兩種 handler 的取捨如下。

* `RPCHandler`：oRPC 自家協定，Date、Set 等型別原樣送達，但人類看不懂
* `OpenAPIHandler`：標準 REST，可以直接產生 OpenAPI spec 丟給別人，代價是型別會被 JSON 化

也可以兩個一起掛，一條 `/rpc` 給自家前端，一條 `/api` 給外部串接 %(ゝ∀・)b%

產生 spec 也相當簡單：

```ts
import { OpenAPIGenerator } from '@orpc/openapi'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'

const generator = new OpenAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
})

const spec = await generator.generate(router, {
  info: { title: '鱈魚水族館 API', version: '1.0.0' },
})
```

### 當然也有合約優先（contract-first）

ts-rest 只有 contract-first 一條路，oRPC 兩種都行。

想先立合約的話，改用 `@orpc/contract` 的 `oc`。

```ts
import { oc } from '@orpc/contract'
import * as z from 'zod'

export const planetContract = {
  find: oc
    .route({ method: 'GET', path: '/planets/{id}' })
    .input(z.object({ id: z.string() }))
    .output(planetSchema),
}
```

後端用 `implement` 把合約轉成實作器。

```ts
import { implement } from '@orpc/server'

const os = implement(planetContract)

export const router = os.router({
  find: os.find.handler(async ({ input }) => getPlanet(input.id)),
})
```

`os.router()` 會強制檢查實作有沒有對齊合約，少一支 procedure 就會把錯誤噴到你眼前。%(・∀・)９%

這時候前端改成從合約推型別。

```ts
import type { ContractRouterClient } from '@orpc/contract'
import { planetContract } from '@project-code/shared'

const client: ContractRouterClient<typeof planetContract> = createORPCClient(link)
```

合約要怎麼共享？和概念篇的結論一樣，私有 npm 或 monorepo 挑一個。%ԅ( ˘ω˘ԅ)%

## 心智模型

比較表如下，第一列是關鍵部分。

| 項目 | ts-rest | oRPC |
| --- | --- | --- |
| 合約本體 | HTTP 端點描述（method、path、responses） | 函式簽章（input、output、errors） |
| REST | 必須 | 選配，靠 `.route()` 開啟 |
| 錯誤處理 | HTTP status code + response schema | 具名 typed error |
| 驗證器 | Zod（`3.53.0` 起支援 Standard Schema） | Standard Schema，Zod、Valibot、ArkType 隨你挑 |
| 可傳輸型別 | JSON 表達得出來的範圍 | 外加 Date、BigInt、Set、Map、File、Blob 等 |
| 後端整合 | Nest、Express、Fastify、Next 等 | Nest、Hono、Elysia、Node、Bun、Deno、Workers 等 |
| 前端整合 | Fetch Client、TanStack Query（React / Vue / Solid） | Fetch Client、TanStack Query（React / Vue / Solid / Svelte / Angular）、Pinia Colada |
| 最新穩定版 | `3.52.1`（2025-06） | `1.14.x`，持續更新中 |

## 實務篇在 oRPC 會怎樣？

來看看實務篇提到的內容，換成 oRPC 會變怎樣。%◝( •ω• )◟%

為了方便對照，以下沿用實務篇的分法，一樣切成三塊。

1. 通用概念

   不分前後端的注意事項

2. 前端

   Client 初始化、結果與錯誤處理、表單驗證等

3. 後端

   NestJS 整合、拿合約寫測試，最後加碼實務篇沒有的 Nuxt

## 通用概念

### jsonQuery

實務篇花了不少篇幅講 `jsonQuery`，因為 REST 的 query string 全是字串，數字、布林、單一元素矩陣都會出現歧異。

走 `RPCHandler` 時就沒這問題了。

oRPC 有自己的序列化協定，Date 傳過去還是 Date，Set 還是 Set，`undefined` 也不會憑空蒸發。

```ts
await client.planet.create({
  name: '地球',
  discoveredAt: new Date(),
  tags: new Set(['js', 'ts']),
  cover: file, // File 也可以直接塞
})
```

代價是這條線只有 oRPC client 能通，你用 cURL 會看到一堆天書。%(◜௰◝)%

走 `OpenAPIHandler` 時，oRPC 支援 Bracket Notation，可以用 `?tags[0]=js&tags[1]=ts` 表達結構化資料，數字與布林一樣交給驗證器轉換。

概念和 `jsonQuery` 想解決的事情一樣，只是編碼方式不同。

### ClientInfer、ServerInfer

ts-rest 分 `ClientInferRequest` 與 `ServerInferRequest`，因為驗證器的輸入與輸出型別可能不一樣。

oRPC 一樣會遇到這件事，只是工具改叫 `InferRouterInputs` 與 `InferRouterOutputs`。

```ts
import type { InferRouterInputs, InferRouterOutputs } from '@orpc/server'

type Inputs = InferRouterInputs<typeof router>
type Outputs = InferRouterOutputs<typeof router>

type FindPlanetInput = Inputs['planet']['find']
```

contract-first 的話，改用 `@orpc/contract` 的 `InferContractRouterInputs`、`InferContractRouterOutputs`。

切法從「client 視角 / server 視角」變成「輸入 / 輸出」。%ԅ(´∀\` ԅ)%

## 前端

接著來看看前端。%(๑•̀ㅂ•́)و✧%

### 初始化 Client 與 memoize

實務篇為了避免重複建立 client，特地拉了 `memoize` 加 `object-hash` 包一層，還寫了三個測試確認快取有效。

這段在 oRPC 直接可以刪掉。

oRPC 的 client 是一個 Proxy，整包 router 建立一次就好，之後到處 import 都是同一個。

```ts
// api.ts
export const client: RouterClient<typeof router> = createORPCClient(link)
```

::: tip link 可以換
後端用 `RPCHandler` 就配 `RPCLink`，用 `OpenAPIHandler`（包含後面會聊的 `@orpc/nest`）則配 `OpenAPILink`。

兩者的 `url`、`headers`、`fetch`、`interceptors` 幾乎一模一樣，所以底下的寫法兩邊都通用，換掉 link 就好。%( ‧ω‧)ノ╰(‧ω‧ )%
:::

那需要動態調整的部分呢？交給 link 的 `headers` 與 `context`。

```ts
const link = new RPCLink<{ skipAuth?: boolean }>({
  url: `${import.meta.env.VITE_API_BASE_URL}/rpc`,
  headers: async ({ context }) => {
    if (context?.skipAuth) {
      return {}
    }

    const { accessToken } = useAuthStore()
    return { Authorization: `Bearer ${accessToken}` }
  },
})
```

呼叫時把 context 帶進去即可。

```ts
await client.planet.find({ id: '1' }, {
  context: { skipAuth: true },
})
```

根本差別在於，ts-rest 是「不同設定等於不同 client 實例」，所以要想辦法快取實例。

oRPC 則是「一個 client，設定逐次用 context 傳」，快取問題自然消失。%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

### 401 自動 refresh

實務篇是覆寫 `api` 參數，自己包一層 `tsRestFetchApi`，再用 `ref` 加 VueUse 的 `until` 防止重複 refresh。

oRPC 同樣可以覆寫 `fetch`，寫法幾乎一模一樣，只是掉到更底層一點。

```ts
/** 用於防止多次 refresh */
const isRefreshing = ref(false)

const link = new RPCLink({
  url: `${import.meta.env.VITE_API_BASE_URL}/rpc`,
  headers: () => ({
    Authorization: `Bearer ${useAuthStore().accessToken}`,
  }),
  fetch: async (request, init) => {
    await until(isRefreshing).toBe(false)

    // 重試需要用到請求內容，先留一份
    const retryRequest = request.clone()

    const response = await globalThis.fetch(request, init)
    if (response.status !== 401) {
      return response
    }

    // 防止多次 refresh
    if (!isRefreshing.value) {
      isRefreshing.value = true
      await refreshToken()
      isRefreshing.value = false
    }

    await until(isRefreshing).toBe(false)

    // headers 是建立請求時就算好的，重試前要換上新的 token
    retryRequest.headers.set(
      'Authorization',
      `Bearer ${useAuthStore().accessToken}`,
    )
    return globalThis.fetch(retryRequest, init)
  },
})
```

::: tip 官方也有現成的重試工具
`@orpc/client/plugins` 提供 `ClientRetryPlugin`，可以設定 `retry`、`retryDelay`、`shouldRetry` 等等。

單純的重試建議直接用它，上面那段是因為 refresh token 需要換 header，才自己動手。%( ´ ▽ \` )ﾉ%
:::

### 狀態與結果資料

這個部分差異就比較大了。%(◜௰◝)%

實務篇的做法是把 HTTP code 寫進合約，前端拿 `result.status` 收斂型別。

```ts
// ts-rest
const result = await accountApi.create({ body: form })

if (result.status === 200) {
  const newId = result.body.id
}

if (result.status === 400) {
  if (result.body.reason === 'username-duplicate') {
    // 處理重複的使用者名稱
  }
}
```

oRPC 把錯誤變成合約的一部分，用 `.errors()` 定義。

```ts
export const accountContract = {
  create: oc
    .errors({
      CONFLICT: {
        message: '使用者名稱重複',
        data: z.object({ username: z.string() }),
      },
    })
    .input(createAccountDtoSchema)
    .output(z.object({ id: z.string() })),
}
```

::: tip 錯誤代碼與 HTTP 狀態碼
`CONFLICT`、`NOT_FOUND`、`UNAUTHORIZED` 等常見代碼內建了 HTTP 狀態碼對照，走 OpenAPI 模式時會自動套用。

代碼也可以自訂，取捨就看你多在意 HTTP 語意了。%(´,,•ω•,,)%
:::

後端從 handler 參數拿到 `errors`，直接 throw。

```ts
.handler(async ({ input, errors }) => {
  if (await isUsernameDuplicate(input.username)) {
    throw errors.CONFLICT({
      data: { username: input.username },
    })
  }

  return { id: await createAccount(input) }
})
```

前端則用 `safe` 與 `isDefinedError` 收斂。

```ts
import { isDefinedError, safe } from '@orpc/client'

const [error, data] = await safe(client.account.create(form))

if (isDefinedError(error)) {
  if (error.code === 'CONFLICT') {
    // error.data.username 有完整型別
  }
}
else if (error) {
  // 非預期錯誤，例如網路斷掉
}
else {
  // data.id 有完整型別
}
```

::: tip
這裡的 `safe` 用法剛好和我以前介紹過的 [`await-to-js`](/blog-program/await-to-js-keeps-your-promises-slick) 相同，真有趣 %(´,,•ω•,,)%
:::

兩者差別在於：

* ts-rest 是「先看 status，再看 body 裡的 reason」。
* oRPC 是「錯誤本身就有名字」，`error.data` 的型別跟著 `code` 一起收斂。

### 表單資料驗證

實務篇是直接從合約上取 schema，不獨立匯出輸入輸出的 schema。

```ts
// ts-rest
const schema = accountContract.create.body
```

這個寫法的價值在於，合約才是入口基準，不然會發生 schema 很多種導致誤取問題。

好消息是 oRPC 也拿得到，只是沒開成公開屬性，東西收在 `~orpc` 裡面。

```ts
import { accountContract } from '@project-code/shared'

const schema = accountContract.create['~orpc'].inputSchema
```

只是這寫法不算正規解法，波浪號是 oRPC 標記非公開 API 的慣例，不保證版本相容。

也有人也在[官方討論串](https://github.com/middleapi/orpc/discussions/1298)問了一模一樣的問題，作者本人的回覆就是這樣，並強調要從 contract 取得，不是 client。

希望 oRPC 盡快解決。%(´･ω･\`)%

### Vue Query

ts-rest 要另外建立一個 `initQueryClient`，變成兩種 client 並存。

oRPC 不用，同一個 client 包一層工具就好。

```ts
import { createTanstackQueryUtils } from '@orpc/tanstack-query'

export const orpc = createTanstackQueryUtils(client)
```

接著就是熟悉的 TanStack Query。

```ts
const query = useQuery(computed(() => orpc.planet.find.queryOptions({
  input: { id: id.value },
})))

const mutation = useMutation(orpc.planet.create.mutationOptions())
```

失效處理也有現成 key 可以用。

```ts
queryClient.invalidateQueries({
  queryKey: orpc.planet.key(),
})
```

:::tip Pinia Colada
oRPC 也有整合 [Pinia Colada](https://orpc.dev/docs/integrations/pinia-colada)，大家也可以試試看。
:::

## 後端

後端分成三塊，NestJS 整合、拿合約寫測試，最後加碼一個實務篇沒有的 Nuxt。%੭ ˙ᗜ˙ )੭%

### NestJS 整合

[概念篇](/blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest)用的是 `@TsRestHandler` 加 `tsRestHandler`，oRPC 則是 `@Implement` 加 `implement`。

```ts
import { Implement, implement } from '@orpc/nest'

@Controller()
export class AccountController {
  constructor(
    private readonly loggerService: LoggerService,
    private readonly accountService: AccountService,
  ) { }

  @Implement(accountContract.create)
  create() {
    return implement(accountContract.create).handler(async ({
      input,
      errors,
    }) => {
      if (await this.accountService.isUsernameDuplicate(input.username)) {
        throw errors.CONFLICT({
          data: { username: input.username },
        })
      }

      const [error, data] = await to(this.accountService.create(input))
      if (error) {
        this.loggerService.error('建立 account 錯誤')
        this.loggerService.error(error)
        throw error
      }

      return data
    })
  }
}
```

寫法幾乎一樣，差別在錯誤從「回傳一個 status」變成「throw 一個有名字的錯誤」。

```ts
// ts-rest：錯誤是一種回傳值
return tsRestHandler(accountContract.create, async ({ body }) => {
  if (await this.accountService.isUsernameDuplicate(body.username)) {
    return { // [!code highlight]
      status: 400, // [!code highlight]
      body: { reason: 'username-duplicate' }, // [!code highlight]
    } // [!code highlight]
  }

  return {
    status: 200,
    body: await this.accountService.create(body),
  }
})
```

```ts
// oRPC：錯誤是一種例外
return implement(accountContract.create).handler(async ({ input, errors }) => {
  if (await this.accountService.isUsernameDuplicate(input.username)) {
    throw errors.CONFLICT({ // [!code highlight]
      data: { username: input.username }, // [!code highlight]
    }) // [!code highlight]
  }

  return this.accountService.create(input)
})
```

ts-rest 不管成功與失敗都用 `{ status, body }` 回傳，oRPC 失敗則是丟合約裡定義好的錯誤。

相較於 `return`，`throw` 有個明確的好處：

* `return` 只能結束當前函式，在 `forEach()` 這類 callback 裡就要想辦法把結果帶回最外層在次 `return`。

* `throw` 則可以從任意深處直接拋出，直接中斷後續流程。%(ゝ∀・)b%

```ts
return implement(accountContract.create).handler(async ({ input, errors }) => {
  input.tagList.forEach((tag) => {
    if (isReservedTag(tag)) {
      // 巢狀再深都拋得出去，errors 也還在 closure 裡
      throw errors.CONFLICT({ data: { username: input.username } }) // [!code highlight]
    }
  })

  return this.accountService.create(input)
})
```

::: warning callback 換成 async 就接不住了
`forEach()` 的 callback 加上 `async` 之後，`throw` 只會變成沒人 `await` 的 rejection，handler 照樣往下跑。

這是 JavaScript 本身的規則，與 oRPC 無關，改用 `for...of` 就好。%(´,,•ω•,,)%
:::

#### 全域設定

`ORPCModule` 負責全域設定，`forRoot` 與 `forRootAsync` 都有。

```ts
import { ORPCModule } from '@orpc/nest'
import { onError } from '@orpc/server'

@Module({
  imports: [
    ORPCModule.forRootAsync({
      inject: [LoggerService],
      useFactory: (loggerService: LoggerService) => ({
        interceptors: [
          onError((error) => loggerService.error(error)),
        ],
        eventIteratorKeepAliveInterval: 5000,
      }),
    }),
  ],
})
export class AppModule { }
```

想在 handler 裡拿到 request 之類的東西，就補上初始 context。

```ts
declare module '@orpc/nest' {
  interface ORPCGlobalContext {
    request: Request;
  }
}

ORPCModule.forRootAsync({
  inject: [REQUEST],
  useFactory: (request: Request) => ({
    context: { request },
  }),
})
```

#### 幾個小小的坑

nest 實際導入可能會遇到以下問題。%ԅ( ˘ω˘ԅ)%

**1. 純 ESM**

oRPC 是 ESM-only 套件。`tsconfig.json` 的 `module` 要設成 `NodeNext`，Node.js 建議 22 以上，才 `require` 得動 ESM。

用 Nest 預設打包設定的話，可能還要另外調整，讓 `@orpc/nest` 一起被編譯進去。

**2. 合約一定要有 path**

每支合約的 `.route()` 都要給 `path`，少一個編譯階段就直接擋下來。

懶得一支一支寫的話，用 `populateContractRouterPaths` 自動補。

```ts
import { populateContractRouterPaths } from '@orpc/contract'

export const contract = populateContractRouterPaths({
  account: accountContract,
})
```

**3. 關掉 NestJS 的 body parser**

```ts
const app = await NestFactory.create(AppModule, {
  bodyParser: false,
})
```

oRPC 會優先用 NestJS 解析的 body，解析不了才用自己的。

問題是 NestJS 的 `urlencoded` parser 不認得 Bracket Notation，而且 `application/json` 這類 content type 的檔案上傳，可能不會解析成 `File`。

**4. 錯誤預設會被包成 HttpException**

這點最容易中招。oRPC 會攔下 handler 丟出的錯誤，再對 NestJS 丟一個通用的 `HttpException`，也就是說你原本寫的 Exception Filter 看到的不是原始錯誤。

想讓 NestJS 拿到原始錯誤，要掛 Rethrow Plugin。

```ts
import { experimental_RethrowHandlerPlugin as RethrowHandlerPlugin } from '@orpc/server/plugins'

ORPCModule.forRoot({
  plugins: [
    new RethrowHandlerPlugin({
      // 不是 ORPCError 的錯誤就丟回去給 NestJS 處理
      filter: (error) => !(error instanceof ORPCError),
    }),
  ],
})
```

**5. 404 完全不會經過 procedure**

路由沒對上時，NestJS 直接回 404，procedure 與它掛的 plugin 一個都不會跑。

所以像 OpenAPI Reference 這種需要攔截未匹配路徑的 plugin，在 NestJS 底下可能不如預期。

**6. Fastify 的路徑參數有限制**

含斜線的路徑參數（`{+path}`）在 Fastify 平台上不支援，因為它沒有 wildcard aliasing。有這需求就乖乖待在 Express。

::: warning v2 beta 已經在路上了
`@orpc/nest` 穩定版是 `1.14.x`，但 `2.0.0-beta` 也在跑了，而且合約定義換了寫法。

`.route({ path })` 變成 `oc.meta(openapi({ path }))`，`populateContractRouterPaths` 也改名為 `populateRouterContractOpenAPIPaths`。

官方文件網站目前是 v1 內容，GitHub 主線則是 v2，看文件時要注意自己在看哪一份。
:::

還有件事要講清楚，走 `@orpc/nest` 的話，端點一定是 OpenAPI 相容的 REST，不會是 oRPC 自家的 RPC 協定。

所以前面聊的 `RPCLink` 在這個組合下要換成 `OpenAPILink`，下一段馬上就會用到。%(ゝ∀・)b%

### 合約 + 測試

NestJS e2e 得打真的 HTTP，所以之前用 ts-rest 時，要先把合約還原成 url、method、query、body 才交得給 Supertest。

實務篇為此刻了一個 `useContract`，接著每個資源還要再包一層 API 轉換層。

oRPC 合約本來就能變出 client，所以直接拿 client 打測試 server 就好，完全不需要轉換層。%ヽ(●\`∀´●)ﾉ%

```ts
import type { ContractRouterClient } from '@orpc/contract'
import type { JsonifiedClient } from '@orpc/openapi-client'
import { createORPCClient, isDefinedError, safe } from '@orpc/client'
import { OpenAPILink } from '@orpc/openapi-client/fetch'

let client: JsonifiedClient<ContractRouterClient<typeof contract>>

beforeAll(async () => {
  // ...啟動 Server 與 DB

  client = createORPCClient(new OpenAPILink(contract, {
    url: await app.getUrl(),
    headers: () => ({ Authorization: `Bearer ${token}` }),
  }))
}, 60000)

describe('建立 account', () => {
  it('全部參數', async () => {
    const result = await client.account.create({
      username: 'cod',
      password: 'fish',
    })

    expect(result.id).toBeDefined()
  })

  it('重複的 username 應該要被擋下來', async () => {
    await client.account.create({ username: 'cod', password: 'fish' })

    const [error] = await safe(
      client.account.create({ username: 'cod', password: 'fish' }),
    )

    expect(isDefinedError(error) && error.code).toBe('CONFLICT')
  })
})
```

::: tip 為什麼要包一層 JsonifiedClient
`OpenAPILink` 走的是標準 JSON，Date 傳過來會變成字串。

`JsonifiedClient` 就是把型別修正成「JSON 化之後的樣子」，免得型別說是 Date、手上拿到的卻是字串。%(´,,•ω•,,)%

換成 `RPCHandler` 加 `RPCLink` 就沒這問題，因為 RPC 協定原生保留了型別。
:::

如果只想測 handler 邏輯，連 server 都不用開，用 `call` 直接呼叫。

```ts
import { call } from '@orpc/server'

const result = await call(router.account.create, {
  username: 'cod',
  password: 'fish',
}, {
  context: { db },
})
```

### Nuxt 整合

ts-rest 官方沒有 Nuxt 或 Nitro 的 adapter，要自己拿 `@ts-rest/serverless/fetch` 在 Nitro 路由裡慢慢湊。

oRPC 則可以無痛使用，因為 Nitro 本身就吃 Fetch API，oRPC 的 fetch adapter 可以直接上場。%ヽ(●\`∀´●)ﾉ%

#### Server Routes 掛上 handler

在 Nuxt 的 Server Routes 放一個 catch-all 路由。

```ts
// server/routes/rpc/[...].ts
import { onError } from '@orpc/server'
import { RPCHandler } from '@orpc/server/fetch'

const handler = new RPCHandler(router, {
  interceptors: [
    onError((error) => console.error(error)),
  ],
})

export default defineEventHandler(async (event) => {
  const request = toWebRequest(event)

  const { response } = await handler.handle(request, {
    prefix: '/rpc',
    context: {}, // 需要的話在這裡給初始 context
  })

  if (response) {
    return response
  }

  setResponseStatus(event, 404, 'Not Found')
  return 'Not found'
})
```

catch-all 匹配不到 `/rpc` 本身，所以還要補一個 index 轉過去。

```ts
// server/routes/rpc/index.ts
export { default } from './[...]'
```

這裡的 handler 換成 `OpenAPIHandler` 也行，端點就變成標準 REST API。

#### Client 放進 Nuxt Plugin

client 要放進 Nuxt Plugin，SSR 才拿得到 request headers。

```ts
// app/plugins/orpc.ts
export default defineNuxtPlugin(() => {
  const event = useRequestEvent()

  const link = new RPCLink({
    url: `${typeof window !== 'undefined' ? window.location.origin : 'http://localhost:3000'}/rpc`,
    headers: event?.headers,
  })

  const client: RouterClient<typeof router> = createORPCClient(link)

  return {
    provide: { client },
  }
})
```

元件裡用 `const { $client } = useNuxtApp()` 取出來就能開工了。%(๑•̀ㅂ•́)و✧%

#### SSR 別再繞一圈 HTTP

上面的寫法很合理，但是多繞了一圈。%(◉◞౪◟◉ )%

SSR 時 Nuxt 的 server 會對自己的 `/rpc` 發一次真的 HTTP 請求，等於自己打自己，白白多一趟來回。

解法是拆成兩個 plugin，讓瀏覽器走 HTTP，server 直接呼叫函式。

```ts
// app/plugins/orpc.client.ts
export default defineNuxtPlugin(() => {
  const link = new RPCLink({
    url: `${window.location.origin}/rpc`,
    headers: () => ({}),
  })

  const client: RouterClient<typeof router> = createORPCClient(link)

  return {
    provide: { client },
  }
})
```

```ts
// app/plugins/orpc.server.ts
export default defineNuxtPlugin(() => {
  const event = useRequestEvent()

  const client = createRouterClient(router, {
    context: {
      headers: event?.headers,
    },
  })

  return {
    provide: { client },
  }
})
```

Nuxt 的 `.client.ts` 與 `.server.ts` 後綴會自動分流，所以 router 實作也不會被打包進瀏覽器，不用擔心 server 端程式碼外洩。

同一個 `$client`，SSR 時是本地函式呼叫，瀏覽器則是 HTTP 請求，元件完全不用改。%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

這招不限 Nuxt，Next.js、SvelteKit 都是同一套概念，只是分流的手法不同。

## oRPC 優勢

oRPC 在檔案、Date、SSE 串流這幾點體驗更好。

`File`、`Blob` 可以直接進出 procedure，`Date` 不會在路上變成字串。

串流則是用 `eventIterator` 定義，handler 回傳 async generator，前端拿到的就是能 `for await` 的迭代器，型別一路保留。

而且 oRPC 的生態系整合相當豐富，ts-rest 則已停止更新，應該是不可能追上了。%( ˘･з･)%

## 總結 🐟

* oRPC 是 RPC 風格但相容 OpenAPI，最大的差別在心智模型，ts-rest 的合約是 HTTP 端點，oRPC 的合約是函式簽章
* 實務篇的 `jsonQuery`、client memoize、e2e 轉換層，在 oRPC 上大多直接消失
* 錯誤處理從 status code 換成具名 typed error，前端用 `safe` 與 `isDefinedError` 收斂
* NestJS 的坑集中在 ESM 與錯誤攔截，導入前務必先看過那六點
* Nuxt 靠 `.client.ts` 與 `.server.ts` 雙 plugin，就能讓 SSR 省掉一趟 HTTP

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去 %(\*´∀\`)~♥%

有錯誤或不周全之處，還請多多指教 %( ´ ▽ \` )ﾉ%

---

---
url: /blog-program/better-enumeration-definition-for-improved-dx.md
description: 不管是 enum 和 literal 的方式其實都有些小缺點，以下推薦一個個人認為體驗更好的方式
---

![better-enumeration-definition-for-improved-dx](/better-enumeration-definition-for-improved-dx.webp){.cover}

# TypeScript 之 DX 體驗更好的列舉資料定義方式

一般在使用 TypeScript 的時候，大家都有遇過定義列舉資料的情境吧。

不過不管是 enum 和 literal 的方式其實都有些小缺點，以下推薦一個個人認為體驗更好的方式。

## defineConstants

舉個栗子。( ´ ▽ \` )ﾉ🌰

```ts
// 可以用各種方式取用列舉
export const {
  FISH_TYPE_KV,
  FISH_TYPE_MAP_BY_KEY,
  FISH_TYPE_MAP_BY_VALUE,
  FISH_TYPE_KEYS,
  FISH_TYPE_VALUES,
} = defineConstants(
  [
    {
      key: 'COD',
      value: 'cod',
      // 除了 key value 外，還可以額外包含其他資訊
      label: '鱈魚',
    },
    {
      key: 'OCTOPUS',
      value: 'octopus',
      label: '章魚',
    },
  ] as const,
  'FISH_TYPE'
)

FISH_TYPE_KV.OCTOPUS // octopus
FISH_TYPE_MAP_BY_KEY.COD // { key: 'COD', value: 'cod', label: '鱈魚' },
FISH_TYPE_MAP_BY_VALUE.cod // { key: 'COD', value: 'cod', label: '鱈魚' },
FISH_TYPE_KEYS[0] // COD
FISH_TYPE_VALUES[1] // octopus

// value 使用數字也是沒問題
export const {
  TYPE_VK,
  TYPE_MAP_BY_VALUE,
} = defineConstants(
  [
    {
      key: 'COD',
      value: 0,
    },
    {
      key: 'OCTOPUS',
      value: 1,
    },
  ] as const,
  'TYPE'
)

TYPE_VK[0] // COD
TYPE_MAP_BY_VALUE[1] // { key: 'OCTOPUS', value: 1 }
```

唯一的缺點是 value 如果使用數字要自己訂，不會像 enum 一樣自己遞增。(›´ω\`‹ )

鱈魚：「看起來是不是很不錯啊。(´,,•ω•,,)」

路人：「所以我說那個 defineConstants 是甚麼鬼？ლ(・´ｪ\`・ლ)」

鱈魚：「別急別急，去找吧，都放在下面的連結了。◝( •ω• )◟」

[範例程式碼](https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgJICE4GcIBEIzIDeAUMsgNYQCeAXMgApQD2ADtGNQNI0DcZyAG5wANgFcI9LGCigA5sgA+yEGIC2AI2j8AviRKd2yACrMmbDtSYFgADwA8AOWQRbkEABMsyabJAKAXmQAcmCAPmQg51d3LxDg5AB+eOR6AAMAEiJHHQB9NP4DaiNTc3YoTnsBMssXNwhPb195ABoBaPrGnxl5SPi2iKDMolKWcs5rGDsnMJ0smorqHQL9QxRTHmose2NBkzrY7ygIOA9mEBFqZABtUBhoZABBFuQAOne7h-QAXQFkx4ODTipHI5GOp3Ol0oNHonygyC4-HIenIyXQ12CIgacjAAAtgt9AV0AAx-G5cX7kejXLgvd6vDY0bboMKU1IqCCCaACanfQprEzMABqogk212fWMRLi4LOFyutxA93hzzeHyVXzZ-2l3hBoNlkKuwnEkmQcIRSOQKKSyHRmOxeIJOuQpNR5LZ1NpaoZwtFEGZrJ5HK5UCD1z5q2K62YAGV5FjNgBZOCsHZ7KUxIG6gQG+XQuhmjXwxEka3JLjOhacTZkvVgk5yqE0miFhHfejGS3W+ggTncqnB7T6VysZgVZACxPQOQQVDgaA4BBgYDneyPPYAzNdc3GWvklugfPMQjGdsmZvUQndwdQflRwVJlNpyXO3NN82q+nmn5ku1Y-yOoSW5xK6NqmHG-gJjQyapuuQZTlAM5zpAUCLsuq7gfGECPrBEQAGQPtBT4smEYYRkUJSxlhIomjBz5BBmnTAjmDaGkIfqwkWFqlmSFbAd4VbcDQtYCPWEJ5herYUh2XZBr2IZyX2t6RpRNESHREoMa+rESR+dLqsqtparaGL-ji+JAUx3igckmGQRAakQHRcEDghSHzqhEBLiuIA7FR9mOc5+GCoFxFhKRA7hnelEQXIUHUI59H7PxxAseJUJUAW5olmJjZGhxhaGUKui8ZWYyWDWbp1sgb4KpsUlnsVAjXvJ-bsq1ykUdGmyJZpyVWTVOnvlxn4GZqv6mQ6FnOjZgqxfFiUueybmzh5aE+X583YTQi3BYyCV+vYJFkdF0ZbY5mxJYxhypblbGZZxhk5YN6X5Saj0PE1ZbIEKZUWIslU2tVtX7lch5Cmez0tUpikhqdIV+pdfXXVmL15Tcenet+xl-lNTopbNdlxQ5iM0GuEXLdOq0oetGH+cTF1k+uyAEaYjPUEd4UnfoAD0ABUfPIIAFK6AD2mgBfeoA05aAOhKgCQQYA5oqAJ3aZCC8rCK-YA9Gb5uxJrIIAIW6APCGgC4BoAQAyq6rgBZ2oAlf6AJfugDGaYA4zGAJmmgAYUYA6fqAAVKgBQcsg2DIAg5zSGbyCCwAAq4cBqKwWKq2ksdrFgCCyKwYCqzzPPIIA0gmAIAJgCdpoA8PqABx6gAeplbqsjmOYB+wHlcgoL5C4AAogAMqgQoNwASgAmrkiYN8YAASADyuC5FwQptMHoKNy3bddz3fdDyPQq0qr9fN63Hfd73A-Dz3jwMLk6Dd1wDedxPdfINPG9z9vi97wfR+5EKjxNwAqg359T+vs9bwvu-P2-BuMZVY6D6B4GwvYADC1c4DgCwAAClXjcJB5Ba6gnQQ9EIQ9e7BE-ug8gxoJD0GCLiZgagIC4JQaCEQcAtAiGIYAUO1ACyiZQye6CdB4NBGg-B+ZiExmbgAMVyAwVAkCuCvwYKwi+6DCGmmCDgEQMAAC0rBgAIAoGIVgUieHIBoXQ4hgArwMAGvK2j2GcMJL7f2IBpCcOCFfH+88d64GCKrAAlKndO2d85l1sKOccAp8AiGACGagU48TMA8H0NYx5L7f03o4u+AD34xmuKoTQ0AIyT1jmkZWPMSDl3HDAMQIBvLnGQOAqYUCYFwKqOQFGXQQYYGwHgAg4YJ7IA6DdZo-g+ihAGPAipWAOwvBABHf0rBEAQESPQRwrjbpV2sZXVgxwpi2D6KM8hWAJlIBtMMDZ4zJl5DSOyUIlpjhgDEFAEA8zyDXGGMsmwtgdAn07jGNIZ5BmvDUCmeB8DgCQDUHMgIER-kQDUK8TKrj2m3PuSsuwOgklAPefQT53zWC-NBYCyIIKAWvFkVC0SNxYWPOeUKZF5SCBYFeMcDwYgkCIJ4fAtFLxMVAoiPA6q6D6TMsJeg24uLMpnkxXiv00LQQ6AJTwogHDCWStBHcrIDzVkIq4OSz5NK6UQAZfgplKYWUArZcgDlvLQTcr1Sa25wrZFCoFTQMVyI5XoOlWKx1RLFVwqeYmfeh9j6nzVZS6lEBaX0pNbq1g+qwWGuNTo70PKY38rBRCmgNqwX2qtK61BMr0GuoVUQJV8KvUP27oi-1MAqUapDYy5lZoDXYqNZy017w406ITeC61sIAVpolWm51sqxW5vzU8l599S3lqDZq7V6Cw0RqxcC+tFrY3mvjcKwVHbU0mu7Sa3t2b+3EuVYW0dgbg1atDdW1ldbo06LNeGhdrak2XjXW20VG6M3ECzaCHNe74UtxjMYUd7TQG+xWshBcXl0K+UJQ2ySh5Rj-UqMEMeuCOmsg7MwHqh1diWmRCzG58r6owbMOVRY9hgjLyQ44FDCMTRIzCFhq0OGoP4eubB8YHMEOnxjORyj+1xS0cJaAgijGDzMcI3BtjiLOMvAo2eNmfpeN0YE7h25THBSCRI4Wn1o9T5cZk2hoiqZMP8YYya6DIm1PBA04-RFOnUOhQM3x9hxmeGmdU0R+DhabOEQOiaNMCmnP4JcyxywJGf3GE852fjAg+N6BIGnZAgB75UAKdyQtAAgKoAOi985GKFrLfJviK4LOkPMgRqAYz91yMYTuDAG6j3HgIYrpXyuVeq5Z31Z86slbKxVqr99NOIvafVzrTWtOvP6x1xr3WJNtFAUECpoAIDQMWbAsACCBDXEgyazBwRIHD1Yfg2RxD-YeF2+guLgATNMAGFyWtZHIEAGiagAYf8ACEJSXACyGTdwAoMqAGoVQAboqADW5e2gAoKJNXoiA9CQiAAkcwAWtnHatGKhtm3B6QOMIPBgr9JMmv2yEZgS42BiCwND8gwPQfBEAAdeUOxXvosd4KxNiBDBAG+NhuLj3EkHp116rY9XgI6RyjmMvAeFxax2AHHWAWdjbZz1x+LzXjbdwKCOLRBeEhBl0hjHwRDtIcJ8QyHCQZWs6Gy1p+L936vEO8geXiuts7ZeKr9XLxNfg6hzD0XDXxcvJScSQkMazfpxl87wbE2jdAOuAARk9-z9Ogvhe83TtdwA-vJCyLoAdW1AD6curQASTaAHlVQAMhm5b8ZXanNcBDi+Xu08XBu+uljARA+b1TlvarW06jbMIldW-RwVYk5PYdN4LMELnyPUf4+1kQ5AwfO8CEpwVsA7Tghs6Z-oYvXBrge693Ln3w8SBl+9VZwPIfPfm-h4j-vkmh+mmD1aIAA)

至於這個酷東西怎麼來的？是我有一天路過某篇文章看到的方法，原諒我找不到原始文章了，如果知道的讀者們還請幫忙補充補充。(´,,•ω•,,)

## 總結 🐟

* 這更方便的取用列舉資料，彌補 enum 和 literal 的缺點
* 除了 key value 外，還可以從不同的角度取用資料

---

---
url: /_frame.md
---


---

---
url: /blog-ocean-world/add-responsive-images-to-vite-press.md
description: VitePress 沒有 Nuxt Image 那樣方便且自動的圖片處理，該怎麼辦呢？ლ(・´ｪ`・ლ)
---

![add-responsive-images-to-vite-press](/add-responsive-images-to-vite-press.webp){.cover}

# VitePress 之所以我說那個響應式圖片呢？

此部落格原本使用 Nuxt Content 開發，但是因為 Nuxt Content 把文章也算在 Server 資源內，導致編譯後尺寸超過 Cloudflare Workers 上限。

\~~頹廢~~擱置好長一段時間後，最近終於有時間改用 VitePress 重構了。

不過 VitePress 沒有 [Nuxt Image](https://image.nuxt.com) 可以自動處理[響應式圖片](https://web.dev/articles/responsive-images)，手動處理實在是要魚命。%...(›´ω\`‹ )%

身為一個稱職的碼農，當然要自動處理啊。%⎝(・ω´・⎝)%

結果找不到適合、現成的外掛，只好自己想辦法了。%ლ(・´ｪ\`・ლ)%

如果大大們有更好的解法，~~請不要告訴我，我已經做完了~~，說說的啦，還是告訴我好了。%(\*´∀\`)~♥%

::: tip
本文不是 VitePress 入門教學，不會介紹 VitePress 的基本用法。%( ´ ▽ \` )ﾉ%

若有需要，可以參考此系列文：[30天用Vitepress 開啟我的"部落客"生活](https://ithelp.ithome.com.tw/users/20109918/ironman/7545)。
:::

## 何謂響應式圖片？

響應式圖片是指根據裝置解析度，提供不同尺寸的圖片，以達到最佳的使用者體驗。

例如：手機解析度較低，就不需要載入高解析度的圖片，以節省流量。

詳細內容推薦看看這篇文章：[Responsive images](https://web.dev/responsive-images)。

## 解決方案

搜尋、研究了一下，目前總結出來的步驟為：

1. 建立一個產生響應式圖片的腳本
2. 在 [`buildEnd`](https://vitepress.dev/reference/site-config#buildend) 階段執行腳本
3. 擴展 markdown-it，將 image 標籤替換為自定義 Vue 元件（`base-image`）
4. 開發 `base-image` 元件，產生約定好的圖片尺寸之 srcset 屬性

方向有了，現在來實作吧！%◝( •ω• )◟%

### 產生響應式圖片

這個部分很單純，基本上就是取得所有圖片後，使用 [sharp](https://www.npmjs.com/package/sharp) 產生圖片

```ts
import fs from 'node:fs'
import path from 'node:path'
import { map, pipe } from 'remeda'
import sharp from 'sharp'

const IMAGE_PATH = path.resolve(__dirname, '../../content/public')
const OUTPUT_PATH = path.resolve(__dirname, '../../.vitepress/dist')

const IGNORE_NAME_LIST = [
  'favicon',
]
const IGNORE_PATH_LIST = [
  'public/memes/',
  // 迷因海報與 sprite 由前端直接讀原檔，縮圖用不到；sprite 動輒數千像素，縮放會拖垮 build 時間
  'public/meme-posters/',
  'public/meme-sprites/',
  'public/assets/',
  'public/codstack/',
  'public/hexazen/',
]
const WIDTH_LIST = [700, 300]
const SUFFIX_NAME_LIST = ['.png', '.jpg', '.jpeg', '.webp']

// 是否為資料夾
function isDirectory(path: string) {
  return fs.lstatSync(path).isDirectory()
}

/** 取得所有圖片路徑 */
function getImagePathList(dirPath: string) {
  const files = fs.readdirSync(dirPath)
  const result: string[] = []

  for (const file of files) {
    const filePath = path.join(dirPath, file)
    const isDir = isDirectory(filePath)

    if (isDir) {
      const relativePath = path.relative(path.resolve(__dirname, '../..'), filePath).replace(/\\/g, '/')
      const isIgnoredPath = IGNORE_PATH_LIST.some(
        (ignorePath) => relativePath.includes(ignorePath.replace(/\/$/, '')),
      )

      if (!isIgnoredPath) {
        result.push(...getImagePathList(filePath))
      }
      continue
    }

    if (IGNORE_NAME_LIST.some((name) => file.includes(name))) {
      continue
    }

    const suffix = path.extname(file)
    if (!SUFFIX_NAME_LIST.includes(suffix)) {
      continue
    }

    result.push(filePath)
  }

  return result
}

export async function generateImages() {
  /** 取得所有圖片 */
  const imgList = getImagePathList(IMAGE_PATH)
  console.log(`[ generateImages ] 找到 ${imgList.length} 張圖片`)

  // 產生對應寬度圖片至 .vitepress/dist，檔名後面加上寬度
  for (const imgPath of imgList) {
    const img = fs.readFileSync(imgPath)
    const relativePath = imgPath.replace(IMAGE_PATH, '')
    const parsed = path.parse(relativePath)
    const filePath = path.join(parsed.dir, parsed.name)

    try {
      const tasks = pipe(
        WIDTH_LIST,
        map((width) => {
          const outputPath = path.join(
            OUTPUT_PATH,
            `${filePath}-${width}.webp`,
          )

          return sharp(img)
            .resize({ width })
            .sharpen({ sigma: 0.5 })
            .webp({ quality: 80, effort: 6 })
            .toFile(outputPath)
        }),
        // 輸出一張原圖 quality 60 版本
        (list) => {
          const outputPath = path.join(
            OUTPUT_PATH,
            `${filePath}.webp`,
          )

          list.push(sharp(img)
            .webp({ quality: 80, effort: 6 })
            .toFile(outputPath))

          return list
        },
      )

      await Promise.all(tasks)
    }
    catch (error) {
      console.error(`[ generateImages ] 圖片 ${imgPath} 產生失敗 :`, error)
    }
  }

  // 清理 sharp 的 libvips 執行緒池與快取，避免 process 無法退出
  sharp.cache(false)

  console.log(`[ generateImages ] 產生完成`)
}

```

### 執行腳本

依照 [VitePress 文件](https://vitepress.dev/reference/site-config#build-hooks)說法，`.vitepress\config.mts` 中有多個 Build Hooks 可以設定。

由於我只要建構後產生，所以在 `buildEnd` 階段執行即可。

`.vitepress\config.mts`

```ts
import { generateImages } from './scripts/resize-images'

// https://vitepress.dev/reference/site-config
export default ({ mode }) => {
  return defineConfig({
    // ...
    async buildEnd() {
      await generateImages()
    },
  })
}
```

現在讓我們試試 build 後會不會跑出各種尺寸的圖片。%(´・ω・\`)%

執行 build 後，沒有意外的話，應該要出現以下文字。

```shell
  vitepress v1.5.0

✓ building client + server bundles...
✓ rendering pages...
✓ generating sitemap...
[ generateImages ] 找到 43 張圖片
[ generateImages ] 產生完成
build complete in 11.75s.
```

且 dist 資料夾內應該要跑出各種尺寸的圖片。

![generate-rwd-image](/add-responsive-images-to-vite-press/generate-rwd-image.jpg)

圖片出現了！%◝(≧∀≦)◟%

### 擴展 markdown-it

[`config.mts` 中有保留欄位](https://vitepress.dev/guide/markdown#advanced-configuration)，可以設定自行拓展 markdown-it 功能。

新增一個 markdown-it 外掛，功能很單純，就是將 markdown 中的 `img` 標籤替換為 `base-image` 元件。

```ts
import type { RequiredDeep } from 'type-fest'
import type { UserConfig } from 'vitepress'
import { map, pipe } from 'remeda'

type MarkdownIt = Parameters<
  RequiredDeep<
    UserConfig['markdown']
  >['config']
>[0]

/** 將 img 轉換成 base-img 元件
 * https://vitepress.dev/guide/markdown#advanced-configuration
 *
 * @param md
 * @param mode 用於判斷是否為開發模式
 */
export function markdownItBaseImg(md: MarkdownIt, mode: string) {
  md.renderer.rules.image = (tokens, idx) => {
    const token = tokens[idx]
    if (!token) {
      return ''
    }

    const attrs = pipe(
      token.attrs ?? [],
      map(([key, value]) => {
        if (key === 'alt') {
          return `alt="${token.content}"`
        }

        return `${key}="${value}"`
      }),
    )

    return [
      `<base-img`,
      ...attrs,
      `/>`,
    ].join(' ')
  }
}

```

### 開發元件

最後也是最重要的一步，開發 `base-image` 元件並產生 srcset 屬性。

```vue
<template>
  <picture>
    <template v-if="sourceVisible">
      <source
        v-if="isDark && !darkSrcError"
        :srcset="darkSrcset"
        :sizes="sizes"
        type="image/webp"
      >
      <source
        :srcset="lightSrcset"
        :sizes="sizes"
        type="image/webp"
      >
    </template>

    <img
      v-bind="imgProps"
      @error="darkSrcError = true"
    >
  </picture>
</template>

<script setup lang="ts">
import type { ImgHTMLAttributes } from 'vue'
import { join, map, pipe } from 'remeda'
import { useData } from 'vitepress'
import { computed, ref, useAttrs } from 'vue'

interface Props extends /* @vue-ignore */ ImgHTMLAttributes {
  src: string;
  /** 指定特定尺寸 */
  useSize?: typeof WIDTH_LIST[number];
  /** 圖片 sizes 屬性，用於搭配 srcset 讓瀏覽器選擇正確尺寸 */
  sizes?: string;
}

const props = withDefaults(defineProps<Props>(), {
  useSize: undefined,
  sizes: '(max-width: 700px) 100vw, 700px',
})

const { isDark } = useData()
const darkSrcError = ref(false)

const attrs = useAttrs()

const WIDTH_LIST = [700, 300] as const

// 去除附檔名
const fileName = computed(() => props.src
  .split('.')
  .slice(0, -1)
  .join('.'),
)

const src = computed(() => isDark.value ? props.src.replace('.webp', '-dark.webp') : props.src)

/** 封面圖為首屏 LCP 元素，需優先載入；其餘圖片延後載入以釋放頻寬 */
const isCover = computed(() => String(attrs.class ?? '').includes('cover'))

const imgProps = computed(() => ({
  ...props,
  ...attrs,
  src: src.value,
  loading: isCover.value ? 'eager' : 'lazy',
  fetchpriority: isCover.value ? 'high' : undefined,
  decoding: isCover.value ? undefined : 'async',
}))

/** 抽取邏輯：根據傳入的檔名 (baseName) 產生對應的 srcset 字串
 */
function getSrcset(baseName: string) {
  // 指定特定尺寸
  if (props.useSize) {
    return `${baseName}-${props.useSize}.webp`
  }

  // 產生響應式清單
  return pipe(
    WIDTH_LIST,
    map((size) => `${baseName}-${size}.webp ${size}w`),
    join(', '),
  )
}

/** 一般模式的 srcset */
const lightSrcset = computed(() => getSrcset(fileName.value))

/** 暗黑模式的 srcset
 * 邏輯：在原檔名後加上 -dark
 * 例如：image-700.webp -> image-dark-700.webp
 */
const darkSrcset = computed(() => getSrcset(`${fileName.value}-dark`))

const sourceVisible = computed(() => {
  /** DEV 模式不顯示響應式圖片 */
  if (import.meta.env.DEV) {
    return false
  }

  /** gif 不特別處理 */
  return !props.src.includes('.gif')
})
</script>

```

接著將 `base-image` 註冊為全域元件。

`.vitepress\theme\index.ts`

```ts
import type { Theme } from 'vitepress'
// https://vitepress.dev/guide/custom-theme
import BaseImg from '../../web/components/base-img.vue'

export default {
  // ...
  enhanceApp({ app, router, siteData }) {
    app.component('BaseImg', BaseImg)
  },
} satisfies Theme
```

## 實測

現在讓我們執行 `vitepress preview`，來試試看效果如何吧。

![rwd-result](/add-responsive-images-to-vite-press/rwd-result.jpg)

可以注意到原本的 `img` 標籤已替換為 `picture` 標籤（`base-image` 元件），並且產生了 `srcset` 屬性。

大功告成！%੭ ˙ᗜ˙ )੭%

## 總結 🐟

* 使用 [sharp](https://www.npmjs.com/package/sharp) 產生多種尺寸圖片
* 擴展 markdown-it，將 image 標籤替換為自定義 Vue 元件（`base-image`）
* 藉由 `base-image` 元件產生約定好的圖片尺寸之 srcset 屬性

以上我們完成自動產生、替換響應式圖片的功能了！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

其實還有很多細節可以處理，例如：如果圖片小於目標尺寸，就不需要產生新圖片等等。

我就不剝奪其他人實驗的機會了，留給大大們自己嘗試惹。

要改得太多惹，我決定改天！ᕕ( ﾟ ∀。)ᕗ

---

---
url: /blog-vue/vue-3-5-update-on-watcher-cleanup-with-the-forgotten-on-cleanup.md
description: >-
  Vue 3.5 更新新增了 onWatcherCleanup，用於清理 watcher 中的副作用（Side Effect），可是原本的 watch 已經有
  onCleanup，所以到底差在哪呢？(╯▽╰ )
---

![vue-3-5-update-on-watcher-cleanup-with-the-forgotten-on-cleanup](/vue-3-5-update-on-watcher-cleanup-with-the-forgotten-on-cleanup.webp){.cover}

# Vue 3.5 更新，onWatcherCleanup 與 onCleanup

[Vue 3.5 更新了](https://blog.vuejs.org/posts/vue-3-5)！除了其他改進與實用功能外，有一個很有趣的新 API，[叫做 `onWatcherCleanup`](https://blog.vuejs.org/posts/vue-3-5#onwatchercleanup)。

不過原本的 watch 已經有 `onCleanup` 了，所以到底差在哪呢？

[文件 Side Effect Cleanup 一節](https://vuejs.org/guide/essentials/watchers.html#side-effect-cleanup)中提到的用法為：

```ts
import { onWatcherCleanup, watch } from 'vue'

watch(id, (newId) => {
  const controller = new AbortController()

  fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
    // callback logic
  })

  onWatcherCleanup(() => {
    // abort stale request
    controller.abort()
  })
})
```

不過 watch 本身就有 onCleanup，所以應該可以這樣寫。

```ts
watch(id, (newId, oldId, onCleanup) => {
  const controller = new AbortController()

  fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
    // callback logic
  })

  onCleanup(() => {
    // abort stale request
    controller.abort()
  })
})
```

[文件 onWatcherCleanup 章節](https://vuejs.org/api/reactivity-core#onwatchercleanup)也沒有其他說明。

說不定實際效果不一樣？讓我們來實測看看吧。%(๑•̀ㅂ•́)و✧%

這裡我們使用一個[免費的 API](https://alexwohlbruck.github.io/cat-facts/docs/) 來測試，順便取得貓貓冷知識 XD。

::: warning
如果 API 壞了，大家可以換成[其他 API 測試](https://free-apis.github.io/#/browse)。
:::

## 實際測試

```vue
<script setup>
import { onWatcherCleanup, ref, watch } from 'vue'

const id = ref('cod')
const data = ref([])

watch(id, (newId, oldId, onCleanup) => {
  const controller = new AbortController()

  fetch(
    `https://cat-fact.herokuapp.com/facts?id=${newId}`,
    { signal: controller.signal }
  )
    .then((res) => res.json())
    .then((value) => {
      data.value = value
    })
    .catch((error) => {
      console.error(error)
    })

  onWatcherCleanup(() => {
    console.log('[ onWatcherCleanup ] : ', controller)
    controller.abort()
  }) // */

  /* onCleanup(() => {
    console.log('[ onCleanup ] : ', controller);
    controller.abort()
  }) // */
})

function getData() {
  id.value = crypto.randomUUID()
}
</script>

<template>
  <button @click="getData()">
    取得貓貓小知識
  </button>

  <p v-for="datum, i in data" :key="i">
    {{ i + 1 }}. {{ datum.text }}
  </p>
</template>
```

[範例程式碼](https://play.vuejs.org/#eNqdVM1u1DAQfpWRhbRpSRNVhcuyWyhtD+UACKg41BV1E2fXrWNHtrMtWuUZekACbpw4IiEegLdZ0cdg7OxPCqhIXa1ie2a+b2Y+TzIlO1WVTGpO+mRgMyMqB5a7utqmSpSVNg6mYHgRwwVz2TgGrd76DTe7kjNVV9BAYXQJPeToUUVVppV1IHIYelzUy3TeW1uYc+bY3HF0jFaqAm0k8hgixS8OcNUyD4uaZ1iD4TZMqQJoOfDpjJaSG2RCDOycYpm7S2sUeAEK7pn9DuBk7Fxl+2maMbdRsMwl2IE+rxk2n+ky9Sb7WOTDe9NQRXMSt8ApWDFSTPY7aZPWBI0PwWQ+LnFjrqLIcBvKxTU5s1pFazf9EyZrvmrI/7wkSbBjO2F91LqaBRRrxkYibow2N7FeEC15ElzzgA7a75YyRlEXu0BKPYp6R6soOIY+9OJOtwvCTv/MC+5l9mkgTWE9bZOl63/Nx3/S/jFMd87etlvUKnNCKxhxt4e6Yu6QWORLhTPzvnI6MUzlujw8PNiLfAq8ykHajj8OPh4cLyvJHMcTwOC0dg5Zn2RSZOdDSpb0lGzPrj7Ofn66/vEB/7PvV7++fL3+9nmQtpBAhgQVTDYKbRCK112XMQgQKlw9MswnbYrG+7AJTZP4QwhMHL90aAkkqX8pB2mnNBITZ1GaQozCuOFLHPqlBIe6EqjWi8rrYSnpL66AEialvngWbM7UfD7piBnz7Pwf9jN76W2UvMSx5mbCKVn6HDMoRuvef/0cq+04S53XEqNvcb7iOA+1r7ENe1qrHMvuxIVqD8KnSKjRG7t/6biyi6Z8oWESQjwl+BXavaX1VblbyYOAw7tHFd9NuPGcKOBW8jDZJM1vjAKyGQ==)

就一個簡單的按鈕，點擊後會取得貓貓小知識，並顯示在畫面上。

![測試程式](/vue-3-5-update-on-watcher-cleanup-with-the-forgotten-on-cleanup/1.webp)

每次 watch 觸發時，會呼叫上一次的 onCleanup 或 onWatcherCleanup，這樣就可以清理上一次的副作用。

所以讓我們快速點擊按鈕兩下，觀察一下 DevTools 之 Network 的結果。

![Network](/vue-3-5-update-on-watcher-cleanup-with-the-forgotten-on-cleanup/2.webp)

可以注意到上次的 fetch 順利取消了！

現在讓我們把 onWatcherCleanup 註解掉，改用 onCleanup，再來觀察一下。

見證奇蹟的時刻到了！

結果一模一樣！%╮(╯▽╰)╭%

...嗯，以上例子的確看不出差別，但是不代表 onWatcherCleanup 沒有用途，讓我們再來看看其他情境吧。

## onWatcherCleanup 使用情境

::: tip
感謝 Line Vue.js Taiwan 社群裡的 dog 大大[提供的資訊](https://github.com/vuejs/core/pull/9927)，忽然茅舍頓開。%ᕕ( ﾟ ∀。)ᕗ%
:::

目前來看 onWatcherCleanup 比較類似 getCurrentScope、onScopeDispose 這類底層 API，平常不會特別使用，一般業務邏輯用 onCleanup 就好。（想統一用 onWatcherCleanup 也是可以 XD）

不過如果你希望「在 watch 中重新執行時，會自動清理上一次動作」的實用 API，這時候 onWatcherCleanup 就派上用場了。

概念上有點類似 [VueUse 的 useEventListener](https://vueuse.org/core/useEventListener/#useeventlistener)，此 API 可以在元件中註冊事件，並在元件被銷毀時自動移除。

```ts
import { useEventListener } from '@vueuse/core'

// 像這樣註冊事件，不用手動 removeEventListener
useEventListener(document, 'visibilitychange', (evt) => {
  console.log(evt)
})
```

只是 useEventListener 的目標是「整個元件的 effect scope」，而 onWatcherCleanup 的目標是「單一 watcher scope」。

讓我們延伸剛剛的例子，設計一個在 watch 使用時會自動取消前一次請求，並在元件解除後也會自動取消請求的 API。

新增一個 useCatFact。

```js
import { onBeforeUnmount, onWatcherCleanup, shallowRef } from 'vue'

export function useCatFact() {
  const abortController = shallowRef()

  /** 元件解除前，自動取消請求 */
  onBeforeUnmount(() => {
    abortController.value?.abort()
  })

  /** 取得貓貓小知識 */
  function getFact(id) {
    return new Promise((resolve, reject) => {
      const controller = new AbortController()

      fetch(
        `https://cat-fact.herokuapp.com/facts?id=${id}`,
        { signal: controller.signal }
      )
        .then((res) => res.json())
        .then((value) => resolve(value))
        .catch((error) => {
          // 忽略終止錯誤
          if (error.name === 'AbortError')
            return
          reject(error)
        })

      /**
       * 在 watcher 範圍內會自動取消前一次請求
       *
       * 第二個參數 true 表示忽略不在 watcher 範圍內警告
       */
      onWatcherCleanup(() => {
        controller.abort()
      }, true)

      abortController.value = controller
    })
  }

  return {
    getFact,
  }
}
```

接著在元件中使用。

```vue
<script setup>
import { ref, watch } from 'vue'
import { useCatFact } from './useCatFact.js'

const id = ref('cod')
const data = ref([])

const { getFact } = useCatFact()

watch(id, async (newId) => {
  data.value = await getFact(newId)
})

async function getData() {
  id.value = crypto.randomUUID()
}
</script>

<template>
  <button @click="getData()">
    取得貓貓小知識
  </button>

  <p v-for="datum, i in data" :key="i" class="tip">
    {{ i + 1 }}. {{ datum.text }}
  </p>
</template>
```

現在連續點擊按鈕，可以看到前次請求都會取消，而且元件解除時也會自動取消請求。

[範例程式碼](https://play.vuejs.org/#eNp9VW1rG0cQ/ivDUdDJVe4Iab+4ktPEccH90Ia0ph96pbncray1T7vH7p7sIAQhbuiLbUwp7gsYSlqnCalN2kKDSd/+jE9SPvUvZHbvdLpTRIRf2NmZ2WeeeWbUt67EsdNLiLVoNWUgaKxAEpXESx6j3ZgLBX0QpN2ALV8FHRhAW/Au1DCiVvJIJFn21Tt+oAoPx50anQ1Ze8tjHgs4kwpoCC2d1K4FPKzVJ+bQV35+8fEnaJ3Y+7BOJrlbpafsuslpgNk0bIAvb7MAbEa2VsM6tJag7zEwaZ2eHyUEo/0tn6pJvtwTswzMc1l8O2GBopxpr2sYa9ezPDQssgTidqy4I3wW8u7a2uo1A2XgsaabcYjs4UGRbhz5iuAJoHkrUQqzvh1ENNhseVaR3rOW0oNv03+/G//xDf6kvx2MfnwwPv2+6WYhJhkmiCGIfCkxVNHYs6B3oc0FnrDApNsACpSZYjGf9gfo99H4OlyEwcDRB+PoKLKNTCJYTOnqPjfdElCrYSmJvLfpOnaNM9SFqd6zAt6NaUTE+7FmR3rWYsaLvvOjiG+9a2xKJKQxsQcdEmzOsW/IbW3zrOuCSCJ6xLOKO+ULpCa7XvngPURbuuzyMInQ+xWXN4jkUaIxZm5XExYi7JKfQbtqtEvZ+odyZVsRJidFaaDac2D8PQulvvyK0qdwLzlvmDhUArJYUT+yWMwKZx9pxRKxHBGfJXEDZMcguqHHjLOrBNtK1liXJ2w6TmbgBCoBf8m2SVUItTwSCAw9ALLR8W+h4zJnSvAI8aN0p29pzeYJAdyFBUjv7Zz/9XT88OfnPxynX+7///fe+PPH6e4hinP49Ivxr7vD3+/CgpsFzOC08WUzcOYSZh/OJueyY8yoeOM1eAnAvCkoXizPpamV4pAXDwpcWoIBTjRcR8KoJLaN2uJRjzTwcoMEqopwQhH+nbKjw69UoWdop1FtotfN9Axws6NULBddN/DVhbZuODaXbyY+blYcGleb5GUatl7r03Bws1GO7YOk68yPFks4nMyEQiocc8ayj6M6hJnqTEX430yqXZ/nZYif+Gk2ckvVF5FjUTYRgotZmvTHdSH975/R4YPRn3eHpz8933syfnxcdaFtyOId5ndxSbZaUDNUrmhjrZ53yLR8GpV1Jn+4cocrucK7FkjpHtVy9Cj7UsLOjZ58lh7tp/ceDo92yqJFGZ+f3Rme3M/UW4mvHEYnJ+fP9tI7u+nBzvDwzCwBGN9/NDp+lhV+frY/98Hx6S/p11+Vc+Vy1Z/ZUZ+dklyFk75XpsNw0DBAZpiYO1v6W6kwFURmJOqdVGTIB6XAkE9TrkrjqNfXpz0i9ErEzXXJedO5aA1eAOJa7Q0=)

::: tip
這個時候可能有人會有疑問：「如果把 `onCleanup` 傳到 `useCatFact` 裡，不也可以嗎？」

的確可以，就看設計需求與風格了，像是剛剛提到的 `useEventListener` 就是自動處理的方式。%( •̀ ω •́ )✧%
:::

可以看到程式碼變得相當乾淨，不需要手動 onCleanup，也不用擔心忘記取消請求，非常方便。%∠( ᐛ 」∠)\_%

除了發送 HTTP 請求，這在設計動畫也十分實用，可以有效防止同一物件上的動畫重複執行。

舉一個動畫的例子，這裡使用 [anime.js](https://animejs.com/)。

設計一個名為 useBoxAnimation 的動畫工具，可以對指定元素執行各類預先定義好的動畫。

```ts
import anime from 'animejs'

export function useBoxAnimation() {
  /** 動畫目標元素 */
  const boxRef = ref<HTMLElement>()

  /** 元件解除前，刪除動畫 */
  onBeforeUnmount(() => {
    anime.remove(boxRef.value)
  })

  function translate(x, y) {
    anime({
      targets: boxRef.value,
      translateX: x,
      translateY: y,
      easing: 'spring(1, 80, 10, 0)'
    })

    onWatcherCleanup(() => {
      anime.remove(boxRef.value)
    }, true)
  }

  function rotate(deg) {
    anime({
      targets: boxRef.value,
      rotate: deg
    })

    onWatcherCleanup(() => {
      anime.remove(boxRef.value)
    }, true)
  }

  return {
    boxRef,
    translate,
    rotate,
  }
}
```

以上只是我目前的心得與理解，如果有更多的使用情境或是更深入的解釋，歡迎大家一起討論！%(´▽\`ʃ♡ƪ)%

## 總結 🐟

* 認識 `onCleanup` 與 `onWatcherCleanup`
* `onWatcherCleanup` 適合用在封裝後的功能，一般業務邏輯用 `onCleanup` 就好
* 官方文件的 `onWatcherCleanup` 例子舉的不太好，看不出與 `onCleanup` 的應用差異，害我一開始看得一頭霧水 XD

最後再次感謝 dog 大大提供的資訊，也歡迎大家加入 [Vue.js 社群](https://web-tech-tw.github.io/openchat/#/join/vue-tw)

一起討論 Vue 相關議題！(/≧▽≦)/

---

---
url: /blog-vue/vue-reactive-cheat-sheet.md
description: 現在官方推薦使用 ref 就行，所以 reactive 還有甚麼用處呢？讓我們筆記一下。(。・∀・)ノ
---

![vue-reactive-cheat-sheet](/vue-reactive-cheat-sheet.webp){.cover}

# Vue Reactive 使用筆記

使用 Vue 定義資料時，到底要用 `ref` 還是 `reactive` 是一個很常見的問題

不過[官方文件推薦使用 `ref`](https://vuejs.org/guide/essentials/reactivity-fundamentals#limitations-of-reactive:~:text=Due%20to%20these%20limitations%2C%20we%20recommend%20using) 就行，所以其實也不是甚麼大問題了。%( •̀ ω •́ )✧%

一般情況下的確 `ref` 更好，坑也相對少一點，且更容易拆分邏輯，詳細說明可以看看[尤大訪談](https://www.youtube.com/watch?v=e8Wlv4AGJjk\&ab_channel=%E6%88%90%E5%BC%8F%E8%AA%9E%E8%A8%80%2FMikeCheng)。

之前看到有人分享：「統一使用 `ref` 的優點是可以明確區分資料，需要用 `.value` 存取的資料一定為響應式資料，反之則否」，我覺得這個準則確實有幫助。

所以 `reactive` 真的沒用用途了嗎？這篇文章來記錄一下 `reactive` 的用法。

不定期更新，會持續補充用法。%( ´ ▽ \` )ﾉ%

## 解包響應式資料

以 VueUse 的 [useElementBounding](https://vueuse.org/core/useElementBounding/) 為例。

此 API 可以取得多個 element 的 bounding 資料，只需要寬高資料，就可以只取出寬高：

```ts
const { width, height } = useElementBounding(el)
```

但是有時候會需要全部都要，可能會這樣寫：

```ts
const bounding = useElementBounding(el)
```

這時候因為內部資料還是 ref，所以取值需要 .value（例如 `bounding.width.value`），這個時候就可以先用 reactive 包起來：

```ts
const bounding = reactive(useElementBounding(el))
```

包起來後，就可以 `bounding.width`，不用 value 了

以上用法供大家參考，若有錯誤還請大家多多指教。

## 建立簡易 store

Vue 官方[文件](https://vuejs.org/guide/scaling-up/state-management#simple-state-management-with-reactivity-api)提到 `reactive` 可以用來建立簡易的 store。

```ts
import { reactive } from 'vue'

export const store = reactive({
  count: 0,
  increment() {
    this.count++
  }
})
```

```vue
<template>
  <button @click="store.increment()">
    From B: {{ store.count }}
  </button>
</template>
```

不過除非很原因很明確，否則還是建議使用 Pinia 這類成熟的狀態管理套件，否則未來維護很麻煩。

::: tip
我曾經在[酷酷元件的落雪元件](https://chillcomponent.codlin.me/components/bg-snow/)中[實作過此用法](https://gitlab.com/side_project/chill-component/-/blob/main/src/components/bg-snow/bg-snow-store.ts)。

這麼做是因為此為內聚性高的獨立元件，若要求使用者在使用此元件前，必須先安裝 Pinia，這樣就太過於繁瑣了。

但若是一般網頁專案，在不確定專案會不會持續增長的情況下，還是建議使用 Pinia。
:::

## 總結 🐟

* 官方推薦使用 `ref`
* `reactive` 可以用在解包響應式資料、建立簡易 store
* 有其他用法也歡迎補充 %(´▽\`ʃ♡ƪ)%

---

---
url: /blog-vue/vue-template-compilation-magic.md
description: 常聽別人說 Vue template 有編譯魔法，來仔細看看到底差在哪，順便看看酷酷的 Vapor 模式。ლ(´ڡ`ლ)
---

![vue-template-compilation-magic](/vue-template-compilation-magic.webp){.cover}

# Vue template 編譯魔法

和同事討論到 Vue template、`h()` 的使用情境剛好最近使用 Nuxt UI 也常使用 `h()` 來渲染內容。

在高度動態的場景下，使用 `h()` 會更加方便，先前也有[文章](/blog-vue/vue-h-function-makes-quasar-dialog-easier-to-reuse.html)提到相關應用。

::: tip 甚麼是 `h()`
`h()` 是 Vue 的渲染函式，詳細說明可以[看看官方文件](https://vuejs.org/guide/extras/render-function.html)
:::

但是 `h()` 不會有 template 的編譯最佳化，所以沒有特別需求的情境下，還是建議使用 template。

[官方文件](https://vuejs.org/guide/essentials/template-syntax.html)的說法如下：

> If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also directly write render functions instead of templates, with optional JSX support. However, do note that they do not enjoy the same level of compile-time optimizations as templates.

聽說歸聽說，~~忍者龜忍者~~，從來沒有仔細研究過到底差在哪，趁這次機會來看看吧。%( ´ ▽ \` )ﾉ%

## 速度真的有差？

口說無憑，直接寫個範例比較看看吧。%( ´ ▽ \` )ﾉ%

由於 JSX 與 `h()` 概念相近，所以這裡只比較 template 與 `h()` 的差異。

分別建立 template 與 `h()` 的範例：

::: code-group

```vue \[list-template.vue]
<script setup>
defineProps(['items'])
</script>

<template>
  <div class="root-container">
    <div v-for="item in items" :key="item.id" class="card-wrapper" data-test="static-attr">
      <div class="card-header" style="background: #eee; padding: 10px; border-bottom: 1px solid #ddd;">
        <h4 class="title" style="margin: 0; color: #333;">
          靜態標題 - Level 1
        </h4>
        <span class="badge" style="background: red; color: white; padding: 2px 5px;">Static Badge</span>
      </div>

      <div class="level-2-wrapper" style="display: flex; gap: 10px; padding: 10px;">
        <div class="static-col-left" style="width: 50px; background: #ccc;">
          Left
        </div>

        <div class="level-3-wrapper" style="flex: 1; border: 1px dashed blue;">
          <ul class="static-list" style="list-style: none; margin: 0; padding: 0;">
            <li style="padding: 5px;">
              Static List Item A
            </li>
            <li style="padding: 5px;">
              Static List Item B
            </li>

            <li class="level-4-target" style="padding: 5px; background: #eef;">
              <span class="label" style="font-weight: bold; margin-right: 10px;">Value:</span>

              <span class="dynamic-val" style="color: blue; font-size: 1.2em;">
                {{ item.text }}
              </span>
            </li>
          </ul>
        </div>
      </div>

      <div class="card-footer" style="padding: 5px; text-align: center; color: #999;">
        Copyright &copy; 2024 Static Inc.
      </div>
    </div>
  </div>
</template>

```

```ts \[list-h.ts]
import { h } from 'vue'

export default {
  props: ['items'],
  setup(props: { items: any[] }) {
    return () => h('div', { class: 'root-container' }, props.items.map((item) =>
      h('div', { 'key': item.id, 'class': 'card-wrapper', 'data-test': 'static-attr' }, [
        h('div', { class: 'card-header', style: 'background: #eee; padding: 10px; border-bottom: 1px solid #ddd;' }, [
          h('h4', { class: 'title', style: 'margin: 0; color: #333;' }, '靜態標題 - Level 1'),
          h('span', { class: 'badge', style: 'background: red; color: white; padding: 2px 5px;' }, 'Static Badge'),
        ]),

        h('div', { class: 'level-2-wrapper', style: 'display: flex; gap: 10px; padding: 10px;' }, [
          h('div', { class: 'static-col-left', style: 'width: 50px; background: #ccc;' }, 'Left'),

          h('div', { class: 'level-3-wrapper', style: 'flex: 1; border: 1px dashed blue;' }, [
            h('ul', { class: 'static-list', style: 'list-style: none; margin: 0; padding: 0;' }, [
              h('li', { style: 'padding: 5px;' }, 'Static List Item A'),
              h('li', { style: 'padding: 5px;' }, 'Static List Item B'),

              h('li', { class: 'level-4-target', style: 'padding: 5px; background: #eef;' }, [
                h('span', { class: 'label', style: 'font-weight: bold; margin-right: 10px;' }, 'Value:'),

                h('span', { class: 'dynamic-val', style: 'color: blue; font-size: 1.2em;' }, item.text),
              ]),
            ]),
          ]),
        ]),

        h('div', { class: 'card-footer', style: 'padding: 5px; text-align: center; color: #999;' }, 'Copyright © 2024 Static Inc.'),
      ]),
    ))
  },
}

```

:::

接著引用以上元件並計時更新耗時，為了讓差距明顯一點，讓內容重複 2000 次。

`perf-comparison.vue`

```vue
<template>
  <div class="flex flex-col gap-2 border border-gray-300 dark:border-gray-600 p-4 rounded">
    <div class="flex gap-2 text-base">
      <div
        :class="{ 'bg-primary': currentMode === 'template' }"
        class="bg-gray-200/50 dark:bg-gray-700/50 p-3 rounded cursor-pointer duration-300 flex-1"
        @click="currentMode = 'template'"
      >
        使用 Template
      </div>

      <div
        :class="{ 'bg-primary': currentMode === 'h' }"
        class="bg-gray-200/50 dark:bg-gray-700/50 p-3 rounded cursor-pointer duration-300 flex-1"
        @click="currentMode = 'h'"
      >
        使用 h()
      </div>
    </div>

    <div
      class="flex justify-center cursor-pointer border p-2 rounded duration-300"
      :class="{ ' border-dashed opacity-60': isStarted }"
      @click="isStarted = !isStarted"
    >
      {{ isStarted ? '停止' : '開始' }}
    </div>

    <div class="mt-2">
      更新耗時：<span>{{ timeCost }} ms</span>
    </div>

    <div class="h-0 overflow-hidden">
      <list-template
        v-if="currentMode === 'template'"
        :items="items"
      />
      <list-h
        v-else
        :items="items"
      />
    </div>
  </div>
</template>

<script setup>
import { useRafFn } from '@vueuse/core'
import { nextTick, ref, watch } from 'vue'
import ListH from './list-h.ts'
import ListTemplate from './list-template.vue'

const COUNT = 2000
const items = ref(Array.from({ length: COUNT }).fill(0).map((_, i) => ({ id: i, text: `Item ${i}` })))
const currentMode = ref('template')
const timeCost = ref(0)
const isStarted = ref(false)

async function runTest() {
  const newVal = `Updated ${Math.floor(Math.random() * 1000)}`
  const start = performance.now()

  items.value[COUNT - 1].text = newVal

  // 等待 DOM 更新完成
  await nextTick()

  const end = performance.now()
  timeCost.value = (end - start).toFixed(2)
}

const ticker = useRafFn(() => {
  runTest()
}, {
  fpsLimit: 10,
  immediate: false,
})

watch(isStarted, (value) => {
  value ? ticker.resume() : ticker.pause()
})
</script>

<style></style>

```

現在大家可以按下開始按鈕並切換模式，看看耗時有甚麼差異。

在我的電腦上，template 大約在 5 ms，`h()` 大約在 20 ms。

不同裝置結果會不一樣，不過很明顯可以看出 template 的速度會比 `h()` 快得多。

不過通常不會產生大量元素，所以平時完全看不出差別，只是當你的網頁量級增加，積少成多，性能負擔自然會增加。

所以實務上來說除非有明確的需求或元件 API 限制，否則比較推薦使用 template。%(・∀・)９%

## 編譯結果

template 為甚麼會比較快呢？文件的說法是因為 Vue 的編譯器會自動最佳化（Compile-time Optimization），快取靜態節點、加速 Patch Flags 加速比較過程等等。

實際上不管是 template 還是 `h()`，最終 Vue 都會編譯成 JS 程式碼，用以產生 Virtual DOM (VDOM)。

讓我們來看看編譯後的產物有甚麼差別吧。%੭ ˙ᗜ˙ )੭%

這裡使用 [Vue SFC Playground](https://play.vuejs.org/) 的 PROD 模式進行編譯，來比較 template、`h()` 與 JSX 的編譯內容。

分別建立 3 種版本的簡單範例：

::: code-group

```vue [template]
<script setup>
import { ref } from 'vue'

const msg = ref('Hello Vue!')
</script>

<template>
  <h1>{{ msg }}</h1>
  <input v-model="msg">

  <h2>Hi</h2>
</template>
```

```ts [h()]
import { defineComponent, h, ref } from 'vue'

export default defineComponent({
  setup() {
    const msg = ref('Hello Vue!')

    return () => h('div', null, [
      h('h1', null, msg.value),
      h('input', {
        value: msg.value,
        onInput: (e: Event) => {
          msg.value = (e.target as HTMLInputElement).value
        },
      }),
      h('h2', null, 'Hi'),
    ])
  },
})
```

```tsx [JSX]
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const msg = ref('Hello Vue!')

    return () => (
      <div>
        <h1>{msg.value}</h1>
        <input
          value={msg.value}
          onInput={(e) => (msg.value = (e.target as HTMLInputElement).value)}
        />
        <h2>Hi</h2>
      </div>
    )
  },
})
```

:::

編譯結果：

::: code-group

```js [template]
/* Analyzed bindings: {
  "ref": "setup-const",
  "msg": "setup-ref"
} */
import { createElementBlock as _createElementBlock, createElementVNode as _createElementVNode, Fragment as _Fragment, openBlock as _openBlock, toDisplayString as _toDisplayString, vModelText as _vModelText, withDirectives as _withDirectives, ref } from 'vue'

const __sfc__ = {
  __name: 'App',
  setup(__props) {
    const msg = ref('Hello Vue!')

    return (_ctx, _cache) => {
      return (_openBlock(), _createElementBlock(_Fragment, null, [
        _createElementVNode('h1', null, _toDisplayString(msg.value), 1 /* TEXT */),
        _withDirectives(_createElementVNode('input', {
          'onUpdate:modelValue': _cache[0] || (_cache[0] = ($event) => ((msg).value = $event))
        }, null, 512 /* NEED_PATCH */), [
          [_vModelText, msg.value]
        ]),
        _cache[1] || (_cache[1] = _createElementVNode('h2', null, 'Hi', -1 /* CACHED */))
      ], 64 /* STABLE_FRAGMENT */))
    }
  }
}
__sfc__.__file = 'src/App.vue'
export default __sfc__
```

```js [h()]
/* Analyzed bindings: {} */

import { defineComponent, h, ref } from 'vue'

const __sfc__ = defineComponent({
  setup() {
    const msg = ref('Hello Vue!')

    return () => h('div', null, [
      h('h1', null, msg.value),
      h('input', {
        value: msg.value,
        onInput: (e) => {
          msg.value = (e.target).value
        },
      }),
      h('h2', null, 'Hi'),
    ])
  },
})

__sfc__.__file = 'src/App.vue'
export default __sfc__
```

```js [JSX]
/* Analyzed bindings: {} */

import { createTextVNode as _createTextVNode, createVNode as _createVNode, defineComponent, ref } from 'vue'
const __sfc__ = defineComponent({
  setup() {
    const msg = ref('Hello Vue!')
    return () => _createVNode('div', null, [_createVNode('h1', null, [msg.value]), _createVNode('input', {
      value: msg.value,
      onInput: (e) => msg.value = e.target.value
    }, null), _createVNode('h2', null, [_createTextVNode('Hi')])])
  }
})
__sfc__.__file = 'src/App.vue'
export default __sfc__
```

:::

從結果中可以發現 `h()` 與 JSX 結果基本上相似，template 則是加了不少東西，讓我們來看看是甚麼吧。%ヾ(◍'౪\`◍)ﾉﾞ%

## Vue Runtime Helpers

template 編譯結果中的 `openBlock`、`createElementBlock`、`withDirectives`、`toDisplayString`、`_cache` 等等都是 [Vue Runtime Helpers](https://github.com/vuejs/core/blob/main/packages/compiler-core/src/runtimeHelpers.ts) 的一部分，用於處理 Virtual DOM 的操作。

其中 Cache 與 Patch Flags 是相當重要的一環，可以來看看 Vue 的 [Rendering Mechanism](https://vuejs.org/guide/extras/rendering-mechanism) 文件，裡面說明了 Vue 如何改進渲染效能。

不過 `h()` 也可以寫出同 Cache 的效果，只要將希望快取的內容提升到變數中即可，例如剛剛的範例就可以改寫成這樣：

```ts
import { defineComponent, h, ref } from 'vue'

export default defineComponent({
  setup() {
    const msg = ref('Hello Vue!')

    const onInput = (e: Event) => { // [!code ++]
      msg.value = (e.target as HTMLInputElement).value // [!code ++]
    } // [!code ++]

    const staticNode = h('h2', null, 'Hi') // [!code ++]

    return () => h('div', null, [
      h('h1', null, msg.value),
      h('input', {
        value: msg.value,
        onInput: (e) => { // [!code --]
          msg.value = (e.target).value // [!code --]
        }, // [!code --]
        onInput, // [!code ++]
      }),
      h('h2', null, 'Hi'), // [!code --]
      staticNode, // [!code ++]
    ])
  },
})
```

只是這樣寫起來會比較麻煩，也不支援 Patch Flags。%◝( •ω• )◟%

## 同場加映：Vapor Mode

啟發於 SolidJS，Vue v3.6 引入了 Vapor 模式（連名字都有致敬 XD），完全捨棄 VDOM，改為直接操作 DOM。

可以相容原有的寫法，只要在 `<script setup>` 中加入 `vapor` 即可：

```vue{1}
<script setup vapor> // [!code focus]
import { ref } from 'vue'

const msg = ref('Hello Vue!')
</script>

<template>
  <h1>{{ msg }}</h1>
  <input v-model="msg">

  <h2>Hi</h2>
</template>
```

在 [Vue SFC Playground](https://play.vuejs.org/#eNp9Uc1KAzEQfpWYyyrYrbbioWwLKoXqQUXFU0DW7XSbmk1CMlkLy767k5RWD9JTMt/P8M1Mx2+szdsAfMILXzlpkXnAYFlbWuNmQsuGXmQdc7BiPVs507CMDJnQQldGe2SNr9k08qfZApQy7D3ASXYmdDHctaQ2VCA0VpUIVDFWrC9nXZesfV8MqUqo1DYgaweNWYKaCk684MkeLaPZQpJ2REAxPLTj5xw9JVnJOt94o2mULuoFr0xjpQL3ZFFSUsEnLDGRKyno90PC0AU43+PVGqqvf/CN30ZM8GcHHlwLgh84LF0NuKPnr4+wpf+BpFGCIvUR8gW8USFm3Mlug15S7D+6lPY+nULq+s3Ptwja74eKQaOyT3rB6Tx3R0b/jTvOr5JP6J62+NGCiz1pgeP8Or8YfAKW+Zj3P/ZVs9o=) 中將版本改為 v3.6，可以看到編譯結果已經沒有 VDOM 的身影了。

```js
/* Analyzed bindings: {
  "ref": "setup-const",
  "msg": "setup-ref"
} */
import { applyTextModel as _applyTextModel, renderEffect as _renderEffect, setText as _setText, template as _template, toDisplayString as _toDisplayString, txt as _txt, ref } from 'vue'

const __sfc__ = {
  __name: 'App',
  __vapor: true,
  setup(__props, { expose: __expose }) {
    __expose()

    const msg = ref('Hello Vue!')

    const __returned__ = { msg, ref }
    Object.defineProperty(__returned__, '__isScriptSetup', { enumerable: false, value: true })
    return __returned__
  }
}

const t0 = _template('<h1> ')
const t1 = _template('<input>')
const t2 = _template('<h2>Hi')
function render(_ctx, $props, $emit, $attrs, $slots) {
  const n0 = t0()
  const n1 = t1()
  const n2 = t2()
  const x0 = _txt(n0)
  _applyTextModel(n1, () => (_ctx.msg), (_value) => (_ctx.msg = _value))
  _renderEffect(() => _setText(x0, _toDisplayString(_ctx.msg)))
  return [n0, n1, n2]
}
__sfc__.render = render
__sfc__.__file = 'src/App.vue'
export default __sfc__
```

其中 `_template` 用來建立真實 DOM，仔細比對可以發現：

* `n1` 為 `input` 元素，`_applyTextModel` 處理 `v-model` 指令，同步 `msg` 資料
* `x0` 為 `h1` 元素，`_renderEffect` 追蹤 `msg` 響應，使用 `_setText` 更新 text 資料

可以注意到 Vapor 模式的更新關注點是 DOM，透過響應式系統精準更新，而原本 VDOM 則是整個元件，每次更新都需要比較整個元件的 VDOM。

相較之下 Vapor 省掉許多不必要的計算，配合 [`alien-signals`](https://github.com/stackblitz/alien-signals) 更是如虎添翼，性能大幅提升。

不過目前 Vapor 模式還在實驗階段，期待 v3.6 的正式推出！%╰(*´︶\`*)╯%

## 總結 🐟

* template 比 `h()` 快
* 高度動態情境使用 `h()` 更加方便
* Vue Compiler 會自動最佳化 template，更高效的操作 VDOM
* Vapor 模式則無 VDOM，可以節省許多不必要的計算，藉此提高性能

---

---
url: /blog-vue/hang-tight-for-a-sec-before-you-start-watch.md
description: watch 不是不能用，而是在使用 watch 之前，先想想有沒有其他方案，真的沒有才用 watch。
---

![dont-depend-on-watch](/dont-depend-on-watch.webp){.cover}

# Vue watch 前先小等一下

先說結論：

::: danger
`watch` 不是不能用，而是在使用 `watch` 之前，先想想有沒有其他方案，真的沒有才用 `watch`。
:::

千萬不要為了一時方便讓元件裡滿滿的 `watch`，因為容易產生難以追蹤的副作用，會讓資料流更加複雜。

口說無憑，讓我們舉個栗子 (｡･∀･)ﾉ🌰。

## 舉個栗子 (｡･∀･)ﾉ🌰

考慮一個簡單的元件，輸入資料型別可以為 `string` 或 `number`，回傳則固定為 `number`。

```vue
<script setup lang="ts">
interface Props {
  modelValue?: string | number;
}
const props = withDefaults(defineProps<Props>(), {
  modelValue: 0,
})

const emit = defineEmits<{
  (e: 'update:modelValue', value: number): void;
}>()

const numberValue = ref(props.modelValue)

watch(() => props.modelValue, (value) => {
  numberValue.value = Number.parseFloat(value)
})
</script>
```

你可能會想問：「阿不是說能不用就不要用，怎麼開場就有 `watch`？」

這是因為除了 `watch` 以外，沒有其他方法可以在元件內得知  `props.modelValue` 發生變更，所以此部分使用 `watch` 沒問題。

以上程式已經將 `props.modelValue` 數值同步至 `numberValue` 中，現在只差將 `numberValue` 數值 emit 出去部分，直覺上可能會這樣寫：

```vue
<script setup lang="ts">
// ...

watch(numberValue, (value) => {
  emit('update:modelValue', Number.parseFloat(value))
})
</script>
```

在簡單的例子中，這樣寫不會有太大問題，但是若 `numberValue` 資料較為複雜（例如深層物件、矩陣等等）或者耦合其他邏輯時，這樣寫可能會導致 watch 無限呼叫或其他難以追蹤的副作用。

一般情況下，我們應該可以直接知道 `numberValue` 的變化來源。

::: warning
⚠ 如果沒辦法得知，應該重新仔細思考設計
:::

如果是 input 的話，我們可以從 `@change` 事件得知數值變化，所以此例子可以不使用 watch，結果可能會這樣：

```vue
<script setup lang="ts">
// ...

function handleUpdate() {
  emit('update:modelValue', Number.parseFloat(numberValue.value))
}

// 或是這樣
function handleUpdate(value: string) {
  emit('update:modelValue', Number.parseFloat(value))
}
</script>
```

也就是在明確的資料流中呼叫 emit。

::: tip
或者使用 input 的 `@blur` 事件，可以在確保使用者輸入完畢，離開 input 後再觸發，減少不必要的連續觸發。
:::

## 總結 🐟

* 設計元件時，資料流越單純越好，以免寫得時候很爽，除錯的時候火葬場
* watch 是一個很方便的 API，但不要濫用，以免過多副作用難以追蹤

但是如果發現元件內有很多「只能用 `watch` 才能處理的邏輯」，那就表示你可能耦合了太多邏輯和副作用在單一元件內。

請好好思考拆分元件、重構或者重新探討元件設計。( ‧ω‧)ノ╰(‧ω‧ )

---

---
url: /blog-vue/vue-trigger-ref-problem.md
description: 前陣子使用 triggerRef 時發現某些情境下無法觸發響應，一起來看看發生甚麼事吧 (´・ω・`)
---

![vue-trigger-ref-problem](/vue-trigger-ref-problem.webp){.cover}

# Vue 之 triggerRef 問題

`triggerRef` 主要用於觸發 `shallowRef` 響應，但是在某些情境下會無法觸發響應。%( ´•̥̥̥ ω •̥̥̥\` )%

::: tip 甚麼是 `shallowRef`
想了解甚麼是 `shallowRef` 的朋友，可以參考我之前寫的[文章](./vue-shallow-ref-and-ref)。
:::

## 問題

[問題重現](https://play.vuejs.org/#eNqNVLuO00AU/ZUrN3Gk4PCqghPx2C2ggNWCaOIUxr52vDsej2bGSSTLiAoKSqSVoACJYmskGj4IVin5BO6MEydkl7BN4rmPc4/vnOPKeSCENyvRGTi+imQmNCjUpQAW8nQYOFoFzijgWS4KqaECiUkP1DRkrJgfm2ctszRFSc9QQyKLHDoE12lbHhW5WMW9vjmYaZ17AQ94VHClIQ51CMMtTF8RJk/Hk5E7nnRNYcCTkkc6KziEcXxADW4XqoCDbfZmISvRE6Waup0ONcAWKddUUKy+CuXm7f/gbMLEcOx53iYwsZh+v1karYgOGnPBQo10AvBflVrTrPsRy6JTWmVLnTZ6cfbt19fPy+/vLs4++v2mcm+Xodr2/fxxvjx/u/zw/hKAhZjeGtGt+n36t2clQj6qqmbTdU2cTWBVbO9ndiMvYmQ0ztQEDvQp7fe33sfpkRTowpIs9U5UwUkvdnGBExFAxlA+E2a1JJdBs1KTs1f6xMa0LLG3jkdTjE6viJ+ohYkFzpFEhXKGgdPmdChT1E368PlTXNBzmyT6JaPqPcljVAUrDcem7GHJY6K9VWfZPrayJf29UIcLjVytX8oQNZW1rQ8ckrHZ3b9efUP3jnfX9pFgaItrC1zXcPNQR9Mda1Gaa5RJGCEcyUKoZqy9w5dGnANYe4iMZqXfeE3Y4iHMMz09wCQsmVZujEnG0eL49nfkdntQ1SvrWQIuGWU4avq9zZweuNYMNmk5mDkFQ48Vqdv5/eXTG3gN4+YjYIEmlzAGxmo1DbSGQxRbmsjyHOOMFNjGDKt9piPNm2E74gdS/+5ccgK0Vvhb6/UfhXHI0A==)

從以上例子可以看到，當 `shallowRef` 傳遞給子元件後，執行 `triggerRef` 並沒有觸發子元件內的響應。

官方有一個 [issue](https://github.com/vuejs/core/issues/7614) 討論此問題。

不過目前看來還沒辦法解決，所以遇到此問題時，只能回歸直接賦值或者參考 issue 內其他解法。

## 總結 🐟

* `shallowRef` 傳遞給子元件後，執行 `triggerRef` 不會觸發子元件內的響應
* 直接賦值或者參考 issue 內其他解法

---

---
url: /blog-vue/use-suspense-to-load-components-asynchronously.md
description: 切換頁面卡卡有很多種原因，這裡舉的例子只針對元件太大的情境。除了想辦法拆分外，還有一個方法就是利用 Vue 的 Async Component。
---

![use-suspense-to-load-components-asynchronously](/use-suspense-to-load-components-asynchronously.webp){.cover}

# Vue 元件太肥，切換頁面卡卡怎麼辦？讓 Suspense 登場吧！

醜話說在前頭，切換頁面卡卡有很多種原因，這裡舉的例子只針對元件太大的情境喔。( •̀ ω •́ )✧

甚麼樣的情況會讓元件太大呢？有可能是 HTML、CSS 太多，但最常見的情況就是包了太多 JS 在一起了。╮(╯▽╰)╭（import 一大堆套件等等）

除了想辦法拆分外，還有一個方法就是利用 Vue 的 Async Component。

## Async Component 是什麼？

甚麼是 [Async Component](https://vuejs.org/guide/components/async)？簡單來說就是在真的要用的時候才從 server 下載元件，如果熟悉 Vue Router 的朋友們對以下寫法一定不陌生：

```ts
const router = createRouter({
  // ...
  routes: [
    {
      path: '/users/:id',
      component: () => import('./views/UserDetails.vue')
    },
  ],
})
```

這個在 Vue Router 中被稱為 [Lazy Loading Routes](https://router.vuejs.org/guide/advanced/lazy-loading.html)。

此概念與 Async Component 概念相同，編譯、打包時會將每個頁面拆分，只有在真的需要某頁面元件時，才從 server 下載，才不會讓進入網頁的使用者等待下載一堆還不會用到的頁面。

讓我們來一個簡單的範例：

`App.vue`

```vue
<script setup>
import FatComp from './components/FatComp.vue'
</script>

<template>
  Vue Suspense

  <hr>

  <fat-comp />
</template>
```

其中 FatComp 是一個和鱈魚一樣超肥的元件，會顯示「很大很大的元件」。

鱈魚：「說好的尊重呢？(ﾟДﾟ\*)ﾉ」

如果我們直接 import 元件，就必須等待元件下載完成，`App.vue` 的畫面才會出現。

![同步載入](/use-suspense-to-load-components-asynchronously/sync.gif){width="240px" format="gif"}

可以注意到 Vue Suspense 的文字會等到 FatComp 載入完成後才會顯示。

如果我們使用 Suspense 改寫：

```vue
<script setup>
import { defineAsyncComponent } from 'vue'

const AsyncFatComp = defineAsyncComponent(() =>
  import('./components/FatComp.vue')
)
</script>

<template>
  Vue Suspense

  <hr>

  <Suspense>
    <async-fat-comp />

    <template #fallback>
      Loading...
    </template>
  </Suspense>
</template>
```

![非同步載入](/use-suspense-to-load-components-asynchronously/async.gif){width="240px" format="gif"}

可以看到 Vue Suspense 字樣先出現，肥肥的元件則會等到下載完成才出現。

恭喜頁面不卡了！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

Suspense 元件詳細說明可以來[官方文件](https://cn.vuejs.org/guide/built-ins/suspense)看看。

以上[範例程式在此](https://stackblitz.com/edit/vue-suspense-cmte55?file=src%2FApp.vue\&terminal=dev)，我們下次再見囉！(´▽\`ʃ♡ƪ)

## 總結 🐟

* 肥大元件請用 Async Component
* 配合 Suspense 可以讓頁面有更好的使用者體驗

---

---
url: /blog-vue/vue-generic-components.md
description: Vue 3.3 終於新增了泛型元件（Generic Component），可以在 TypeScript 環境中得到更準確的型別提示了！ˋ( ° ▽、° )
---

![vue-generic-components.jpg](/vue-generic-components.webp){.cover}

# Vue 泛型元件，讓 TypeScript 更精確

大家好，我是鱈魚。%（＾∀＾●）ﾉｼ%

Vue 3.3 終於新增了泛型元件（Generic Component），可以在 TypeScript 環境中得到更準確的型別提示了！%ˋ( ° ▽、° )%

這個泛型元件與 TypeScript 的 Generic 是同一個概念，不知道 Generic 的朋友可以先來來[複習一下](https://www.typescriptlang.org/docs/handbook/2/generics.html)。

甚麼？你說你沒有使用 TypeScript？抱歉浪費您 5 秒鐘，可以上一頁了。%（＞人＜；）%

或者在離開前路過[文件](https://vuejs.org/guide/typescript/overview#generic-components)湊個熱鬧。%( •̀ ω •́ )y%

有使用 TypeScript 的朋友就讓我們一起繼續看下去吧。%ლ(╹◡╹ლ)%

## 來個 select

假設我需要一個綁定物件的 select，最常見的問題就是 `modelValue` 只能 `any`，如下：

`SelectAny.vue`

```vue
<script setup lang="ts">
// ...（省略其他程式碼）

interface Prop {
  modelValue: any;
  label?: string;
  options: any[];
  optionLabel?: (option: any) => string;
  /** 是否多選 */
  multiple?: boolean;
}

// ...
</script>
...
```

### v-model 這個糖

忘記元件怎麼實現 v-model 的朋友們別擔心，讓我們複習一下。

::: tip
Vue 3.4 開始可以使用 `defineModel`，不過與此文主題無關，所以我們先使用經典寫法。
:::

v-model 只是一個語法糖，實際上的程式碼如下（[文件](https://vuejs.org/guide/components/v-model.html#under-the-hood)）。

```vue
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', $event.target.value)"
  >
</template>
```

`modelValue` 就是用來表示預設綁定值的變數，讓我們回到剛剛的 `any`。

所以現在就算我們的 `modelValue` 與 `options` 的型別不同，或者  `multiple` 為 `true`，而 `modelValue` 卻沒有給矩陣時，都不會有任何錯誤提示。

```vue
<script setup lang="ts">
// ...
import SelectAny from './SelectAny.vue'

const options: User[] = [
  { name: '鱈魚', price: 10000 },
  { name: '章魚', price: 100 }
]

const anyDatum = ref<{ age: number }>()
const selectedAnyDatum = ref<User>()
</script>

<template>
  <!-- anyDatum 與 option 型別不同 -->
  <select-any v-model="anyDatum" :options="options" :option-label="getLabel" />

  <!-- modelValue 沒有給矩陣 -->
  <select-any v-model="selectedAnyDatum" multiple :options="options" :option-label="getLabel" />
</template>
```

畢竟是 any 嘛。%(˘･\_･˘)%

## 加上泛型

如果加上元件泛型就不會有以上問題了。

`SelectGeneric.vue`

```vue
<script
  setup
  lang="ts"
  generic="ModelValue, Multiple extends boolean"
>
// ...

interface Prop {
  modelValue: Multiple extends true ? ModelValue[] : ModelValue;
  label?: string;
  options: ModelValue[];
  optionLabel?: (option: any) => string;
  /** 是否多選 */
  multiple?: Multiple;
}

// ...
</script>
// ...
```

除了 `modelValue`、`options` 有泛型 `ModelValue` 外，我們還加上 `multiple` 判斷，如果為 true，則 `modelValue` 為 `ModelValue`\[]，否則為 `ModelValue`。

這樣子就可以達成以下效果：

* `modelValue` 與 `options` 型別不同時警告，
* `multiple` 為 true 時，如果 `modelValue` 沒有提供矩陣時發出警告。

```vue
<script setup lang="ts">
// ...
import SelectGeneric from './SelectGeneric.vue'

const options: User[] = [
  { name: '鱈魚', price: 10000 },
  { name: '章魚', price: 100 }
]

const anyDatum = ref<{ age: number }>()
const selectedGenericDatum = ref<User>()
const selectedGenericData = ref<User[]>([])
</script>

<template>
  <!-- Type '{ age: number; }' is not assignable to type 'User | User[]'.ts(2322) -->
  <select-generic v-model="anyDatum" :options="options" :option-label="getLabel" />

  <!-- Type 'User' is not assignable to type 'User[]'.ts(2322) -->
  <select-generic v-model="selectedGenericDatum" multiple :options="options" :option-label="getLabel" />

  <!-- 正確 -->
  <select-generic v-model="selectedGenericData" multiple :options="options" :option-label="getLabel" />
</template>
```

TypeScript 成功重返光榮。%o((>ω< ))o%

文章到此結束了，感謝您的閱讀，以上程式碼可以[在此](https://play.vuejs.org/#eNrtWM1u20YQfpUxL6INRWrQnlRJRpoYRYLmB3Xai+gDLS1lptSS4C5lGwIPvcVAgBQ9FUEPPaQ9tCiM9lSg6dvEbn3KK3R2lrsiKdlJHOWQID4Y5OzMzjezs9+MOHOuJUlrmjGn43TFMA0TCYLJLIHI5+Oe50jhOX2Ph5MkTiXMIGUB5BCk8QQaaNb4tLT2lWCpXWy15WHChFKwKtssYkN5jR9aHStRGEqbafnnjLM0HNa0C6mx8Pgw5kJCnMgQHzoEY7ADPRh4HBAW9yesA42zPx6e/f6k0YQEjVFw9SP8g7xZUfr3t5/qSpB7fIf8BBkfKh8wZvILf5dFrvapXa7DTG2VYvZSXqBpqW3RFrcwMH1+eMOX2QTxYS67M/DH6Idnk12VvL67jupaU2C0ko0wOWUD5Upr1fSKtCzXPUfTLykOdvruYEcpd9u6EvDc8UWySRL5kuEbQHfvat+eWbeNbySdH+z0yiQesQgrpwbfc6BTHBEuFk9z4ZVIJRRXTG5xqU0Aak7h7NHxf78+hbtk9uLZw9M/vz/98QjubxcrL54dzYEl/dNHR8//eQzXZRrByePj53//fPL0ydm3f3XbyfnYzSGtDPTtLJJhErG3hHcx15PC4eXxJ/3ZbKEG81zj0BGmC7EWpVWvDHORFxCXi/ZNkm2KFD2EAeoEfiQYMRfg3wK+xSI670QuCGEFRbIMWrlULoFqeWLfqBzQW7vEAgvVUWGeV6wQG+Ylav8VgvZXEPPyEH0bYSUpThNbJbJsEI5bD0TMsZ9SO/CcYTxJwoilutbQdUc3CrXmR1G8f4tkMs0Y9SKy2WPDb5bIH4gDJfOceylDyp5iids16acYg17e2r7DDvDZLmKisgi1L1j8kok4yhRGrfZZxkcIu6RHaG9Sgw75+L7YOpCMCxOUAqo0dUf1HGzP1y8IfQ7349YnZIdtErNYmQheYyppgoy/9iNMFuz7crjXBJX4DM+uPq+gHZcsDfwhg3tpnGhMVEq0QUf1aNQD9IYFsdkBIVMMmER2ykCdgRoLjIiKB3XtTIAK69Drl43bGxtw+sPxyXe/6LqGjTa5LgoVrXfjOGI+1yODbtqJgtiD/VDu3WCBj7rCHbEg5EyBF131H5t8U4dRAmOxEIxb23fvtDSWMDg0K3RWxn8H8Mhp5xHK8/X5iMEmoUQMenELX0SXvDWyZIT135knr9GBwVRnUQEbNEpLOypfxYhTnaZu8lCSjovb+UXuyEMYgLumhOtmslIvlE0NDS8CwkdwFGDip4K5tVjJXDvVG6qUtkzUhSM7uRUbbpoHDEifMw1xNbXqbEeB65HKrUSlHdpMEBiqUpdMmuDSGREQlWt3SWJtgWsb2iPHU8dTYYm+fpCX50LLfz17FdySH5UINaLHAZWYzQf0ej1o6Ow16slRXpYkY22tsoVC9rJBchROTSuja2Y6N73g7Ubu1XJFt/Q075mKlIeYbsv/lBFF6gYBytbWzIudA9BU1z2aBnFq+wGEZmCnzkC72cWSNf5QmJVvmL1fOaajcNDWMhNbW2MtuqgOut44Fn7WlGhP2Wnq04Rk6Y/ex9oGRbdtoTRtawWkecZHwrCK53gK19tizQW3VJKbMIeGv8pQzb6+lGPLliunWgN3tVxbBv2e8G6VAapcsYnkiGdqOZnuwXtKzLWwqmwMvliSeIJ3PqHrvT4Q+cVE/q7QOH3vakmB7M0OiGLnjEmfxmZequz1pybDVSQqvjbpr0Aky538f3lI90M=)取得。

有其他想法請不吝告訴我，鱈魚感謝您！%(o゜▽゜)o☆%

## 總結 🐟

* Vue 3.3 新增泛型元件
* 泛型元件可以讓 TypeScript 推導更精確

---

---
url: /blog-vue/vue-shallow-ref-and-ref.md
description: 熟悉 Vue 的朋友們一定知道 `ref` 是啥，一起來看看 `shallowRef` 和 `ref` 有甚麼差別吧！ԅ( ˘ω˘ԅ)
---

![vue-shallow-ref-and-ref](/vue-shallow-ref-and-ref.webp){.cover}

# Vue 的 shallowRef 是啥？和 ref 有甚麼差別？

熟悉 Vue 的朋友們一定知道 `ref` 是啥。ԅ( ˘ω˘ԅ)

不知道大家有沒有注意到 Vue 還有一個名字有點像的 API，叫做 `shallowRef`。

`shallowRef` 和 `ref` 有甚麼差別呢？

顧名思義，簡單來說 `shallowRef` 只對淺層（第一層）進行響應式處理。

也就是說以下程式碼。

```vue
<script setup>
import { shallowRef } from 'vue'

const shallowData = shallowRef({ cod: [] })

async function updateShallowData() {
  shallowData.value.cod.push('fish')
}
</script>

<template>
  <div>
    <div>
      shallowData: {{ shallowData.cod.length }}
    </div>

    <button
      class="bg-gray-300/50 dark:bg-gray-600/50 duration-100 p-1! px-3! rounded! active:bg-gray-400/80"
      @click="updateShallowData"
    >
      更新資料
    </button>
  </div>
</template>

```

當我們點擊「更新資料」按鈕時，`{{ shallowData.cod.length }}` 部分不會被更新，文字會保持 shallowData: 0。

除非 `updateShallowData` 內容改成：

```ts
async function updateShallowData() {
  const cod = [...shallowData.value.cod, 'fish']
  shallowData.value = { cod }
}
```

這樣就會因為第一層，也就是 `shallowData.value` 的值被改變，才會觸發響應，讓畫面更新。

或者使用 `triggerRef` 觸發響應也可以。

```ts
async function updateShallowData() {
  shallowData.value.cod.push('fish')
  triggerRef(shallowData)
}
```

看到這裡你可能會想「怎麼搞得更麻煩了？ლ（´口\`ლ）」

別急別急，讓我們來看看為甚麼需要 `shallowRef` 這個玩意兒。

## shallowRef 的使用場景

先來個工程師的好習慣，第一步先看看[文件寫甚麼](https://vuejs.org/api/reactivity-advanced.html)。

其實文件說得很清楚，主要目的是為了「性能考量」與「外部狀態管理整合」。

文件也給了具體例子：

* [Guide - Reduce Reactivity Overhead for Large Immutable Structures](https://vuejs.org/guide/best-practices/performance#reduce-reactivity-overhead-for-large-immutable-structures)
* [Guide - Integration with External State Systems](https://vuejs.org/guide/extras/reactivity-in-depth#integration-with-external-state-systems)

### 大型物件

對整個龐大物件進行響應式處理，會導致性能下降。

只看文字說明不夠具體，讓我們用程式碼證明看看吧。

考慮以下程式碼。

```vue
<template>
  <div
    ref="exRef"
    class="grid md:grid-cols-2 divide-y md:divide-y-0 md:divide-x divide-gray-100 dark:divide-gray-800"
  >
    <div class="p-8 flex flex-col items-center space-y-6">
      <span class="px-5 py-2 text-xs font-semibold bg-blue-100 dark:bg-blue-900/40 text-blue-700 dark:text-blue-300 rounded-md">
        Ref
      </span>

      <div class="text-xs  uppercase tracking-wider mb-1">
        耗時
      </div>
      <div class="text-3xl font-mono font-bold ">
        {{ dataCost }} <span class="text-sm font-normal">ms</span>
      </div>
    </div>

    <div class="p-8 flex flex-col items-center space-y-6">
      <span class="px-5 py-2 text-xs font-semibold bg-emerald-100 dark:bg-emerald-900/40 text-emerald-700 dark:text-emerald-300 rounded-md">
        Shallow Ref
      </span>

      <div class="text-xs  uppercase tracking-wider mb-1">
        耗時
      </div>
      <div class="text-3xl font-mono font-bold ">
        {{ shallowDataCost }} <span class="text-sm font-normal">ms</span>
      </div>
    </div>
  </div>
</template>

<script setup>
import { useIntersectionObserver, useRafFn } from '@vueuse/core'
import { ref, shallowRef, triggerRef, useTemplateRef } from 'vue'

// 建立 1 萬筆資料
function createData() {
  return {
    list: Array.from({ length: 10000 }).map((_, i) => ({ id: i, val: 0 })),
  }
}

const data = ref(createData())
const dataCost = ref('0.00')

function tortureDeep() {
  const start = performance.now()

  // 每一次 .val 讀取和寫入都會經過 Proxy 的攔截
  data.value.list.forEach((item) => {
    item.val++
  })

  const end = performance.now()
  dataCost.value = (end - start).toFixed(2)
}

const shallowData = shallowRef(createData())
const shallowDataCost = ref('0.00')

function tortureShallow() {
  const start = performance.now()

  // 操作 raw object，完全沒有 Proxy 介入，速度等同於原生 JS
  shallowData.value.list.forEach((item) => {
    item.val++
  })
  triggerRef(shallowData)

  const end = performance.now()
  shallowDataCost.value = (end - start).toFixed(2)
}

const exRef = useTemplateRef('exRef')

const ticker = useRafFn(() => {
  tortureShallow()
  tortureDeep()
}, {
  immediate: false,
  fpsLimit: 5,
})

useIntersectionObserver(exRef, ([entry]) => {
  entry.isIntersecting ? ticker.resume() : ticker.pause()
}, {
  immediate: true,
})
</script>

```

以上程式的邏輯為：

1. `createData` 建立一個長度 10000 的大型物件。
2. 分別使用 `ref` 和 `shallowRef` 對 `createData` 的結果進行包裝。
3. `performance.now()` 紀錄更新資料所需時間。

在我的電腦上 `ref` 大約需要 7ms，`shallowRef` 大約需要 0.1ms。

可以注意到 `shallowData` 的更新時間比 `data` 快了近 70 倍！%( •̀ ω •́ )✧%

路人：「雖然差 70 倍，但實際上也才花了 7ms，平常也用不到這麼大的物件，這樣是不是不用 `shallowRef` 也無所謂啊？%(\*´･д･)?%」

鱈魚：「你說沒錯 %(\*´,,•ω•,,)%，平常很難遇到大型物件，不過還要是注意一些情境。」

### 配合第三方套件

當你使用 pixi、babylon.js 這類套件時，套件本身會建立各種複雜物件，例如：Engine、Scene、Mesh 等等。

雖然一般情況下，完全不需要 `ref`，直接使用即可。

```ts
// ❌ 不需要 ref 包裝
const engine = ref(new Engine(canvas, true))

// ✅
const engine = new Engine(canvas, true)
```

但是有時候還是需要響應怎麼辦？這個時候就可以用 `shallowRef` 了！%੭ ˙ᗜ˙ )੭%

直接使用 `ref` 包裝，會讓畫面會卡到爆炸喔。

除了卡到炸以外，`ref` 的 `Proxy` 還有可能破壞套件的內部邏輯，導致套件無法正常運作。

例如以下 issue：

* [Bug: When Application is proxied by Vue 3(ref), an error occurs when rendering graphics](https://github.com/pixijs/pixijs/issues/10477)

可以看到裡面提到的解法也是用 `shallowRef` 解決。%◝( •ω• )◟%

::: tip
例如酷酷元件中的 [useBabylonScene](https://gitlab.com/side_project/chill-component/-/blob/main/src/composables/use-babylon-scene.ts?ref_type=heads#L67)，用於快速建立一個 3D 場景。其中的 babylon.js 相關物件就是使用 `shallowRef` 包裝。
:::

再進階一點還可以考慮使用 `customRef`，不過這個就留到未來有機會再聊啦。%( ´ ▽ \` )ﾉ%

## 總結 🐟

目前為止的經驗，性能問題通常是 DOM 太多，幾乎不會是 `ref` 的問題，過早使用 `shallowRef` 反而容易搞出其他 Bug 喔。%(  ˙꒳​˙)%

* `shallowRef` 只對第一層進行響應式處理，適合複雜物件。
* 配合第三方套件的複雜物件時，使用 `shallowRef` 可以避免破壞物件內部邏輯或拖垮性能。

---

---
url: /blog-vue/nuxt-ui-v4-revisited.md
description: 快一年前寫過 Nuxt UI v4 初探，當時列的坑補了幾個？這一年又多了哪些好東西？ლ（´∀`ლ）
---

![nuxt-ui-v4-revisited](/nuxt-ui-v4-revisited.webp){.cover}

# 一年後再看 Nuxt UI

大家好，我是鱈魚。(｡･∀･)ﾉﾞ

去年九月寫過一篇 [初探 Nuxt UI v4](https://codlin.me/blog-vue/a-first-look-at-nuxt-ui-v4.html)，文末列了一串「目前還沒有的東西」。

不到一年，Nuxt UI 已經從 v4.0 一路衝到 **v4.11**，元件數從 113 個長到 133 個 %੭ ˙ᗜ˙ )੭%

\~~感謝 Vercel 乾爹~~ XD

來先驗收以前列的坑，再挑幾個這一年來有沒有甚麼有趣的酷功能！%੭ ˙ᗜ˙ )੭%

## 先看版本節奏

從去年底到現在的釋出時間表，大概一個月一個 minor：

| 版本 | 時間 | 招牌功能 |
| --- | --- | --- |
| v4.1.0 | 2025/10 | Empty、五個元件支援虛擬化、componentDetection |
| v4.2.0 | 2025/11 | InputDate／InputTime、`data-slot`、Tailwind prefix |
| v4.3.0 | 2025/12 | Editor 全家桶、ScrollArea |
| v4.4.0 | 2026/01 | Calendar 週次、CommandPalette 調校 |
| v4.5.0 | 2026/02 | Theme 元件、四款新中性色、Toast 去重 |
| v4.6.0 | 2026/03 | Sidebar、AI Chat 元件三兄弟 |
| v4.7.0 | 2026/04 | Listbox、Link 自動 i18n |
| v4.8.0 | 2026/05 | Theme 元件可設 prop 預設值、ContentSearch 非同步搜尋 |
| v4.9.0 | 2026/06 | Calendar 月/年模式、useTour、theme.unstyled |
| v4.10.0 | 2026/07 | InputRating、icon 打包進 build、unmountOnHide |
| v4.11.0 | 2026/08 | Splitter、ProgressGroup、Vue 端 CSS 掃描剔除 |

節奏穩定到有點可怕，官方團隊真的很拚 %(\*´∀\`)~♥%

## 舊坑驗收時間

先給大家看結論表，細節在後面。

| 當初的抱怨 | 現況 |
| --- | --- |
| Table 沒有虛擬滾動 | ✅ v4.1 補上，而且一次給了五個元件 |
| ui prop 不知道對到哪個 DOM | ✅ v4.2 `data-slot`，後面又加了 Theme 元件 |
| 沒有 Time Picker | ✅ v4.2 `UInputDate`、`UInputTime` |
| 沒有所見即所得編輯器 | ✅ v4.3 直接送一整套 |
| `useFormField` 文件找不到 | 🔶 Form 文件裡有提到，但獨立頁面反而消失了 |
| 元件無法從 `@nuxt/ui` 引入 | ❌ 還是只能走目錄 |
| 沒有 directives、utils | ❌ 還是沒有 |
| Toast 不能單獨設定位置 | ❌ 官方已標記 not planned |
| 不能用 UnoCSS | ❌ issue 早就 not planned 了 |

九項裡面補了四項半，以一年來說算相當有誠意 %(・∀・)９%

### ✅ 所見即所得編輯器

這是我最意外的一項。當初的結論是「要自己引 Tiptap 或 TinyMCE」，結果 v4.3.0 官方直接端出六個元件：

* `Editor`：本體，支援 JSON、HTML、Markdown 三種內容格式
* `EditorToolbar`：工具列，可自訂功能群組
* `EditorSuggestionMenu`：打 `/` 叫出的指令選單
* `EditorMentionMenu`：打 `@` 提及某人
* `EditorEmojiMenu`：打 `:` 插入 emoji
* `EditorDragHandle`：拖曳把手，可重新排序區塊

底層就是 [Tiptap](https://tiptap.dev/)，MIT 授權，沒有授權疑慮惹！%੭ ˙ᗜ˙ )੭%

最基本的用法只有一行：

```vue
<script setup lang="ts">
const value = ref('# Hello World')
</script>

<template>
  <UEditor v-model="value" content-type="markdown" class="w-full min-h-21" />
</template>
```

`v-model` 綁下去、`content-type` 選格式，就這樣 %(๑•̀ㅂ•́)و✧%

官方還附了 [Editor 模板](https://editor-template.nuxt.dev/)，裡面有用 PartyKit 做的即時協作，還有接 AI SDK 的自動補字。

想加自訂功能的話，Tiptap 的 extension 系統整套開放，`editor` 實例也拿得到，天花板很高。

::: tip
Tiptap 相關套件掛在 peerDependencies，記得自己裝。
:::

### ✅ ui prop 與 DOM 結構

當初的痛點是 `ui` 參數一堆 key，不知道對應到哪層 DOM。v4.2 加了 `data-slot` 已經緩解一半，這一年又多了三個新解法。

**第一招，Theme 元件（v4.5.0）。**

不用一個一個元件改，包起來就好：

```vue
<template>
  <UTheme
    :ui="{
      button: { base: 'rounded-full' },
      input: { base: 'rounded-full' },
    }"
  >
    <UButton label="Button" color="neutral" variant="outline" />
    <UInput placeholder="Search..." />
  </UTheme>
</template>
```

它不渲染任何 DOM，底層走 Vue 的 `provide` / `inject`，所以不管巢狀多深都吃得到。可以層層嵌套，內層蓋外層，元件上直接寫的 `ui` 優先權最高。

**第二招，Theme 元件也能設 prop 預設值（v4.8.0）。**

```vue
<template>
  <UTheme
    :props="{
      tooltip: { delayDuration: 0, arrow: true },
      button: { color: 'neutral', variant: 'subtle', size: 'lg' },
      input: { size: 'lg' },
    }"
  >
    <UTooltip text="Tooltip">
      <UButton label="Save" />
    </UTooltip>
  </UTheme>
</template>
```

某個區塊要整批換成大尺寸？包一層就好，再也不用複製貼上 `size="lg"` 三十次 %(´,,•ω•,,)♡%

**第三招，slot class 可以寫成 function（v4.9.0）。**

以前傳字串是「合併」到預設 class 上，遇到要覆蓋的情境就得跟 `tailwind-merge` 角力。現在傳 function 就變成「取代」：

```vue
<template>
  <!-- 完全取代 base 的預設 class -->
  <UButton :ui="{ base: () => 'text-3xl font-bold' }" label="Button" />

  <!-- 想留一部分也可以，參數就是解析後的預設值 -->
  <UButton :ui="{ base: (defaults) => `${defaults} text-3xl` }" label="Button" />
</template>
```

`:ui`、`app.config.ui`、`<UTheme :ui>` 三個地方都通用。

**加碼，`theme.unstyled`（v4.9.0）。**

如果想連預設樣式都不要，直接在 build 階段剝光：

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    theme: {
      unstyled: true,
    },
  },
})
```

只留結構與 a11y 邏輯，樣式全部自己來，順便減少 HTML 與 bundle 肥肉。

路人：「你看起來也很需要 unstyled。%( ・ิω・ิ)%」

鱈魚：「說好的尊重呢？！%Σ(ˊДˋ;)%」

::: warning
連結構性 class 也會一起剝掉（定位、transition、flex/grid 都算）。像 `Modal`、`Drawer`、`Calendar` 這種版面吃重的元件，得自己重新排版。
:::

### 🔶 自定義 Form 欄位

當初的狀況是「`useFormField` 存在，但文件網頁沒有」。

現在反過來了，`docs/content/docs/3.composables/use-form-field.md` 這個檔案直接從 repo 消失，改成在 [Form 文件](https://ui.nuxt.com/docs/components/form)的自訂驗證段落用一句 tip 帶過：

> You can use the `useFormField` composable to implement this inside your own components.

功能還在、`src/runtime/composables/useFormField.ts` 也還在，就是沒有獨立說明頁。想知道回傳哪些東西，還是得翻原始碼 %(´・ω・\`)%

### ❌ 元件顯式引入

還是老樣子。看一下 `@nuxt/ui` 的 `exports` 欄位就知道原因：

```json
{
  ".": {
    "types": "./dist/module.d.mts",
    "import": "./dist/module.mjs"
  },
  "./components/*": "./dist/runtime/components/*",
  "./composables/*": {
    "types": "./dist/runtime/composables/*.d.ts",
    "import": "./dist/runtime/composables/*.js"
  }
}
```

根路徑導出的是 Nuxt module 本體，所以 `import { UModal } from '@nuxt/ui'` 永遠拿不到元件。乖乖走目錄：

```ts
import UModal from '@nuxt/ui/components/Modal.vue'
```

好消息是 `./composables` 與 `./utils` 這兩個路徑開出來了，寫共用邏輯時方便一點。

### ❌ Directives、Utils

翻了一下 `src/runtime`，資料夾只有 `components`、`composables`、`locale`、`plugins`、`types`、`utils`、`vue`，沒有 `directives`。

`utils` 裡面是 `ai.ts`、`form.ts`、`link.ts`、`tv.ts` 這類內部工具，跟 Quasar 那種通用工具庫是兩回事。

這塊還是繼續靠 VueUse 補，實務上影響不大。

### ❌ Toast 單獨設定位置

[官方 issue](https://github.com/nuxt/ui/issues/808) 在 2024 年底就標記 not planned 了，現在文件還是同一句話：

> Change the `toaster.position` prop on the App component to change the position of the toasts.

不過 v4.5.0 加了我覺得更實用的 **Toast 去重**。同樣 `id` 的 toast 再叫一次，現有那張會跳一下脈動動畫，畫面上永遠只有一張：

```ts
const toast = useToast()

// 連按十次也只會有一張，只是會抖十下 XD
toast.add({ id: 'save-success', title: '儲存成功' })
```

手殘連點的使用者終於不會噴出一整排通知了 %(≧∀≦)%

### ❌ UnoCSS

[issue #196](https://github.com/nuxt/ui/issues/196) 2023 年就 not planned 結案，六十幾個讚也救不回來。

現在 `tailwindcss` 掛在 dependencies 裡（v4.3.3），`tailwind-variants`、`tailwind-merge` 也是核心依賴，這條路基本上封死了。想用 UnoCSS 就只能看 [Una UI](https://github.com/una-ui/una-ui)，不過生態系差距擺在那，我還是繼續用 Nuxt UI %( ˘･з･)%

## 酷酷的新東西

除了上面補坑的部分，還有一票純新增的功能。

### Splitter（v4.11.0）

熱騰騰，八月才出的可拖曳分割版面：

```vue
<script setup lang="ts">
import type { SplitterItem } from '@nuxt/ui'

const items: SplitterItem[] = [
  { slot: 'sidebar', minSize: 15, maxSize: 40, defaultSize: 25 },
  { slot: 'main', defaultSize: 75 },
]
</script>

<template>
  <USplitter id="layout" :items="items" class="h-96">
    <template #sidebar>
      Sidebar
    </template>
    <template #main>
      Main
    </template>
  </USplitter>
</template>
```

支援 min/max 尺寸、可收合、可巢狀、可直向。SSR 記得給 `id` 讓水合時對得上，另外 `auto-save-id` 會把版面存進 `localStorage`，使用者調好的比例下次還在 %(ﾉ>ω<)ﾉ%

寫 IDE 風格的工具或後台時超好用。

### Sidebar（v4.6.0）

以前要自己拼 Dashboard 元件才做得出來的側邊欄，現在有專門元件了。桌機固定、手機自動變成 Modal、Slideover 或 Drawer：

```vue
<template>
  <USidebar v-model:open="open" collapsible="icon">
    <template #header>
      <logo />
    </template>

    <UNavigationMenu :items="items" />

    <template #footer>
      <user-menu />
    </template>
  </USidebar>
</template>
```

三種外觀（`sidebar`、`floating`、`inset`）配三種收合模式（`offcanvas`、`icon`、`none`），排列組合夠用了。

::: warning
v4.6.0 改用 Nuxt 的 `moduleDependencies` API，最低要求變成 **Nuxt 4.1.0**，升級前先確認一下。
:::

### useTour（v4.9.0）

新手導覽終於不用自己刻，用法很簡單，整趟導覽共用同一個 `Popover`，換步驟時把錨點重新指過去就好：

```vue
<script setup lang="ts">
const card = useTemplateRef('card')

const tour = useTour([
  { target: '#cta', title: 'Get started' },
  { target: () => card.value, title: 'Profile', side: 'right' },
  { target: null, title: 'All set' },
])
</script>

<template>
  <UButton @click="tour.start()">
    Start tour
  </UButton>

  <UPopover
    :open="tour.open.value"
    :reference="tour.reference.value"
    :dismissible="false"
  >
    <template #content>
      <UButton :disabled="!tour.hasPrev.value" @click="tour.prev()">
        Back
      </UButton>
      <UButton @click="tour.next()">
        {{ tour.hasNext.value ? "Next" : "Finish" }}
      </UButton>
    </template>
  </UPopover>
</template>
```

`target` 收字串選擇器、function 或 `null`（`null` 就是置中不指任何東西）。它只管步驟狀態與錨點解析，內容跟按鈕全部交給你，彈性剛剛好。

會自動把目標捲進畫面，切換時 popover 也會平滑移動 %(ゝ∀・)b%

### 虛擬滾動與 Listbox

v4.1.0 補虛擬滾動時，官方一口氣給了五個元件，`CommandPalette`、`InputMenu`、`SelectMenu`、`Table`、`Tree` 通通追加了 `virtualize` 參數：

```vue
<template>
  <UTable :data="data" :columns="columns" virtualize />
  <USelectMenu v-model="value" :items="items" virtualize />
</template>
```

`ScrollArea`（v4.3.0）則是有內建虛擬滾動的捲動容器，底層一樣是 [TanStack Virtual](https://tanstack.com/virtual/latest)，任何自己刻的長清單都能套。

`Listbox`（v4.7.0）是常駐顯示的可選清單，內建搜尋與虛擬化。跟 `SelectMenu` 的差別在於它不會彈出浮層：

```vue
<script setup lang="ts">
const items = ref([
  { label: 'France', icon: 'i-lucide-map-pin', value: 'FR' },
  { label: 'Germany', icon: 'i-lucide-map-pin', value: 'DE' },
])

const value = ref()
</script>

<template>
  <UListbox v-model="value" :items="items" />
</template>
```

雙欄式的挑選介面（左邊清單、右邊詳情）就靠它了。

### unmountOnHide（v4.10.0）

這招很實用。`Modal` 與 `Slideover` 關閉時預設會卸載內容，表單填一半關掉就沒了。設成 `false` 就會留著：

```vue
<template>
  <UModal :unmount-on-hide="false">
    <UButton label="Open" />

    <template #content>
      <!-- 關掉也還在 -->
    </template>
  </UModal>
</template>
```

表單狀態、捲動位置、初始化很貴的子元件，都能撐過開開關關 %(´▽\`ʃ♡ƪ)%

### Icon 打包進 build（v4.10.0）

以前 icon 是執行時去 Iconify API 撈，離線就 GG。現在會直接嵌進 build 產物，SSR 當下就渲染得出來，離線也能用。

Nuxt 端靠 `@nuxt/icon` 的 client bundle 自動處理。純 Vue + Vite 專案則是 `@nuxt/ui/vite` 多了 `icon.clientBundle` 選項：

```ts
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    ui({
      icon: {
        clientBundle: {
          // 手動列
          icons: ['lucide:heart', 'simple-icons:github'],
          // 或整包掃
          scan: true,
        },
      },
    }),
  ],
})
```

記得把用到的 collection 裝起來（`@iconify-json/{collection_name}`），不然沒東西可以打包。

### CSS 掃描剔除終於下放到 Vue（v4.11.0）

這功能其實 v4.1.0 就有了，叫做 `experimental.componentDetection`。打開之後會掃過你的原始碼，只替真正用到的元件（連同它們的相依元件）產出 CSS：

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    experimental: {
      componentDetection: true,
    },
  },
})
```

一百多個元件的樣式全塞進去實在有點浪費，掃過一輪只留用到的，CSS 直接瘦一大圈。

v4.2.0 又補了兩個洞，lazy component 掃得到了，Nuxt Layers 也會一起掃。

不過這一年來它都只有 Nuxt module 吃得到，純 Vue + Vite 專案只能眼巴巴看著。%(╥ω╥\`)%

直到 v4.11.0，`@nuxt/ui/vite` 終於也支援了：

```ts
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    ui({
      experimental: {
        componentDetection: true,
      },
    }),
  ],
})
```

用 `<component :is>` 動態渲染的元件掃不到，改傳陣列手動列出來即可。

Nuxt 與純 Vue 兩邊的功能落差又補平一項 %(´,,•ω•,,)♡%

### 純 Vue 的待遇一路補上來

把這一年的更新排在一起看，會發現純 Vue 專案的待遇正在追上 Nuxt。

* v4.3.0：`unplugin` 加了 `router` 與 `scanPackages` 選項，也支援 prose 元件
* v4.6.0：`Icon` 開放 Vue 端的全域設定，官方還架了獨立的 Vue REPL playground
* v4.9.0：`vite` 外掛加了 `root` 選項，可以自訂 `.nuxt-ui` 目錄位置
* v4.10.0：icon 打包進 Vite build
* v4.11.0：`componentDetection` 下放

文件也多了一整頁[純 Vue 的 SSR 指南](https://ui.nuxt.com/docs/getting-started/integrations/ssr)。Nuxt 那邊開箱即用，純 Vue 得自己用 `@unhead/vue/server` 把顏色變數注進 `<head>`，不然 SSR 會少一截樣式：

```ts
import { createHead, renderSSRHead } from '@unhead/vue/server'

const head = createHead()

const payload = await renderSSRHead(head)
app.head.push(payload.headTags)
```

Laravel Inertia 與 AdonisJS 的完整範例文件裡也都有，這兩個生態系要接 Nuxt UI 變得容易很多。

::: tip 小插曲
當初在 Vite + Vue 專案照文件設定完，發現 theme 相關的 prop 型別提示缺一塊。

研究後發現是 `tsconfig` 少了 `#build/ui/*` 這條 path，補上就好了：

```json
{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": ["./node_modules/.nuxt-ui/ui/*"]
    }
  }
}
```

[PR](https://github.com/nuxt/ui/pull/5706) 在 v4.4.0 釋出。

雖然只是改了一點點文件，不過能夠協助貢獻感覺很不錯 %(≧∀≦)%
:::

### Tailwind class 前綴（v4.2.0）

這個功能對舊專案來說很關鍵。

Nuxt UI 會產出一大堆 Tailwind utility class，跟你自己的樣式或其他 UI 函式庫撞名的機率不低。v4.2.0 開放了 Tailwind CSS 的 `prefix` 選項：

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw',
    },
  },
})
```

CSS 那邊也要對應改一下：

```css
@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";
```

之後所有 utility 都變成 `tw:flex`、`tw:p-4` 這種樣子，跟既有樣式井水不犯河水。

要把 Nuxt UI 塞進既有專案漸進式導入時，這招很實用。%(´,,•ω•,,)♡%

### 更加 AI 友善：Agent Skills

去年那篇寫了 MCP Server 與 LLMs.txt，這一年官方又多開了一條路，**Agent Skills**。

跟 MCP 提供即時工具呼叫不同，Skills 是把結構化的知識檔直接塞進 AI 的上下文，整段對話都參考得到。官方的 usage skill 涵蓋安裝、主題、全部元件、composables、表單驗證、版面組合與官方模板。

安裝靠 [`skills`](https://skills.sh) CLI，支援三十幾種 agent：

```bash
# 裝進目前專案
npx skills add nuxt/ui

# 指定 agent
npx skills add nuxt/ui --agent claude-code

# 全域安裝，所有專案共用
npx skills add nuxt/ui --global
```

裝完在對話框打 `/nuxt-ui` 就能叫出來。

Claude Code 也可以直接用自己的指令裝：

```bash
claude skill add https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui
```

Skill 檔案本身就放在 [repo 的 `skills/nuxt-ui/`](https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui)，任何吃自訂上下文的工具都能引用。

順帶一提，ProsePrompt 元件在 v4.10.0 多了 `claude` 這個 action，文件網頁上的範例 prompt 可以一鍵丟進 Claude %(・∀・)９%

### 動畫節奏統一（v4.11.0）

所有動畫與位移轉場（含離場）統一走 `--ease-out`。想調整整套函式庫的手感，覆寫一個 token 就好：

```css
@theme {
  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
}
```

`prefers-reduced-motion` 的覆蓋範圍也擴大了，浮層改成原地淡入，`Tabs` 指示器之類的位移轉場會停掉。無障礙有顧到，讚讚 %(ゝ∀・)b%

### 其他小東西

* **Empty**（v4.1.0）：空狀態元件，`icon`、`title`、`description`、`actions`、`loading` 一次到位，不用每個專案自己刻一份
* **InputRating**（v4.10.0）：星等評分，支援半星、hover 預覽、自訂 icon
* **ProgressGroup**（v4.11.0）：多段式進度條配圖例，硬碟容量分析那種畫面
* **Calendar `type` prop**（v4.9.0）：一個參數在日/月/年選擇器之間切換，標題也變成可點的按鈕，不用狂按上一頁下一頁
* **AI Chat 三兄弟**（v4.6.0）：`ChatReasoning`、`ChatTool`、`ChatShimmer`，串 AI SDK 的訊息 parts 就能做出有思考過程與工具呼叫的聊天介面
* **四款新中性色**（v4.5.0）：`taupe`、`mauve`、`mist`、`olive`，來自 Tailwind CSS v4.2
* **Link 自動 i18n**（v4.7.0）：裝了 `@nuxtjs/i18n` 之後，所有吃 `to` 參數的元件自動走 `$localePath`
* **統一 focus 樣式**（v4.9.0）：所有元件共用同一套 `focus-visible` 光暈，顏色跟著元件的 `color` 走
* **Form 程式化送出也走 HTML5 驗證**（v4.5.0）：呼叫 `form.submit()` 時會先跑原生驗證，送出按鈕放在 Modal footer 那種情境特別有用
* **Table row pinning**（v4.6.0）：可以把指定列釘在上下兩端，v4.7.0 又補上虛擬化模式下的 sticky header/footer
* **`useToast` 的 `max`**（v4.1.0）：全域設定同時最多顯示幾張通知
* **`Popover` 的 `enableTouch`**（v4.10.0）：觸控裝置上也能觸發，久違的 [#2346](https://github.com/nuxt/ui/issues/2346) 終於結案
* **Prose 標題錨點與複製按鈕可設定**（v4.10.0）：拿 Nuxt UI 寫文件站的話會用到
* **`Checkbox`／`Switch` 的 `trueValue`／`falseValue`**（v4.6.0）：接後端那種 `'Y'` / `'N'` 欄位不用再自己轉
* **icon 可以用 `false` 隱藏**（v4.9.0）：不用再想辦法塞空字串
* **新增 composable 文件**：`useScrollShadow`（捲動陰影）、`extractShortcuts`（從選單項目自動抽出快捷鍵）、`defineLocale` 與 `extendLocale`

## 升級要注意的地方

跨這麼多版本，難免有 breaking change。

\~~不過不是問題，當然是鞭打 AI 叫他給我升到好。~~ %◝( •ω• )◟%

| 版本 | 異動 |
| --- | --- |
| v4.1.0 | `CommandPalette` 的 `trailing-icon` 改給 input 用，子項目的 icon 改用 `children-icon` |
| v4.1.0 | `Table` 的 `select` 事件參數順序調整 |
| v4.2.0 | `InputMenu`、`InputNumber`、`InputTags`、`Select`、`SelectMenu` 的 exposed ref 統一回傳 HTML 元素，不再給元件實例 |
| v4.6.0 | 改用 Nuxt 的 `moduleDependencies` API，最低需求變成 **Nuxt 4.1.0** |
| v4.8.0 | `InputMenu` 的 `autocomplete` 改名 `mode`，值為 `'combobox'`（預設）或 `'autocomplete'` |

v4.8.0 那個改名非改不可。原本的 `autocomplete` 跟 HTML 原生屬性撞名，瀏覽器自動填入（`email`、`one-time-code` 那些）會失效。改名之後原生屬性就能正常穿透到內層 input 了：

```diff
- <UInputMenu autocomplete :items="items" />
+ <UInputMenu mode="autocomplete" :items="items" />
```

官方在 v4.1.0 的 release note 還特地道歉了一下，說一百多個元件偶爾就是得修正一致性。我是覺得這種頻率完全可以接受啦 %(´∀\`)%

## 總結 🐟

* 一年內從 v4.0 到 v4.11，元件 113 個變 133 個，一個月一個 minor，節奏穩定得誇張
* 當初列的九個坑補掉四個半，**Editor 全家桶**影響最直接，商業專案的授權疑慮直接解決；剩下三個（顯式引入、directives、UnoCSS）是架構取向問題，短期內不用期待
* **Theme 元件**加上 slot class function、`theme.unstyled`、`theme.prefix`，客製化路線從「猜 DOM」變成「有工具可用」
* 純 Vue 專案的待遇一路補上來，SSR 文件、icon 打包、`componentDetection` 陸續下放，Nuxt 與 Vue 的落差越來越小
* AI 整合從 MCP、LLMs.txt 延伸到 **Agent Skills**，一行 `npx skills add nuxt/ui` 就到位

一年前的結論是「潛力無窮」，一年後看起來，的確不斷成長。%( •̀ ω •́ )✧%

如果去年因為缺編輯器或缺虛擬滾動而放棄的大大們，現在可以回鍋看看了 %ლ（´∀\`ლ）%

以上如有錯誤，還請多多指教。

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

---

---
url: /blog-program/optical-illusion-museum.md
description: 拉動滑桿揭開錯覺真相，Web 上的互動式視錯覺展
---

![optical-illusion-museum](/optical-illusion-museum.webp){.cover}

# 互動式視錯覺展

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

最近展示視錯覺圖片給小鱈魚看，結果反應超乎預期。

小鱈魚：「媽！老爸又在變奇怪的魔術騙人了。%ლ(╹口╹ლ)%」

鱈魚：「怎麼是這種反應。%(。-\`ω´-)%」

展示這些視錯覺圖片時，發現這些範例很適合以網頁為載體，做成可互動的展示。

不然證明錯覺只能用手指遮擋，很不方便，絕對不是因為手指太肥 %( ˘･з･)%

這裡我選了幾個有趣的視錯覺效果，每一個都有滑桿，方便從「錯覺」過度到「真相」。

一起來見證大腦被騙的瞬間吧！%( ´ ▽ \` )ﾉ%

## 亮度錯覺

人類的大腦在判斷「這玩意兒有多亮」時，不靠絕對亮度，而是和周圍的東西做比較。

### 棋盤陰影錯覺

看看下面這張棋盤，A 格和 B 格其實是同一個顏色。%( ´ ▽ \` )ﾉ%

這個錯覺是 MIT 教授 [Edward Adelson](https://persci.mit.edu/gallery/checkershadow) 在 1995 年發表。

大腦為了幫你「看懂」這個場景，會自動對陰影區域做亮度補償。

它覺得「這裡有陰影，所以實際上應該比看到的更亮」，結果就擅自上調了 B 格的感知亮度。

導致明明是同一個灰色，卻不管是躺著看、橫著看還是站著看，怎麼看都覺得 B 比 A 亮。%ლ(╹ε╹ლ)%

### 同時對比錯覺

兩個完全相同的灰色方塊，一個放在深色背景上，一個放在淺色背景上，你卻會感覺左邊那個比較亮。

同時對比錯覺早在 19 世紀就有人研究，法國化學家 Michel Eugène Chevreul 在研究織品染色時就發現了這個現象。

大腦不會判斷「真正的亮度」，只在乎「相對於旁邊的東西，這個算亮還是暗」。

### Hermann Grid 幽靈灰點

盯著下面的格子，在白線的十字交叉點看到若隱若現的灰色小圓點？

但只要你直接盯著某一個交叉點看，灰點就消失了。

這個現象最早由德國生理學家 Ludimar Hermann 在 1870 年發現，距今已經超過 150 年了。

成因是視網膜上的「側抑制」機制。

當較多亮色圍繞某個區域時（就像四條白線圍繞交叉點），周邊的神經細胞會互相「壓制」，讓你覺得那個地方沒那麼亮。

結果就是明明是白色的交叉點，你卻看到了根本不存在的灰色圓點。

## 顏色錯覺

大腦不但會搞錯亮度，連顏色都可以無中生有。%(´⊙ω⊙\`)%

### 霓虹色擴散

看看下面這張圖，中間的圓形區域是不是隱約有一層淡藍色的薄紗？但其實圓形區域的背景和外面一樣，都是純白色，唯一的差別只有線條的顏色。

這個現象稱為「霓虹色擴散」，Dario Varin 在 1971 年首先描述，Harrie van Tuijl 在 1975 年進一步研究並命名。

當黑色線條有一段換成彩色時，大腦會自動在彩色線段之間「補上」一層透明的顏色。

### Munker 錯覺

左邊的球看起來偏紫藍，右邊的球看起來偏黃綠？但其實兩顆球都是完全相同的青色。

這個錯覺由 Hans Münker 在 1970 年的博士論文中首次描述。

當密集的彩色條紋覆蓋在目標色上方時，大腦會把條紋的顏色「混」進去。

導致紫色條紋讓青色看起來偏藍紫，黃色條紋讓青色看起來偏黃綠。

### 互補色殘影

盯著下面的彩色圖案中心十字 15 秒，然後把滑桿拉過一半。

你會在空白畫面上看到紅色的圓、洋紅色的三角形、藍色的方塊。

殘影現象早在 19 世紀初就有紀錄，歌德在《色彩論》中就有詳細描述。

長時間盯著某個顏色，負責感應該色的視錐細胞會疲勞。

當你移開視線看白色時，其他未疲勞的視錐細胞會「搶戲」，讓你看到互補色，像極了那些摸魚但很會刷存在感的同事。%(›´ω\`‹ )%

青色的互補色是紅色，綠色的互補色是洋紅，黃色的互補色是藍色。

## 幾何錯覺

大腦在判斷「大小」和「長度」上也差不多隨便。%(・ω・)%

### Ponzo 透視錯覺

上方的黃色橫線看起來是不是比下方的長？其實兩條線完全一樣長。

這個錯覺由義大利心理學家 [Mario Ponzo](https://en.wikipedia.org/wiki/Ponzo_illusion) 在 1911 年提出。

鐵軌向遠方匯聚營造出透視感，大腦會根據透視線索推斷「遠處的物體看起來這麼大，實際上一定更大」，於是擅自認定上方的線更長。

### Ebbinghaus 大小錯覺

左邊的橘色圓看起來是不是比右邊的小？被大東西包圍就覺得自己小，被小東西包圍就覺得自己大。

這個錯覺以德國心理學家 [Hermann Ebbinghaus](https://zh.wikipedia.org/zh-tw/%E8%89%BE%E8%B3%93%E6%B5%A9%E6%96%AF%E9%8C%AF%E8%A6%BA) 命名。

大腦在判斷物體大小時，也會拿它和周圍的東西做比較。

大圓包圍 → 中心圓看起來小。

小圓包圍 → 中心圓看起來大。

路人：「難怪站在你旁邊會顯瘦 %◝( •ω• )◟%」

鱈魚：「你今天是來找碴的嗎？%(ﾟ皿ﾟ)%」

### Müller-Lyer 箭頭錯覺

上面那條線看起來是不是比下面那條長？（不包含箭頭部分）

這個錯覺由德國社會學家 [Franz Carl Müller-Lyer](https://zh.wikipedia.org/zh-tw/%E7%B1%B3%E5%8B%92-%E8%8E%B1%E5%B0%94%E9%94%99%E8%A7%89) 在 1889 年提出，是最早有系統研究的幾何錯覺之一。

向外張開的箭頭讓視線往外延伸，大腦就覺得「這條線很長」。

向內收縮的箭頭把視線往回拉，大腦就覺得「這條線比較短」。

有個有趣的研究發現，生活在「盒子型建築」環境裡的人（就是現代都市人）比較容易被這個錯覺騙到。

可能是因為我們太習慣用直角來判斷距離了。

### Jastrow 弧形錯覺

下面的弧形看起來是不是比上面的大？同樣的形狀，只是擺放位置不同，感覺就完全不一樣。

這個錯覺由美國心理學家 [Joseph Jastrow](https://zh.wikipedia.org/zh-tw/%E5%8A%A0%E6%96%AF%E7%89%B9%E7%BD%97%E5%9B%BE%E5%BD%A2) 在 1892 年發現。

上面弧形的短邊（內弧）緊鄰下面弧形的長邊（外弧），大腦在兩者交界處做比較時，就會覺得下面的比較大。

鱈魚：「同事質疑我的披薩片特別大塊時，只要說是 Jastrow 錯覺，大家馬上就理解了！%( •̀ ω •́ )✧%」

路人：「我覺得他們只是覺得你沒救了 %(´・ω・\`)%」

### 咖啡牆錯覺

下面的水平線看起來是不是歪歪斜斜的？但它們全部是水平的平行線。

1979 年，英國布里斯托的研究者 [Richard Gregory](https://en.wikipedia.org/wiki/Caf%C3%A9_wall_illusion) 在一家咖啡館的牆壁磁磚上發現了這個現象，所以才叫 Café Wall。

黑白磚塊的交錯排列配上灰色的間隔線，讓大腦誤判了線條的角度。

把磚塊拿掉，線就乖乖變回水平了。%(・ิω・ิ)%

### Zöllner 平行線錯覺

長線看起來是平行的嗎？看起來東倒西歪的，但其實每一條都是完美的水平線。

這個錯覺由德國天體物理學家 [Johann Karl Friedrich Zöllner](https://zh.wikipedia.org/zh-tw/%E7%AD%96%E5%B0%94%E7%BA%B3%E9%94%99%E8%A7%89) 在 1860 年發現，是最早被記錄的幾何錯覺之一。

和咖啡牆類似，不過它是用交叉的短線製造干擾。

## 所以大腦為甚麼老是被騙？

會有這麼多錯覺是因為大腦不夠優秀嗎？其實這些錯覺反而是它強大的證明。%(・∀・)９%

鱈魚：「就像常常寫出 BUG，反而是強大的證明！%(｢･ω･)｢%」

同事：「？？？？%('◉◞⊖◟◉\` )%」

視覺系統每秒要處理海量資訊，資料量之大，就像你那些只看的到 icon 的 Chrome 分頁一樣。%ᕕ( ﾟ ∀。)ᕗ %

如果每個像素都要精確分析，大腦早就當機了。

所以大腦發展出了一套「捷徑」系統，用各種經驗法則來快速解讀眼前的畫面。

這些捷徑在 99% 的日常情境下都非常好用，只有這些特殊情境才會變成誤判。

同事：「就跟你總是漏掉的測試案例一樣嗎？%( ・ิω・ิ)%」

鱈魚：「別提這種傷心事了。･ﾟ･(つд\`ﾟ)･ﾟ･」

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

以上有任何錯誤或不清楚的地方，還請各位大大多多指教。%( •̀ ω •́ )✧%

---

---
url: /blog-program/improve-speed-using-memoization.md
description: 最近遇到從大矩陣資料找出指定資料的需求，是時候使用 memoization 來提升效能了。੭ ˙ᗜ˙ )੭
---

![improve-speed-using-memoization](/improve-speed-using-memoization.webp){.cover}

# 你是個成熟的 function 了，該自己記得結果了

```js
const data = [
  { name: 'A', color: 'red', condition: () => 'A' },
  { name: 'B', color: 'blue', condition: () => 'B' },
  { name: 'C', color: 'green', condition: () => 'C' },
  { name: 'D', color: 'yellow', condition: () => 'D' },
  { name: 'E', color: 'black', condition: () => 'E' },
  // ... 200 多個
]
```

想要取得符合條件的資料，最直覺的方式就是用 `filter`，例如：

```ts
function getData(color: string) {
  return data.filter((item) => item.color === color)
}
```

由於 `data` 不會變動，output 只與 input 相關。

此 function 又會大量使用，可以預期有非常多重複的運算。

這時候就可以使用 memoization 這個技巧，透過記憶化來提升計算效能。

## 什麼是 memoization

Memoization 是一種簡單的技巧，透過記憶化來提升計算效能。

當 function 被呼叫時，會先檢查是否有相同的輸入值，如果有就直接回傳記憶的結果，而不是重新計算。

就是一個使用空間換時間的概念。%◝( •ω• )◟%

使用 Vue 的朋友們，如果有用過 `computed`，其實都用過 memoization 了。

有興趣的朋友們可以看看我先前的文章「[善用 computed](https://codlin.me/blog-vue/make-good-use-of-computed)」，裡面有詳細探討。

## Lodash memoize

這次我直接使用 Lodash 提供的 [`memoize`](https://www.lodashjs.com/docs/lodash.memoize) 來實現 memoization。

口說無憑，讓我們實際跑跑看 benchmark，看看實際上差多少。

使用 [BenchJS](https://benchjs.com/) 這個酷炫的網站，可以直接在 Web 跑 benchmark，非常方便。

首先在 Code 分頁中，準備資料並撰寫實作。

首先在 `setup.ts` 裡面建立測試資料，export 後就可以在各實作中共用。

`setup.ts`

```ts
function generateTestData(size: number) {
  return Array.from({ length: size }, (_, i) => ({
    key: `${i}`,
    value: i
  }))
}
export const length = 200
export const data = generateTestData(length)
```

接著在 implementations 中建立兩個檔案，檔名與實作相同。

`implementations/memoize.ts`

```ts
import { memoize } from 'lodash'

const getData = memoize((key: string) =>
  data.find((datum) => datum.key === key),
)

export function run() {
  getData(`${length - 1}`)
}
```

`implementations/no-memoize.ts`

```ts
const getData = (key: string) => data.find((datum) => datum.key === key)

export function run() {
  getData(`${length - 1}`)
}
```

可以看到資料與實作都一樣，只差在 `memoize.ts` 的 `getData` 有 memoize。

現在讓我們到 Compare 分頁，按下 Run All。

BenchJS 會開始跑 `run` 的內容，並且計算時間。

![compare-result](/improve-speed-using-memoization/compare-result.png)

可以看到 `memoize` 比 `no-memoize` 快非常多。

不難理解，因為原本的操作之時間複雜度是 O(n)，而 memoize 後只需要 O(1)。

[範例網址](https://benchjs.com/playground#/N4IgzgLghhCmIC5QDdYCcwEsD2A7RAjADQiYC2ADgDaxmy7QQ65iIDaomAJoiAEoAjAGa40AYwBeADQBaABRkCAksgDuABgCcADwC0ADgCKIEkMw1cUOrzplsmCbAB0EViTF44DXuQrY0EAAEwIG29o6BAL6BQmjYZIEA5FTYXFBgABaJADq4uR4sQQDmsBAAIjBQgQC8obThsAAUjQDWsACeCIGQaJi4RQCUNQB8uYGBadBOZrhczZMArmRD1cMTMEtObe011bXbA0S5A7m5sNp+ATELuGJMeIFoN41DwGOBJeWVjQAGACTACxFCAZQK6QIESI-E64SIgSJETg8BDgMSwABW2AEACYFmg+FB9AAxAASLRk6QA8pgKCYQGYLFZ4CjcNhdGEHM5XHSCl4ILwCpAPqUKtAaoFWh0uj0+oMRuspjM5o1Fst5aqth1dvsOjCzhd-EEhDc7sxHs9Xu9PqKoL8AUCQWCIVCYXDIgBdEhQU2oAAqUGUyPApQWFBcbmDEFDAGFUsz6Sb7rhhbh0DBYL7YJAbY0sI4urglgJ0Jbk48Q2hkwBBNBoKDtaZxMiNEIOjLSzlRIgSgD63cwKzWLfe422XX+wEwUKOZfGyCgVAWsC6mHekQGrv1lyCgqCbfF2PU6i3hsCu4VVVqJVTdbgmez3zbAzpYBDFDKvoAyrwuLAxFQoDQWAPhSAQF2Cd5f3-QDgPPfdakPdQAG5IL-ACgLPPAhUmKAujeWdxkCMduggXp+hQgi5wXJcCyLdAKPGSI2HdBjAlySJTlTA0rmASIkLpICoC4OhYwYeh+RRABiQJDAWTAxBaQJP2gK4AHE5N-TjJOkolzGA5SnjuPFYFycFXyjMNXC6T830w39AggbBAgoICKBgi9uzEQS4ECDJYCoCh0GuW4kzAbtSjEJxTMCXwaDoBgYGYMAAHoAConGAVwiHRMBIi6JRKDi8TEoeBks0whK+llQJi1uDIyEAloiTyFrtMCAB1XomH6QIACF6DEerGrATiCCcJTbNzN9wwGBBOIAUVQNB2hBar2mwBZAnObdAlUcwqBq4CoHncwAxoQJ0gukCsXAoR-C271QVi2hiqTKKWp+T6IHaQKwC8mkIFyZLkrPbyjtmLbuKCOBsMqE8rnPHDxRrOsG1ieIW0CNsugII91C7Xt+0HGKBgo7bT3PMAlnFRpALQWiyGLNBmOJumnCArgFjRZooG7ARWcCABqGru3UUnck+n5OOxcaCuoF6EtCiVziseWZrmlq5aKxXmF0MBArETAzDEOzgKKbByr8oDuygCH1s21NYC4BynPJq4qmNEKzUsOhncSJ5cESd6Ja+n6s3+ihAa4nbzwDmnifw8YgKjSsL3Zp2uaaKmyFF8XYRDqX8BIKhMAEOteizdhQB9+MUjSTJ4XdBEQCWrA8EISIgA)

## 為甚麼不要都 memoization 就好？

因為實作 memoization 也需要額外的計算與記憶體。

在資料很少、計算負荷極低的情況下，可能沒什麼差別，甚至可能比較慢。

在這次的例子中，把 `length` 改成 5，再跑一次 benchmark。

```txt
memoize.ts     141,218,403   (-0.7%)
no-memoize.ts  142,192,549   Best
```

會看到結果很接近，甚至 `no-memoize` 還比 `memoize` 快一點。

所以實際上要看情況使用，不是所有情況都適合使用 memoization。

真的遇到性能瓶頸，需要進行改善時，再來評估改進方案。

記得要跑 benchmark，有多少證據，說多少話喔。%( ´ ▽ \` )ﾉ%

## 總結 🐟

* memoization 可以提升效能，透過記憶化來避免重複計算。
* 不是所有情況都適合使用 memoization，要看情況使用。
* 記得要跑 benchmark，才能確定是否真的有提升效能。

---

---
url: /blog-vue/do-not-always-fetch-api-in-on-mounted.md
description: Vue 你還在 onMounted 中取 API 嗎？其實不一定要這樣做，來看看不同做法吧。( ͡~ ͜ʖ ͡°)
---

![do-not-always-fetch-api-in-on-mounted](/do-not-always-fetch-api-in-on-mounted.webp){.cover}

# 其實 Vue 不一定要在 onMounted 取 API

大家好，我是鱈魚。(｡･∀･)ﾉﾞ

最近看到大家討論取得 API 時機，有許多人都提到「一定要」或者「習慣」，在 `onMounted` 這個 hook 內呼叫 API 取得資料。

其實這也沒不好，但是也沒什麼好處就是了。(。・ω・。)

讓我們來思考一下下，有關於 Vue 取得 API 資料這檔事。（~~不會轉生，也沒有史萊姆~~）

## 「一定要」在 onMounted

有人說「一定要」是因為不這麼做會壞掉，這個可以從 2 個部分來看。

首先是 `onMounted` 這個 hook 是甚麼？讓我們看看官網的定義：

> Registers a callback to be called after the component has been mounted.

意思就是「註冊一個會在元件安裝完成後被呼叫的 callback」。

甚麼意思呢？也就是他和有沒有資料一點關係都沒有。`onMounted` 沒辦法幫你保證有資料、template 不會壞，從此天下太平，再也不用加班，。(´。＿。｀)

所以就牽扯到了第二部分：為甚麼會壞掉？

馬上取會壞，`onMounted` 取就不會壞，這表示你的資料可能和 DOM 或元件發生耦合，這其實不是好現象，不但違反了資料驅動的概念還埋了隱形的~~翅膀~~…地雷。

具體原因可能如下：

* API 參數耦合了某個 DOM 的資料，導致「沒有在 `onMounted` 取值」等於「對 undefined 動手動腳」，當然就壞掉惹。（〃｀ 3′〃）
* API 參數或操作耦合了某個子元件，而 Vue 的 `onMounted` 會保證子元件都 `onMounted` 完後，自己的 `onMounted` 才會觸發，導致 `onMounted` 取才沒事。

所以總結來說，所謂的「壞掉」很有可能只是資料流沒考慮 undefined 的情境。

::: tip
可能啦，我巫力不足，只能通靈到這裡惹。 ╮(╯▽╰)╭
:::

如果有使用 TypeScript 就很少會出現這類問題了，因為 TypeScript 會先不開心、滿江紅給你看。ᕦ(ò\_óˇ)ᕤ

## 「習慣」在 onMounted

習慣上可能會這樣寫：

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { getUser, User } from './api'

const user = ref<User>()

onMounted(async () => {
  try {
    user.value = await getUser()
  }
  catch (error) {
    console.error('QQ')
  }
})
</script>

<template>
  <h1>Classic</h1>
  <div>
    user: {{ user?.name }}
  </div>
</template>
```

考慮讀取狀態則可能再加個 loading：

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { getUser, User } from './api'

const user = ref<User>()
const isLoading = ref(false)

onMounted(async () => {
  try {
    isLoading.value = true
    user.value = await getUser()
  }
  catch (error) {
    console.error('QQ')
  }
  finally {
    isLoading.value = false
  }
})
</script>

<template>
  <h1>Classic</h1>
  <div v-if="isLoading">
    資料讀取中...(～﹃～)~zZ
  </div>
  <div v-else>
    user: {{ user?.name }}
  </div>
</template>
```

剛剛說了，其實不用在 `onMounted` 才取資料，早一點取也行，所以可以變成這樣：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { getUser, User } from './api'

const user = ref<User>()
const isLoading = ref(true)

getUser().then((data) => {
  user.value = data
}).catch(() => {
  console.error('QQ')
}).finally(() => {
  isLoading.value = false
})
</script>
...
```

路人：「這樣真的有比較好嗎？」

鱈魚：「當然沒有。(≧∇≦)ﾉ」

路人：（抄起球棒）

鱈魚：「冷靜冷靜，還沒說完啊。(っ °Д °;)っ」

## 來點 Composition

讓我們回想一下 Vue 3 的 Composition API 精神，一但要取得資料變多後，仔細觀察可以發現「資料、狀態（isLoading）、取資料的 function」會重複出現。

讓我們抽離、重組一下，新增一個檔案。

`useAsyncData.ts`

```ts
import { ref } from 'vue'

interface UseAsyncDataParam<Data> {
  executor: () => Promise<Data>;
  onError?: (error: unknown) => void;
}

export function useAsyncData<Data>(param: UseAsyncDataParam<Data>) {
  const data = ref<Data>()
  const isLoading = ref(true)

  param.executor().then((result) => {
    data.value = result
  }).catch((error) => {
    param.onError?.(error)
  }).finally(() => {
    isLoading.value = false
  })

  return {
    data,
    isLoading,
    execute: param.executor,
  }
}
```

::: tip
寫過 Nuxt 的朋友們一定會有熟悉的感覺。(. ❛ ᴗ ❛.)
:::

現在讓我們用這個 `useAsyncData` 改寫一下剛剛的例子看看。

```vue
<script setup lang="ts">
import { getUser } from './api'
import { useAsyncData } from './useAsyncData'

const {
  data: user,
  isLoading,
} = useAsyncData({
  executor: () => getUser(),
  onError() {
    console.error('QQ')
  },
})
</script>

<template>
  <h1>Composable</h1>
  <div v-if="isLoading">
    資料讀取中...(～﹃～)~zZ
  </div>
  <div v-else>
    user: {{ user?.name }}
  </div>
</template>
```

就算有多個狀態要取得也變得更好組織程式碼了，是不是看起來乾淨許多呢？

恭喜我們重複造了 Nuxt 的 `useAsyncData` 與 VueUse 的 `useAsyncState` 的輪子了！

✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

沒錯，雖然目前這個 `useAsyncData` 的功能很簡陋，有很多需要改進的部分，但是這就是上述兩個 API 的基礎精神。

不過 Nuxt 還包含了 SSR 行為，所以更加複雜，推薦大家可以看看 VueUse `useAsyncState` 的[文件](https://vueuse.org/core/useAsyncState/#useasyncstate)或[原始碼](https://github.com/vueuse/vueuse/blob/main/packages/core/useAsyncState/index.ts)，一定可以獲益良多。

文章到此結束了，感謝您的閱讀，以上範例程式碼可以[在此取得](https://play.vuejs.org/#eNrNVb1u1EAQfpWVm/NJhy8oVJdLohBSgPhJIDTIzeKbS5z4dq3d9eXCyQiJgpIuEg1vAA0NFLwNoHR5BWbW6z378gMVoohjz8w3O/N9M3vzYCvPo2kBwSAY6kSluWEaTJFvxCKd5FIZtp1xrdNkm2tgYyUnrBP1GzYCd9YW0RL/a/4ygzagZa4xw351JB6GHwYmecYN4Bdjw+axfWdq5ybrsN9ABb3A6ESKcXoQHWkpsKc5AeMgQWSagXqSm1QKHQcDZj3k41kmTx5Ym1EF9Gp7cgjJ8RX2Iz0jWxzsKtCgphAH3me4OgBTuXeePYYZvnvnRI6KDKNvcD4FLbOCaqzC7hZihGU34my19y3XqTjY1zszA0LXTVGhFFna+DhAnom061pflLsa3bG4WJTI4pK8y7PBMi4O1hGO2RZzMmdSPJKFMDDqMQVjVjr12wMyZ3jkcySux+jpo6I+z9MODQIqqA0ryLlOiYYUtxF2MUflSvVDyUfYfuUPqWvyxsKlDruROQQRhiNueJetb1QtU8poyrMCEEguxJTdKOEmOQzDRRydIjOIQCmpws7eXoeyY+Q4Fcj/aTPW1+ITj3mmwcb/YcIPb284ood9fLe2UTpl01vpGNn1mS3JJNj5l3e/zj6cf37z8/3Zj6+foigKL75/vPj2Fp/d169e2Ax9TNHMBViNw1P/qP7cvmxGgk+AlSj5ArW8TihJZDTqDzMrXorqqjFPoNJuHitCU6IB00ZhsWtkKulBfw42LkRC01dLj/w5qMJ5UoIJOGG7OAapBqd2iMslsyk4pm0wo/HbTycgC+M1cB5KZQFhw1SX1knkqLMwkzLuo+yx1ZWVldrgPLQDyNGWPhXJPZyTigM/wJeH27Xbosejd7nikyG9+XphBklhJKpRtVH3boNcLVLs0PxtYowdxAErxLGQJ8IipjId3cx1s4EqcZhTJYPrivOiVFtGC+IWsELXJN24hK4YxuxZUd2o30hUqchMWzs6ya9PFeD1qLfTUtCGVSfUNEUuZIFc3lYHu3ZjmxPQms5Wob1Lebylahbnrd2781uh7O166bfwn16wPqw5II2oprlxH9vbjgjAOaTkrcsPv0oksgnFPbxi0P0FYPFOO3sdWAavvnmr37O/uk89tf/plVr+BtH4PtM=)。

有其他想法請不吝告訴我，鱈魚感謝您！(o゜▽゜)o☆

## 總結 🐟

* 不一定要在 `onMounted` 取 API，這樣做可能會讓程式碼更複雜
* 使用 Composition API 可以更好組織程式碼
* 重複造輪子是進步的關鍵，但是也不要隨意在正式專案造輪子，以免埋下地雷

---

---
url: /blog-vue/a-first-look-at-nuxt-ui-v4.md
description: Nuxt UI 釋出 v4 了，免費開放許多進階元件，馬上來研究看看 ლ（´∀`ლ）
---

![a-first-look-at-nuxt-ui-v4](/a-first-look-at-nuxt-ui-v4.webp){.cover}

# 初探 Nuxt UI v4

Nuxt UI v4 熱騰騰釋出囉！%੭ ˙ᗜ˙ )੭%

期待很久了，終於等到這一天，馬上來研究看看 %ლ（´∀\`ლ）%

## 研究目標

雖然 Quasar 目前滿足大部分情境，但是 Quasar 更新放緩，作者心力分散至 Quasar CLI、SSR 開發，許多 UI 相關 issue 排不進排程，隨著需求與限制增加，可能會遇到瓶頸

而我目前僅用到 UI，至於為甚麼只用到 UI，以下是我的考量：

* Electron、Capacitor 整合：

  Quasar 雖然可以整合 Electron、Capacitor，但是截至目前的開發經驗，依照需求直接使用 Electron、Capacitor 會更好

  因為 Quasar CLI 二次封裝後，不但更難除錯（很難知道是 CLI 有問題、還是框架有問題），且封裝後許多設定參數脫離原框架的文件，很難找到參考資料

* SSR：

  我比較信任更成熟的 Nuxt，畢竟 SSR、SSG 是一個很複雜的問題，Nuxt 團隊有更多資源與人力可以解決問題

Nuxt UI 除了有官方背景外，還深度整合 Nuxt，潛力無窮，順便解決以下問題：

* Quasar utils class 衝突問題（因為統一使用 Tailwind CSS 了）
* Design Token 分散問題（雖然這個已經靠 UnoCSS 解決）
* SSR 整合問題（Quasar + Nuxt 有時候會遇到一些水合小毛病）
* Router 整合問題（Quasar + Nuxt 時，Router 跳轉按鈕不會使用 NuxtLink 元件）

## 背景資料

基於 [Reka UI](https://reka-ui.com/)、[Tailwind CSS](https://tailwindcss.com/) 與 [Tailwind Variants](https://www.tailwind-variants.org/) 開發，內部還整合了 VueUse、多個 `unplugin` 套件與資源，滿滿自家人的概念 %(◐‿◑)%

還有以下特點：

* MIT 授權
* a11y 完善
* VueUse 深度整合
* Nuxt SSR 整合
* Vue i18n 整合
* [元件超多](https://ui.nuxt.com/docs/components)

## 重點筆記

### 元件特點

以下筆記主要相對於 Quasar UI 出發。

### ui prop

[Nuxt UI：Customize components](https://ui.nuxt.com/docs/getting-started/theme/components#ui-prop)

```vue
<template>
  <u-button
    trailing-icon="i-lucide-chevron-right"
    size="md"
    color="neutral"
    variant="outline"
    :ui="{
      trailingIcon: 'rotate-90 size-3',
    }"
  >
    Button
  </u-button>
</template>
```

可以注入 class 至元件指定層級 DOM 中，這個功能與 `PrimeVue` 的 [`passthrough`](https://primevue.org/passthrough/) 類似

雖然實務開發上不是甚麼大問題，不過我自己有一個小疑問：基於 [BEM 規範](https://nedhsu.github.io/posts/CSS-Day25/)的 UI 套件若要魔改樣式，因為命名結構明確，可以很容易指向目標，但這類基於 Tailwind CSS 的 UI 套件若 `ui` 參數沒有開到，要指向特定的 DOM 是不是就需要相對複雜的 CSS 選擇器？

::: tip v4.2.0 新增 `data-slot` 屬性
v4.2.0 開始，對應 ui prop 的 DOM 會加入 `data-slot` 屬性，CSS 選擇器可以更容易指向目標 DOM 了 %(/≧▽≦)/%
:::

#### Form

[Nuxt UI：Form](https://ui.nuxt.com/docs/components/form)

欄位驗證可以直接用 Zod（支援 [Standard Schema](https://github.com/standard-schema/standard-schema) 的驗證器都可以）

配合 [ts-rest](https://codlin.me/blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest.html) 更簡單惹！%(ゝ ∀・)b%

#### Icon

內部使用 [unplugin-icons](https://github.com/unplugin/unplugin-icons)，[超多 icon](https://icones.js.org/collection/all) 可以用%！੭ ˙ᗜ˙ )੭%

會自動對 icon 進行按需引入（On-demand），不會載一大包字型檔案

![icon](/a-first-look-at-nuxt-ui-v4/icon.webp)

SSR、SSG 友善，不會有 [FOUC](https://inbound.technology/fouc-flash-of-unstyled-content-%E7%B6%B2%E9%A0%81%E6%A8%A3%E5%BC%8F%E7%9F%AD%E6%9A%AB%E5%A4%B1%E6%95%88%E6%98%AF%E4%BB%80%E9%BA%BC%EF%BC%9F%E5%8E%9F%E5%9B%A0%E7%82%BA%E4%BD%95%EF%BC%9F/) 問題

#### Dashboard

[Nuxt UI：Dashboard](https://ui.nuxt.com/docs/components/dashboard-group)

一系列 Dashboard 元件，可以輕鬆拼出[專業後台](https://dashboard-vue-template.nuxt.dev/)

### Page

[Nuxt UI：Page](https://ui.nuxt.com/docs/components/page)

一系列 Page 元件，幾乎內建 [Landing 頁面](https://landing-template.nuxt.dev/)會用到的基礎元件了

綜合 Dashboard 元件，Nuxt UI 用來開發前後台都很適合

### Image

[Nuxt UI：ColorModeImage](https://ui.nuxt.com/docs/components/color-mode-image)

沒有額外封裝 img 元件，不過有提供一個 **`ColorModeImage`**，自動依照明暗模式切換圖片

若有安裝 `@nuxt/image` 會在內部自動依賴 `NuxtImg` 元件

#### Table

[Nuxt UI：Table](https://ui.nuxt.com/docs/components/table)

基於 [TanStack Table](https://tanstack.com/table/latest) 開發功能強大

cell 內容[同時支援 slot 與 h function](https://ui.nuxt.com/docs/components/table#with-slots) 更彈性

[`h` function](https://vuejs.org/guide/extras/render-function.html) 可以用來建立 vDOM，與 JSX 概念類似，適合用來渲染動態內容。

先前有一篇文章有提到其應用：[Vue h function 讓 Quasar Dialog 更容易重複使用](https://codlin.me/blog-vue/vue-h-function-makes-quasar-dialog-easier-to-reuse.html)
:::

如果內容只是簡單的調整樣式、排版，或簡單元件（例如：`Badge`、`Tag`） 等等，可以直接使用 `h` function：

```vue
<script setup lang="ts">
import type { TableColumn } from "@nuxt/ui";
import { h, resolveComponent } from "vue";

const UBadge = resolveComponent("UBadge");

const data = [
  // ...
];

const columns: TableColumn[] = [
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ row }) => {
      const color = {
        paid: "success" as const,
        failed: "error" as const,
        refunded: "neutral" as const,
      }[row.getValue("status") as string];

      return h(UBadge, { class: "capitalize", variant: "subtle", color }, () =>
        row.getValue("status")
      );
    },
  },
  {
    accessorKey: "email",
    header: "Email",
  },
  {
    accessorKey: "amount",
    header: () => h("div", { class: "text-right" }, "Amount"),
    cell: ({ row }) => {
      const amount = Number.parseFloat(row.getValue("amount"));

      const formatted = new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "EUR",
      }).format(amount);

      return h("div", { class: "text-right font-medium" }, formatted);
    },
  },
];
</script>

<template>
  <u-table :data="data" :columns="columns" class="flex-1" />
</template>
```

內容更內聚，不需要額外建立 slot 元件

但如果是較複雜的內容，還是使用 slot 更好，除了支援度更好外，template 編譯性能也比較好：

```vue
<script setup lang="ts">
import type { TableColumn } from "@nuxt/ui";

const data = [
  // ...
];

const columns: TableColumn[] = [
  {
    accessorKey: "id",
    header: "ID",
  },
  {
    accessorKey: "name",
    header: "Name",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
  {
    accessorKey: "role",
    header: "Role",
  },
  {
    id: "action",
  },
];
</script>

<template>
  <u-table :data="data" :columns="columns" class="flex-1">
    <template #name-cell="{ row }">
      <div class="flex items-center gap-3">
        <u-avatar
          :src="`https://i.pravatar.cc/120?img=${row.original.id}`"
          size="lg"
          :alt="`${row.original.name} avatar`"
        />
        <div>
          <p class="font-medium text-highlighted">
            {{ row.original.name }}
          </p>
          <p>
            {{ row.original.position }}
          </p>
        </div>
      </div>
    </template>
  </u-table>
</template>
```

#### Modal

Quasar 是 Dialog，在 Nuxt UI 中叫做 Modal

[Nuxt UI：Modal](https://ui.nuxt.com/docs/components/modal)

開啟方式不同於 Quasar，可以不用傳遞額外變數控制開啟（有需要的話還是可以綁定變數）

在 default slot 放入按鈕，即可以開啟，內容則寫在 content slot 中

```vue
<template>
  <u-modal>
    <u-button label="Open" color="neutral" variant="subtle" />

    <template #content>
      <placeholder class="h-48 m-4" />
    </template>
  </u-modal>
</template>
```

### Design System

承襲 Tailwind CSS v4 設計，設定變成基於 CSS 變數

[Nuxt UI：Design System](https://ui.nuxt.com/docs/getting-started/theme/design-system)

### Figma Kit

所有的顏色、樣式幾乎都已用 token 定義，與 CSS 名稱一致，可以直接複製貼上，元件也有定義相關變體，可以直接切換

這個資源很讚，這樣 UI 或 PM 要出設計稿或草稿時，都可以直接使用、不用重畫，更不容易出現認知落差。(・∀・)９

[Nuxt UI：Figma Kit](https://ui.nuxt.com/figma)

### Template

可以從模板借鑒~~抄襲~~內容過來用 (≖‿ゝ ≖)✧

[Nuxt UI：Templates](https://ui.nuxt.com/templates)

### AI 整合

#### MCP Server

可以與 AI 工具整合，甚至 [ChatGPT 也可以用](https://ui.nuxt.com/docs/getting-started/ai/mcp#chatgpt)

[Nuxt UI：MCP Server](https://ui.nuxt.com/docs/getting-started/ai/mcp)

安裝完成後使用指令（輸入 /）會出現以下提示：

![mcp](/a-first-look-at-nuxt-ui-v4/mcp.webp)

* **`find_component_for_usecase`**: Find the best component for your specific use

  給它功能情境，會幫你從 Nuxt UI 元件庫中挑最適合的元件（或元件組合），並說明為什麼、需要搭配哪些 props/slots/events、還會附上簡短使用片段。

* **`implement_component_with_props`**: Generate complete component implementation with proper
  當你已經決定「要用哪個 Nuxt UI 元件」與「要怎麼配置 props/事件/slots」，這個 prompt 會直接產出**完整可用的 SFC 實作**（含 `<script setup>` 型別、狀態、事件、slot 範例、a11y 小細節）。

* **`setup_project_with_template`**: Get guided setup instructions for project

  引導式教學，教你怎麼設定環境

#### LLMs.txt

可以在詢問時提及 [LLMs.txt URL](https://ui.nuxt.com/docs/getting-started/ai/llms-txt#other-ai-tools)，簡單來說就是一個適合 AI 閱讀文件，可以讓 AI 回應更精確

以下是 GPT-5 的問答結果：

**Table 提問：**

![llm-table](/a-first-look-at-nuxt-ui-v4/llm-table.webp)

**Modal 提問：**

![llm-modal](/a-first-look-at-nuxt-ui-v4/llm-modal.webp)

配合 MCP 與 LLMs.txt 可以有效降低 Nuxt UI 入門門檻 %✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

## 問題討論

### 沒有 Directives、Utils

Quasar 內建有許多方便的 [directives](https://quasar.dev/vue-directives/touch-pan) 與 [utils](https://quasar.dev/quasar-utils/scrolling-utils)，不過 VueUse 有提供許多 directives 可以彌補這個缺點。

### 顯示引入元件

底層是 `unplugin-auto-import` 與 `unplugin-vue-components`，印象中可以這樣導入：

![auto-import](/a-first-look-at-nuxt-ui-v4/auto-import.webp)

不知道為甚麼不行，直接從 `@nuxt/ui` 引入也不行

不過還好可以根據目錄引入元件

```ts
import UModal from "@nuxt/ui/components/Modal.vue";
```

### ~~ui prop 與 DOM 結構~~

::: tip v4.2.0 新增 `data-slot` 屬性
v4.2.0 開始，對應 ui prop 的 DOM 會加入 `data-slot` 屬性
:::

ui prop 可以直接將 class 放到對應的 DOM 結構中，不過文件沒有明確說明 ui prop 具體對應哪一個 DOM？

`PrimeVue` 會在 DOM 之 attr 加入 `data-pc-section` 屬性，方便尋找。

雖然大部分元件的結構很單純，不難猜出位置，不過有些元件的 ui prop 有點多，例如 [CommandPalette](https://ui.nuxt.com/docs/components/command-palette#props)：

```
{
  root?: ClassNameValue;
  input?: ClassNameValue;
  close?: ClassNameValue;
  back?: ClassNameValue;
  content?: ClassNameValue;
  footer?: ClassNameValue;
  viewport?: ClassNameValue;
  group?: ClassNameValue;
  empty?: ClassNameValue;
  label?: ClassNameValue;
  item?: ClassNameValue;
  itemLeadingIcon?: ClassNameValue;
  itemLeadingAvatar?: ClassNameValue;
  itemLeadingAvatarSize?: ClassNameValue;
  itemLeadingChip?: ClassNameValue;
  itemLeadingChipSize?: ClassNameValue;
  itemTrailing?: ClassNameValue;
  itemTrailingIcon?: ClassNameValue;
  itemTrailingHighlightedIcon?: ClassNameValue;
  itemTrailingKbds?: ClassNameValue;
  itemTrailingKbdsSize?: ClassNameValue;
  itemLabel?: ClassNameValue;
  itemLabelBase?: ClassNameValue;
  itemLabelPrefix?: ClassNameValue;
  itemLabelSuffix?: ClassNameValue;
}
```

目前看來好像只能直接試試看了。%(´・ω・\`)%

### ~~Table 尚未支援 Virtual Scroll~~~

::: tip v4.1.0 後支援
[使用 `virtualize`](https://github.com/nuxt/ui/releases/tag/v4.1.0#:~:text=Component%20Virtualization) 即可啟用虛擬滾動 ੭ ˙ᗜ˙ )੭
:::

底層的 TanStack Table 可以使用 [`@tanstack/vue-virtual`](https://tanstack.com/virtual/latest/docs/introduction) 支援虛擬滾動，不過 Nuxt UI 的 Table 尚未支援，只能等待更新了

[Table 原始碼](https://github.com/nuxt/ui/blob/v4/src/runtime/components/Table.vue)沒有複雜依賴，真的需要也是可以考慮自行加上 `@tanstack/vue-virtual` 封裝

### useToast 位置不能單一設定

::: tip
感謝狐狸大大的補充 (\*´∀\`)~♥
:::

Toast 位置只能[全域設定](https://ui.nuxt.com/docs/components/toast#change-global-position)，不能像 Quasar 那樣每個 Toast 可以獨立設定位置

[官方說](https://github.com/nuxt/ui/issues/808) Headless UI 和 Radix Vue 都不支援單一設定，目前沒有計畫支援 %(´・ω・\`)%

不過實際上影響不大，沒事不會一直換位置 XD

### useOverlay

[文件](https://ui.nuxt.com/docs/composables/use-overlay)預期用來開啟 Modal 元件，這樣的缺點是需建立一個被開啟元件的 Modal 變體，使用上沒那麼方便，所以同[先前 Quasar Dialog 的封裝](https://codlin.me/blog-vue/vue-h-function-makes-quasar-dialog-easier-to-reuse)，我也做了一個 `openUsingModal` function。

````typescript
import type { Component } from "vue";
import type {
  ComponentProps,
  ComponentSlots,
} from "vue-component-type-helpers";
import UModal from "@nuxt/ui/components/Modal.vue";
import { h } from "vue";

type ModelProps = ComponentProps<typeof UModal>;

/** 將 Vue SFC 元件包装為 UModal，可以更簡單配合 useOverlay 使用
 *
 * @param component Vue SFC 元件
 * @param props SFC 內所有參數，包含 class、style、event 等等
 * @param modalProps UModal 原本參數
 * @param slots SFC 插槽
 */
function wrapWithModal<Comp extends Component>(
  component: Comp,
  props?: ComponentProps<Comp>,
  modalProps?: ModelProps,
  slots?: ComponentSlots<Comp>
) {
  return h(
    UModal,
    {
      class: "w-auto!",
      ...modalProps,
    },
    {
      body: () => h(component, props ?? {}, slots ?? {}),
    }
  );
}

/** 使用 useOverlay + UModal 開啟元件
 *
 * @param component Vue SFC 元件
 * @param props SFC 內所有參數，包含 class、style、event 等等
 * @param modalProps UModal 原本參數
 * @param slots SFC 插槽
 *
 * @example
 * ```typescript
 * const dialog = openUsingModal(BrandEditStatusForm, {
 *   data,
 *   onSuccess() {
 *     dialog.hide();
 *     handleEditSuccess();
 *   },
 * });
 * ```
 */
export function openUsingModal<Comp extends Component>(
  component: Comp,
  props?: ComponentProps<Comp>,
  modalProps?: ModelProps,
  slots?: ComponentSlots<Comp>
) {
  const overlay = useOverlay();

  const modal = overlay.create(
    wrapWithModal(
      component,
      props,
      {
        close: false,
        ui: { body: "p-0!" },
        ...modalProps,
      },
      slots
    ),
    { props }
  );
  modal.open();

  return modal;
}
````

### 沒有簡易所見及所得編輯器

需要額外引入，目前候選為：

* Tiptap：MIT
* TinyMCE：GPLv2+

TinyMCE 功能強大，不過 GPLv2+ 授權不太適合商業專案

### 自定義 Form 欄位

Quasar 可以使用 [`useFormChild`](https://quasar.dev/vue-composables/use-form-child#syntax) 或 [`Field` 元件](https://quasar.dev/vue-components/field)包裝，自定義 Form 內的驗證欄位

研究了一下，其實有提供 `useFormField`，只是不知道為甚麼文件網頁沒有出現，但[文件原始碼有此 md 檔](https://github.com/nuxt/ui/blob/v4/docs/content/docs/3.composables/use-form-field.md)。

### ~~沒有 Time Picker~~

::: tip v4.2.0 後新增 `UInputDate`、`UInputTime`
可喜可賀！%੭ ˙ᗜ˙ )੭%

[Nuxt UI：UInputDate](https://ui.nuxt.com/docs/components/input-date)

[Nuxt UI：UInputTime](https://ui.nuxt.com/docs/components/input-time)
:::

[官方說](https://github.com/nuxt/ui/issues/957)沒有計畫。%...(›´ω\`‹ )%

欸不是，都有 Calendar 了，做個 Time Picker 不過份吧！%ლ（´ 口\`ლ）%

只能自己拼一個或是用 input 將 type 設為 time 版本

不過原生的 time input 在 window 的 chrome 上有點醜就是了 %(。-\`ω´-)%

```vue
<UInput v-model="data" type="time" />
```

![input-time](/a-first-look-at-nuxt-ui-v4/input-time.webp)

## 總結 🐟

* Nuxt UI v4 元件多、功能強大且免費，潛力無窮
* Nuxt 深度整合，SSR、SSG 友善
* VueUse、Vue i18n、unplugin 等等 Vue 生態系深度整合，可以省去不少設定時間
* AI 整合（MCP、LLMs.txt），降低入門門檻

以上就是這次初探，其他細節或坑就要等到實務開發時再慢慢研究了 %◝( •ω• )◟%

Nuxt UI v4 整體感覺很不錯，不過有一個小小遺憾，就是[不能使用 UnoCSS](https://github.com/nuxt/ui/issues/196) %( ˘･з･)%

雖然有基於 UnoCSS 的 [Una UI](https://github.com/una-ui/una-ui)，不過考量生態系問題，還是先用 Nuxt UI 比較實際

---

---
url: >-
  /blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest-practical-experience.md
description: 紀錄一下使用 ts-rest 實際開發的點點滴滴
---

![unleash-the-magic-of-type-script-with-ts-rest](/unleash-the-magic-of-type-script-with-ts-rest-practical-experience.webp){.cover}

# 前後端不再打架，讓 ts-rest 發揮 TypeScript 的魔法吧！（實務篇）

距離上次[概念篇](/blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest)也快一年了，時間過得真快。%(´・ω・\`)%

本文延續概念篇內容，紀錄一些實作筆記，大家若有更好的做法還請不吝指教。%(\*´∀\`)~♥%

技術堆疊以 Vue、NestJS 為例，相關套件版本如下：

* @nestjs/core：`11.1.5`
* @ts-rest/core：`3.52.1`
* @ts-rest/nest：`3.52.1`
* zod：`3.25.76`

::: tip
ts-rest 預計 `^3.53.0` 開始支援 [`Standard Schema`](https://github.com/standard-schema/standard-schema) 驗證，只要支援此規範的驗證器（例：[Zod v4](https://zod.dev/v4)、[Valibot](https://valibot.dev/guides/introduction/)、[ArkType](https://arktype.io/)）的驗證器都可以用來定義合約資料，不限於 Zod 了！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%
:::

本文分成 3 個主要部分：

1. 通用概念

   不分前後端的注意事項與心得

2. 前端

   前端 ts-rest 應用，包含初始化 Client、狀態與結果資料、表單資料驗證等

3. 後端

   後端 ts-rest 應用，包含定義 API 合約、驗證資料、處理請求等

讓我們開始吧！%♪( ◜ω◝و(و%

::: tip 不定期更新
本文為 ts-rest 應用筆記，會隨著時間推移而變化、更新，甚至過時，我會盡快更新，還請大家多多包涵。%(´,,•ω•,,)%
:::

## 通用概念

### jsonQuery

ts-rest 提供的 [`jsonQuery`](https://ts-rest.com/contract/overview#json-query-parameters) 參數可以讓你輕鬆處理 REST API 的 query string。

一般來說 REST API 的 query string 會被視為字串，其中數字、布林與矩陣可能會出現歧異。

啟用 `jsonQuery` 就可以讓 query string 中的資料使用 JSON 形式發送，這樣就可以避免以上問題。

舉個栗子。%( ´ ▽ \` )ﾉ🌰%

#### 數字與布林

若 URL 為 `/posts?take=10&draft=false`，伺服器會取得 `{ take: "10", draft: "false" }`，可以看到內容都是字串。

你可能會說：Zod 可以用 `z.coerce.number()`、`z.coerce.boolean()` 轉換啊？

的確可以轉換沒錯，但這裡有個[隱藏的小地雷](https://github.com/colinhacks/zod/issues/1630)，就是字串的 `"true"` 與 `"false"`，經過 `z.coerce.boolean()` 都會變成 `true`！%╭(°A ,°\`)╮%

::: tip Zod v4 之 `z.stringbool()`
感謝社群的一隻狐狸大大補充

Zod v4 新增了 [`stringbool`](https://zod.dev/api?id=stringbool)，可以正確處理字串的布林值，v4 讚讚！%(/≧▽≦)/%
:::

當然可以自定義轉換器解決，不過若啟用 `jsonQuery`（前端後端都要開），伺服器會取得 `{ take: 10, draft: false }`，就不用特別轉換了。%(≖‿ゝ≖)✧%

#### 矩陣

若 URL 為 `/posts?tags=js&tags=ts`，伺服器會拿到 `['js', 'ts']`，但若 `tags` 只有一個呢？

URL 變為 `/posts?tags=cod`，

這樣伺服器取到的參數可能會變成 `{ tags: 'cod' }`，而不是 `{ tags: ['cod'] }`！ %Σ(ˊДˋ;)%

若啟用 `jsonQuery`，則 URL 會變成 `/posts?tags=["js","ts"]`，就沒有以上分歧的問題了。%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

路人：「如果 client 端不是使用 ts-rest client，是不是可能有一樣的問題？」

鱈魚：「你說的沒錯 ...%(›´ω\`‹ )%，如果使用端不是用 JSON Query Parameters 發送，還是要乖乖的把合約內的驗證器與轉換器寫好寫滿了 %( ˘･з･)%」

### ClientInfer、ServerInfer 傻傻分不清楚？

ts-rest 本身提供了很方便的 [Type Helper 工具](https://ts-rest.com/contract/type-helpers)，可以輕鬆提取合約內的型別。

不過有分 ClientInfer 與 ServerInfer，看的出來一個是 Client 視角，一個是 Server 視角，所以具體差在哪呢？%(\*´･д･)%

簡單來說就是進去與出來的資料型別不同，假設合約這麼寫：

```ts
export const collectionDataContract = contract.router({
  find: {
    method: 'GET',
    path: '/v1/collection-data',
    query: z.object({
      age: z.string().transform(Number),
    }),
    responses: {
      200: collectionDataSchema.array(),
    },
    summary: '取得 collection-data',
  },
})
```

可以看出 `age` 輸入型別是 `string`，但輸出型別是 `number`。

現在讓我們實際看看 ClientInfer 與 ServerInfer 取出來的 `age`

```ts
// type 為 string
type ClientInput = ClientInferRequest<typeof collectionDataContract>['find']['query']['age']
// type 為 number
type ServerInput = ServerInferRequest<typeof collectionDataContract>['find']['query']['age']
```

對 Request 來說，client 是提供端（輸入至合約），而 server 是接收端（取得合約輸出）。

所以得到 `ClientInput` 為 `string`，而 `ServerInput` 為 `number`。

不難發現只有在輸入與輸出型別不同才會有明顯差別，否則兩者型別會相同。

以上就是 ClientInfer 與 ServerInfer 具體差別，有沒有比較清楚了呢？%ԅ(´∀\` ԅ)%

## 前端

### 初始化 Client

如同[文件描述](https://ts-rest.com/client/fetch)，使用 `initClient` 即可以將合約轉換成可直接呼叫的 Client。

可以考慮多一層封裝，提供基礎設定值：

```ts
import type { AppRouter } from '@ts-rest/core'
import { initClient } from '@ts-rest/core'

const baseUrl = import.meta.env.VITE_API_BASE_URL ?? ''

export function useClient<T extends AppRouter>(
  router: T,
  options?: Parameters<typeof initClient>[1],
) {
  return initClient(router, {
    baseUrl,
    baseHeaders: {},
    jsonQuery: true,
    ...options,
  })
}
```

Client 會在網頁中到處出現，希望不要重複建立，避免不必要的記憶體浪費。

可以存在某個變數並 `export` 給其他檔案使用，不過這樣每次微調 `options` 都要建立共用變數有點麻煩（命名好難 %(。-\`ω´-)%），使用 memoization 方式處理會更簡單。

::: tip 甚麼是 memoization
[先前的文章](/blog-program/improve-speed-using-memoization)曾經聊過，有興趣的朋友可以來看看
:::

這裡用 `lodash-es` 提供的 `memoize` 實作：

```ts
import hash from 'object-hash'

export const useClient = memoize(
  <T extends AppRouter>(
    router: T,
    options?: Parameters<typeof initClient>[1],
  ) => initClient(router, {
    baseUrl,
    baseHeaders: {},
    jsonQuery: true,
    ...options,
  }),
  (router, options) => hash({ router, options }),
)
```

`hash` 是為了計算快取用的 key，這裡使用 [`object-hash`](https://www.npmjs.com/package/object-hash) 處理，大家可以換成自己喜歡的實作。%ヾ(◍'౪\`◍)ﾉﾞ%

需要授權的 API 需要在 Authorization Header 提供 Access Token 才能存取，讓我們加入自動加入 Authorization Header 的功能：

```ts
import { initClient, tsRestFetchApi } from '@ts-rest/core'

/** 自動加入 Authorization Header */
export const useClient = memoize(
  <T extends AppRouter>(
    router: T,
    options?: Parameters<typeof initClient>[1],
  ) => initClient(router, {
    baseUrl,
    baseHeaders: {},
    jsonQuery: true,
    api: async (args) => {
      const { accessToken } = useAuthStore()

      return tsRestFetchApi({
        ...args,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          ...args.headers,
        },
      })
    },
    ...options,
  }),
  (router, options) => hash({ router, options }),
)
```

`api` 參數可以讓我們自定義請求如何送出。%(ゝ∀・)b%

說到 Access Token，就一定有 Refresh Token，讓我們加入 401 時自動 Refresh Token 邏輯：

```ts
import { authContract } from '@project-code/shared'

/** 自動加入 Authorization Header 且 401 時自動 refresh */
export const useClient = memoize(
  <T extends AppRouter>(
    router: T,
    options?: Parameters<typeof initClient>[1],
  ) => initClient(router, {
    baseUrl,
    jsonQuery: true,
    api: async (args) => {
      const authStore = useAuthStore()
      let accessToken = authStore.accessToken

      let res = await tsRestFetchApi({
        ...args,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          ...args.headers,
        },
      })

      // 只有 401 需要處理 refreshToken
      if (res.status !== 401) {
        return res
      }

      const authApi = initClient(authContract, {
        baseUrl,
        ...options,
      })

      const result = await authApi.refresh()
      if (result.status === 200) {
        accessToken = result.body.accessToken
        authStore.setAccessToken(accessToken)
      }

      /** 再發送一次剛剛被 401 的請求 */
      res = await tsRestFetchApi({
        ...args,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          ...args.headers,
        },
      })
      if (res.status === 401) {
        // 可加入要求使用者登入邏輯
      }

      return res
    },
    ...options,
  }),
  (router, options) => hash({ router, options }),
)
```

這時候有個小問題，若有請求同時發出，就會重複 refresh 很多次。

甚麼？你說你們後端不在意？那就跳...還是來加個基本處理好了。%(・∀・)９%

使用 Vue 的 `ref` 與 VueUse 的 [`until`](https://vueuse.org/shared/until/) 實現基本版：

```ts
/** 用於防止多次 refresh */
const isRefreshing = ref(false)

/** 自動加入 Authorization Header 且 401 時自動 refresh */
export const useClient = memoize(
  <T extends AppRouter>(
    router: T,
    options?: Parameters<typeof initClient>[1],
  ) => initClient(router, {
    baseUrl,
    jsonQuery: true,
    api: async (args) => {
      const authStore = useAuthStore()

      await until(isRefreshing).toBe(false)
      let res = await tsRestFetchApi({
        ...args,
        headers: {
          Authorization: `Bearer ${authStore.accessToken}`,
          ...args.headers,
        },
      })

      // 只有 401 需要處理 refreshToken
      if (res.status !== 401) {
        return res
      }

      // 防止多次 refresh
      if (!isRefreshing.value) {
        const refreshClient = initClient(authContract, {
          baseUrl,
          ...options,
        })

        isRefreshing.value = true
        const result = await refreshClient.refresh()
        isRefreshing.value = false

        if (result.status === 200) {
          authStore.setAccessToken(result.body.accessToken)
        }
      }

      await until(isRefreshing).toBe(false)
      /** 再發送一次剛剛被 401 的請求 */
      res = await tsRestFetchApi({
        ...args,
        headers: {
          Authorization: `Bearer ${authStore.accessToken}`,
          ...args.headers,
        },
      })
      if (res.status === 401) {
        // 可加入要求使用者登入邏輯
      }

      return res
    },
    ...options,
  }),
  (router, options) => hash({ router, options }),
)
```

這樣可以處理基本 9 成常見的情境了。%◝( •ω• )◟%

二次封裝後可以很輕鬆地加入各種自定義邏輯，有需求的話還可以加入 Queue 等等花式功能，這個就看實際需求而定了。%੭ ˙ᗜ˙ )੭%

眼尖的朋友可能還有注意文件有提到 [Query Client](https://ts-rest.com/client/vue-query-v4)，實際上就是 Vue Query（Tanstack Query）。

Vue Query 內建資料快取、背景更新、自動重試等等強大功能，推薦大家可以玩玩看。

與一般的 Client 差別在初始化與參數稍微不同而已，所以 Query Client 的封裝同理：

```ts
import { initQueryClient } from '@ts-rest/vue-query'

/** 自動加入 Authorization Header 且 401 時自動 refresh */
export const useQueryClient = memoize(
  <T extends AppRouter>(
    router: T,
    options?: Parameters<typeof initQueryClient>[1],
  ) => initQueryClient(router, {
    baseUrl,
    baseHeaders: {},
    jsonQuery: true,
    api: async (args) => {
      // ...
    },
    ...options,
  }),
  (router, options) => hash({ router, options }),
)
```

可以注意到 ts-rest 支援同時使用兩種 Client，這讓實務開發上更有彈性

資料邏輯很單純的網頁使用一般的 Client 即可，有複雜需求的部分再使用 Query Client。

正所謂小朋友才做選擇，我兩種都要！%ヽ(●\`∀´●)ﾉ%

如此可以讓專案保持簡單、乾淨，更不容易出現協作斷層。%( ‧ω‧)ノ╰(‧ω‧ )%

最後讓我們來點測試，確認一下 `memoize` 有正常工作：

`/apps/admin-web/src/common/api.test.ts`

```ts
import { initContract } from '@ts-rest/core'
import { describe, expect, it } from 'vitest'
import { useClient } from './api'

const baseContract = initContract().router({
  create: {
    method: 'GET',
    path: '/v1/collection-data',
    responses: {},
    summary: '建立 collection-data',
  },
}, {
  pathPrefix: '/api',
})

describe('api', () => {
  describe('useClient', () => {
    it(`相同設定應取得同一個實例`, () => {
      const client1 = useClient(baseContract)
      const client2 = useClient(baseContract)

      expect(client1).toBe(client2)
    })

    it(`不同設定應取得不同實例`, () => {
      const client1 = useClient(baseContract)
      const client2 = useClient(baseContract, {
        baseUrl: '/custom',
        baseHeaders: { a: 'a', b: 'b' },
      })

      expect(client1).not.toBe(client2)
    })

    it(`同樣設定但順序不同，也應取得同一個實例`, () => {
      const client1 = useClient(baseContract, {
        baseUrl: '/custom',
        baseHeaders: { a: 'a', b: 'b' },
      })
      const client2 = useClient(baseContract, {
        baseHeaders: { b: 'b', a: 'a' },
        baseUrl: '/custom',
      })

      expect(client1).toBe(client2)
    })
  })
})
```

以上程式碼可以[在此取得](https://github.com/Codfisher/blog-ts-rest-practice/blob/main/apps/admin-web/src/common/api.ts)。

### 狀態與結果資料

ts-rest 回應的結果會將 HTTP Code 包含在資料內，其結構範例如下：

```txt
{
  status: 200,
  body: {
    name: 'cod'
  },
  header: {}
}
```

假設 API 合約為：

```ts
const c = initContract()

export const accountContract = c.router({
  create: {
    method: 'POST',
    path: '/v1/accounts',
    body: z.object({
      username: z.string(),
      password: z.string(),
      name: z.string(),
      description: z.string().optional(),
    }),
    responses: {
      200: z.object({
        id: z.string(),
      }),
      400: z.object({
        reason: z.enum([
          'username-duplicate',
        ]).optional(),
        message: z.string(),
      }),
      401: c.noBody(),
      403: c.noBody(),
    },
    summary: '建立 account',
  },
})
```

可以根據 `status` 取得具體內容，例如：

```ts
const accountApi = useClient(accountContract)

const result = await accountApi.create({})

if (result.status === 200) {
  const newId = result.body.id
  // 提示成功建立使用者
}

if (result.status === 400) {
  if (result.body.reason === 'username-duplicate') {
    // 處理重複的使用者名稱
  }
  else {
    // 處理其他錯誤
  }
}
```

這樣前後端只要約定好 `status` 或列舉資料（像是 `reason` 欄位），就可以精準處理各種業務邏輯了。%( ´ ▽ \` )ﾉ%

當然如果不需要關心細節，直接比較數字即可：

```ts
const accountApi = useClient(accountContract)

const result = await accountApi.create({})

if (result.status >= 400) {
  // 提示建立使用者失敗
}
```

### 表單資料驗證

若 UI 套件的 Form 可以使用驗證器，可以直接與取得合約內的驗證器進行表單驗證，以 Nuxt UI Form 為例：

```vue
<script setup lang="ts">
import type { FormSubmitEvent } from '@nuxt/ui'
import { accountContract } from '@project-code/shared'
import * as z from 'zod'

const schema = accountContract.create.body
type Schema = z.output<typeof schema>

const state = reactive<Partial<Schema>>({
  email: undefined,
  password: undefined
})

const toast = useToast()
async function onSubmit(event: FormSubmitEvent<Schema>) {
  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
}
</script>

<template>
  <UForm
    :schema="schema"
    :state="state"
    class="space-y-4"
    @submit="onSubmit"
  >
    <UFormField label="Email" name="email">
      <UInput v-model="state.email" />
    </UFormField>

    <UFormField label="Password" name="password">
      <UInput v-model="state.password" type="password" />
    </UFormField>

    <UButton type="submit">
      Submit
    </UButton>
  </UForm>
</template>
```

若 Form 不能直接使用驗證器（Zod schema、ArkType type 等等），也不是大問題，來個轉換器就行。

以我常用的 Quasar 為例，可以參考此[實作](https://github.com/Codfisher/blog-ts-rest-practice/blob/main/apps/admin-web/src/common/zod-validator.ts)。

::: tip 感謝優秀的同事們
此轉換器是公司的夥伴們開發，我幫忙寫測試與文件，感謝他們的努力！%(´,,•ω•,,)%
:::

## 後端

### 合約 + 測試 = 更可靠的 API

後端實作合約基本上就和概念篇相同，實作上最重要的部分是可以拿合約寫 e2e 測試，這樣只要測試有過，API 基本上不會有錯惹。%ԅ(´∀\` ԅ)%

所以要怎麼拿合約寫 e2e 測試呢？

概念如下：

1. 將資料輸入合約，取得 API 請求資料（例如 url、query string、body data）
2. 利用第 1 步取得的資料，使用測試工具（例如 Supertest）發送請求

接下來以 [`collection-data` 合約](https://github.com/Codfisher/blog-ts-rest-practice/blob/main/packages/shared/src/collection-data/contract.ts)為例，一步一步來吧。

建立一個將 ts-rest 合約轉換成 API 請求資料的工具：

`apps\api-server\src\common\utils\utils-ts-rest.ts`

```ts
type ExtractQuery<T> = T extends { query: infer U } ? U : never
type ExtractBody<T> = T extends { body: infer U } ? U : never

interface UseContractReturn<Query, Body> {
  url: string;
  method: Lowercase<AppRoute['method']>;
  query: Query;
  body: Body;
}

/** 協助取出合約 API 指定 API 內容
 *
 * 主要用於 e2e 測試
 */
export function useContract<
  Route extends AppRouteQuery,
  Data extends ClientInferRequest<Route>,
>(
  route: Route,
  data?: Data
): UseContractReturn<ExtractQuery<Data>, ExtractBody<Data>>
export function useContract<
  Route extends AppRouteMutation,
  Data extends ClientInferRequest<Route>,
>(
  route: Route,
  data?: ClientInferRequest<Route>
): UseContractReturn<ExtractQuery<Data>, undefined>
export function useContract<
  Route extends AppRouteQuery | AppRouteMutation,
>(
  route: Route,
  data?: ClientInferRequest<Route>,
): any {
  const {
    method,
    path,
  } = route

  const url = path.replace(
    /:(\w+)/g,
    (match, key) => data?.params?.[key],
  )

  if (data && 'body' in data) {
    return {
      url,
      method: method.toLowerCase() as Lowercase<AppRoute['method']>,
      query: data?.query,
      body: data,
    }
  }

  return {
    url,
    method: method.toLowerCase() as Lowercase<AppRoute['method']>,
    query: data?.query,
  }
}
```

測試工具使用 Supertest，建立一個將合約資料透過 Supertest 發送請求的工具：

`apps/api-server/src/resource/collection-data/collection-data.e2e.ts`

```ts
import type { ClientInferRequest, ClientInferResponseBody } from '@ts-rest/core'
import type { IncomingHttpHeaders } from 'node:http'
import {
  collectionDataContract,
} from '@ts-rest-practice/shared'
import request from 'supertest'
import { useContract } from '../../common/utils/utils-ts-rest'

// 這裡不可能出現其他 Contract，所以可以簡短命名
type Contract = typeof collectionDataContract
type ContractRequest = ClientInferRequest<Contract>

interface ApiOptions {
  headers?: IncomingHttpHeaders;
}

/** e2e 測試之合約轉換層
 *
 * 將合約轉換成 API 呼叫，這樣就可以直接拿合約內容進行 e2e 測試
 *
 * 也就是說只要合約有變動，這裡也要跟著變動，這樣就可以確保合約的正確性
 *
 * 同時只要 e2e 測試通過，即表示合約正確，可以交付
 *
 * 另一個附加好處是如果其他資源的 e2e 測試有依賴此資源，也可以直接拿去重複使用
 *
 * @param server 測試環境中的 HTTP server 主體
 * @param globalOptions 額外的選項。同 method 內的 options，method 內的 options 會覆蓋這裡的 options
 */
export function createCollectionDataApi(
  server: any,
  globalOptions?: ApiOptions,
) {
  return {
    async create<
      Code extends keyof Contract['create']['responses'] = 200,
    >(
      data: ContractRequest['create']['body'],
      code = 200 as Code,
      options?: ApiOptions,
    ) {
      const { url, method } = useContract(collectionDataContract.create, {
        body: data,
      })

      const { body, statusCode, headers } = await request(server)[method](url)
        .set({
          ...globalOptions?.headers,
          ...options?.headers,
        })
        .send(data)

      if (code !== statusCode) {
        throw new Error(`${statusCode} : ${JSON.stringify(body, null, 2)}`)
      }

      return {
        headers,
        body: body as ClientInferResponseBody<
          typeof collectionDataContract.create,
          Code
        >,
      }
    },

    // 其他方法同理
  }
}
```

最後就針對此資源建立 e2e 測試（以下為參考，實作可以替換成自己喜歡的方式）：

```ts
type CollectionDataContract = ClientInferRequest<typeof collectionDataContract>

describe('collectionData e2e', () => {
  /** 使用記憶體版本 MongoDB 運行測試 */
  let mongodb: MongoMemoryReplSet
  let mongoConnection: Connection
  let app: INestApplication
  let server: ReturnType<INestApplication['getHttpServer']>

  let collectionDataApi: ReturnType<typeof createCollectionDataApi>

  beforeAll(async () => {
    // ...啟動 Server 與 DB

    collectionDataApi = createCollectionDataApi(server)
  }, 60000)

  /** 測試結束，關閉 DB */
  afterAll(async () => {
    // ...
  })

  async function clearAll() {
    // ...
  }
  /** 每次測試開始前與結束時，都清空 collection 資料，以免互相影響 */
  beforeEach(async () => await clearAll())
  afterEach(async () => await clearAll())

  function createCollectionData(
    params?: Partial<CollectionDataContract['create']['body']>,
  ) {
    const expectData: CollectionDataContract['create']['body'] = {
      name: 'test',
      description: '安安',
      ...params,
    }

    return collectionDataApi.create(expectData)
  }

  describe('建立 collection-data', () => {
    it('全部參數', async () => {
      const expectData: Required<CollectionDataContract['create']['body']> = {
        name: 'name',
        description: 'description',
        remark: 'remark',
      }

      const { body: result } = await collectionDataApi.create(expectData)

      expect(result).toMatchObject(pick(
        expectData,
        ['name', 'description', 'remark'],
      ))
    })
  })

  describe('取得 collection-data', () => {
    it('取得指定筆數資料', async () => {
      await Promise.allSettled([
        createCollectionData(),
        createCollectionData(),
      ])

      const { body: result } = await collectionDataApi.find({ limit: 1 })
      expect(result.total).toBe(2)
      expect(result.data).toHaveLength(1)
    })
  })

  describe('取得指定 collection-data', () => {
    it('取得指定資料', async () => {
      const { body: data } = await createCollectionData()
      const { body: newData } = await collectionDataApi.findOne(data.id)

      expect(newData).toEqual(data)
    })
  })

  describe('更新指定 collection-data', () => {
    it('修改 name 為 cod', async () => {
      const { body: data } = await createCollectionData()
      const { body: newData } = await collectionDataApi.update(data.id, {
        name: 'cod',
      })

      expect(newData.name).toBe('cod')
    })
  })

  describe('刪除指定 collection-data', () => {
    it('刪除資料後，find 無法取得', async () => {
      const { body: data } = await createCollectionData()
      await collectionDataApi.remove(data.id)
      const { body: result } = await collectionDataApi.find()

      expect(result.data).toHaveLength(0)
    })
  })
})
```

為了防止篇幅過長，這裡只展示部分測試內容，完整測試程式碼可以[在此查看](https://github.com/Codfisher/blog-ts-rest-practice/blob/main/apps/api-server/src/resource/collection-data/collection-data.e2e.spec.ts)。

理論上測試內容只要覆蓋合約內的所有 API 與業務邏輯之測試案例，就可以確保 API 正常交付惹。

至於測試案例怎麼列？這個就是一門藝術了。%(◜௰◝)%

## 總結 🐟

感謝大家看到這裡，以上為使用 ts-rest 實際開發的點點滴滴，內容與觀念會隨著時間推移而變化，所以本文會不定期更新。

特別感謝公司優秀的同事們，導入 ts-rest、專案結構、使用設計與實作，很多靈感都來自同事們的提問與建議，非常感謝大家。%( ‧ω‧)ノ╰(‧ω‧ )%

也感謝前端社群的 Danny 大大推薦 ts-rest 這個好東西，有任何問題還請大家不吝指教。%(\*´∀\`)~♥%

本文完整程式碼可以[在此取得](https://github.com/Codfisher/blog-ts-rest-practice)。

---

---
url: /blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest.md
description: 'ts-rest 可以實現從伺服器到客戶端的全型別安全，可以有效降低前後端溝通血流成河的機率。(´,,•ω•,,)'
---

![unleash-the-magic-of-type-script-with-ts-rest](/unleash-the-magic-of-type-script-with-ts-rest.webp){.cover}

# 前後端不再打架，讓 ts-rest 發揮 TypeScript 的魔法吧！（概念篇）

本文基於 TypeScript，如果沒有採用的小夥伴可以狠心離開惹。~(>\_<。)

或者一起湊個熱鬧。(´▽\`ʃ♡ƪ)

此文為概念篇，顧名思義就是來認識認識何謂 ts-rest。

## 甚麼是 ts-rest？

ts-rest 是基於 TypeScript 的 RESTful API 工具，主要目的在於實現從介面定義開始，涵蓋至伺服器、客戶端的全型別安全，而且無需額外、繁瑣的標註或生成過程。

風格類似 RPC，可以讓 API 呼叫更加直覺，配合 TSDoc 有更完整、詳盡的說明，可以大幅降低使用 API 的心智負擔。

### 優點

* 前後端溝通基於 TypeScript 合約，有完整的型別提示，可以避免很多錯誤
* 資料欄位與端點更明確，可以讓使用者更容易理解 API 功能
* 降低發布、變更導致 API 錯誤的風險

### 缺點

* 學習成本較高
* 需要遵守一定的規範
* 前後端需要有良好的溝通模式或管道

## 從前有個後端和前端

以下範例以 Vue、NestJS 為例，相關套件版本如下：

* @nestjs/core：`10.4.1`
* @ts-rest/core：`3.51.0`
* @ts-rest/nest：`3.51.0`
* zod：`3.23.8`

他們想要合力串接一個資料，叫做 CollectionData。

### 通用資料

前後端手牽手，先討論想要的格式。(*≧︶≦))(￣▽￣* )ゞ

第一步定義傳輸層的 schema，方式與 zod 相同。

[定義 Zod Object](https://zod.dev/?id=objects)

```ts
import { z } from 'zod'

export const collectionDataSchema = z.object({
  id: z.string(),
  /** 名稱 */
  name: z.string(),
  description: z.string(),
  remark: z.string(),
})
export interface CollectionData extends z.infer<
  typeof collectionDataSchema
> { }

// 用 type 也可以，取決於貴團隊的規範
// export type CollectionData = z.infer<typeof collectionDataSchema>
```

接著根據剛剛制定的 schema 和 API 功能定義合約：

[ts-rest：Define Contract](https://ts-rest.com/docs/core/)

```ts
import { AppRoute, initContract } from '@ts-rest/core'
import { z } from 'zod'
import { collectionDataSchema } from './schema'

// 建立 collection-data
export const createCollectionDataDtoSchema = collectionDataSchema.omit({
  id: true,
  timestamp: true,
}).partial({
  remark: true,
  description: true,
})

/**
 * 使用 satisfies 是為了 AppRoute 的欄位提示又可以保留具體內容定義。
 * 當然 as const 也行，只是輸入的過程不會有 AppRoute 欄位提示。
 * const create: AppRoute 會遺失詳細的內容定義，所以最後採用 satisfies。
 */
const create = {
  method: 'POST',
  path: '/v1/collection-data',
  body: createCollectionDataDtoSchema,
  responses: {
    201: collectionDataSchema,
  },
  summary: '建立 collection-data',
} satisfies AppRoute

export const collectionDataContract = initContract().router({
  create,
}, {
  pathPrefix: '/api',
  commonResponses: {
    500: z.object({
      message: z.string(),
    }),
  },
})
```

路人：「怎麼只有一個 create？ಠ\_ಠ」

鱈魚：「我懶。(ツ)」

路人：（抽刀）

鱈魚：「刀下留魚啊 (＃°Д°)，是因為內容太多怕大家會累啦，用心良苦欸。」

## 後端實作（NestJS）

依照官網步驟實作。

[ts-rest：Nest](https://ts-rest.com/docs/nest/)

以下是一個簡單的範例：

```ts
// ...

@Controller()
export class CollectionDataController {
  constructor(
    private readonly loggerService: LoggerService,
    private readonly collectionDataService: CollectionDataService,
  ) { }

  @TsRestHandler(collectionDataContract.create, {
    validateResponses: true
  })
  async create() {
    return tsRestHandler(collectionDataContract.create, async ({
      body: dto,
    }) => {
      const [error, data] = await to(this.collectionDataService.create(dto))
      if (error) {
        this.loggerService.error(`建立 CollectionData 錯誤 :`)
        this.loggerService.error(error)

        return {
          status: 500,
          body: {
            message: '建立 CollectionData 錯誤',
          },
        }
      }

      return {
        status: 201,
        body: data,
      }
    })
  }
}
```

::: tip
那個奇怪的 await to 是因為我用了[這個](./blog-program/await-to-js-keeps-your-promises-slick)，不是寫錯喔。(｡･∀･)ﾉﾞ
:::

開啟 validateResponses 的話，ts-rest 會嚴格驗證 API 響應資料格式是否正確，錯誤的話會直接噴 500，這就表示後端最好在 e2e 測試時，就該把可能情境測出來，只要測試有過，資料格式就不可能錯。

前後端就不用再為了資料有坑吵架了。( ‧ω‧)ノ╰(‧ω‧ )

## 前端實作（Vue）

前端用法有兩種，可以依照需求挑適合的用：

* [Fetch Client](https://ts-rest.com/docs/core/fetch)：用法和 axios、fetch 概念相同。
* [Vue Query](https://ts-rest.com/docs/vue-query)：其實就是 TanStack Query

可以漸進式導入，兩個同時用也沒問題。

個人推薦 Vue Query，雖然有點門檻，可是功能很強很好用。(๑•̀ㅂ•́)و✧

如果都不喜歡，也可以[自定義](https://ts-rest.com/docs/core/custom)。

### 驗證

前端如果呼叫 API 前想先驗證一次參數正確性。例如：驗證 collectionData API 的 body 資料是否正確。

只要取得 contract 中對應路徑的 zod schema 即可。

```ts
const createCollectionDataDto = collectionDataContract.create.body

createCollectionDataDto.parse({
  // ...
})
```

剩下就是 zod 的工作了。(oﾟvﾟ)ノ

[Zod：parse](https://zod.dev/?id=parse)

### 型別

型別則是使用 ts-rest 提供的 [Inferring Types 工具](https://ts-rest.com/docs/core/infer-types)。

例如回應型別可以使用 `ServerInferResponseBody` 推導：

```ts
type Data = ServerInferResponseBody<
  typeof collectionDataContract.create,
  201
>
```

![ServerInferResponseBody](/unleash-the-magic-of-type-script-with-ts-rest/ServerInferResponseBody.png)

ts-rest 還有很多內容，可以[來官網逛逛](https://ts-rest.com/docs/intro)。♪(^∇^\*)

## 所以前後端要怎麼共享合約？

鱈魚：「真是個好問題，當然是複製貼...ᕕ( ﾟ ∀。)ᕗ 」

路人：（拿起球棒）

鱈魚：「開玩笑的啦。∠( ᐛ 」∠)\_」

目前我自己已知不錯的方式有：

* 私有 npm
* monorepo

個人比較推薦使用 monorepo，我們公司也是如此，至於怎麼用 Google 有很多教學，這裡就不贅述囉。ԅ( ˘ω˘ԅ)

## 總結 🐟

* ts-rest 可以讓前後端串接更加嚴謹、自動化
* 介紹後端、前端實作
* 合約可以藉由私有 npm、monorepo 共享

以上恭喜你完全發揮 TypeScript 的魔法惹！ˋ( ° ▽、° )

從此前後端再也不用為資料不一致問題打架了。✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

甚麼？你說還有很多事情可以吵？╭(°A ,°\`)╮

那就超過本文的探討範圍惹，要打去練舞室打。ᕕ( ﾟ ∀。)ᕗ

---

---
url: /blog-vue/make-good-use-of-computed.md
description: 常聽說不要把複雜的表達式寫在 template 裡，應先用 computed 裝起來，來試試有甚麼差別吧。ლ（´∀`ლ）
---

![make-good-use-of-computed](/make-good-use-of-computed.webp){.cover}

# 善用 computed

常聽說不要把複雜的表達式寫在 template 裡，應優先用 computed 裝起來再放到 template 中。

聽說歸聽說，~~苓膏龜苓膏~~，來試著探討看看吧。%( ´ ▽ \` )ﾉ%

::: tip
Vue 官方 Style Guide 之「Priority B Rules: Strongly Recommended」中有「[Simple expressions in templates](https://vuejs.org/style-guide/rules-strongly-recommended.html#simple-expressions-in-templates)」

不過規則還是要依照團隊內採用規範為主。%ԅ( ˘ω˘ԅ)%
:::

## 聽說性能有差？

設計一個繁重的計算方便比較差別，來看看 computed 與 template 結果。

`utils.ts`

```ts
export function getFibonacci(n: number): number {
  if (n <= 1)
    return n
  return getFibonacci(n - 1) + getFibonacci(n - 2)
}
```

就是一個經典的費氏數列計算。

接著設計兩個元件，一個使用 computed，一個直接在 template 裡計算。

`components/ComputedCalc.vue`

```vue
<script setup lang="ts">
import { useIntervalFn } from '@vueuse/core'
import { computed, nextTick, ref } from 'vue'
import { getFibonacci } from '../utils'

const n = ref(30)
const key = ref('')

const result = computed(() => getFibonacci(n.value))

useIntervalFn(
  async () => {
    key.value = crypto.randomUUID()

    console.time('computed')
    await nextTick()
    console.timeEnd('computed')
  },
  3000,
  {
    immediateCallback: true,
  }
)
</script>

<template>
  <div>
    <h1>computed</h1>
    <div :key>
      {{ result }}
    </div>
  </div>
</template>
```

`components/TemplateCalc.vue`

```vue
<script setup lang="ts">
import { useIntervalFn } from '@vueuse/core'
import { nextTick, ref } from 'vue'
import { getFibonacci } from '../utils'

const n = ref(30)
const key = ref('')

useIntervalFn(
  async () => {
    key.value = crypto.randomUUID()

    console.time('template')
    await nextTick()
    console.timeEnd('template')
  },
  3000,
  {
    immediateCallback: true,
  }
)
</script>

<template>
  <div>
    <h1>template</h1>
    <div :key>
      {{ getFibonacci(n) }}
    </div>
  </div>
</template>
```

主要邏輯為：

* 透過 `useIntervalFn` 每 3 秒更新一次 `key`，觸發 template 更新
* `console.time` 計算 template 更新所需的時間
* `ComputedCalc.vue` 使用 `computed` 儲存 `getFibonacci` 結果
* `TemplateCalc.vue` 則直接在 `template` 裡呼叫 `getFibonacci`。

接著我們在 `App.vue` 中來測試這兩個元件。

`App.vue`

```vue
<script setup>
import { ref } from 'vue'
import ComputedCalc from './components/ComputedCalc.vue'
import TemplateCalc from './components/TemplateCalc.vue'

const toggle = ref(true)
</script>

<template>
  <input v-model="toggle" type="checkbox">切換</input>
  <computed-calc v-if="toggle" />
  <template-calc v-else />
</template>
```

切換 `checkbox` 會在 devtool 的 console 看到 computed 與 template 的時間差異。

範例程式碼[在此](https://stackblitz.com/edit/make-good-use-of-computed-rnmb827u?file=src%2FApp.vue)

console 的內容如下

```text
computed: 16.491943359375 ms
computed: 0.996826171875 ms

template: 12.89794921875 ms
template: 12.85302734375 ms

computed: 13.27294921875 ms
computed: 0.20703125 ms
computed: 0.18408203125 ms

template: 15.92578125 ms
template: 12.6689453125 ms
template: 12.741943359375 ms
```

可以注意到計算 `getFibonacci(30)` 的時間，兩者基本上差不多，最大的差別在於 `computed` 只有第一次計算時會花較多時間。

這就是官文文件提到的 [Computed Caching](https://vuejs.org/guide/essentials/computed#computed-caching-vs-methods) 效果，只有在 reactive dependency 改變時才會重新計算。

所以不管 template 如何更新，都不會觸發額外的計算。

從這個結果來看，善用 `computed` 最大的優點是可以減少不必要的計算，提升效能。

## 性能之外呢？

路人：「一般才不會有這麼繁重的計算，所以是不是沒差？%(。-\`ω´-)%」

鱈魚：「的確，你說的沒錯。%(´,,•ω•,,)%」

雖然說元件中若有一堆不必要的計算，可能會有積少成多，導致性能不佳的部分。

但根據個人一直以來的開發經驗，主要的性能瓶頸都不是這類問題，通常都是 DOM 太多導致畫面卡頓。

「性能比較好」，這個理由個人覺得不夠充分，不過 `computed` 除了性能之外，還有其他優點，例如：

### 方便除錯

配合 [debugger](https://vuejs.org/guide/extras/reactivity-in-depth.html#computed-debugging)，方便追蹤響應過程。

```ts
const plusOne = computed(() => count.value + 1, {
  onTrack(e) {
    // triggered when count.value is tracked as a dependency
    debugger
  },
  onTrigger(e) {
    // triggered when count.value is mutated
    debugger
  }
})
```

### 方便測試

`computed` 的內容放到 `defineExpose` 中，就可以在單元測試中測試。

```vue
<script setup>
import { computed, defineExpose, ref } from 'vue'
import { getFibonacci } from '../utils'

const n = ref(0)
const result = computed(() => getFibonacci(n.value))

defineExpose({ result })
</script>
```

這一點與 Style Guide 中的「[Simple computed properties](https://vuejs.org/style-guide/rules-strongly-recommended.html#simple-computed-properties)」的理念有點類似。

除了更容易測試外，命名準確的 `computed` 也能提升程式碼的可讀性。

## 真的不好嗎？(\*´･д･)

所以把表達式放在 `template` 中，真的很不好嗎？

我自己是覺得下面這種情況，還是很可以接受的啦。%ԅ(´∀\` ԅ)%

```vue
<template>
  <div :class="{ active: isActive }">
    <h1>{{ i + 1 }}</h1>

    <div :style="{ color: isActive ? 'red' : 'blue' }">
      安安你好
    </div>
  </div>
</template>
```

這類例子要是用 `computed` 裝起來，命名也不太好想。

但下面這種就有點過分了。%(。-\`ω´-)%

```vue
<template>
  <div>
    <div
      :style="{
        color: message.length > 10 ? 'red' : 'blue',
        fontSize: message.length > 10 ? '20px' : '16px',
        letterSpacing: message.length > 10 ? '2px' : '1px',
        fontWeight: message.length > 10 ? 'bold' : 'normal',
      }"
    >
      {{ message }}
    </div>

    總合為 {{
      data
        .filter((item) => item.name === 'cod')
        .map((item) => item.price)
        .reduce((acc, cur) => acc + cur, 0)
    }}
  </div>
</template>

<script setup lang="ts">
const message = ref('安安你好')
const data = ref([
  { name: 'cod', price: 18 },
  { name: 'cod', price: 20 },
  { name: 'cod', price: 22 },
])
</script>
```

建議用 `computed` 裝起來吧。%(\*´∀\`)~♥%

```vue
<template>
  <div>
    <div :style="messageStyle">
      {{ message }}
    </div>

    總合為 {{ total }}
  </div>
</template>

<script setup lang="ts">
import type { CSSProperties } from 'vue'
import { computed } from 'vue'

const message = ref('安安你好')
const messageStyle = computed<CSSProperties>(() => ({
  color: message.value.length > 10 ? 'red' : 'blue',
  fontSize: message.value.length > 10 ? '20px' : '16px',
  letterSpacing: message.value.length > 10 ? '2px' : '1px',
  fontWeight: message.value.length > 10 ? 'bold' : 'normal',
}))

const data = ref([
  { name: 'cod', price: 18 },
  { name: 'cod', price: 20 },
  { name: 'cod', price: 22 },
])
const total = computed(() => {
  return data.value
    .filter((item) => item.name === 'cod')
    .map((item) => item.price)
    .reduce((acc, cur) => acc + cur, 0)
})
</script>
```

## 同場加映

路人：「如果真的有繁重的計算需求，有甚麼方法嗎？」

鱈魚：「可以請打工仔支援。%ᕕ( ﾟ ∀。)ᕗ %」

路人：「...？%( ・ิω・ิ)%」

Web Worker 可以在背景執行的獨立執行緒 ，可以避免主執行緒被阻塞。

我的酷酷元件的[落雪效果](https://chillcomponent.codlin.me/components/bg-snow/)也是用 Web Worker 計算雪花動態與碰撞偵測。

即使雪花超過 10 萬個，FPS 很低，也不會讓網頁卡頓。%( •̀ ω •́ )✧%

::: tip 所以我說那個支援度呢？
截至 2025/01/17 為止，[支援度](https://caniuse.com/webworkers)達到了 98.19%，基本上可以快樂使用！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡
:::

VueUse 有一個 [`useWebWorkerFn`](https://vueuse.org/core/useWebWorkerFn/#usewebworkerfn) 可以簡化 Web Worker 的使用。

來試試看吧。%੭ ˙ᗜ˙ )੭%

`components/WorkerCalc.vue`

```vue
<script setup lang="ts">
import {
  useDateFormat,
  useIntervalFn,
  useTimestamp,
  useWebWorkerFn,
} from '@vueuse/core'
import { ref } from 'vue'
import { getFibonacci } from '../utils'

const time = useTimestamp()
const computedTime = useDateFormat(time, 'YYYY-MM-DD HH:mm:ss SSS')
const result = ref(0)

const { workerFn } = useWebWorkerFn((n: number) => getFibonacci(n), {
  timeout: 50000,
  localDependencies: [getFibonacci],
})

useIntervalFn(
  async () => {
    console.time('worker')
    result.value = await workerFn(40)
    console.timeEnd('worker')
  },
  3000,
  {
    immediateCallback: true,
  }
)
</script>

<template>
  <div>
    <h1>worker</h1>
    <div>
      {{ result }}
    </div>

    <div>{{ computedTime }}</div>
  </div>
</template>
```

每 3 秒計算一次 n=40 的費氏數列，並且顯示目前時間。

接著在 `App.vue` 中加入 `WorkerCalc`。

`App.vue`

```vue
<script setup>
import { ref } from 'vue'
import ComputedCalc from './components/ComputedCalc.vue'
import TemplateCalc from './components/TemplateCalc.vue'
import WorkerCalc from './components/WorkerCalc.vue' // [!code ++]

const toggle = ref(true)
</script>

<template>
  <input v-model="toggle" type="checkbox">切換</input>
  <computed-calc v-if="toggle" />
  <template-calc v-else />

  <worker-calc /> // [!code ++]
</template>
```

現在 console 會多出 worker 的計算時間。

```text
worker: 959.0419921875 ms
worker: 996.47998046875 ms
worker: 980.422119140625 ms
```

可以注意到即使花了將近 1 秒計算，網頁依舊很流暢。%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

## 總結 🐟

* `computed` 有著 `Computed Caching` 的效果，只有在 reactive dependency 改變時才會重新計算，可以減少不必要的計算。
* `computed` 除了性能之外，還有方便除錯、測試、提升可讀性等優點。
* 繁重的計算可以考慮交給 Web Worker，避免網頁卡到歪。

---

---
url: /blog-program/await-to-js-keeps-your-promises-slick.md
description: 可以在特定情境下簡化 Promise 寫法
---

![await-to-js](/await-to-js.webp){.cover}

# 回不去惹，用 await-to-js 讓你的 Promise 操作簡潔又俐落

前陣子意外注意到一個有趣的套件，名為 [await-to-js](https://www.npmjs.com/package/await-to-js)。

主要用途是多一種 Promise 與 await 的寫法，可以在特定情境下讓程式碼更簡潔。

類似的實作其實 [Radash](https://radash-docs.vercel.app/docs/async/tryit) 也有，不過 await-to-js 用法比較單純。

::: tip 2024/08/26 更新
[ECMAScript 新提案： Safe Assignment Operator Proposal](https://dev.to/dharamgfx/bye-bye-try-catch-blocks-meet-javascripts-safe-assignment-operator-proposal-1j7?ref=dailydev)

等於直接把 await-to-js 加到語言規格中，期待 await-to-js 套件退休那一天。(๑•̀ㅂ•́)و✧
:::

## 具體差在哪？

假設原本的 Promise 是這樣：

```ts
let isLoading = true
task().then(() => {
  console.log('done')
}).catch(() => {
  console.error('error')
}).finally(() => {
  isLoading = false
})
```

用 await 會這樣寫。

```ts
let isLoading = true
try {
  await task()
  console.log('done')
}
catch (e) {
  console.error('error')
}
isLoading = false
```

使用 await-to-js 改寫後變成：

```ts
import to from 'await-to-js'

let isLoading = true
const [error] = await to(task())
isLoading = false

if (error) {
  console.error('error')
  return
}

console.log('done')
```

除了看起來比較簡潔，不用 try catch 外，配合 early return 很有效。

在前端可能還好，在後端各種 Promise 操作的場合的很方便，從此以後寫法再也回不去了。XD

以下是官方的範例。

```ts
import to from 'await-to-js'

async function asyncTaskWithCb(cb) {
  let err, user, savedTask, notification;

  [err, user] = await to(UserModel.findById(1))
  if (!user)
    return cb('No user found');

  [err, savedTask] = await to(TaskModel({ userId: user.id, name: 'Demo Task' }))
  if (err)
    return cb('Error occurred while saving task')

  if (user.notificationsEnabled) {
    [err] = await to(NotificationService.sendNotification(user.id, 'Task Created'))
    if (err)
      return cb('Error while sending notification')
  }

  if (savedTask.assignedUser.id !== user.id) {
    [err, notification] = await to(NotificationService.sendNotification(savedTask.assignedUser.id, 'Task was created for you'))
    if (err)
      return cb('Error while sending notification')
  }

  cb(null, savedTask)
}

async function asyncFunctionWithThrow() {
  const [err, user] = await to(UserModel.findById(1))
  if (!user)
    throw new Error('User not found')
}
```

我自己的話後端比較常用，例如 NestJS 的 Controller 中：

```ts
@Controller()
export class ArticleController {
  // ..

  @UseGuards(AuthGuard('jwt'))
  @Post('articles')
  async getInfo(
    @User() jwtPayload: JwtPayload,
    @Body() body: CreateArticleDto,
  ) {
    const [userError, result] = await to(
      this.userService.check(jwtPayload)
    )
    if (userError) {
      throw new HttpException(
        `使用者身分異常`,
        HttpStatus.FORBIDDEN,
      )
    }

    const [checkError, result] = await to(
      this.articleService.checkQuota(jwtPayload)
    )
    if (checkError) {
      throw new HttpException(
        `建立文章失敗，請稍後再試`,
        HttpStatus.INTERNAL_SERVER_ERROR,
      )
    }

    if (result.reason === 'quota-has-been-used-up') {
      throw new HttpException(
        `文章額度已滿，請聯絡客服`,
        HttpStatus.BAD_REQUEST,
      )
    }

    const [createError, article] = await to(
      this.articleService.create(body)
    )
    if (createError) {
      throw new HttpException(
        `建立文章失敗，請稍後再試`,
        HttpStatus.INTERNAL_SERVER_ERROR,
      )
    }

    return article
  }
}
```

可以提前處理 error，更方便使用 early return。◝(≧∀≦)◟

await-to-js 的實現很簡單，他的原始碼只有 22 行。

```ts
/**
 * @param { Promise } promise
 * @param {object=} errorExt - Additional Information you can pass to the err object
 * @return { Promise }
 */
export function to<T, U = Error>(
  promise: Promise<T>,
  errorExt?: object
): Promise<[U, undefined] | [null, T]> {
  return promise
    .then<[null, T]>((data: T) => [null, data])
    .catch<[U, undefined]>((err: U) => {
      if (errorExt) {
        const parsedError = Object.assign({}, err, errorExt)
        return [parsedError, undefined]
      }

      return [err, undefined]
    })
}

export default to
```

如果不想 npm install 的話，也可以直接貼到自己的專案使用。ヾ(◍'౪\`◍)ﾉﾞ

## Promise 都改用 await to 嗎？

當然不是這樣啦，await to 只是多一個選擇。ლ(╹ε╹ლ)

實際上還是有些地方更適合使用 then 或 try catch。

例如：

有時候根本就不會有錯誤，就維持 await。

```ts
const result = await task()
```

有錯誤也沒關係，不需要特別處理，用 catch 紀錄一下就行。

```ts
await task().catch(console.error)
```

單一錯誤不重要，統一處理即可，就直接 try catch。

```ts
try {
  await task1()
  await task2()
  await task3()
  await task4()
}
catch (error) {
  console.error(error)
}
```

請依照實際情況挑選適合的寫法喔。(｡･∀･)ﾉﾞ

## 總結 🐟

* await-to-js 可以在特定情境下簡化 Promise 寫法
* 配合 early return 很有效
* 請不要只用 await-to-js，需要用 then 或 try catch 還是用原本的寫法

---

---
url: /blog-program/remeda-pipe.md
description: pipe 代表函數式程式設計中的概念，利用多個功能結合在一起，資料依序通過每個功能進行處理
---

![remeda-pipe](/remeda-pipe.webp){.cover}

# 好 pipe 不用嗎？藉由 remeda 讓程式碼更簡潔彈性吧！

## 甚麼是 pipe

顧名思是就是水管，但是不會像瑪利歐由人來鑽，而是讓資料通過。

pipe 是一種函數式程式設計中的概念，用來表示一條資料處理的管道。

可以將多個 function 組合在一起，資料會依序經過每個 function 進行處理。

這種方法使程式碼更加清晰、模組化，並且易於維護。

個人覺得和以往指令式的寫法最大差別在於關注點不同。

怎麼說呢？讓我們看看以下兩種等效的程式。

例 1：

```ts
const data = [1, 2, 3]
const filteredData = data.filter((value) => value > 1)
const result = filteredData.join('-')
```

例 2：

```ts
const result = pipe(
  [1, 2, 3],
  filter((value) => value > 1),
  join('-'),
)
```

::: warning
我知道你很想問例 1 明明可以一行解決。範例而已啦，讓我們慢慢來。(´・ω・\`)
:::

可以注意到：

* 例 1 的專注點在「結果」
* 例 2 的寫法專注點在「過程」

了解差異後學習轉換上就會相對容易了。（應該吧 ლ(╹ε╹ლ)）

## ramda、remeda？

這兩個都是基於 FP 概念設計的優秀套件，其實選一個喜歡的都行。

不過我主要用 remeda，因為 remeda 可以完美配合 TypeScript，而且同時支援 data-first 與 data-last 的寫法，兩個範例如下：

* data-first：

```ts
const data = {
  name: 'cod',
  age: '18',
}

const result = pick(data, ['name'])
```

* data-last：

```ts
const data = {
  name: 'cod',
  age: '18',
}

const pickName = pick(['name'])
const result = pickName(data)
```

個人覺得使用上更為直覺。

此外 remeda 還有其他特性，詳細說明就不再此贅述，可以參考以下文件。

[Remeda](https://remedajs.com/)

## 所以 pipe 有甚麼好處？

個人覺得最大的好處是不用一直想變數名稱 XD，而且 function 方便抽換，整體來說增加了程式的彈性。

### 減少臨時變數

你有一個物件陣列代表員工資料：

```ts
const employees = [
  { name: '鱈魚', age: 30, active: true, department: 'HR' },
  { name: '阿貓', age: 25, active: false, department: 'IT' },
  { name: '阿狗', age: 28, active: true, department: 'HR' },
  { name: '章魚', age: 35, active: true, department: 'IT' },
  { name: '鯊魚', age: 26, active: true, department: 'Sales' },
]

type Employee = (typeof employees)[0]
```

要處理以下流程：

1. 挑出 active 員工

2. 根據部門分組

3. 每個部門挑出年紀最小的員工

4. 最後依年紀排序顯示這些員工

一般可能會這樣寫：

```ts
// 1. 篩選 active
const activeEmployees = employees.filter((e) => e.active)

// 2. 分組（用物件表示）
const grouped = activeEmployees.reduce((acc, e) => {
  (acc[e.department] ||= []).push(e)
  return acc
}, {} as Record<string, Employee[]>)

// 3. 每組取年紀最小的員工
const youngestPerDept = Object.values(grouped).map((group) =>
  group.reduce((min, item) => (item.age < min.age ? item : min))
)

// 4. 排序
const result = youngestPerDept.sort((a, b) => a.age - b.age)
```

使用 remeda 就可以這樣寫：

```ts
const result = pipe(
  employees,
  filter((e) => e.active),
  groupBy((e) => e.department),
  mapValues((group) => group.reduce(
    (min, item) => (item.age < min.age ? item : min)
  )),
  values(),
  sortBy((e) => e.age)
)
```

可以看到不但不需要臨時變數，要追加邏輯也很方便。

### 更容易使用 Early Return

使用 Early Return 可以讓程式碼更簡潔，避免過多的巢狀結構。

但是抽離太多 function 反而會讓程式碼變得冗長、難以閱讀。

remeda 的 `pipe` 可以讓我們在一個區塊內使用 Early Return，這樣就可以避免過多的巢狀結構。

例如：提取 `MaybeElement` 型別內部的 `HTMLElement`，若不存在則取得目前元件的 `el`，若都不存在則使用 `document.documentElement`。

一般可能會這樣寫：

```ts
function getRootElement(target: MaybeElement) {
  let rootElement: HTMLElement | undefined
  /** target 為 MaybeElement */
  let value = toValue(target)

  if (value && '$el' in value) {
    value = value.$el
  }
  else {
    const instance = getCurrentInstance()

    value = value
      ?? instance?.vnode?.el
      ?? instance?.proxy?.$el
      ?? document.documentElement
  }

  if (!value) {
    rootElement = undefined
  }
  else if (value instanceof HTMLElement) {
    rootElement = value
  }
  else {
    throw new TypeError(
      '[useImagesReady] 取得目標元素異常，請確認 target 是否為 HTMLElement 或 Vue 元件',
    )
  }

  return rootElement
}

const rootElement = getRootElement(target)
```

如果想要改為 Early Return，可能要把部分邏輯拆成 function：

```ts
function resolveEl(_value: MaybeElement) {
  const value = toValue(_value)

  if (value && '$el' in value) {
    return value.$el
  }
  const instance = getCurrentInstance()

  return value
    ?? instance?.vnode?.el
    ?? instance?.proxy?.$el
    ?? document.documentElement
}

function resolveRootElement(value: unknown) {
  if (!value) {
    return undefined
  }

  if (value instanceof HTMLElement) {
    return value
  }

  throw new Error(
    '[useImagesReady] 取得目標元素異常，請確認 target 是否為 HTMLElement 或 Vue 元件',
  )
}

function getRootElement(target: MaybeElement) {
  const value = resolveEl(target)
  return resolveRootElement(value)
}

const rootElement = getRootElement(target)
```

但是這種只用一次的 function 反而讓程式碼變得冗長。

使用 remeda 的 `pipe`，則可以這樣寫：

```ts
const rootElement = pipe(
  toValue(target),
  /** 提取 el 部分 */
  (value) => {
    if (value && '$el' in value) {
      return value.$el
    }
    const instance = getCurrentInstance()

    return value
      ?? instance?.vnode?.el
      ?? instance?.proxy?.$el
      ?? document.documentElement
  },
  /** 收束型別 */
  (value) => {
    if (!value) {
      return undefined
    }

    if (value instanceof HTMLElement) {
      return value
    }

    throw new Error(
      '[useImagesReady] 取得目標元素異常，請確認 target 是否為 HTMLElement 或 Vue 元件',
    )
  },
)
```

這樣就可以避免過多的巢狀結構，不需定義多餘的 function，讓程式碼更清晰。

### 內建 Lazy Evaluation

remeda 的 `pipe` 會自動使用 lazy evaluation，在某些情境下有奇效，詳情請見[這篇文章](/blog-program/remeda-lazy-evaluator)

### 讓邏輯結構清晰

使用像是 babylon.js 這類有大量物件的套件時，常常會有這種改寫物件資料的部分。

```ts
function createHole(data: ElData) {
  const depth = Math.max(data.width, data.height)

  const texture = new Texture(
    '/minecraft/textures/block/dirt.png',
    scene.value,
    true,
    false,
    Texture.NEAREST_NEAREST
  )
  /** 方塊基準尺寸 */
  const baseSize = 80
  texture.uScale = data.width / baseSize
  texture.vScale = data.height / baseSize

  const material = new StandardMaterial('hole', scene.value)
  material.emissiveColor = new Color3(0.1, 0.1, 0.1)
  material.diffuseTexture = texture

  const hole = MeshBuilder.CreateBox(data.id, {
    width: 1,
    height: 1,
    depth,
    sideOrientation: Mesh.BACKSIDE,
  }, scene.value)

  // 使用縮放對應寬高，這樣就可以自由調整尺寸，而不用變更 mesh
  hole.scaling.x = data.width
  hole.scaling.y = data.height
  hole.renderingGroupId = 1

  hole.material = material

  hole.position.x = data.x + data.width / 2 - windowSize.width / 2
  hole.position.y = -data.y - data.height / 2 + windowSize.height / 2
  hole.position.z = depth / 2

  hole.isVisible = !data.visible
  hole.metadata = {
    ...data,
    position: hole.position,
  }

  return hole
}
```

其實仔細一看就會知道每個區塊的功能，段落也相當明確，但是如果用 pipe 寫會更清晰。

讓我們改寫一下。

```ts
function createHole(data: ElData) {
  const depth = Math.max(data.width, data.height)

  const texture = pipe(
    new Texture(
      '/minecraft/textures/block/dirt.png',
      scene.value,
      true,
      false,
      Texture.NEAREST_NEAREST
    ),
    tap((texture) => {
      /** 方塊基準尺寸 */
      const baseSize = 80
      texture.uScale = data.width / baseSize
      texture.vScale = data.height / baseSize
    })
  )

  const material = pipe(
    new StandardMaterial('hole', scene.value),
    tap((material) => {
      material.emissiveColor = new Color3(0.1, 0.1, 0.1)
      material.diffuseTexture = texture
    }),
  )

  const hole = pipe(
    MeshBuilder.CreateBox(data.id, {
      width: 1,
      height: 1,
      depth,
      sideOrientation: Mesh.BACKSIDE,
    }, scene.value),
    tap((hole) => {
      // 使用縮放對應寬高，這樣就可以自由調整尺寸，而不用變更 mesh
      hole.scaling.x = data.width
      hole.scaling.y = data.height

      hole.renderingGroupId = 1
      hole.material = material

      hole.position.x = data.x + data.width / 2 - windowSize.width / 2
      hole.position.y = -data.y - data.height / 2 + windowSize.height / 2
      hole.position.z = depth / 2

      hole.isVisible = !data.visible
      hole.metadata = {
        ...data,
        position: hole.position,
      }
    }),
  )

  return hole
}
```

::: tip 那個 tap 是甚麼？
[`tap`](https://remedajs.com/docs/#tap) 是 remeda 提供的 function，可以讓我們在 pipe 中執行副作用，並且回傳原本的值。
:::

這樣每個區塊做的事情更加清晰。

甚至 Vue 的 `watch`、`useEventListener` 等等額外副作用也可以放在同一個區塊內。

以下是 Matter.js 的例子：

```ts
const mouse = pipe(
  Mouse.create(document.body),
  tap((item) => {
    // 移除 wheel listener 否則葉面無法使用滾輪捲動
    // @ts-expect-error 存在 mousewheel
    item.element.removeEventListener('wheel', item.mousewheel)

    // 同步滾動量，以免滾動後拉不到 ball
    useEventListener('scroll', () => {
      Mouse.setOffset(item, {
        x: window.scrollX,
        y: -window.scrollY,
      })
    })

    watch(pixelRatio, (value) => {
      item.pixelRatio = value
    }, { immediate: true })
  }),
)
```

可以清楚看到相關副作用都集中在同一個區塊內。

路人：「看起來好像差不多？(´・ω・\`)」

鱈魚：「看起來的確差不多，現在讓我們配合編輯器的功能。ლ（´∀\`ლ）」

VSCode 可以摺疊指定區塊，這樣就可以乾淨的分開每個段落。

快捷鍵如下：

* `Ctrl + K` -> `Ctrl + J`：展開全部區塊
* `Ctrl + K` -> `Ctrl + 0`：摺疊全部區塊
* `Ctrl + K` -> `Ctrl + 1`：摺疊第 1 層區塊
* `Ctrl + K` -> `Ctrl + 2`：摺疊第 2 層區塊

... 以此類推

所以我們就可以將剛剛的程式摺疊第 2 層區塊，會變成這樣：

```ts
function createHole(data: ElData) {
  const depth = Math.max(data.width, data.height)

  const texture = pipe(
    // ...
  )

  const material = pipe(
    // ...
  )

  const hole = pipe(
    // ...
  )

  return hole
}
```

Matter.js 的例子則可以摺疊第 1 層，變為：

```ts
const mouse = pipe(
  // ...
)
```

這樣不管是在閱讀或是維護上都會更加方便。( •̀ ω •́ )✧

### 處理資料

接著看看資料處理的例子。

假設我們有多個 IoT 設備回傳資料，網頁需要彙整並顯示內容，資料為：

```ts
interface Datum {
  deviceId: string;
  type: string;
  temperature: number;
  humidity: number;
  otherSensorData: Array<{
    type: string;
    value: number;
  }>;
}

const data: Datum[] = [
  {
    deviceId: 'device_1',
    type: 'A',
    temperature: 24.5,
    humidity: 50.0,
    otherSensorData: [
      { type: 'A', value: 10 },
      { type: 'A', value: 20 }
    ]
  },
  {
    deviceId: 'device_2',
    type: 'B',
    temperature: 22.3,
    humidity: 45.5,
    otherSensorData: [
      { type: 'B', value: 15 },
      { type: 'C', value: 25 }
    ]
  }
]
```

以下讓我們來實際撰寫程式。

#### 列出所有設備 ID 並用頓號分隔

熟悉 JS 的人一定可以很快寫出以下程式：

```ts
const result01 = data
  .map(({ deviceId }) => deviceId)
  .join('、')
```

用 pipe 寫則會像這樣：

```ts
const result02 = pipe(
  data,
  map(prop('deviceId')),
  join('、')
)
```

看起來好像沒比較好捏？但是用 remeda 可以更簡單抽離與複用：

```ts
const getDeviceIdListString = piped(
  map<Datum, string>(prop('deviceId')),
  join('、')
)
```

也方便加入新的處理邏輯：

```ts
import { trim } from 'ramda'

const getDeviceIdListString = piped(
  /** 將每個 deviceId 去除頭尾空白 */
  map<Datum, string>(
    piped(prop('deviceId'), trim),
  ),
  join('、'),
)
```

邏輯越複雜效果會越明顯，來看看其他例子。

#### 將設備依照 type 分類

```ts
const groupByType = pipe(
  data,
  groupBy(prop('type')),
  values,
)
```

#### 取得平均溫度與平均濕度

```ts
const meanData = {
  temperature: pipe(data, meanBy(prop('temperature'))),
  humidity: pipe(data, meanBy(prop('humidity'))),
}
```

#### 取得 otherSensorData type 種類清單

```ts
const typeList = pipe(
  data,
  /** 將所有 otherSensorData 攤平、組成新矩陣 */
  flatMap(prop('otherSensorData')),
  /** 依照 type 數值去除重複項目 */
  uniqBy(prop('type')),
  /** 取出 type 數值產生新矩陣 */
  map(prop('type'))
)
```

#### 取得所有溫溼度不在舒適範圍內的設備

```ts
function isComfortableTemperature(value: number) {
  return value >= 22 && value <= 28
}
function isComfortableHumidity(value: number) {
  return value >= 40 && value <= 60
}

const isComfortable = piped(
  allPass<Datum>([
    piped(prop('temperature'), isComfortableTemperature),
    piped(prop('humidity'), isComfortableHumidity),
  ])
)

const uncomfortableList = pipe(data, reject(isComfortable))

/**
 * 因為只有一個參數，所以也可以用 data-first 的方式寫
 * const result = reject(data, isComfortable);
 */
```

從以上例子來看，其實就算沒有註解，從 function 的名稱我們看得出來此程式在做甚麼。( •̀ ω •́ )✧

這樣可讀性是不是提升了許多呢？如果沒有，就再多看幾次（？

如果錯誤或更好的做法，歡迎大家多多指教。(´▽｀)

## 總結 🐟

* pipe 可將多個功能串聯，資料依序通過每個功能進行處理
* remeda 可以完美配合 TypeScript，同時支援 data-first 與 data-last 的寫法
* 使用 pipe 可以讓程式碼結構更加清晰、模組化，並且易於維護

---

---
url: /blog-ocean-world/flexible-data-reordering.md
description: 如何實現靈活的資料排序
---

![flexible-data-reordering](/flexible-data-reordering.webp){.cover}

# 如何實現靈活的資料排序

最近遇到任意排序資料的需求，研究了一輪後找到了一個有趣的解決方案。

方案是一個名為 Fractional indexing 的演算法，能夠實現靈活的資料排序。

其特點為能夠在現有清單中任意位置插入新資料且不改變其他資料順序的情況下進行排序。

換個比喻，就像是可以在不變更其他人號碼牌的情況下，讓你手上的號碼牌變成任意位置，可以隨意插隊的感覺。%◝( •ω• )◟%

讓我們一步步探討看看。

## 如何排序？

如何自由調整資料排序呢？%ლ(╹ε╹ლ)%

有人可能會想說：「阿不就調整矩陣順序就好了？%( ˘･з･)%」

不過那是在同一個矩陣中才有辦法，如果是從 DB 取出來呢？

DB 內的資料通常都只能依靠某個欄位進行排序取值，不能像矩陣換個位置就行。

舉個類比情境，就像是 `object` 的 key-value 資料那樣，例如：

```ts
const data = {
  1: {
    name: 'cod',
    age: 10,
  },
  2: {
    name: 'cat',
    age: 1,
  },
  3: {
    name: 'dog',
    age: 4,
  },
}
```

需要將此 `data` 內容轉換成矩陣，若依據 `age` 排升序則為：

```ts
const list = [
  {
    name: 'cat',
    age: 1,
  },
  {
    name: 'dog',
    age: 4,
  },
  {
    name: 'cod',
    age: 10,
  },
]
```

`object` 不會保證資料順序，所以直接轉換成 `array` 不能保證順序正確，一定要先 `sort()` 才行。

剛剛依 `age` 欄位排序，現在需求改成可以隨意調整資料順序，該怎麼做呢？

大家可能應該都想到方法了，新增一個 `order` 欄位不就好了嗎？

```ts
const data = {
  1: {
    name: 'cod',
    age: 10,
    order: 1,
  },
  2: {
    name: 'cat',
    age: 1,
    order: 2,
  },
  3: {
    name: 'dog',
    age: 4,
    order: 3,
  },
}
```

若要移動位置，只需要調整 `order` 欄位的值即可。

例如：要將 `dog` 移到 `cat` 前面，只需要將 `dog` 的 `order` 改成 `1.5` 即可。

這就是 Fractional indexing 的核心概念！%( •̀ ω •́ )✧%

不過此演算法的數值範圍使用 0 到 1 之間的浮點數。

::: tip
至於為甚麼是 0 到 1 之間，這個倒是沒有特別找到具體的原因，若有大大知道為甚麼還請不吝告訴我。%(\*´∀\`)~♥%
:::

此演算法來自鼎鼎大名的 Figma，其 CTO 分享的[這篇文章](https://madebyevan.com/algos/crdt-fractional-indexing/)。

文章內有很生動的互動效果，能夠讓人更直覺地理解 Fractional indexing 運作方式。

## 浮點數精度

不過這裡還有個小問題，就是浮點數的精度有限，若交換太多次可能會導致因精度不足，讓排序異常。

以 JS 的數字（IEEE 754 的 64 位元雙精度浮點數）為例，小數點後大約可以正確表示到 15~17 位數字，若超過這個範圍，會出現數值遺失問題。

有沒有可以存好存滿的方法呢？

那就用字串吧！同時使用 Base62 編碼，讓字串短一點。%(・∀・)９%

::: tip
JS 有時候也會使用字串表示數值，避免潛在的精度損失問題。

[Decimal.js](https://github.com/MikeMcl/decimal.js?tab=readme-ov-file#use:~:text=it%20is%20recommended%20to%20pass%20strings%20rather%20than%20numbers%20to%20avoid%20a%20potential%20loss%20of%20precision.)
:::

甚麼是 Base62 編碼？這是一種將資料轉換成只包含 62 個可列印字元的編碼方式

62 個字元包括：

* 數字：0 到 9（共 10 個）
* 大寫英文字母：A 到 Z（共 26 個）
* 小寫英文字母：a 到 z（共 26 個）

總共：10 + 26 + 26 = 62 個字元

舉個例子：%( ´ ▽ \` )ﾉ🌰%

假設要將十進位的數字 125 轉成 Base62 編碼

1. 125 ÷ 62 = 2 餘 1 → 第一個字元是 1
2. 2 ÷ 62 = 0 餘 2 → 第二個字元是 2

最終得到 125 的 Base62 編碼為 21

所以 [Fractional Indexing](https://github.com/rocicorp/fractional-indexing?tab=readme-ov-file#generatekeybetween) 範例程式碼才會都是奇怪的英文數字組合：

```ts
import { generateKeyBetween } from 'fractional-indexing'

const first = generateKeyBetween(null, null) // "a0"

// Insert after 1st
const second = generateKeyBetween(first, null) // "a1"

// Insert after 2nd
const third = generateKeyBetween(second, null) // "a2"

// Insert before 1st
const zeroth = generateKeyBetween(null, first) // "Zz"

// Insert in between 2nd and 3rd (midpoint)
const secondAndHalf = generateKeyBetween(second, third) // "a1V"
```

## 所以我說那個程式碼呢？

讓我們用工程師的語言來對話吧！來人啊，上程式碼！%(≖‿ゝ≖)✧%

這裡實作使用 [`fractional-indexing-jittered`](https://www.npmjs.com/package/fractional-indexing-jittered) 這個套件。

讓我們新增一個 `createDataManager` function 建立一個管理資料排序的物件。

首先新增一些預期可能用到的基礎方法。

`content\blog-ocean-world\flexible-data-reordering\index.ts`

```ts
export function createDataManager<Data>() {
  const dataMap: Map<string, {
    data: Data;
    order: string;
  }> = new Map()

  return {
    add(data: Data) {
      return ''
    },

    moveBefore(
      id: string,
      targetId: string,
    ) { },

    moveAfter(
      id: string,
      targetId: string,
    ) { },

    delete(id: string) { },

    getAll() {
      return []
    },
  }
}
```

接著讓我們新增測試檔案與測試案例。

`content\blog-ocean-world\flexible-data-reordering\index.test.ts`

```ts
import { describe, expect, it } from 'vitest'
import { createDataManager } from './'

interface Data {
  name: string;
  value: number;
}

describe('createDataManager', () => {
  it('新增資料並取得所有資料', () => {
    const manager = createDataManager<Data>()
    manager.add({ name: 'a', value: 1 })
    manager.add({ name: 'b', value: 2 })

    const allData = manager.getAll()

    expect(allData).toHaveLength(2)
    expect(allData[0]?.name).toBe('a')
    expect(allData[1]?.name).toBe('b')
  })

  it('根據 id 刪除資料', () => {
    const manager = createDataManager<Data>()
    const aId = manager.add({ name: 'a', value: 1 })
    manager.add({ name: 'b', value: 2 })

    manager.delete(aId)

    const allData = manager.getAll()
    expect(allData).toHaveLength(1)
    expect(allData[0]?.name).toBe('b')
  })

  it('可以移動資料到指定資料之後', () => {
    const manager = createDataManager<Data>()
    const aId = manager.add({ name: 'a', value: 1 })
    const bId = manager.add({ name: 'b', value: 2 })
    const cId = manager.add({ name: 'c', value: 3 })

    manager.moveAfter(aId, cId)

    const allData = manager.getAll()
    expect(
      allData.map((d) => d.name),
    ).toEqual(['b', 'c', 'a'])
  })

  it('可以移動資料到指定資料之前', () => {
    const manager = createDataManager<Data>()
    const aId = manager.add({ name: 'a', value: 1 })
    const bId = manager.add({ name: 'b', value: 2 })
    const cId = manager.add({ name: 'c', value: 3 })

    manager.moveBefore(bId, aId)

    const allData = manager.getAll()
    expect(
      allData.map((d) => d.name),
    ).toEqual(['b', 'a', 'c'])
  })
})
```

執行測試，結果全部失敗，不意外，因為還沒有實作任何邏輯，如果全過我會比較驚訝。%(´・ω・\`)%

現在讓我們完成實作吧！%ヾ(◍'౪\`◍)ﾉﾞ%

`content\blog-ocean-world\flexible-data-reordering\index.ts`

```ts
import { generateKeyBetween } from 'fractional-indexing-jittered'

export function createDataManager<Data>() {
  const dataMap: Map<string, {
    data: Data;
    order: string;
  }> = new Map()

  function getDataEntriesList() {
    return Array
      .from(dataMap)
      .sort((a, b) => a[1].order < b[1].order ? -1 : 1)
  }

  return {
    add(data: Data) {
      const id = crypto.randomUUID()
      const lastData = getDataEntriesList().at(-1)

      const order = generateKeyBetween(
        lastData?.[1].order ?? null,
        null,
      )
      dataMap.set(id, { data, order })
      return id
    },
    moveBefore(
      id: string,
      targetId: string,
    ) {
      const currentData = dataMap.get(id)
      if (!currentData)
        return
      const targetData = dataMap.get(targetId)
      if (!targetData)
        return

      const dataList = getDataEntriesList()
      const targetIndex = dataList.findIndex((item) => item[0] === targetId)
      const prevTarget = dataList[targetIndex - 1]

      const newOrder = generateKeyBetween(
        prevTarget?.[1].order ?? null,
        targetData.order,
      )
      currentData.order = newOrder
      dataMap.set(id, currentData)
    },
    moveAfter(
      id: string,
      targetId: string,
    ) {
      const currentData = dataMap.get(id)
      if (!currentData)
        return
      const targetData = dataMap.get(targetId)
      if (!targetData)
        return

      const dataList = getDataEntriesList()
      const targetIndex = dataList.findIndex((item) => item[0] === targetId)
      const nextTarget = dataList[targetIndex + 1]

      const newOrder = generateKeyBetween(
        targetData.order,
        nextTarget?.[1].order ?? null,
      )
      currentData.order = newOrder
      dataMap.set(id, currentData)
    },
    delete(id: string) {
      dataMap.delete(id)
    },

    getAll() {
      return getDataEntriesList()
        .map(([_, { data }]) => data)
    },
  }
}
```

沒意外的話，現在測試應該全部通過了。

在 `getDataEntriesList` 中 log 一下內容，觀察看看 `order` 欄位的值。

```txt
{ data: { name: 'b', value: 2 }, order: 'a1' }

{ data: { name: 'b', value: 2 }, order: 'a1' }

{ data: { name: 'b', value: 2 }, order: 'a1' }
{ data: { name: 'c', value: 3 }, order: 'a2' }
{ data: { name: 'a', value: 1 }, order: 'a3' }

{ data: { name: 'b', value: 2 }, order: 'Zz' }
{ data: { name: 'a', value: 1 }, order: 'a0' }
{ data: { name: 'c', value: 3 }, order: 'a2' }
```

可以發現內容與官方範例程式碼一致，相當有趣。%(´,,•ω•,,)%

::: tip
這裡的測試案例只有簡單驗證，沒有考慮到其他案例與邊界情況，大家有興趣可以自己擴充測試。%( ‧ω‧)ノ╰(‧ω‧ )%
:::

完整程式碼可以在[這裡找到](https://github.com/Codfisher/cod-aquarium/blob/main/content/blog-ocean-world/flexible-data-reordering)。

## 拖來拖去玩玩看

光看程式碼還是有點抽象，不如直接動手拖動看看。%( ´ ▽ \` )ﾉ%

拖動任一項目放開後，只有被移動的那筆資料的 order 會變化，其他資料完全不受影響。

這正是 Fractional indexing 的精髓，換成 DB 情境，就是一次移動只需要更新一筆資料。%(≖‿ゝ≖)✧%

多拖幾次會發現字串會變長，例如 `a1V`、`a1Fzz`，這就是字串精度所帶來的效果。

```vue
<template>
  <div class="w-full border border-gray-200 dark:border-gray-700 rounded p-3">
    <div class="text-sm opacity-70 mb-3">
      直接拖動項目調整順序，右側為該筆資料目前的 order 字串。
    </div>

    <div
      ref="list"
      class="flex flex-col gap-2 select-none"
    >
      <div
        v-for="item, index in itemList"
        :key="item.id"
        class="item flex items-center gap-2 px-3 py-2 rounded border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 cursor-grab"
        :class="{ 'cursor-grabbing! shadow-lg': item.id === dragState?.id }"
        :style="getItemStyle(index)"
        @pointerdown="startDrag($event, index)"
        @pointermove="updateDrag($event)"
        @pointerup="endDrag()"
        @pointercancel="endDrag()"
      >
        <svg
          class="w-4 h-4 opacity-40 shrink-0"
          viewBox="0 0 24 24"
          fill="currentColor"
        >
          <path d="M9 20q-.825 0-1.412-.587T7 18t.588-1.412T9 16t1.413.588T11 18t-.587 1.413T9 20m6 0q-.825 0-1.412-.587T13 18t.588-1.412T15 16t1.413.588T17 18t-.587 1.413T15 20m-6-6q-.825 0-1.412-.587T7 12t.588-1.412T9 10t1.413.588T11 12t-.587 1.413T9 14m6 0q-.825 0-1.412-.587T13 12t.588-1.412T15 10t1.413.588T17 12t-.587 1.413T15 14M9 8q-.825 0-1.412-.587T7 6t.588-1.412T9 4t1.413.588T11 6t-.587 1.413T9 8m6 0q-.825 0-1.412-.587T13 6t.588-1.412T15 4t1.413.588T17 6t-.587 1.413T15 8" />
        </svg>

        <span class="flex-1 truncate">{{ item.name }}</span>

        <span class="font-mono text-sm opacity-60">{{ item.order }}</span>
      </div>
    </div>

    <div class="flex gap-2 mt-3">
      <button
        class="px-3 py-1 text-sm rounded border border-gray-200 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-800 disabled:opacity-40"
        :disabled="itemList.length >= maxLength"
        @click="addItem()"
      >
        新增資料
      </button>

      <button
        class="px-3 py-1 text-sm rounded border border-gray-200 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-800"
        @click="resetList()"
      >
        重設
      </button>
    </div>

    <div class="mt-3 p-2 rounded bg-gray-100 dark:bg-gray-800 font-mono text-sm break-all">
      [{{ orderText }}]
    </div>
  </div>
</template>

<script setup lang="ts">
import type { CSSProperties } from 'vue'
import { generateKeyBetween } from 'fractional-indexing-jittered'
import { computed, nextTick, onMounted, ref, useTemplateRef } from 'vue'

interface Item {
  id: string;
  name: string;
  order: string;
}

interface DragState {
  id: string;
  fromIndex: number;
  toIndex: number;
  startY: number;
  deltaY: number;
  /** 相鄰項目的間距，單位 px */
  pitch: number;
}

const maxLength = 8
const nameList = ['鱈魚', '鮭魚', '鮪魚', '鯖魚', '秋刀魚', '比目魚', '沙丁魚', '旗魚']

const listElement = useTemplateRef<HTMLElement>('list')
const itemList = ref<Item[]>([])
const dragState = ref<DragState | undefined>()
/** 順序提交的當下，DOM 位置與 transform 會同時變化，需暫時關閉動畫避免項目滑過畫面 */
const transitionEnabled = ref(true)

let idCount = 0

const orderText = computed(
  () => itemList.value.map(({ order }) => `'${order}'`).join(', '),
)

function sortItemList(list: Item[]) {
  return list.sort((a, b) => a.order < b.order ? -1 : 1)
}

function addItem() {
  if (itemList.value.length >= maxLength)
    return

  const lastOrder = itemList.value.at(-1)?.order ?? null
  idCount += 1

  itemList.value = sortItemList([
    ...itemList.value,
    {
      id: `item-${idCount}`,
      name: nameList[itemList.value.length % nameList.length] ?? '不明魚類',
      order: generateKeyBetween(lastOrder, null),
    },
  ])
}

function resetList() {
  itemList.value = []
  idCount = 0

  for (let i = 0; i < 5; i++) {
    addItem()
  }
}

/** 移動資料，並依前後鄰居產生新的 order */
function moveItem(fromIndex: number, toIndex: number) {
  const list = [...itemList.value]
  const [target] = list.splice(fromIndex, 1)
  if (!target)
    return

  list.splice(toIndex, 0, target)

  target.order = generateKeyBetween(
    list[toIndex - 1]?.order ?? null,
    list[toIndex + 1]?.order ?? null,
  )

  itemList.value = sortItemList(list)
}

function getPitch() {
  const elementList = listElement.value?.children
  const first = elementList?.[0]
  const second = elementList?.[1]
  if (!(first instanceof HTMLElement) || !(second instanceof HTMLElement))
    return 0

  return second.offsetTop - first.offsetTop
}

function startDrag(event: PointerEvent, index: number) {
  const item = itemList.value[index]
  const element = event.currentTarget
  if (!item || !(element instanceof HTMLElement))
    return

  element.setPointerCapture(event.pointerId)
  dragState.value = {
    id: item.id,
    fromIndex: index,
    toIndex: index,
    startY: event.clientY,
    deltaY: 0,
    pitch: getPitch(),
  }
}

function updateDrag(event: PointerEvent) {
  const state = dragState.value
  if (!state)
    return

  const deltaY = event.clientY - state.startY
  const step = state.pitch > 0 ? Math.round(deltaY / state.pitch) : 0

  state.deltaY = deltaY
  state.toIndex = Math.min(
    Math.max(state.fromIndex + step, 0),
    itemList.value.length - 1,
  )
}

function endDrag() {
  const state = dragState.value
  if (!state)
    return

  dragState.value = undefined
  if (state.toIndex === state.fromIndex)
    return

  transitionEnabled.value = false
  moveItem(state.fromIndex, state.toIndex)

  // 等 DOM 更新並實際繪製後再恢復動畫
  nextTick(() => {
    requestAnimationFrame(() => {
      requestAnimationFrame(() => {
        transitionEnabled.value = true
      })
    })
  })
}

/** 拖動中的項目跟著手指移動，被擠開的項目則位移一個間距 */
function getItemStyle(index: number): CSSProperties {
  const baseStyle: CSSProperties = transitionEnabled.value
    ? {}
    : { transition: 'none' }

  const state = dragState.value
  if (!state)
    return baseStyle

  const { fromIndex, toIndex, deltaY, pitch } = state

  if (index === fromIndex) {
    return {
      transform: `translateY(${deltaY}px)`,
      transition: 'none',
      zIndex: 1,
    }
  }

  if (fromIndex < toIndex && index > fromIndex && index <= toIndex) {
    return { ...baseStyle, transform: `translateY(${-pitch}px)` }
  }

  if (toIndex < fromIndex && index >= toIndex && index < fromIndex) {
    return { ...baseStyle, transform: `translateY(${pitch}px)` }
  }

  return baseStyle
}

// order 由 jitter 亂數產生，須避免 SSR 與 client 內容不一致
onMounted(() => resetList())
</script>

<style scoped lang="sass">
.item
  touch-action: none
  transition: transform 0.2s
</style>

```

## 總結 🐟

* Fractional indexing 演算法能夠實現靈活的資料排序，讓資料可以任意插隊。
* 浮點數有精度問題，使用 Base62 編碼的字串表示數值，可以避免精度損失。

---

---
url: /blog-vue/vue-watch-may-cause-a-memory-leak.md
description: 某些情境會讓 watch 不會自動解除，一起來看看吧！(ˊДˋ;)
---

![vue-watch-may-cause-a-memory-leak](/vue-watch-may-cause-a-memory-leak.webp){.cover}

# 小心遺漏的 watch 讓網頁爆炸

最近注意到 `watch` 有一個有趣的現象，一個可能會挖坑的現象。

在某些特殊情境下，`watch` 的位置可能不會在元件最外層。

類似這種感覺：

```vue
<script setup>
import { ref, watch } from 'vue'

const data = ref(1)

setTimeout(() => {
  watch(data, (value) => {
    console.log('[ Comp ] data: ', value)
  })
}, 500)
</script>
```

先別吐槽這樣寫超廢，只是個簡單的示意啦。%(ʘ ͜ʖ ʘ)%

::: tip
其實如果有這類需求，推薦使用 VueUse 提供的 [watchPausable](https://vueuse.org/shared/watchPausable/)、[watchTriggerable](https://vueuse.org/shared/watchTriggerable/#watchtriggerable) 這類進階版 watch，看起來更漂亮、更好維護。
:::

我們知道正常情況下，元件 `onUnmounted` 後，`watch` 就會自動解除。

但是剛剛的那個例子，`onUnmounted` 後 `watch` 不會自動解除喲！%ლ(╹◡╹ლ)%

所以如果頁面中有很多這類 `watch`，很有可能讓網頁爆掉唷！%o(≧∀≦)o%

路人：「是在開心個毛線喔。%(ﾟДﾟ\*)ﾉ%」

這是因為如果在內層呼叫 `watch`，會讓 `watch` 與元件處在不同 effectScope，導致此結果。

## 該怎麼辦？%(っ °Д °;)っ%

解法也很簡單，勤奮一點手動解除。%◝( •ω• )◟%

```vue
<script setup>
import { ref, watch } from 'vue'

const data = ref(1)

let unwatch
setTimeout(() => {
  unwatch = watch(data, (value) => {
    console.log('[ CompUnwatch ] data: ', value)
  })
}, 500)

onUnmounted(() => {
  console.log('[ onUnmounted ]')
  unwatch()
})
</script>
```

路人：「啊如果有很多 watch，這樣一個一個解除很累欸。%(ˊДˋ;)%」

鱈魚：「…%('◉◞⊖◟◉`)%，先不探究這種 code 怎麼過得了 code review ，假設真的有很多`watch\` 要解除，可以用剛剛提到的關鍵字『effectScope』」

[effectScope](https://vuejs.org/api/reactivity-advanced.html#effectscope) 可以用來捕捉範圍內的 reactive effects，所以可以把所有的 watch 收集起來統一解除。

例如像這樣：

```vue
<script setup>
import { effectScope, onUnmounted, ref, watch } from 'vue'

const scope = effectScope()
const data = ref(1)
const number = ref(0)

setTimeout(() => {
  scope.run(() => {
    watch(data, (value) => {
      console.log('[ CompScope ] data: ', value)
    })
  })
}, 500)

setTimeout(() => {
  scope.run(() => {
    watch(number, (value) => {
      console.log('[ CompScope ] number: ', value)
    })
  })
}, 1000)

onUnmounted(() => {
  console.log('[ onUnmounted ]')
  scope.stop()
})
</script>
```

世界再度回復和平！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

以上提到的範例可以在[此連結查看](https://play.vuejs.org/#eNrNVctu2zAQ/JWFLlYKRXbQ9uLaAdoihxToA01yqnJQ5JWtVCIJPpwUhv69S1Jy5ES2EbdBexN3h7sz3CG1Ct4LES8NBuNgojJZCA0KtRGnCSsqwaWGFUjMoYZc8goGBB2sUx95JZp4PLQLW2nwbiN/kXGBGyAX6UFesbtUZ4sNbBNr0QnLOFMaloUqbkqEqeUW5mmp8Chhk6FXQNxpobESZaqRVgCTxcnparXeV9eTIUVcpmDCUMXjis+wnCZBg0kC0L8EUiBbYPbzht8ngd/gVC+Pi3wDPHxIesm7EK3UXsxk2KEeRIFWJDov5vGt4ozmtLJliBbVKUqUX4Uu6FCSYAwuY3NpWfK7Ty6mpcGojTspPfFbRerG9PFNokK5JCrrnE7lHLVPn118wXv6Xifp0IwlviP5HRUvjeXoYR8MmxHtDs6xPXdGKNj8Up3da2SqFWWJWmTt8HRYBu0RbpP+QPd1/MbtS1hNp9jac4/RI3CTiYCzK1ZxwzTOIsA8x0z7uW7ehNaRNCPKTbvIkCzpk7NUp41XT46cjan1ZVEhNzoMj2B66vm71qFFRxAu09LgQw7A1uIlxiWfh4Mf/vJdu9pjGETg8VSdJFPnOoK3o5Hv1tHSbfeoYAcF1wO709ZJWG5YZs8ZjKBmJMvvto1j15SkfU71IpYpm/GK8q/gZDSy+xup51RTErTbvC1mYZHFO667rvCsWLoPcNJdaOhjj2/MxivzPwzcR5mpblA28WY0/UZwxWNpWDe4zx+9DvES+m3ijfLULgdw8tKezcpv28Or9cbhPm7JK82Fd9wfGhsa5v/Q/+4I912Czu/zgGuwxflPX7MSNRjfitb99mnytPHZr1z7t3zZx25N8a845CVH35zH9uHXvwG30kPy)。

::: danger
可以觀察到即使元件消失後，devtool 的 console 依舊持續跑出 log！%(ﾟДﾟ\*)ﾉ%
:::

不過說的真，請不要這樣用 `watch`。…%(›´ω\`‹ )%

## 總結 🐟

* watch 不會自動解除的原因是在不同 effectScope
* 使用 effectScope 可以統一解除 `watch`

---

---
url: /blog-vue/quasar-menu-hover-on-open.md
description: 原本想說應該很簡單，仔細探討後發現事情沒有像憨魚想的那麼簡單。(◉◞౪◟◉ )
---

![quasar-menu-hover-on-open](/quasar-menu-hover-on-open.webp){.cover}

# 幫 Quasar Menu 加上 hover 開啟功能

最近遇到 Menu 想要使用 hover 開啟的需求，不過 Quasar 的 Menu 預設沒有這個功能，只好自行處理了。%◝( •ω• )◟%

原本想說應該很簡單，不是只要偵測 mouseenter 與 mouseleave 就好了嗎？

沒想到多層級 menu 就出事了，因為從第 1 層移動到第 2 層 menu 的瞬間，就會導致第 1 層選單隱藏。

結果，趴！都沒惹，事情果然沒有像憨魚想的那麼簡單。%(◉◞౪◟◉ )%

多說無益，直接來看看成果。

（按下 Run Project 後需要稍等一會兒）

::: tip 不僅用於 Quasar Menu
雖然這篇針對 Quasar Menu 開發，但此邏輯沒有綁定 Quasar Menu 特有功能，所以微調後也可用於其他 UI 套件的 Menu，~~應該啦 %(ゝ∀・)b%~~。
:::

::: warning WCAG
hover 開啟 Menu 功能可能會違反 WCAG 某些準則，這點要多注意。
:::

鱈魚：「（省略一千字）...，建議不要做 hover 開啟 Menu 功能 %(⌐■\_■)✧%」

甲方：「我要 %(◉◞౪◟◉ )%」

鱈魚：「好，我做給你 %...(›´ω\`‹ )%」

## 需求

所有的開發第一步都是釐清需求。

甚麼？你說沒有需求怎麼辦？那就開始通靈吧！%(。-\`ω´-)%

### 基本需求

* 當滑鼠 hover 在按鈕（或觸發器）上時，Menu 自動開啟。
* 滑鼠從按鈕移出時：
  * 移至 Menu 上，Menu 保持開啟
  * 否則 Menu 關閉

### 多層級單選單

假設開啟了 3 層，則：

* 滑鼠離開第 3 層回到第 2 層時，第 3 層消失
* 直接離開第 3 層至頁面，所有選單消失
* 直接回到第一層，第 2、3 層關閉

### 使用需求

計畫開發一個可以無痛替換 Quasar Menu 元件，假設叫做 `menu-hover`。

先來複習一下 [Quasar Menu 用法](https://quasar.dev/vue-components/menu)。

用法很簡單，只要在預期產生 Menu 的元素內放入 `q-menu` 即可。

```vue
<template>
  <q-btn
    color="primary"
    label="Basic Menu"
  >
    <q-menu>
      <q-list>
        <q-item v-close-popup clickable>
          <q-item-section>New tab</q-item-section>
        </q-item>
        <q-item v-close-popup clickable>
          <q-item-section>New incognito tab</q-item-section>
        </q-item>
      </q-list>
    </q-menu>
  </q-btn>
</template>
```

`menu-hover` 元件需要像這樣簡單替換即可使用：

```vue
<template>
  <q-btn
    color="primary"
    label="Basic Menu"
  >
    <menu-hover>
      // ...
    </menu-hover>
  </q-btn>
</template>
```

## 架構

主要有兩個工作，概念如下圖所示：

1. 注入一個紀錄 Menu 層級的變數
2. root menu 注入收集 child 資料之 function

![menu-hover 架構圖](/quasar-menu-hover-on-open/menu-hover-架構圖.png)

由於要傳遞未知層級的資料，預計使用 [Vue 的 Provide/Inject](https://vuejs.org/guide/components/provide-inject) 處理。

## 開發

### props 與 hover 邏輯

現在來實際開發吧，首先從最基本的 props 開始。

因為要可以無痛替換原本的 `q-menu`，所以需要繼承 `q-menu` 的 props。

::: tip
為了單純一點，這次排除 `target` 和 `modelValue`，有需要再想辦法加進來。
:::

`src/components/menu-hover/menu-hover.vue`

```vue
<script setup lang="ts">
import type { QMenuProps } from 'quasar'

interface Props extends Omit<QMenuProps, 'modelValue' | 'target'> {
  disableHoverOpen?: boolean;
}
const props = withDefaults(defineProps<Props>(), {
  disableHoverOpen: false,
})
</script>
./type./type
```

接下來是觸發器與 menu 自己本身的 hover 邏輯。

`src/components/menu-hover/menu-hover.vue`

```vue
<template>
  <q-menu
    ref="menuRef"
    @mouseenter="handleMenuHover"
    @mouseleave="handleMenuLeave"
  >
    <slot />
  </q-menu>
</template>

<script setup lang="ts">
// ...

// 辨識元件，Vue 3.5 之後可以直接使用 useId()
const id = crypto.randomUUID()

const triggerEl = useParentElement()
const isTriggerHover = useElementHover(triggerEl, {
  delayLeave: 100,
})

const menuRef = ref<InstanceType<typeof QMenu>>()
const isMenuHover = ref(false)
const handleMenuLeave = debounce(() => {
  isMenuHover.value = false
}, 100)
function handleMenuHover() {
  isMenuHover.value = true
  handleMenuLeave.cancel()
}
</script>
```

這裡使用 `VueUse` 提供的 `useParentElement` 與 `useElementHover` 簡單完成。

menu 的部分則是因為 `useElementHover` 放入元件沒有作用，所以改用普通的 `mouseenter` 與 `mouseleave` 處理。

::: tip

menuRef 與 `useElementHover` 目前做過以下嘗試。

這樣寫 TS 不開心：

```ts
useElementHover(menuRef, {
  delayLeave: 100,
})
```

這樣寫沒反應：

```ts
useElementHover(() => menuRef.value?.$el, {
  delayLeave: 100,
})
```

若有大大知道怎麼做，還請不吝告訴我！(\*´∀\`)~♥
:::

### 注入 level 並蒐集 child menu 資料

先來定義形別資料。

`src/components/menu-hover/type.ts`

```ts
import type { InjectionKey, Ref } from 'vue'

export interface MenuData {
  id: string;
  level: number;
}

export const menuLevelInjectionKey = Symbol('menu-level') as InjectionKey<number>

export const menuInjectionKey = Symbol('menu-hover') as InjectionKey<{
  bindSubmenu: (data: MenuData) => void;
  unbindSubmenu: (id: string) => void;
  submenuList: Ref<MenuData[]>;
}>
```

並在元件引用。

`src/components/menu-hover/menu-hover.vue`

```vue
// ...

<script setup lang="ts">
import type { MenuData } from './type'
import { computed, inject, provide, ref } from 'vue'
import { injectionKey } from './type'

// ...

/** 只有 root menu 使用，child menu 應該使用 currentSubmenuList */
const submenuList = ref<MenuData[]>([])

const rootProvider = inject(injectionKey, null)
const currentSubmenuList = computed(() => rootProvider?.submenuList.value ?? [])

// 紀錄目前是第幾層 menu
const menuLevel = inject(menuLevelInjectionKey, 0)
provide(menuLevelInjectionKey, menuLevel + 1)

function bindSubmenu(data: MenuData) {
  /** 清掉同一層者，因為同層同時只會顯示一個 */
  submenuList.value = submenuList.value.filter((item) => item.level !== data.level)
  submenuList.value.push(data)
}
function unbindSubmenu(id: string) {
  const index = submenuList.value.findIndex((item) => item.id === id)
  if (index !== -1) {
    submenuList.value.splice(index, 1)
  }
}
// 只有 root menu provide
if (!rootProvider) {
  provide(injectionKey, {
    bindSubmenu,
    unbindSubmenu,
    submenuList,
  })
}
</script>
```

基本上就是當 child menu 顯示時，將自己的資料傳遞給 root menu，隱藏、消失時移除資料。

並透過 `menu-level` 紀錄目前是第幾層，這樣 root 與 child 都可以得知目前整體 Menu tree 狀態了。

有狀態後，要判斷 hover 邏輯就簡單多了。

### 開啟選單

最後就是實際開啟 Menu 的部分了，使用 `menuVisible` 來控制 Menu 的顯示與隱藏。

有 3 種方式會觸發 Menu 顯示：

1. 觸發器 hover
2. Menu hover
3. 自己的子選單開啟

```vue
<template>
  <q-menu
    ref="menuRef"
    v-model="menuVisible"
    v-bind="props"
    @mouseenter="handleMenuHover"
    @mouseleave="handleMenuLeave"
  >
    <slot />
  </q-menu>
</template>

<script setup lang="ts">
// ...

const menuVisible = ref(false)
const hasSubmenuVisible = computed(() => {
  if (menuLevel === 0 && submenuList.value.length > 0) {
    return true
  }

  const visible = currentSubmenuList.value.some(({ level }) => level > menuLevel)

  // 自己也要顯示才算是自己的 submenu
  return visible && menuVisible.value
})

watch(() => [
  isTriggerHover,
  isMenuHover,
  hasSubmenuVisible,
], () => {
  if (props.disableHoverOpen) {
    return
  }

  menuVisible.value = isTriggerHover.value || isMenuHover.value || hasSubmenuVisible.value
}, { deep: true })

watch(menuVisible, (value) => {
  if (value) {
    rootProvider?.bindSubmenu({
      id,
      level: menuLevel,
    })
  }
  else {
    rootProvider?.unbindSubmenu(id)
  }
})

onBeforeUnmount(() => {
  rootProvider?.unbindSubmenu(id)
})
</script>
```

以上我們完成 hover 開啟的邏輯了。

若有哪個部分解解釋得不夠清楚或有大神知道更簡潔的方法，還請不吝告訴我。%੭ ˙ᗜ˙ )੭%

完整原始碼[在這裡](https://github.com/Codfisher/blog-quasar-menu-open-on-hover)

想嘗試看看的朋友可以[點這裡](https://stackblitz.com/~/github.com/Codfisher/blog-quasar-menu-open-on-hover?file=src/components/menu-hover/menu-hover.vue)

## 總結 🐟

* 微調後可以用於其他 UI 套件的 Menu
* 使用 Vue 的 Provide/Inject 來傳遞未知層級的資料

---

---
url: /aquarium/meme-cache.md
description: 常常找不到記憶中的梗圖嗎？我來幫你找找 ԅ(´∀` ԅ) 可用描述或圖中文字搜尋近千張迷因梗圖。
---


---

---
url: /blog-program/remeda-lazy-evaluator.md
description: remeda 實作中有 lazy evaluator 有甚麼好處？來 Bench 一下看看◝( •ω• )◟
---

![remeda-lazy-evaluator](/remeda-lazy-evaluator.webp){.cover}

# 懶有懶的好處，聊聊 Lazy Evaluation

故事發生於某天平凡的午後，鱈魚我和平常一樣快樂地用著 [`Remeda`](https://remedajs.com/)，使用 [`take`](https://github.com/remeda/remeda/blob/main/packages/remeda/src/take.ts) 時忽然很好奇原始碼如何實作。

鱈魚：「給我照腳本念，不要偷嘴我！%ლ（´口\`ლ）%」



讓我們看看 `Remeda` 的 `take` 原始碼：

```ts
export function take(...args: ReadonlyArray<unknown>): unknown {
  return purry(takeImplementation, args, lazyImplementation)
}

function takeImplementation<T extends IterableContainer>(array: T, n: number): Array<T[number]> {
  return n < 0 ? [] : array.slice(0, n)
}

function lazyImplementation<T>(n: number): LazyEvaluator<T> {
  if (n <= 0) {
    return lazyEmptyEvaluator
  }

  let remaining = n
  return (value) => {
    remaining -= 1
    return { done: remaining <= 0, hasNext: true, next: value }
  }
}
```

`purry` 是 `Remeda` 特殊函數，不在此文章討論範圍，有興趣的朋友可以來[這裡看看](https://remedajs.com/docs/#purry)。

可以看到的確有 `Array.slice` 沒錯，不過還有 `lazyImplementation` 部分，這個其實就是實作「惰性求值」（Lazy Evaluation）邏輯。

至於甚麼是「惰性求值」？簡單來說，就是在需要時才計算，而不是一開始就計算所有東西。

細節網路上超多文章，這裡就不贅述了。%(ゝ∀・)y%

## 來 Bench 一下

讓我們來 Bench 一下，感受看看差異吧。

邏輯為：將一個巨大的矩陣 map、filter 後，只取前 5 筆資料。

資料定義如下：

```ts
export const mapFn = (x: number): number => x * 2
export const filterFn = (x: number): boolean => x % 3 === 0
export const TAKE_COUNT = 5

const DATA_SIZE = 1_000_000
export const data = Array.from({ length: DATA_SIZE }, (_, i) => i + 1)
```

總共測試三種版本程式：

`Remeda` 的 `lazy` 版本：

`lazy.ts`

```ts
import { filter, map, pipe, take } from 'remeda'

pipe(
  data,
  map(mapFn),
  filter(filterFn),
  take(TAKE_COUNT)
)
```

原生 Array 版本：

`native.ts`

```ts
data
  .map(mapFn)
  .filter(filterFn)
  .slice(0, TAKE_COUNT)
```

將 `Remeda` function 拆開來用，不要使用 `lazy`：

`no-lazy.ts`

```ts
import { filter, map, take } from 'remeda'

const mapped = map(data, mapFn)
const filtered = filter(mapped, filterFn)
take(filtered, TAKE_COUNT)
```

[實際跑個 Bench](https://benchjs.com/playground#/N4IgzgLghhCmIC5QDdYCcwEsD2A7RAjADQiYC2ADgDaxmy7QQ65iIDaomAJoiAMIB1AQC8ACgBUAEl2EB9PtgBmAZgAeAdgByAWUniAHCBKLMNXFDq8qUYQE8AdBFYkAxnjgNe5CtjQQABMD+ZFAURP4mVHBo4dAA1rDhFJgUsP4AvhFo2GT+AORotLBcUHkAOrgVsKo+fv5uLAFoAK64-gC8-gAUAJQdAHyBFf7+hRDNaG3JqV3DI-4l0ERzIyEUXWsAYrg9y23zkdFdh+jbuyv+8bBd4gCCANIAovIA8gCqmuI9cz0A3BXpX4gdJETg8BAgABaAE04i4AIpvAAMBDeAE5FAANe64ABWzVuLkwAHcACxGECRegWeAQ3DYAC01jsjmcIAaHggXkovgCQTW4ROMUuUASGSyOXyhToJXKlVw1VqAQakFGrQ63T67UGwDmKoCa1SXA1ay6iyg4S2O1+81tIz1eFVQuKGqFG1CRsFpmiZxtczGEzaV2O3vQxXCdyerw+X3+uEBwNBpHB-AAjgALTQANmJSOUAHF86FocgCEjFGQ+AARYkUqnmSx0mCYVCsikc+hciFVGq8+qOprqzq9AZDfYByYLGBQC72U1W777Eb2N1Cs6zsBUTAua5IiMPZ58d6fP4AoHpAC6JCgLiYqHEUAARgBJFN8DPZ3MFosUEtlivVrWJBgLA4wUAoXC0iAip9vqwShNsGpdKoCD+LgzRkI+6A9Kh6GYego6qP4ABU-gAExxjBdRwWubTDihaEYVhaA4f4j7YNgNBQHRgxEQApP4ygdO0nRIpRvbUQO-iRoex7iBqACscYVHBVa3HcsgAMrPpCjwagQshIkZhlGX6CoScqUnmhqtxoGgUAOIo2RkF0QRmAA5hA6aoWpGnabpGThF0sjhJgWqDJg-gANT+AQp74MBoHNBQVbiJpvCQS41iFP47lUNgj5QFQY4jJl2VpHBVqochuFMdho54cxcalbAWVQDlNGhmg2zVQxjX1dqbEcVxuDNQsrXlf2jTSQe0afIpY1le1FVWdOtX4WgbAXmNAIVD2SqBAmJCFFAXB0AoDCdrwADE-jws025xP4mnQHU+YPZBe24Ndt2bKYaQvS0t4TLAFQMv4IFgayqGaUlFD9pBlzYP4FCFBQy1Tks9QnXA-jprAVCpGgEStLezBgOEoEuPYYP+N4NB0AwzaOgA9MR9jAE4RC4mA6Soc+lAM52zNtFSYBTdAmC4FL7lsfQLjpiEaBxNsX0-f4AhoJgTC4LLABC8uK+1cRgF9BD2M9cPdJDyWsjhX2PKgaC2F5Mv+LY2DNP4VEBMSpjFVh-hQMgUCmE+NBB+LUC5flhXFYovjeze6Z04LRRM0weA0-KAAGecQLYqRgC4WsUBAFQsyz2OwDAaTccaPuXLAqrmvtsGrdANl2Q5K7Oa5-geV5qFlkZgXdCFdPhZP4kHXBYAYUh7VoOtzFbVPS-2IUXDNDuXRdBabHr9FbHhEi8V5znX1kRbAvUOnjDk901QWHfdsIF9t9CxnzAMmAqREiYFwCM0juWwM3PGYZwj13dp7NCsAXQQGRo3aOihSaZzaA2F0BRWh5GzhUC+Bci4lxSOXcys8pItDopqUcupxxJUnOaTexQd7XHnmQU+8V0j4LzhUCkW5Hz2S1s3dgoBMG8GlMUKAwILwghAE7LAeBCDpCAA)

可以看到結果差距非常驚人。

| Name       | Ops/sec                                         |
|------------|-------------------------------------------------|
| lazy.ts    | 1,113,819 Best |
| no-lazy.ts | 63 (-100.0%)  |
| native.ts  | 61 (-100.0%)  |

* `lazy` 版本表現最佳，達到每秒 111 萬次操作，遠超過其他兩個版本。

* `no-lazy` 與 `native` 版本表現相近很合理，因為 `Remeda` 的 `map`、`filter` 都是使用原生的 `Array.map`、`Array.filter`。

`lazy` 版本會那麼快，是因為它只需要計算到滿足 `take` 的部分，並不會計算整個資料集，所以時間才差那麼多。

## 所以用 Remeda 性能都會好棒棒嗎？

倒也不能這麼說，讓我們去掉 `take` 的部分，再跑一次看看。

| Name       | Ops/sec                                      |
|------------|----------------------------------------------|
| lazy.ts    | 19(-70.4%) |
| no-lazy.ts | 64 Best      |
| native.ts  | 63(-1.8%)  |

可以看到 `lazy` 的效能大幅下降，甚至比不上 `no-lazy` 版本。

這是因為 `lazy` 的 `take` 只在需要時才計算，當沒有 `take` 時，整個資料集都需要計算，這樣就失去了惰性求值的優勢，反而會因為 `lazy` 額外的計算邏輯，導致效能下降。

或者把資料數量改成 50 筆，再跑一次。

| Name       | Ops/sec                                              |
|------------|------------------------------------------------------|
| lazy.ts    | 1,017,423 (-36.0%) |
| no-lazy.ts | 1,539,932 (-3.2%)  |
| native.ts  | 1,590,550 Best      |

可以看到 `lazy` 版本下降惹 %Σ(ˊДˋ;)%

這是因為瀏覽器為了 JS 性能操碎了心，這點資料才不算甚麼，`lazy` 的計算邏輯反而拖累了性能。

## 原生不能懶懶的嗎？

可以使用 generator 來實作惰性求值邏輯：

`generator.ts`

```ts
function* mapIterator<T, U>(
  iterable: Iterable<T>,
  mapFn: (item: T) => U
): IterableIterator<U> {
  for (const item of iterable) {
    yield mapFn(item)
  }
}

function* filterIterator<T>(
  iterable: Iterable<T>,
  filterFn: (item: T) => boolean
): IterableIterator<T> {
  for (const item of iterable) {
    if (filterFn(item)) {
      yield item
    }
  }
}

function* takeIterator<T>(
  iterable: Iterable<T>,
  count: number
): IterableIterator<T> {
  let i = 0
  for (const item of iterable) {
    if (i++ >= count)
      break
    yield item
  }
}

export function run() {
  const iterator = takeIterator(
    filterIterator(
      mapIterator(data, mapFn),
      filterFn
    ),
    TAKE_COUNT
  )
  const result = Array.from(iterator)
}
```

Bench 結果：

| Name         | Ops/sec                                            |
|--------------|----------------------------------------------------|
| lazy.ts      | 636,538 (-0.2%)   |
| no-lazy.ts   | 40 (-100.0%)  |
| native.ts    | 40 (-100.0%)  |
| generator.ts | 637,597 Best     |

也有 [proposal-iterator-helpers 提案](https://github.com/tc39/proposal-iterator-helpers/)，截至 2025/05/26 還在 Stage 4，雖然已經有瀏覽器實作，不過要注意[支援度](https://caniuse.com/?search=Iterator)。

`iIterator.ts`

```ts
function* toIterator<T>(array: T[]) {
  for (const val of array) {
    yield val
  }
}

export function run() {
  toIterator(data)
    .map(mapFn)
    .filter(filterFn)
    .take(TAKE_COUNT)
    .toArray()
}
```

Bench 結果：

| Name         | Ops/sec                                              |
|--------------|------------------------------------------------------|
| lazy.ts      | 586,274 Best         |
| no-lazy.ts   | 30 (-100.0%)      |
| native.ts    | 34 (-100.0%)      |
| generator.ts | 501,987 (-14.4%)   |
| iterator.ts  | 545,057 (-7.0%)    |

[Bench 程式碼](https://benchjs.com/playground#/N4IgzgLghhCmIC5QDdYCcwEsD2A7RAjADQiYC2ADgDaxmy7QQ65iIDaomAJoiAMIB1AQC8ACgBUAEl2EB9PtgBmAZgAeAdgByAWUniAHCBKLMNXFDq8qUYQE8AdBFYkAxnjgNe5CtjQQABMD+ZFAURP4mVHBo4dAA1rDhFJgUsP4AvhFo2GT+AORotLBcUHkAOrgVsKo+fv5uLAFoAK64-gC8-gAUAJQdAHyBFf7+hRDNaG3JqV3DI-4l0ERzIyEUXWsAYrg9y23zkdFdh+jbuyv+8bBd4gCCANIAovIA8gCqmuI9cz0A3BXpX4gdJETg8BAgABaAE04i4AIpvAAMBDeAE5FAANe64ABWzVuLkwAHcACxGECRegWeAQ3DYAC01jsjmcIAaHggXkovgCQTW4ROMUuUASGSyOXyhToJXKlVw1VqAQakFGrQ63T67UGwDmKoCa1SXA1ay6iyg4S2O1+81tIz1eFVQuKGqFG1CRsFpmiZxtczGEzaV2O3vQxXCdyerw+X3+uEBwNBpHB-AAjgALTQANmJSOUAHF86FocgCEjFGQ+AARYkUqnmSx0mCYVCsikc+hciFVGq8+qOprqzq9AZDfYByYLGBQC72U1W777Eb2N1Cs6zsBUTAua5IiMPZ58d6fP4AoEgsG8ZqPZq4hmQ7RcSS2KvqLOY7QsdTKABGuLrpjUo2IAAOb0OgMC+G2rjuJ2vCKK0LhMHgABUwShAAktEkFoAAPOI4RvP0XSYNhP40Ag-hYRB5GwPh-SWqE2yUSRcBkJRXyjm8PSUdRaBQLRfE4bhRFjiMii+N0+r+KRtD+EoMlkTQfS6ku-i2JgsBUMaVqsbQp77OkAIVBUCG4EhzBoUKQkQL49F6fxtG8UpdHiAxEShmgzHdLJ7H+Jx2r+D+2DYDQUA7M5NE0DZdluWJESSV00m+fJiiKVFsAqRcmBpSGUSnLgelkD0WVqSMGlacavlxraRmGcZ8pmRZqEigkMV4W5DkCRRVEufR4RuK0ECUbgzRkD+6A8b1GXtfR8U0AEmAakiNUJWgUkDuluQKbJjnKfFIw5T5ADUx3+P0nSDQwfQ-oUoqreVmnaVtq11XVPZKv2jRqm0w5ajqDrfbtOEalc7WzGp1nYbZaAQ3a6EUOD5qMRQZx7PDa7yra5xqZGh7HuIPyrdJhRgM0UQarcaD8Q4ijZGQXUwwZgImfgF7JrwVZoOIYAAEIAEqyFAUDiPzzSYD+oiPBAmyPBhtwAWYNJeO10HsrBngQk1yG4GhtmzZ1UDU1AtgcWwAC6pXiYl0nIFAVCpf4Rs01b8wVc9dtUHMb2sx9fYk0OmqjqpIz69DvhmtOi62nOoTuqjOyzqunnrmpjiitcePRies62VTNO9GerPAubJBQBZqDiAJGEpjCcKIii6JYji+KEiS5IkGAsDjBQChcLSICKv7m1WhqXSqCNY0TWgU2jeN6Cjqo-hoQATHGQ91NJmNjxP-hz9PU3BaFsDhYv-gAKT+MoHTtJ0K1+5vm1Z0eMYagArHGFTSVWtx3LIADKGFISPA1AQWQSIIHgIgX6BUvZH7fXNJTY2tN6ZdCCGYECEB0yUR-n-QBwCMjhC6LIcImB-oyX8GdAgBkKRdx7lWcQ-9eD9xcNYQo-gQJUGwD+e28UWFsLSNJK0LFd770mqOMRaBVr8KNoIzamMRGT3njPUcR8wq4GkbAVhsivqqmfgTd+mjtHsOkuaJR08LarQag-PkCYSB3S4HQBQDA4IQgAMT+HhOLFwcR-D-2gHUfM4t+6szcR4zYgE-EQBaEhCYsAKgMn8HQ5oFBWSUX-t3FJ-Z+6XGwP4CghQKA6ORvUO6cB-Dpi0qkda2tmBgHCN3Fw9gEkyUoDQOgDBmyOgAPQoXsMAJwRBcRgHSLxNpRROk6w8jQMAX1oCYFwAskCQV6AuHTCENAcRtihI8QINApEln+F5qs9ZRs4hgFZgQewfjMkUG6Mk1JTgeKs0eKgNAtgsGHNsNgZo-gN4BGJKYB2E0nZ21MN1NIUBZlQA4VwnhDsJLrRPms1p1AJmMGYM0+UAADXFEBbCpDAC4fZFAIAVG6d00pJ9ynhWNP8y4sBVTmhsbogIiDOj5xNiuVB6D6CYOwf4MsEDCHdBITJchZD15wOVJtMmuRhzO3MegC25Dnb2EKFwZoO4uhdAtEFVVlCgrhCRAZXF2LWYr2uRhcZHSMWOm6NUCwaLWTPPlNatFtqum4AZGAVIRITAuGyWkEC2BGUVLDOEWl6kfl71gC6WyfzpVOwiIhKZDYXQFFaHkLFFQzX4sJcSlIZLYGfQDr9IOgUQ6jEyZOc06rihauuHK41zNc24oqBSLct0jaaVYAgDgIB028GlMUKAJcQQgDeVgPAhB0hAA)

以上就是這次的簡單測試。%੭ ˙ᗜ˙ )੭%

鱈魚：「以後遇到懶得做的 feature，就說我正在 Lazy Evaluation 就對惹。%(ゝ∀・)b%」

PM：（抽出生魚片刀 ( ˘•ω•˘ )）

## 總結 🐟

* `Remeda` 的 `lazy` 版本在處理大量資料時，能夠避免不必要的計算，提升效能。
* 不過當資料量小時，`lazy` 反而會拖慢效能。
* 性能會因情境、runtime、瀏覽器最佳化與程式寫法而有所不同，最好應該實際跑過 benchmark 再做選擇。

---

---
url: /blog-vue/vue-h-function-with-type-hints.md
description: 先前提到 Quasar 的 Dialog Plugin 很好用，再讓我補充一個用法。ლ(╹◡╹ლ)
---

![vue-h-function-with-type-hints](/vue-h-function-with-type-hints.webp){.cover}

# 所以我說那個型別呢？來一個有形別提示的 Vue h function 吧！

[先前提到](./blog-vue/vue-h-function-makes-quasar-dialog-easier-to-reuse) Quasar 的 Dialog Plugin 很好用，再讓我補充一個用法。

有時候會希望可以點擊圖片時將圖片最大化呈現，這個需求如果要簡單實現，可以使用 QDialog 實作。

最直接的做法應該是點擊指定圖片時，將圖片的 src 存起來，再將 dialog 的顯示狀態改為 true，讓 Dialog 開啟。

其實你可以直接使用 $q.dialog 配合 h function 簡單完成。

```vue
<template>
  <div class="fit flex flex-col gap-4">
    <q-img
      class="w-[20rem] h-[15rem]"
      src="https://live.staticflickr.com/4325/35716212880_217fa28b46_k.jpg"
      @click="openImgWithDialog('https://live.staticflickr.com/4325/35716212880_217fa28b46_k.jpg')"
    />
  </div>
</template>

<script setup lang="ts">
import { QDialog, QImg, useQuasar } from 'quasar'
import { h } from 'vue'

const $q = useQuasar()

/** 將 QImg 使用 QDialog 包起來後，使用 $q.dialog 開啟 */
function openImgWithDialog(src: string) {
  $q.dialog({
    component: h(
      QDialog,
      undefined,
      {
        default() {
          return h(QImg, { src })
        }
      }
    )
  })
}
</script>
```

這樣就可以簡單快速的利用 Dialog 開啟圖片了，完全不會有額外的 template 與變數！♪( ◜ω◝و(و

::: tip
不過如果要複雜的互動，例如：縮放平移等等，當然還是要包個專用元件處理。
:::

當然不只有 QImg，想用其他元件也行，概念都一樣。◝( •ω• )◟

不過這裡稍微有個小小的困擾，就是 h function 不會提示元件的參數，給錯或是參數改了都不知道。…(›´ω\`‹ )

讓我們建立一個有元件參數提示的 h function 吧！(/≧▽≦)/

## 有形別提示的 h function

第一步是建立協助抽取 Vue 元件型別的實用 function。

::: tip 推薦官方工具
推薦使用官方的 [vue-component-type-helpers](https://www.npmjs.com/package/vue-component-type-helpers)
:::

`types/index.ts`

```ts
import { Slot } from 'vue'

/** 提取 Vue Component 之內部 props
 *
 * 會將 style、class、event 全部取出來
 */
export type ExtractComponentProps<Comp> = Comp extends new () => {
  $props: infer P;
}
  ? P
  : never

/** 提取 Vue Component slots */
export type ExtractComponentSlots<Comp> = Comp extends new (...args: any) => {
  $slots?: infer S;
}
  ? (S extends Slot ? Parameters<S>[0]
      : {}
    ) : {}
```

接著新增 typedH function。

`common/utils.ts`

```ts
import { Component, h } from 'vue'
import { ExtractComponentProps, ExtractComponentSlots } from '../types'

/** 元件繼承參數
 *
 * [文件](https://cn.vuejs.org/guide/components/attrs.html#fallthrough-attributes)
 */
export interface InheritAttr {
  class?: string;
  style?: Record<string, string>;
  /** 為了讓範例精簡，這裡只列出 click，可以自行追加基礎事件 */
  onClick?: (event: MouseEvent) => void;
}

/** Veu h function 有型別推導的版本
 *
 * [何謂 h function](https://cn.vuejs.org/guide/extras/render-function.html)
 *
 * @param component Vue SFC 元件或 html tag 名稱
 * @param props SFC 內所有參數，包含 class、style、event 等等
 * @param slots SFC 插槽
 */
export function typedH(
  component: string,
  props?: string,
): ReturnType<typeof h>
export function typedH<Comp extends Component>(
  component: string,
  props?: InheritAttr,
  slots?: ExtractComponentSlots<Comp>,
): ReturnType<typeof h>
export function typedH<Comp extends Component>(
  component: Comp,
  props?: ExtractComponentProps<Comp> & InheritAttr,
  slots?: ExtractComponentSlots<Comp>,
): ReturnType<typeof h>
export function typedH(
  component: any,
  props?: any,
  slots?: any,
) {
  if (!slots) {
    return h(component, props)
  }
  return h(component, props, slots)
}
```

用法與原本的 h function 一模一樣，現在我們有型別提示了！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡\*｡

![型別提示](/vue-h-function-with-type-hints/Untitled.png)

就這樣，其實也不是甚麼神奇的東西。(´,,•ω•,,)

[範例程式](https://stackblitz.com/~/github.com/Codfisher/blog-vue-typed-h)在此，大家下次見。( ´ ▽ \` )ﾉ

## 總結 🐟

* h function 快速將現有元件變成 Dialog 元件
* 透過 typedH function 可以有型別提示

---

---
url: /blog-ocean-world/use-nodejs-to-automatically-generate-the-compressed-file.md
description: 有些案子需要打包、壓縮後交付，雖然壓縮按一下很簡單，但是一直重複就不簡單了。讓我們使用腳本自動產生壓縮檔，不用再手動壓縮了。♪(^∇^*)
---

![use-nodejs-to-automatically-generate-the-compressed-file](/use-nodejs-to-automatically-generate-the-compressed-file.webp){.cover}

# 打包後順便壓縮一下吧，使用 Node.js 自動產生壓縮檔

有些案子需要打包、壓縮後交付，雖然壓縮也只是簡單按一下，但是一直重複就不簡單了。(˘･\_･˘)

讓我們使用腳本自動產生壓縮檔，解放手動壓縮輪迴吧。♪(^∇^\*)

## 檔案結構

第一步當然是先介紹一下檔案結構。

```text
.
├─ dist              // 打包後的檔案
├─ scripts
│   └─ arch-dist.ts  // 產生壓縮檔的腳本
├─ package.json
└─ ...
```

## 安裝套件

搜尋了一下發現有個套件叫做 [archiver](https://www.npmjs.com/package/archiver)，可以幫我們打包、壓縮檔案。

安裝 archiver：

```bash
npm i -D archiver @types/archiver
```

來寫程式吧！( •̀ ω •́ )✧

`scripts\arch-dist.ts`

```ts
import fs from 'node:fs'

import archiver from 'archiver'
import { name } from '../package.json'

const fileName = `${name}.zip`

const output = fs.createWriteStream(`./${fileName}`)
const archive = archiver('zip', {
  zlib: { level: 9 }
})

output.on('close', () => {
  console.log(`zip 壓縮完成 : `, fileName)
})

archive.on('error', (err) => {
  throw err
})

/** 將資料傳輸至 output */
archive.pipe(output)
/** 指定要加入的目錄，第二參數為 false，表示不要將自己加入 */
archive.directory('./dist', false)
archive.finalize()
```

程式碼就這麼簡單，非常的樸實無華。(´・ω・\`)

鱈魚：「現在我們來執行腳本吧！」

路人：「Node.js 又不能直接跑 TypeScript。(⊙\_⊙)？」

鱈魚：「沒錯，所以讓我們來編譯吧。(≧∇≦)ﾉ」

路人：（直接離場）

先別走啊！開玩笑的啦，我才不會這樣自找麻煩。(´,,•ω•,,)

可以利用 vite-node 直接執行 TypeScript 腳本。

vite-node 就是 Vitest 與 Nuxt 3 Dev SSR 底層使用的工具，可以讓我們無痛執行 TypeScript。

甚麼？你說 ts-node？那個實在太難用，我們還是用 vite-node 吧。(´・ω・\`)

現在讓我們新增腳本。

`package.json`

```json
{
  "scripts": {
    "build": "vite build && npm run build:arch",
    "build:arch": "npx vite-node scripts/arch-dist.ts"
  }
}
```

::: tip
使用 npx 就不需要先安裝 vite-node 了，不知道的朋友可以看看[這裡](https://hoyis-note.coderbridge.io/2021/07/20/npm-npx-%E5%B7%AE%E5%88%A5/)
:::

這樣就可以在 build 後，自動執行壓縮檔案的腳本了。

## 總結 🐟

* archiver 套件可以幫我們打包、壓縮檔案
* 使用 vite-node 可以無痛執行 TypeScript 腳本

終於不用一直手動壓縮惹。(。・ω・。)

---

---
url: /article-overview.md
description: 來找吧！我把所有的文章都放在這了！
---


---

---
url: /blog-ocean-world/meme-blur-detection.md
description: 如何用 Node.js 判斷梗圖是否模糊？從 Laplacian Variance 到分塊 P75，一路踩坑的演算法探索之旅
---

# 梗圖太糊怎麼辦？自動模糊偵測的踩坑之旅 %(・∀・)９%

大家好，我是鱈魚 🐟

最近分享快取梗圖強化搜尋功能時，發現有些圖片糊到不行，嚴重影響使用體驗。

問題是圖庫裡有近 900 張圖，總不能一張一張人工檢查吧？%(◞‸◟ )%

## 總結 🐟

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去 %(\*´∀\`)~♥%

有錯誤或不周全之處，還請多多指教 %( ´ ▽ \` )ﾉ%

---

---
url: /blog-program/what-is-property-based-testing.md
description: 測試案例都是自己想的，那沒想到的 bug 怎麼辦？讓機器幫你找吧 (ง •̀_•́)ง
---

![what-is-property-based-testing](/what-is-property-based-testing.webp){.cover}

# 測試案例都是自己想的，那沒想到的呢？(◜௰◝)

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

[上一篇](/blog-program/bdd-with-vitest-cucumber)聊流程測試，結尾提到使用者會怎麼操作系統，你永遠想不到，那又是另一個故事。

路人當時吐槽「是有多少故事」，今天就來講其中一個。%(σﾟ∀ﾟ)σ%

回想一下那筆退款比營業額還高的 bug。

單元測試、整合測試、突變測試全部綠燈，最後是有人想到「客服可能分三次退」，才靠流程測試抓到。

問題是想得到的才寫得出來。

bug 偏偏躲在沒想到的地方。%( ´•̥̥̥ ω •̥̥̥\` )%

有沒有辦法不列情境，只寫規則，剩下交給機器自己去找反例？

有喔，這就是 Property-Based Testing。%( •̀ ω •́ )✧%

這篇會先介紹它，再拿實驗數據一條一條質疑它，最後聊它跟突變測試怎麼搭配。

## 什麼是 Property-Based Testing

平常寫的測試叫做範例測試（Example-Based Testing），自己挑一組輸入、自己算好答案，再比對函式的輸出跟答案一不一樣。

```ts
it('100 元拆成 3 期', () => {
  expect(splitPayment(100, 3)).toEqual([33.34, 33.33, 33.33])
})
```

Property-Based Testing 反過來，不寫答案，只寫「不管輸入是什麼都要成立」的規則，工具會自己產生上百組輸入，想辦法打破這條規則。

```ts
import { fc, test } from '@fast-check/vitest'

// 金額用「分」產生再除以 100，保證最多兩位小數
const totalArbitrary = fc.integer({ min: 0, max: 10_000_000 }).map((cents) => cents / 100)
const countArbitrary = fc.integer({ min: 1, max: 36 })

test.prop([totalArbitrary, countArbitrary])('拆完加回去，不多一分也不少一分', (total, count) => {
  const centsList = splitPayment(total, count).map((value) => Math.round(value * 100))

  expect(centsList.reduce((sum, cents) => sum + cents, 0)).toBe(Math.round(total * 100))
})
```

property 在這裡指數學上的「性質」，例如加法的交換律，所以我習慣叫它**性質測試**，免得跟物件的屬性搞混。

| | 範例測試 | 性質測試 |
|---|---|---|
| 輸入 | 自己挑 | 工具產生，一輪上百組 |
| 期望 | 具體答案 | 一條規則 |
| 失敗時 | 告訴你哪組輸入錯了 | 縮小過的反例 |

這招來自 Haskell 的 QuickCheck，Koen Claessen 與 John Hughes 在 ICFP 2000 發表，十年後拿下這個會議的[最具影響力論文獎](https://sigplan.org/Awards/ICFP/)。

後來各語言都有自己的版本，Python 有 Hypothesis，Java 有 jqwik，JavaScript 與 TypeScript 則是 [fast-check](https://fast-check.dev/)。

## 把上次的退款 bug 丟給它

先安裝 fast-check，搭配 Vitest 的話再加上官方的整合套件。

```bash
npm install -D fast-check @fast-check/vitest
```

::: tip 還在用 Vitest 3？
`@fast-check/vitest` 0.4 之後要求 Vitest 4.1 以上，Vitest 3 請改裝 `@fast-check/vitest@0.3`。
:::

退款邏輯沿用上一篇的 `checkRefund` 與 `submitRefund`，只把金流呼叫拿掉。

測試只寫一條規則，不管客服怎麼退，累計退款都不能超過訂單金額。

```ts
import { fc, test } from '@fast-check/vitest'
import { expect } from 'vitest'
import { createOrder, getRefundedAmount, submitRefund } from './refund'

test.prop([
  fc.integer({ min: 1, max: 100_000 }), // 訂單金額
  fc.array(fc.integer({ min: 1, max: 100_000 })), // 客服依序申請的退款金額
])('不管客服怎麼退，累計退款都不會超過訂單金額', (total, amountList) => {
  const order = createOrder({ total })

  for (const amount of amountList) {
    submitRefund(order, amount)
  }

  expect(getRefundedAmount(order)).toBeLessThanOrEqual(order.total)
})
```

`fc.integer`、`fc.array` 這類產生器叫做 arbitrary，負責描述輸入的範圍。這裡的意思是一筆 1 到 10 萬元的訂單，加上一串 1 到 10 萬元的退款申請，筆數不限。

跑下去，紅了。

```text
Error: Property failed after 2 tests
{ seed: 614164776, path: "1:1:1:4:0:2:0:1:0:2:3:0:0:2:1:0:0:3:0:0:1:0:2:2:2:2:2:2:2:2:2:2:2:2:2:2:2:2:3", endOnFailure: true }
Counterexample: [23558,[1,23558]]
Shrunk 38 time(s)

Caused by: AssertionError: expected 23559 to be less than or equal to 23558
```

才試到第 2 組輸入就抓到了。%Σ(ˊДˋ;)%

`Counterexample` 翻成人話，一筆 23558 元的訂單，先退 1 元，再退 23558 元，總共退了 23559 元。

每一筆單獨檢查都沒超過訂單金額，加起來就超過了，跟上一篇分三次退 400 元是同一個 bug。

差別在於這次沒有人想到「分次退款」，我只寫了一條規則，情境由機器自己找出來。%( •̀ ω •́ )✧%

### 縮小反例

`Shrunk 38 time(s)` 代表它把反例縮小了 38 次。

fast-check 第一次遇到失敗時，輸入通常亂七八糟。換個 seed（亂數種子）跑，第一次失敗的輸入長這樣。

```text
[99987, [99993, 69478, 74257]]
```

訂單 99987 元，三筆退款申請裡，第一筆超過訂單金額沒有通過，後兩筆加起來才超過，要看懂還得先心算一輪。%(°c＿,°\`)%

找到失敗之後，fast-check 會一直嘗試把數字改小、把陣列改短，只要還是失敗就保留，最後縮成這樣。

```text
[74257, [1, 74257]]
```

這個過程叫做 shrinking。只看縮完的結果，一眼就知道問題出在「先退一點，再退全額」。

為了確認不是運氣好，我用 1000 個不同的 seed 各跑一輪，每輪照預設試 100 組輸入。

* 1000 輪全部抓到
* 中位數試到第 3 組就失敗，最慢的一輪試到第 21 組
* 995 輪縮成「先退 1 元，再退全額」，另外 5 輪縮成「先退全額，再退 1 元」

不過縮小一次只動一個參數，所以停在 `[74257, [1, 74257]]`。最理想的反例是「1 元的訂單退兩次 1 元」，得同時縮小訂單金額與退款金額，它就到不了。%(´・ω・\`)%

## 規則比情境好列

「訂單 1000 元，分三次退 400 元，第三次要拒絕」，情境是分三次退，答案是第三次拒絕，換成規則一句就寫完。

一條規則背後可能有上百種情境。規則的數量少很多，也比較不會隨著需求變動。%(ゝ∀・)b%

路人：「說得那麼好聽，還不是丟亂數進去？%(´・ω・\`)%」

鱈魚：「好問題，接下來就一條一條質疑它。%(ง •̀\_•́)ง%」

## 質疑一：這不就是亂數測試嗎？

跟自己寫個迴圈跑 `Math.random()` 比，差在三件事，而且都量得出來。

### 產生器會偏心

`fc.integer()` 預設的範圍是 -2147483648 到 2147483647，大約 43 億個整數。

我照實際跑測試的設定，用 1000 個 seed 各跑 100 次，收集 10 萬個 `fc.integer()` 產生的值來數。

| 產生的值 | fast-check 實際出現率 | 均勻亂數 |
|---|---|---|
| 剛好是 0 | 0.38% | 43 億分之 1 |
| 絕對值不超過 10 | 7.85% | 約 2 億分之 1 |
| 絕對值不超過 1000 | 23.08% | 約 215 萬分之 1 |
| 離最大值或最小值 10 以內 | 4.05% | 約 2 億分之 1 |

fast-check 刻意偏向 0、小數字與範圍兩端，bug 最常躲在這幾區。%(≖‿ゝ≖)✧%

### 會自己縮小反例

自己寫的亂數迴圈只會丟給你一坨數字，剩下自己想辦法。

### 失敗可以重播

把錯誤訊息裡的 `seed` 與 `path` 填回測試的參數，就能直接重現同一個反例。

```ts
test.prop([
  fc.integer({ min: 1, max: 100_000 }),
  fc.array(fc.integer({ min: 1, max: 100_000 })),
], {
  seed: 614164776,
  path: '1:1:1:4:0:2:0:1:0:2:3:0:0:2:1:0:0:3:0:0:1:0:2:2:2:2:2:2:2:2:2:2:2:2:2:2:2:2:3',
  endOnFailure: true,
})('重播上次失敗的輸入', (total, amountList) => {
  // ...同上
})
```

實際跑一次，第 1 組輸入就失敗，縮小 0 次，反例一樣是 `[23558,[1,23558]]`。

修好之後，可以把反例放進 `examples`，之後每一輪都會先跑它，再跑隨機輸入。

```ts
test.prop([
  fc.integer({ min: 1, max: 100_000 }),
  fc.array(fc.integer({ min: 1, max: 100_000 })),
], {
  examples: [[23558, [1, 23558]]],
})('不管客服怎麼退，累計退款都不會超過訂單金額', (total, amountList) => {
  // ...同上
})
```

這樣修好的 bug 就不會在哪天悄悄回來。%(ゝ∀・)b%

## 質疑二：輸入每次都不一樣，會不會今天綠明天紅？

會。%(´・ω・\`)%

偏心歸偏心，產生器並沒有保證一定會試到哪個值。

我寫了幾個只在特定條件出錯的假 bug，一樣用 1000 個 seed 各跑一輪，統計每一輪抓到的機率。

| bug 在什麼時候出現 | 一輪抓到的機率 |
|---|---|
| `x` 剛好是 0 | 31.3% |
| `x` 剛好是最大值 2147483647 | 17.8% |
| `x` 剛好是 123456 | 0% |
| 兩個整數剛好相等 | 10.9% |
| 陣列裡有重複的值 | 33.4% |
| `x` 小於等於 0 | 100% |

大家都說性質測試會自動測邊界值，可是只在 0 出錯的 bug，每三輪 CI 只有一輪抓得到。%(°ㅂ°)%

反過來，只要 bug 涵蓋一整段範圍，例如「小於等於 0 就出錯」，幾乎第一輪就會現形。

範圍訂得窄一點，情況會好很多。

| 寫法 | 抓到「剛好是 0」的機率 |
|---|---|
| `fc.integer()` | 31.3% |
| `fc.nat()`，只產生非負整數 | 54.0% |
| `fc.integer({ min: 0, max: 1000 })` | 91.5% |
| `fc.integer()` 跑 1000 次 | 94.3% |

範圍越貼近真實的資料，越容易抽中邊界值，所以寫產生器不要偷懶，訂單金額就寫訂單金額的範圍。

### 預設值的盲區

| bug 在什麼時候出現 | 一輪抓到的機率 |
|---|---|
| 陣列超過 10 個元素 | 0% |
| 字串含逗號，預設 `fc.string()` | 97.9% |
| 字串含 emoji，預設 `fc.string()` | 0% |
| 字串含 emoji，`unit: 'grapheme'` | 100% |
| 字串含中文，`unit: 'grapheme'` | 2.7% |
| 字串含中文，`unit: 'binary'` | 100% |

fast-check 預設產生的陣列與字串最長 10 個，預設的 `fc.string()` 只有可列印的 ASCII 字元。

`maxLength` 最容易讓人誤會。寫了 `fc.array(fc.integer(), { maxLength: 50 })`，產生的陣列照樣最長 10 個，因為長度還受 `size` 控制，要加上 `size: 'max'` 才會用到 50。不設 `maxLength` 的話，改成 `size: 'medium'` 最長可到 100。

所以分頁這種「超過 20 筆才出錯」的 bug，用預設值跑到天荒地老也抓不到。

字串也一樣，要測 emoji 得指定 `unit`，偏偏 `'grapheme'` 很少產生中文，`'binary'` 則幾乎不產生逗號、反斜線這類符號。要穩就用 `fc.constantFrom` 列出想測的字元，再跟一般的字串產生器混在一起。%(◞‸◟ )%

**產生器產不出來的輸入，性質測試永遠測不到**。它省下你想情境的力氣，輸入長什麼樣子還是得自己想。

### 那到底算不算 flaky？

一般說的 flaky test，指程式沒問題、測試卻亂紅，例如時間差、網路不穩。

性質測試的紅燈不一樣，每一次紅都附上一組真實的反例，重播就能重現，代表程式真的有 bug，只是這一輪才碰到。

CI 可以固定 seed 求穩定，代價是永遠只測同樣那 100 組輸入。我比較喜歡讓 seed 隨機，多跑一次就多探索一點。

## 質疑三：規則要怎麼想？比寫範例還難吧？

老實說，比較難。%(´ー\`)%

Harrison Goldstein 等人在 ICSE 2024 發表的[〈Property-Based Testing in Practice〉](https://harrisongoldste.in/papers/icse24-pbt-in-practice.pdf)，訪談了 Jane Street 的 31 位工程師。30 場訪談裡有 16 場提到寫規格拖慢了進度，有位受訪者講得很直接，最常見的失敗是根本不知道要測什麼性質。

好在前人整理過套路。Scott Wlaschin 在 2014 年寫的[〈Choosing properties for property-based testing〉](https://fsharpforfunandprofit.com/posts/property-based-testing-2/)列了七種，我挑六種，全部套在實驗會用到的函式上。

| 套路 | 意思 | 範例 |
|---|---|---|
| 來回轉換 | 轉換一次再反過來轉換一次，要回到原點 | 標籤編碼再解碼，拿回同一份清單 |
| 不變量 | 轉換前後有東西不會變 | 金額拆完加回去，不多一分也不少一分 |
| 冪等 | 執行兩次跟執行一次一樣 | 合併過的時段再合併一次，結果不變 |
| 殊途同歸 | 換個順序執行，結果一樣 | 時段輸入順序顛倒，合併結果一樣 |
| 對照組 | 拿笨但一定對的方法比對 | 一分鐘一分鐘數，合併前後涵蓋的時間一樣 |
| 難算易驗 | 答案難算，驗證卻很簡單 | 合併結果照順序排好，段與段之間有空檔 |

來回轉換最好寫，核心只有一行。

```ts
test.prop([fc.array(fc.string({ minLength: 1 }))])('編碼再解碼，要拿回一模一樣的清單', (tagList) => {
  expect(decodeTagList(encodeTagList(tagList))).toEqual(tagList)
})
```

對照組則是把「怎麼算」換成「怎麼驗」。合併時段的演算法要排序、要判斷包含與相接，驗證卻只要把每一分鐘數出來。

```ts
const timeRangeArbitrary = fc
  .tuple(fc.integer({ min: 0, max: 1440 }), fc.integer({ min: 1, max: 180 }))
  .map(([start, duration]): TimeRange => [start, start + duration])

function toMinuteSet(rangeList: TimeRange[]) {
  const minuteSet = new Set<number>()
  for (const [start, end] of rangeList) {
    for (let minute = start; minute < end; minute++) {
      minuteSet.add(minute)
    }
  }
  return minuteSet
}

test.prop([fc.array(timeRangeArbitrary)])('合併前後涵蓋的分鐘一模一樣', (rangeList) => {
  expect(toMinuteSet(mergeTimeRanges(rangeList))).toEqual(toMinuteSet(rangeList))
})
```

笨方法慢歸慢，笨到不可能寫錯，拿來當標準答案剛剛好。%(ゝ∀・)b%

Goldstein 的訪談也發現，業界最常用這種跟另一份實作比對的性質，30 場訪談裡有 17 場提到，例如拿舊版系統當對照組，驗證重寫的新版。

### 別把實作抄一遍

新手很容易把實作再寫一次，拿來當期望值。

```ts
// 別這樣寫
test.prop([totalArbitrary, countArbitrary])('跟實作算的一樣', (total, count) => {
  const totalCents = Math.round(total * 100)
  const baseCents = Math.floor(totalCents / count)
  const remainderCents = totalCents % count
  const expectedList = Array.from({ length: count }, (_, index) =>
    (index < remainderCents ? baseCents + 1 : baseCents) / 100)

  expect(splitPayment(total, count)).toEqual(expectedList)
})
```

實作怎麼錯，測試就跟著怎麼錯，這條測試永遠都會過。%(´\_ゝ\`)%

## 質疑四：AI 一秒寫一百條範例，還需要性質測試嗎？

路人：「現在叫 AI 寫測試，邊界值它比我還會想，範例一口氣生一百條，性質測試還有必要嗎？%(´・ω・\`)%」

鱈魚：「我也不知道，所以來做個實驗。%( •̀ ω •́ )✧%」

### 實驗設計

準備四支常見的商業邏輯函式，每支都附 JSDoc 規格與正確實作。

| 函式 | 規格重點 |
|---|---|
| `splitPayment` | 金額拆成多筆，加總不差一分，任兩筆相差不超過 0.01，大的排前面 |
| `truncateText` | 以 Unicode code point 計算字數，emoji 也算一個字，超過就截斷並接上「…」 |
| `mergeTimeRanges` | 合併重疊或相接的時段，不可修改傳入的陣列 |
| `encodeTagList`、`decodeTagList` | 標籤清單與逗號分隔字串互轉，必須完整還原 |

接著請另一個 AI 扮演「之後來改程式的人」，替每支函式寫 4 個常見的錯誤版本，共 16 個。每個錯誤版本都通過 JSDoc 裡的範例，例如：

* 轉換成「分」時把 `Math.round` 寫成 `Math.floor`，`19.99 * 100` 會變成 `1998.9999999999998`，平白少一分
* 用 `.length` 與 `.slice()` 算字數，會把 emoji 切成一半
* 合併時段時忘了取 `Math.max`，包在前一段裡面的時段會把範圍縮小
* 跳脫字元只跳脫逗號，忘了先跳脫反斜線本身

這 16 個版本在任何測試寫出來之前就定案，寫測試的 AI 看不到。

受試者是 6 個各自獨立的 Claude Sonnet 5，3 個只准寫範例測試（E 組），3 個只准寫性質測試（P 組），除了這條限制以外，指示一字不差。它們看得到規格與正確實作，測試必須在正確實作上全綠。

最後比三件事：

* **擋下幾個錯誤版本**：把錯誤版本換進去跑，至少一條測試失敗就算擋下。性質測試每次輸入不同，所以每個版本跑 20 次取平均
* **突變分數**：Stryker 在正確實作上的分數
* **成本**：測試數量與執行時間

開跑前我先把預測寫下來，其中一條是「P 組擋下的錯誤版本比較多」，信心六成。

### 結果：平手

| | E1 | E2 | E3 | P1 | P2 | P3 |
|---|---|---|---|---|---|---|
| 測試數 | 52 | 57 | 51 | 15 | 19 | 16 |
| 擋下的錯誤版本（共 16 個） | 14 | 15 | 15 | 15.95 | 11.2 | 15.95 |
| 突變分數 | 100% | 98.7% | 100% | 98.7% | 87.3% | 98.7% |

15.95 代表 16 個版本裡有 15 個每次都擋下，剩下那個 20 次擋下 19 次。

E 組平均擋下 14.67 個，P 組 14.37 個。照事先訂的門檻，差距不超過 1 個版本就算量不出差別，我賭的「P 組擋下比較多」不成立。%(´;ω;\`)%

AI 寫的範例測試比我想像的強很多。emoji 切一半、時段互相包含、跳脫字元這些經典邊界，三位 E 組受試者全部都有測。

### 漏掉的地方幾乎不重疊

| 錯誤版本 | 誰漏掉 |
|---|---|
| `splitPayment`：`Math.round` 寫成 `Math.floor` | E1、E2 全漏；P1、P3 二十次各漏一次 |
| `splitPayment`：餘數平均散開，破壞「大的排前面」 | E1、E3 |
| 標籤：四個跟跳脫有關的錯誤 | P2 全漏 |
| 時段：相接判斷用 `<` 取代 `<=` | P2 二十次只抓到四次 |

**範例測試漏掉的錯，全都要剛好挑中某些值才會出現。**

`Math.floor` 那個版本，大約 6.56% 的兩位小數金額會出錯，0.29、0.57、1.13、19.99 都會，而且看不出規律。範例測試多半挑 100、0.01、1999.99 這種漂亮的數字，一個都沒踩中。

E1 特地寫了一條測試防浮點數誤差，註解寫著 `29.99 * 100 !== 2999`，可是在 JavaScript 裡 `29.99 * 100` 剛好等於 2999，這條測試完全擋不下 `Math.floor` 那個版本。%(╯°Д°)╯︵ ┻━┻%

E3 抓到了，也是誤打誤撞。它刻意用 `0.3 / 3` 那條防浮點數誤差，偏偏擋不住，最後靠另一條拿 19.99 測「餘數給第一筆」的案例擋下來。

性質測試一輪試 100 個隨機金額，照機率算幾乎一定會踩到。

**性質測試的漏網之魚，幾乎全來自 P2，問題都出在產生器。**

P2 的測試看起來最用心。它在註解說，字串用 `unit: 'binary'` 涵蓋完整 Unicode，逗號、反斜線這類需要跳脫的字元也會驗到；時段起點則用 `fc.integer()` 開到正負 21 億，驗證大數值與負數。

結果這兩個決定都弄巧成拙。

`unit: 'binary'` 從一百多萬個 code point 裡抽字元。我實際產生 10 萬個字串，找不到任何反斜線，含逗號的也只有 1 個；預設只產生 ASCII 的 `fc.string()`，反而各有約 5%。P2 的標籤清單產生器，一輪 100 次裡出現反斜線的機率只有 0.3%，四個跟跳脫有關的錯誤版本當然全漏。

時段也一樣。兩段剛好首尾相接的機率趨近於零。我把 P2 那條「段與段之間要有空檔」的性質單獨拿出來，只換範圍，各跑 1000 輪：

| 起點範圍 | 抓到相接錯誤的機率 |
|---|---|
| P2 的寫法，正負 21 億 | 6.7% |
| 一天的分鐘數，0 到 1440 | 76.5% |
| 0 到 30 | 100% |

P1 與 P3 剛好相反，兩個都刻意提高逗號與反斜線的出現機率，時段範圍也只有幾十到一百多分鐘，所以都接近滿分。

**範圍開越大，特定的值越稀有**，看起來涵蓋更多，實際上測到的更少。%(╬☉д⊙)%

### 各配一份就幾乎全抓

既然漏的地方幾乎不重疊，把 E1 配 P1、E2 配 P2、E3 配 P3，統計兩份測試加起來擋下幾個。

| 組合 | 擋下的錯誤版本（共 16 個） |
|---|---|
| E1 加 P1 | 15.95 |
| E2 加 P2 | 16 |
| E3 加 P3 | 16 |

最弱的 P2 配上 E2，一樣拿到滿分。範例測試負責經典邊界，性質測試負責那些要剛好挑中的值。

### 成本

| | E 組 | P 組 |
|---|---|---|
| 測試程式碼（非空白行） | 239 到 352 | 157 到 245 |
| 跑一次 `vitest run`（10 次中位數） | 0.67 到 0.69 秒 | 1.5 到 2.9 秒 |
| 其中純測試時間 | 19 到 23 毫秒 | 0.53 到 1.7 秒 |
| 跑一輪 Stryker | 約 9 秒 | 54 到 75 秒 |

性質測試的時間多半花在 `splitPayment`，P 組把筆數開到 500 或 1000，每條性質都要把金額拆成上百筆、重複 100 次。

另外，三位 P 組受試者寫出的 `splitPayment` 性質幾乎一模一樣，就是把 JSDoc 的五條規格逐條翻成五條性質。規格寫成條列時，性質測試幾乎可以照抄。%(´,,•ω•,,)%

### 讀結論前先打折

這個實驗有幾個地方要先講清楚。%(´・ω・\`)%

* **樣本很小。** 4 支函式、16 個錯誤版本、每組 3 位受試者，差一兩個版本就會改變結論。
* **錯誤版本由 AI 產生。** 類型偏向 AI 想得到的錯，真實專案的 bug 可能更刁鑽。
* **受試者看得到正確實作。** 寫範例測試時可以直接執行實作拿期望值，E1 與 E2 都這樣做過。
* **受試者都是 Claude Sonnet 5。** 換模型或換人寫，結果可能不同。
* **P3 自己驗證過。** 它寫了四個故意改壞的版本檢查自己的測試，類型跟實驗的錯誤版本有部分重疊，這在指示允許的範圍內，但可能讓 P3 的成績偏高。

完整的設計、預測、每個錯誤版本的程式碼差異與原始數據，都在[實驗報告](https://github.com/Codfisher/cod-aquarium/blob/main/docs/property-based-testing-experiment.md)。

## 突變測試與性質測試差在哪

看過[突變測試](/blog-program/what-is-mutation-testing-and-stryker)那篇的朋友，可能會覺得兩個很像，都是讓工具自動產生一大堆東西來測程式。

兩者改動的對象剛好相反。%(ゝ∀・)b%

| | 突變測試 | 性質測試 |
|---|---|---|
| 自動產生什麼 | 改壞的程式碼，也就是突變體 | 輸入資料 |
| 回答的問題 | 測試夠不夠嚴 | 程式在沒想到的輸入下對不對 |
| 產出 | 突變分數、存活的突變體 | 縮小過的反例 |
| 身分 | 替測試打分數的工具 | 一種寫測試的方法 |
| 人要想什麼 | 幾乎不用想 | 規則與輸入範圍 |
| 貴在哪 | 突變體數量乘上整套測試的時間 | 每條性質跑上百次 |

兩者不在同一層，所以可以一起用。

### 突變分數 100%，照樣漏掉 bug

回到實驗。E1 的範例測試在 Stryker 拿到 100%，79 個突變體全數擊殺，可是 16 個錯誤版本它漏了 2 個。

打開 Stryker 替 `splitPayment` 產生的 12 個突變體，沒有一個會把 `Math.round` 換成 `Math.floor`。它只會用固定的招式改程式，例如 `*` 換成 `/`、`<` 換成 `<=`、整段清空，招式表裡沒有的錯，分數再高也沒驗到。

E1 另外漏掉「把餘數平均散開」這個版本。這種錯等於換掉了整套演算法，跟[上一篇](/blog-program/bdd-with-vitest-cucumber)說的「少寫的那一行」一樣，都不在突變測試產生得出來的範圍裡。

性質測試只檢查結果有沒有符合規則，改一個符號或整支重寫都一樣。

### 存活的突變體，剛好指出產生器的盲點

反過來看 P2，突變分數 87.3%，六位受試者裡最低，10 個存活的突變體分布如下：

* 9 個在 `tag-list` 的跳脫邏輯
* 1 個在 `mergeTimeRanges` 的相接判斷，把 `<=` 改成 `<`，跟其中一個錯誤版本一模一樣

這正好是 P2 的兩個盲點。它如果寫完測試順手跑一次 Stryker，就會看到跳脫邏輯那幾行全都沒驗到，回頭檢查產生器，發現 `unit: 'binary'` 幾乎不會產生反斜線。

**突變測試幫你檢查性質寫得夠不夠嚴、產生器夠不夠廣；性質測試幫你拿沒想到的輸入檢驗規則。** 兩個剛好各補對方一塊。%( •̀ ω •́ )✧%

## 兩者怎麼配合

### 先避開兩個坑

我第一次拿 Stryker 跑性質測試，分數是 0%。%((((；ﾟДﾟ)))%

測試檔只有兩條 `test.prop`，一條檢查加總，一條檢查相差不超過 0.01。Stryker 產生 12 個突變體，連「整個函式清空」這種必死的突變體都活了下來。

追下去發現是兩個獨立的坑。

**坑一：seed 寫在測試名稱裡。** `@fast-check/vitest` 會把這一輪用的 seed 接在測試名稱後面，沒指定 seed 的話，每次都是新的亂數。

```text
✓ 加總剛好等於總額 (with seed=442508060)
```

Stryker 會先完整跑一次測試，記下每條測試的名稱與它涵蓋的突變體。之後測每個突變體時，它把記下的名稱組成 Vitest 的 `testNamePattern`，只跑相關的測試。

問題是每跑一次，seed 就重抽一次，名稱跟著變，舊名稱一條測試都對不上。Vitest 一條測試都沒跑，沒有失敗，突變體就算存活。報告裡的 `Tests ran` 還會列出那兩條測試，看起來就像真的跑過。

**坑二：Vitest 5 換了名稱的串接符號。** Vitest 5 比對 `testNamePattern` 時，會把 `describe` 與測試名稱用 `>` 串起來，Stryker 10.0.0 還在用空白串接，只要測試包在 `describe` 裡就對不上。這個問題已經有人回報（[stryker-js #6210](https://github.com/stryker-mutator/stryker-js/issues/6210)），修正的 PR 還沒合併。

這個坑跟性質測試無關，純範例測試一樣中招。

我在 Vitest 4.1.11 與 5.0.1 各跑一輪，同一支 `splitPayment`、同樣 12 個突變體。

| 寫法 | Vitest 4.1.11 | Vitest 5.0.1 |
|---|---|---|
| `test.prop`，seed 隨機 | 0% | 0% |
| `test.prop`，固定 seed | 100% | 100% |
| 原生 `it` 包 `fc.assert` | 100% | 100% |
| 名稱固定，但包在 `describe` 裡 | 100% | 0% |

要避開坑一，就替 Stryker 另外準備一份 Vitest 設定，在 setup 檔固定 seed，平常跑測試時 seed 照樣隨機。

```ts
// vitest.stryker.setup.ts
import { fc } from '@fast-check/vitest'

fc.configureGlobal({ seed: 20260924 })
```

接著讓 Stryker 專用的 Vitest 設定載入這支 setup 檔。

```ts
// vitest.stryker.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    include: ['test/**/*.test.ts'],
    setupFiles: ['./vitest.stryker.setup.ts'],
  },
})
```

最後在 Stryker 的設定裡指定這份 Vitest 設定。

```json
// stryker.config.json
{
  "testRunner": "vitest",
  "vitest": { "configFile": "vitest.stryker.config.ts" }
}
```

或者乾脆不用 `test.prop`，改用原生的 `it` 包 `fc.assert`，名稱就固定了。

```ts
import fc from 'fast-check'
import { expect, it } from 'vitest'

it('拆完加回去，不多一分也不少一分', () => {
  fc.assert(fc.property(totalArbitrary, countArbitrary, (total, count) => {
    // ...同前
  }))
})
```

坑二目前只能等 Stryker 修正，或是先留在 Vitest 4。實驗裡的突變分數，就是在 Vitest 4.1.11 加上固定 seed 跑出來的。

兩個坑最麻煩的地方在於踩到了也不會報錯。只要專案裡還有其他測試殺得死那些突變體，分數看起來就很合理，很難察覺有一批測試根本沒跑。

看到分數異常低，或是整輪突變測試跑得異常快，先懷疑工具，再懷疑自己。

### 配合的流程

1. **先寫性質。** 規格裡的條列，大多可以直接翻成性質
2. **產生器貼近真實資料，再刻意提高特殊值的出現機率。** 例如時段用一天的分鐘數，標籤刻意多放逗號與反斜線
3. **用固定 seed 跑 Stryker。** 存活的突變體會告訴你哪條規則太鬆、哪個產生器太窄
4. **關鍵案例寫成範例測試。** 規格裡的範例、踩過的反例、經典邊界，用範例測試釘住，讀的人也最好懂

至於成本，性質測試會讓 Stryker 變慢，因為每個突變體都要把性質重跑上百次。實驗裡慢了六到八倍。跟突變測試那篇的建議一樣，只有核心邏輯值得兩種一起上。

## 別人的研究怎麼說

我的實驗規模很小，所以回頭找了幾篇論文對照。%(´・ω・\`)%

**工業界的戰績。** QuickCheck 作者 John Hughes 在 2016 年的[〈Experiences with QuickCheck〉](http://publications.lib.chalmers.se/records/fulltext/232550/local_232550.pdf)整理了幾個案例。替 Volvo 測汽車軟體標準 AUTOSAR 時，他們讀了約 3000 頁規格，寫成 2 萬行的 QuickCheck 模型，測了 6 家供應商共 100 萬行 C 程式碼，找出 200 多個問題，其中超過 100 個是標準本身的模糊或矛盾。

另一個案例是 Klarna 的資料庫，每兩個月就壞一次，工程師花了六週都找不到原因。QuickCheck 測了大約 10 分鐘就抓到，最後發現只要一筆資料加上五、六次 API 呼叫就能重現。

**業界怎麼用。** 前面提過的 Goldstein 等人訪談 Jane Street，有位受訪者說，抽象很清楚、實作卻很複雜時，性質測試最有用。

**一條性質測試抵幾條範例？** Savitha Ravi 與 Michael Coblenz 在 OOPSLA 2025 發表的[〈An Empirical Evaluation of Property-Based Testing in Python〉](https://cseweb.ucsd.edu/~mcoblenz/assets/pdf/OOPSLA_2025_PBT.pdf)，分析了 426 個使用 Hypothesis 的專案，並對其中 40 個跑突變測試，結論是平均每條性質測試抓到的突變，約是一般單元測試的 50 倍。

這個數字要打折看。一條性質測試本來就會跑上百組輸入，逐條比較先天佔便宜；作者自己也說這是相關性研究，關聯偏弱。而且這些專案裡 98.4% 的測試仍是單元測試。

同一篇還發現，55% 的突變只要一組輸入就抓到，76% 在前 20 組之內。這跟我的實驗對得上，預設 100 次大多夠用，會漏掉通常是因為產生器很少產出那種輸入。

**讓 AI 寫性質測試。** Muhammad Maaz、Nicholas Carlini 等人在 2025 年的[〈Agentic Property-Based Testing〉](https://arxiv.org/abs/2510.09907)（作者多半來自 Anthropic）讓 Claude Code 自己替 100 個熱門 Python 套件寫性質測試，一共產出 984 份 bug 報告。人工抽查之後，56% 確實是 bug，32% 值得回報給維護者，每抓到一個有效 bug 的成本不到 10 美元。其中一個是 NumPy 的 Wald 分布會回傳負數，修正已經合併。

2026 年的 [PBT-Bench](https://arxiv.org/abs/2605.15229) 則專門出難題，植入的 bug 刻意設計成預設產生器幾乎碰不到。AI 得先讀文件找出規則，再寫出能把輸入集中到觸發範圍的產生器，表現最好的模型也只抓到 83.4%。P2 正好栽在這一點上。

| 我的發現 | 研究 | 對照 |
|---|---|---|
| 性質測試能自己找出沒想到的情境 | Klarna 的資料庫 bug | 一致 |
| 規則寫得出來才用得上 | Jane Street 訪談 | 一致 |
| 性質測試沒有擋下比較多 | Ravi 與 Coblenz 的 50 倍 | 比較單位不同 |

Ravi 與 Coblenz 逐條比，一條性質抵很多條範例；我拿整套測試比，E 組用 50 幾條範例，擋下的數量跟 P 組十幾條性質差不多。

## 總結 🐟

AI 一秒寫一百條範例，還需要性質測試嗎？需要，但別期待它單打獨鬥。%(´・ω・\`)%

* **性質測試只要你寫規則，情境交給機器找。** 上一篇靠人想到「分三次退」才抓到的 bug，一條規則加上 fast-check，1000 輪全部抓到，還自動縮成「先退 1 元，再退全額」。
* **它只是抽樣，邊界值也不一定抽得到。** 只在 0 出錯的 bug，每三輪只抓到一輪；紅燈都是真 bug，綠燈只代表這一輪的輸入沒出事。
* **產生器決定它測得到什麼。** 範圍要貼近真實資料，特殊值的出現機率要刻意提高。
* **跟 AI 寫的範例測試互補。** 兩組平均擋下的數量打平，漏掉的地方卻幾乎沒有重疊；範例測試會漏掉要剛好挑中的值，性質測試會漏掉產生器的盲區，各配一份幾乎全抓。
* **突變測試替性質測試健檢。** 突變分數 100% 的範例測試照樣漏掉浮點數錯誤，性質測試補得上；P2 存活的突變體剛好指出它的盲點。搭配時記得固定 seed，Vitest 5 則要等 Stryker 修正。

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。%( ´ ▽ \` )ﾉ%

---

---
url: /blog-program/what-is-mutation-testing-and-stryker.md
description: 測試覆蓋率蓋好蓋滿，卻還是有蟲蟲，有沒有一個更誠實的分數？
---

![what-is-mutation-testing-and-stryker](/what-is-mutation-testing-and-stryker.webp){.cover}

# 測試覆蓋了卻還是有蟲蟲？來點突變吧！

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

有沒有遇過 AI 洋洋灑灑寫了一卡車的測試，跑起來全部亮綠燈，覆蓋率甚至高達 100%，心滿意足地收工回家。

結果馬上就被 bug 炸飛了。%( ´•̥̥̥ ω •̥̥̥\` )%

覆蓋率只代表你的測試**有經過那幾行程式**，不代表那幾行**有被好好驗證**。

有沒有一種指標，能真正告訴我們「測試到底擋不擋得住 bug」？

有喔，這就是「突變測試」（Mutation Testing）。%(ﾉ>ω<)ﾉ%

## 什麼是突變測試

突變測試的主要目的是**測試你的測試**，聽起來很饒舌，其實概念很簡單。

其概念很壞壞，也很聰明。%(´,,•ω•,,)%

簡單來說就是故意把你的程式碼改壞，製造出一堆有 bug 的版本，這些被改壞的版本就叫做「突變體」（Mutant）。

改壞的方式五花八門，例如：

* 把 `>=` 改成 `>`
* 把 `+` 改成 `-`
* 把 `&&` 改成 `||`
* 直接把某行程式刪掉

接著拿你原本的測試，跑每一個突變體，有兩種結果：

* **突變體被殺死（Killed）**：測試失敗了，代表測試成功抓到這個被改壞的地方，這是好事。
* **突變體存活（Survived）**：測試竟然還是全綠，代表程式被改壞了測試卻沒發現，這就是漏洞。

最後它會把「被殺死的比例」算成一個「突變分數」（Mutation Score）：

```text
突變分數 = 被殺死的突變體 / 總突變體數量
```

覆蓋率回答的是「這行有沒有被跑過」，突變分數回答的是「這行如果寫錯了，你的測試攔不攔得住」。

後者才能看出測試是否全面。%(ゝ∀・)b%

## 來個案例吧

光講概念太無聊了，大家可能都跑光了。

甚麼？已經走了？別走啊，程式端上來了啊。%ლ（´口\`ლ）%

假設有個計算運費的函數，規則稍微複雜一點：

* 一般會員：滿 1000 免運，否則收 60 元
* VIP 門檻較低：滿 500 免運，否則收 30 元

`shipping.ts`

```ts
interface Order {
  amount: number;
  isVip: boolean;
}

export function getShippingFee(order: Order): number {
  const threshold = order.isVip ? 500 : 1000
  const base = order.isVip ? 30 : 60
  return order.amount >= threshold ? 0 : base
}
```

接著來點測試，一般會員與 VIP 各測「免運」跟「要付運費」兩種，這裡用 [Vitest](https://vitest.dev/) 示範：

`shipping.test.ts`

```ts
import { describe, expect, it } from 'vitest'
import { getShippingFee } from './shipping'

describe('getShippingFee', () => {
  it('一般會員金額足夠免運', () => {
    expect(getShippingFee({ amount: 1500, isVip: false })).toBe(0)
  })

  it('一般會員金額不足要收運費', () => {
    expect(getShippingFee({ amount: 800, isVip: false })).toBe(60)
  })

  it('VIP 門檻較低，同樣金額就免運', () => {
    expect(getShippingFee({ amount: 800, isVip: true })).toBe(0)
  })

  it('VIP 金額不足，收較低運費', () => {
    expect(getShippingFee({ amount: 300, isVip: true })).toBe(30)
  })
})
```

跑一下測試，全綠。覆蓋率 100%，完美，收工。%ᕕ( ᐛ )ᕗ%

一般會員、VIP、免運、要運費，四種組合全測過了，可以安心下班了吧？%ლ(╹ε╹ლ)%

## 讓 Stryker 上場踢館

再多綠燈也沒用，來點突變測試吧。

TypeScript 最有名的突變測試工具是 [Stryker](https://stryker-mutator.io/)。

名字取自漫威裡專門獵殺變種人的反派 Stryker，用來獵殺程式裡的突變體，這命名真的很會。%(´,,•ω•,,)%

因為我們用 Vitest，所以搭配 Vitest runner，先安裝套件：

```bash
npm install --save-dev @stryker-mutator/core @stryker-mutator/vitest-runner
```

接著加上設定檔：

`stryker.config.json`

```json
{
  "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
  "testRunner": "vitest",
  "mutate": ["src/**/*.ts", "!src/**/*.test.ts"]
}
```

然後執行：

```bash
npx stryker run
```

Stryker 會自動把程式改壞成一堆突變體，逐一丟給測試跑。%( •̀ ω •́ )✧%

```text
#1. [Survived] EqualityOperator
src/shipping.ts:9:10
- return order.amount >= threshold ? 0 : base
+ return order.amount > threshold ? 0 : base
```

結果出爐，竟然溜掉一隻突變體。%ლ(・´ｪ\`・ლ)%

Stryker 把 `>=` 改成 `>`，測試全都沒有發現。

這個改動只影響一種情況，就是金額「剛好等於門檻」的時候。原本剛好 1000 元的一般會員可以免運，改成 `>` 之後就要多付 60 元，這在電商可是會直接引爆客訴的 S 級重大 bug。%(;´༎ຶД༎ຶ\`)%

## 難道不是你太菜嗎？

路人：「本來就該測邊界啊，你確定不是你漏掉案例？%(´・ω・\`)%」

鱈魚：「是...是沒錯啦，只是程式碼一多、邏輯一複雜，很難確保每一個邊界都注意到嘛！%(;´༎ຶД༎ຶ\`)%」

路人：「剛剛的程式碼又不複雜...%ლ(╹ε╹ლ)%」

鱈魚：「不管啦，繼續。%ヽ(́◕◞౪◟◕‵)ﾉ%」

突變測試真正的價值，不是「挖出神秘的 bug」，而是底下這兩點：

1. **比覆蓋率更誠實的指標**：覆蓋率只回答「這行有沒有被跑過」；突變分數回答的是「這行如果寫錯了，測試攔不攔得住」。

2. **真正的價值是規模**：當專案裡有上千個判斷式或你接手一份看不懂的 legacy 測試時，根本沒辦法用肉眼一條一條確認。突變測試可以系統性地幫你把「漏掉的那幾條」標出來，讓你不必再賭自己的細心和運氣。

現在我們補上兩條門檻線：

```ts
it('一般會員剛好 1000 免運', () => {
  expect(getShippingFee({ amount: 1000, isVip: false })).toBe(0) // [!code ++]
})

it('VIP 剛好 500 免運', () => {
  expect(getShippingFee({ amount: 500, isVip: true })).toBe(0) // [!code ++]
})
```

再跑一次 Stryker，這隻突變體立刻被擊殺，突變分數也跟著補回來惹。

甚麼？你說殺突變體好麻煩？當然是叫 AI 殺啊！%ԅ(´∀\` ԅ)%

## 還有一種洞，斷言太鬆

剛剛那個洞是「**案例漏了**」，補一條測試就好。

但還有另一種更陰險的洞，案例明明有寫，卻等於沒寫。%( ˘•ω•˘ )%

回到開頭那個情境，AI 幫你生了一卡車測試。它很可能寫出這種東西：

```ts
it('一般會員金額不足要收運費', () => {
  expect(getShippingFee({ amount: 800, isVip: false })).toBeGreaterThan(0)
})
```

看起來很正常對吧？案例有了、跑得過、那行程式碼也確實被執行到，覆蓋率照樣 100%。%(・∀・)%

問題是 `toBeGreaterThan(0)` 根本沒在驗運費算得對不對，它只驗了「有收錢」。收 60 會過，收 30 會過，收 9999 也會過。%(°ㅂ°)%

這種斷言有正式名稱，叫做**寬鬆斷言**（overly general assertion），`toBeTruthy()`、`toBeDefined()`、`toBeInstanceOf(Object)` 都是常客，本身就被歸類為測試異味。

因為變數幾乎都有定義、物件幾乎都是物件，這種斷言等於什麼都沒驗。

而 Stryker 對這種洞特別敏感，因為它根本不需要你多寫什麼，直接動手改就對了。

```text
#2. [Survived] ConditionalExpression
src/shipping.ts:8:16
- const base = order.isVip ? 30 : 60
+ const base = true ? 30 : 60
```

它把運費強制改成 VIP 價 30 元，一般會員的運費從 60 變 30。

原本 `toBe(60)` 會當場翻臉，但 `toBeGreaterThan(0)` 看到 30 覺得很滿意，於是突變體大搖大擺地活了下來。%ლ(・´ｪ\`・ლ)%

這件事之所以重要，倒不是因為人看不出來。

`toBeGreaterThan(0)` 跟 `toBe(60)` 擺在一起，任誰都知道哪個比較鬆。

真正的問題是，**這種事根本不該由人來做**。%( ˘•ω•˘ )%

逐條檢查兩百行 diff 裡每個斷言有沒有驗到東西，是純粹的機械勞動，做完也不會變聰明，注意力倒是先燒光了。

而人的注意力很貴，應該留給機器做不到的事，例如這條商業規則本身對不對、有沒有漏掉什麼情境、這個設計三個月後會不會後悔。%( •̀ ω •́ )%

所以這跟前面講的「規模」是同一件事，**能自動化的就別交給人**。

斷言一放寬，突變體立刻復活，Stryker 不會累也不會分心，你就可以把腦袋留給真正需要思考的部分。%( •̀ ω •́ )✧%

路人：「所以斷言愈嚴愈好囉？%(｢･ω･)｢%」

鱈魚：「也不是，往另一邊歪一樣有事。%( ˘•ω•˘ )%」

把整個物件連 `createdAt` 時間戳一起 `toEqual` 下去，測試會因為完全無關的欄位變動一直壞掉，這在 xUnit Test Patterns 裡叫做 [Fragile Test](http://xunitpatterns.com/Fragile%20Test.html)。

判斷標準不是「愈嚴愈好」，而是**斷言有沒有正對著這條測試要驗的行為**。太寬驗不到東西，太窄綁到不相干的欄位，兩種都是沒對準。%( •̀ ω •́ )%

## 常見的 mutator 對照表

剛剛 Stryker 對 `getShippingFee` 動的那一刀（`>=` 改成 `>`），只是它眾多招式裡的其中一種。

它到底還會怎麼壞壞？這裡整理一張常見的 mutator 對照表，讓大家心裡有個概念：

| Mutator | 做什麼 | 範例（原始 → 變異） |
|---------|--------|---------------------|
| ArithmeticOperator | 算術運算子對調 | `a + b` → `a - b`、`a * b` → `a / b` |
| EqualityOperator | 比較運算子對調 | `a < b` → `a <= b`、`a === b` → `a !== b` |
| LogicalOperator | 邏輯運算子對調 | `a && b` → `a \|\| b` |
| BooleanLiteral | 布林值翻轉 | `true` → `false`、`!a` → `a` |
| ConditionalExpression | 條件式強制真假 | `if (a > b)` → `if (true)` 或 `if (false)` |
| StringLiteral | 字串內容抽換 | `'hi'` → `''` |
| UnaryOperator | 一元運算子翻轉 | `-a` → `+a` |
| UpdateOperator | 遞增遞減對調 | `a++` → `a--` |
| BlockStatement | 清空整個程式區塊 | `{ ... }` → `{}` |
| ArrayDeclaration | 清空陣列內容 | `[1, 2, 3]` → `[]` |
| OptionalChaining | 拿掉可選鏈 | `foo?.bar` → `foo.bar` |

完整清單可以參考 [Stryker 官方文件](https://stryker-mutator.io/docs/mutation-testing-elements/supported-mutators/)。%( •̀ ω •́ )✧%

## 突變一定要殺掉嗎？

前面一直說「存活的突變體代表漏洞」，但這句話其實有例外。

有些突變體根本**殺不死**，或者**殺了也沒意義**。%( ˘•ω•˘ )%

### 殺不死：等價突變體

先看一段把庫存正規化的函數，負數一律當作 0：

`normalize.ts`

```ts
export function normalizeStock(count: number): number {
  // 庫存不會是負數，負數一律當作 0
  if (count < 0) {
    return 0
  }
  return count
}
```

我們把正數、0、負數三種情況都測好測滿：

```ts
expect(normalizeStock(5)).toBe(5)
expect(normalizeStock(0)).toBe(0)
expect(normalizeStock(-3)).toBe(0)
```

看起來滴水不漏，但 Stryker 就是有辦法生出一隻殺不死的突變體：

```text
[Survived] EqualityOperator
src/normalize.ts:3:7
- if (count < 0) {
+ if (count <= 0) {
```

它把 `count < 0` 改成 `count <= 0`，唯一有差別的地方，是 `count` 剛好等於 0 的時候。

可是你仔細想想，`count` 是 0 時，原本走 `else` 回傳 `count`（也就是 0），改成 `<=` 之後走 `if` 回傳 `0`，兩邊算出來都是 0，結果一模一樣。%(・∀・)%

所以不管丟什麼進去，這兩種寫法的行為**完全相同**。

這種「改了程式碼卻沒改行為」的突變體，就叫做「等價突變體」（Equivalent Mutant）。

它本質上不是 bug，任何測試都不可能讓它失敗，你再怎麼補測試都殺不死它。

而且要判斷一隻突變體算不算等價突變體，工具也幫不了你。

以前判斷這個很麻煩，不過現在你可以叫 AI 看。%(´,,•ω•,,)%

### 殺得死，但不值得殺

另一種情況，是那些「殺得死，但殺了也沒意義」的突變體，最典型的就是 log 訊息：

```ts
export function checkout(order: Order): void {
  logger.info(`結帳開始，訂單編號 ${order.id}`) // Stryker 會把字串改成 ''
  // ...實際結帳邏輯
}
```

Stryker 會把那串 log 改成空字串，然後它就這麼活了下來，因為根本沒有測試在乎 log 印了什麼。

但你真的要為了殺它，特地寫一個「檢查 log 有沒有印出這串字」的測試嗎？

這種測試又脆弱又沒營養，~~就像上司強迫你寫精準到分的工作日誌~~

這種突變體放它一馬就好。%(ゝ∀・)b%

如果這些雜訊看了礙眼，Stryker 也能用 `// Stryker disable next-line all` 註解，或在設定檔排除特定 mutator，直接把它們消音。

所以看到存活突變體，先別急著補測試，先問自己兩個問題，這隻殺得死嗎？值得殺嗎？~~或是丟給 AI 殺。~~%( •̀ ω •́ )%

這也是為什麼突變分數不用硬追求 100%，和人生一樣，夠了就好。%(｢･ω･)｢%

## 有用歸有用，但是別用過頭

突變測試雖然強，但它有個明顯的缺點，就是慢到不行。

因為它要把程式改壞成幾十、幾百個突變體，每一個都得重跑一次測試，時間會指數級上升。

拿本文的範例實際量了一下（Node 22 + Vitest 3 + Stryker 9，11 條測試程序並行）：

| 規模 | 突變體數量 | 一般測試 | 突變測試 |
|------|-----------|---------|---------|
| 單一函數 | 5 | 約 1.8 秒 | 約 6～7 秒（首次冷啟動要 26 秒）|
| 五個函數 | 58 | 約 4.8 秒 | 約 28 秒 |

光是五個小函數，時間就從 5 秒膨脹到 28 秒，足足六倍，而且純突變執行階段會隨突變體數量幾乎線性成長。

真實專案動輒上萬個突變體，跑一輪從幾分鐘到幾小時都有可能。%(°ㅂ°)%

所以實務上通常不會拿它跟一般單元測試一樣，每次 commit 都跑全部。

比較常見的做法，是只針對核心邏輯、金流計算這類特別重要的模組使用，或是放在 CI 排程裡定期跑一次就好。

## 總結 🐟

* 覆蓋率只回答「這行被跑過沒」，不回答「這行寫錯了測試攔不攔得住」。
* **突變測試在測試你的測試**，故意把程式改壞，看測試抓不抓得到，最後給你一個比覆蓋率誠實的「突變分數」。
* 它抓得到兩種洞，**案例漏了**，還有**案例有寫但斷言太鬆**。後者不是看不出來，而是**這種機械檢查不該由人做**，人的注意力該留給「規則本身對不對」這種問題。
* JavaScript / TypeScript 可以用 **Stryker**，搭配 Vitest runner 幾乎無痛上手。
* 突變測試很吃效能，而且存活突變體不一定都要殺（**等價突變體**殺不死、log 訊息不值得殺），鎖定核心邏輯、放進 CI 排程，分數別強求 100%。

所以有突變測試後，系統就 100 分，蟲蟲絕跡，世界和平了嗎？

當然沒有，系統還是會有流程漏洞、規格外的 edge case 等等問題，那又是另一個故事啦。%乁( ◔ ௰◔)「% 。

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

---

---
url: /blog-program/bdd-with-vitest-cucumber.md
description: 單元、整合、突變測試全過，怎麼還是出包了？( ´•̥̥̥ ω •̥̥̥` )
---

![bdd-with-vitest-cucumber](/bdd-with-vitest-cucumber.webp){.cover}

# 測試都加了還是出包？是不是少了流程測試？

大家好，我是鱈魚。%( ´ ▽ \` )ﾉ%

上次聊完[突變測試](/blog-program/what-is-mutation-testing-and-stryker)，結尾說系統還是會有流程漏洞，那又是另一個故事。

今天就是那個故事。%(ﾉ>ω<)ﾉ%

某個平凡的早晨，你拿著早餐在電腦前準備開工。

結果 PM 回報：「這個月退款金額怎麼比營業額還高？」

馬上嚇得沒心情吃早餐了。%(;´༎ຶД༎ຶ\`)%

明明測試都寫好寫滿了，怎麼會這樣勒？%( ´•̥̥̥ ω •̥̥̥\` )%

## 先看看犯案現場

退款這件事，資料結構長這樣，`order.ts`

```ts
export interface Refund {
  amount: number;
  createdAt: string;
}

export interface Order {
  id: string;
  total: number;
  status: 'paid' | 'cancelled';
  /** 這筆訂單所有的退款紀錄 */
  refundList: Refund[];
}

export function getRefundedAmount(order: Order): number {
  return order.refundList.reduce((sum, item) => sum + item.amount, 0)
}
```

接著是退款檢查，`refund.ts`

```ts
export type RefundResult =
  | { accepted: true; amount: number }
  | { accepted: false; reason: 'ORDER_NOT_REFUNDABLE' | 'INVALID_AMOUNT' }

export function checkRefund(order: Order, amount: number): RefundResult {
  if (order.status !== 'paid') {
    return { accepted: false, reason: 'ORDER_NOT_REFUNDABLE' }
  }

  if (amount <= 0 || amount > order.total) {
    return { accepted: false, reason: 'INVALID_AMOUNT' }
  }

  return { accepted: true, amount }
}
```

最後是實際送出退款，`refund-service.ts`

```ts
export function submitRefund(order: Order, amount: number): RefundResult {
  const result = checkRefund(order, amount)
  if (!result.accepted) {
    return result
  }

  paymentGateway.refund(order.id, amount)
  order.refundList.push({ amount, createdAt: getNow() })

  return result
}
```

不到 30 行，邏輯清楚，命名整齊，看起來完全沒有嫌疑犯的樣子。%(・∀・)%

各位大大可以先停下來想三秒，猜猜看犯人是誰。%(´,,•ω•,,)%

## 第一關：單元測試

用 [Vitest](https://vitest.dev/) 把每個函數測好測滿，邊界一個都不放過。

`getRefundedAmount` 很單純，加總跟空陣列兩條就打發了，重點在 `checkRefund`。

```ts
// refund.test.ts
describe('checkRefund', () => {
  const order = createOrder({ total: 1000 })

  it('金額在範圍內就通過', () => {
    expect(checkRefund(order, 400)).toEqual({ accepted: true, amount: 400 })
  })

  it('剛好等於訂單金額也通過', () => {
    expect(checkRefund(order, 1000)).toEqual({ accepted: true, amount: 1000 })
  })

  it('超過訂單金額就擋下來', () => {
    expect(checkRefund(order, 1001)).toEqual({
      accepted: false,
      reason: 'INVALID_AMOUNT',
    })
  })

  it('金額是 0 也擋下來', () => {
    expect(checkRefund(order, 0)).toEqual({
      accepted: false,
      reason: 'INVALID_AMOUNT',
    })
  })

  it('已取消的訂單不能退款', () => {
    const cancelledOrder = createOrder({ total: 1000, status: 'cancelled' })

    expect(checkRefund(cancelledOrder, 400)).toEqual({
      accepted: false,
      reason: 'ORDER_NOT_REFUNDABLE',
    })
  })
})
```

上邊界、下邊界、狀態、剛好等於，全部顧到了。跑起來全綠，覆蓋率 100%。%ᕕ( ᐛ )ᕗ%

## 第二關：整合測試

單元測試只驗單一函數，接著驗模組串起來對不對，金流和資料寫入一起看。

```ts
// refund-service.test.ts
describe('submitRefund', () => {
  it('退款成功時，會呼叫金流並寫入退款紀錄', () => {
    const order = createOrder({ total: 1000 })
    const spy = vi.spyOn(paymentGateway, 'refund')

    const result = submitRefund(order, 400)

    expect(result.accepted).toBe(true)
    expect(spy).toHaveBeenCalledWith(order.id, 400)
    expect(order.refundList).toHaveLength(1)
    expect(getRefundedAmount(order)).toBe(400)
  })

  // 另一條測「檢查沒過時不呼叫金流、不留紀錄」，這裡先省略
})
```

模組確實串接正確，該呼叫的呼叫、該擋的擋、該記錄的記錄，也是全綠。%( •̀ ω •́ )✧%

## 第三關：突變測試

看過[上一篇](/blog-program/what-is-mutation-testing-and-stryker)的朋友一定會說，測試全綠不代表什麼，叫 [Stryker](https://stryker-mutator.io/) 出來踢館。

```bash
npx stryker run
```

Stryker 開始把程式改壞。`!==` 換成 `===`、`<=` 換成 `<`、`>` 換成 `>=`、`||` 換成 `&&`，能想到的壞事全做了一遍。

```text
Ran 9 tests, 9 passed
All found mutants have been killed 🎉
Mutation score: 100.00%
```

全部擊殺，突變分數 100 分。%(ﾉ>ω<)ﾉ%

覆蓋率 100%、突變分數 100%、單元測試綠、整合測試綠。

那筆 1200 元的退款到底怎麼變出來的勒？%ლ(・´ｪ\`・ლ)%

## 第四關：流程測試

前三關都在問「**這段程式碼寫對了嗎**」，現在換個問法，「**顧客實際走一遍會發生什麼事**」。

客服處理瑕疵品時，習慣分次退款，退一件算一件。

```ts
// refund-flow.test.ts
describe('退款流程', () => {
  it('累計退款金額不應該超過訂單金額', () => {
    const order = createOrder({ total: 1000 })

    submitRefund(order, 400)
    submitRefund(order, 400)
    submitRefund(order, 400)

    expect(getRefundedAmount(order)).toBeLessThanOrEqual(order.total)
  })
})
```

紅了。%(;´༎ຶД༎ຶ\`)%

```text
AssertionError: expected 1200 to be less than or equal to 1000
```

犯人抓到了。

`checkRefund` 從頭到尾只檢查「**這一次**的退款金額」有沒有超過訂單金額，完全沒看過之前退了多少。

每一次退 400 都合法，三次加起來就退了 1200 出去。%(°ㅂ°)%

## 為什麼前三關全都擋不住

路人：「所以突變測試和你一樣也是個廢物囉？%(｢･ω･)｢%」

鱈魚：「不能這麼說，它的作用不在此...等等你是不是說了啥？%( ˘•ω•˘ )%」

突變測試的做法是把**已經存在的程式碼**改壞，看測試會不會失敗。

而這個 bug 不在任何一行程式碼裡，而在**不存在的那一行**。

```ts
// 這行從來沒被寫出來，所以 Stryker 沒有東西可以改壞
if (amount > order.total - getRefundedAmount(order)) { /* ... */ }
```

換句話說，突變測試只會問「你寫的這行如果寫錯了，測試攔不攔得住」，永遠不會問「你是不是少寫了一行」。

這類錯誤有個正式名稱，叫做**遺漏型錯誤**（Omission Fault）。

Just 等人在 FSE 2014 的論文《[Are Mutants a Valid Substitute for Real Faults in Software Testing?](https://homes.cs.washington.edu/~rjust/publ/mutants_real_faults_fse_2014.pdf)》拿真實專案的 bug 對照突變體，只有 **73%** 對得上。剩下那 27% 裡，很大一塊就是這種「程式碼多了或少了」。

再往上看一層，三關失守的原因是同一個。

* **單元測試**問的是「這個函數照規格做了嗎」
* **整合測試**問的是「模組串起來還是照規格做嗎」
* **突變測試**問的是「規格裡的每個判斷，測試都驗到了嗎」

三個問題都很好，但共同前提只有一個，**假設規格沒問題**。

生動一點的比喻就是：

* 單元測試測試「積木是否符合模具的形狀」
* 整合測試確定「多個積木是否能正常組合」
* 突變測試是「故意拔掉其中一個積木，看看會不會解體」

結果沒有人告訴你，組出來的椅子造型積木真的要拿來坐，一坐就解體，摔了個狗吃屎。%( ;´༎ຶД༎ຶ )%

三方各自都很合理，湊在一起才出事。

* PM 想的退款是「顧客不要了，整筆退掉」，所以規格只寫「退款金額不得超過訂單金額」
* 工程師為了保留彈性，把金額做成參數，讓未來可以退部分
* 客服遇到三件商品壞一件，很自然就分次退，退一件算一件

三個人都在做對的事，但從頭到尾**沒人想到「分次退款」該怎麼算**。%ლ（´口\`ლ）%

## 那就多寫流程測試？

既然只有第四關擋得住，答案好像很明顯。

問題是流程測試難寫，而且難的地方跟其他三關完全不同。%( ˘•ω•˘ )%

路人：「難在哪？剛剛那條不是三行就寫完了嗎？%(・∀・)%」

鱈魚：「難在兩件事，怎麼知道**要寫哪幾條**，還有寫完之後那條規則**怎麼不蒸發**。%(´・ω・\`)%」

### 難處一：要寫甚麼？

前三關其實都有機械式的對應關係。

* **單元測試**看函數，有幾個參數幾條分支，就配幾條
* **整合測試**看串接路徑，一條路徑配一條
* **突變測試**根本不用你想，工具自己算

流程測試沒有這種對應，你沒辦法說「一個 service 配三條流程測試」，因為它的單位不是程式碼，是**商業規則**。%( ˘•ω•˘ )%

而商業規則不會自己從程式碼裡長出來，得有人挖。

路人：「釐清商業規則不是 PM 的事嗎？%(´・ω・\`)%」

鱈魚：「是沒錯，但**工程師實作時會遇到的細節比 PM 多很多，這很正常**。%( ˘•ω•˘ )%」

需求會議通常這樣結束，主持人問一句「大家還有問題嗎」，沒人說話，散會。%(´\_ゝ\`)%

問題是沒想到的事情不會舉手，而規格的洞往往不是在會議室裡發現，是在**寫程式的時候**。

因為只有工程師有辦法逐行逼近實作細節，PM 想的是「顧客要退款」，你想的是「`amount` 這個參數要不要限制範圍」。%(°ㅂ°)%

別怕煩到 PM，該問就多問吧，記得把問題有條理地整理好再問。%( •̀ ω •́ )✧%

甚麼？你說 PM 回不知道要你自己決定...%('◉◞⊖◟◉\` )%

至於怎麼讓這種對話變得有結構，BDD 圈有現成的做法，例如 Matt Wynne 的 [Example Mapping](https://cucumber.io/docs/bdd/example-mapping/)，把規則和沒答案的疑問寫成不同顏色的卡片，桌上還有紅卡就代表這個 story 還不能開工。有興趣可以去看看。%(´,,•ω•,,)%

### 難處二：規則寫完就蒸發

假設運氣好，那句話真的被問出來了，接下來呢？

`expect(getRefundedAmount(order)).toBeLessThanOrEqual(order.total)` 這行背後藏著一條商業規則。

> 一筆訂單的累計退款金額，不得超過訂單金額。

問題是討論歸討論，最後留下來的只有這行 `expect`。那張紅卡散會就丟了，需求文件沒補、會議記錄也沒人回頭看。%( ˘•ω•˘ )%

而且就算工程師真的把規則寫成註解，PM 和客服也看不懂 `toBeLessThanOrEqual`，沒辦法幫你檢查「你理解的規則跟我想的一樣嗎」。

要補的是這三件事。

* 規則要用**人話**寫，PM 和客服才有辦法幫你檢查
* 規則要**獨立存在**，不能散會就蒸發
* 規則要**跟著測試一起跑**，不然遲早跟實作脫節

路人：「那開個 Notion 頁面寫下來不就好了？%(・∀・)%」

鱈魚：「你自己相信那份文件三個月後還會是對的嗎？%(´\_ゝ\`)%」

把常見做法擺在一起看就很清楚。

| 做法 | 人話 | 獨立存在 | 跟著測試跑 |
|------|:----:|:--------:|:----------:|
| Notion 或 Markdown 文件 | ✅ | ✅ | ❌ |
| 程式碼註解 | ✅ | ❌ | ❌ |
| 寫得很用心的 `it` 描述 | ❌ | ❌ | ✅ |
| Gherkin | ✅ | ✅ | ✅ |

前兩欄好處理，第三欄比較麻煩。

而第三件事之所以難，在於**那份人話不能只是放在旁邊的說明，它必須是測試的執行來源**。

放在旁邊的文件一定會過期，因為沒有任何機制強迫它更新。只有當「改壞那段文字，測試就會跟著壞掉」的時候，它才會有人維護。%( ˘•ω•˘ )%

但這又帶出下一個問題，自然語言要能執行，格式就得受限。

* 太自由，機器讀不懂
* 太嚴格，人就懶得看了，那還不如直接寫程式碼

Gherkin 是個折衷點，著重在三個關鍵字，剩下的部分可以自由發揮。

* **Given**：前提是什麼
* **When**：發生了什麼事
* **Then**：應該得到什麼結果

是不是很眼熟？這就是每條測試都在做的 Arrange-Act-Assert。%( •̀ ω •́ )✧%

所以 Gherkin 並沒有發明新東西，它只是把測試本來就有的形狀，翻譯成 PM 也讀得懂的樣子。

## 把規則寫成 Gherkin

把剛剛那條規則寫下來，`features/refund.feature`

```gherkin
Feature: 訂單退款
  身為 客服人員
  我想要 對訂單分次退款
  以便 處理單件瑕疵的狀況

  Rule: 累計退款金額不得超過訂單金額

    Scenario: 分次退款直到超出訂單金額
      Given 顧客有一筆 1000 元的已付款訂單
      And 這筆訂單已經退款過 800 元
      When 客服再申請退款 400 元
      Then 系統應該拒絕這筆退款
      And 訂單的累計退款金額應該還是 800 元
```

`Feature` 底下那三行是慣例的使用者故事，格式是「身為誰、想要什麼、為了什麼」，不影響執行，純粹讓讀的人知道這功能為何存在。

請特別看 `And 這筆訂單已經退款過 800 元` 這句。

在單元測試的思維裡，不太會存在這種「**已經累積了什麼狀態**」的案例。

單元測試基本上是「給我一組乾淨的輸入」，而真實的小蟲蟲們往往就藏在不乾淨的既有狀態裡。%( ˘•ω•˘ )%

Gherkin 的 `Given` 天生就在描述這件事，逼你去想「動作發生之前，系統已經經歷過什麼」。

這份檔案裡沒有一行程式碼，PM 看得懂、QA 看得懂、客服看得懂，所有人都看得懂！（應該吧 ( ◔ ௰◔)）。

不過有件事得先講清楚，`.feature` 檔本身只是純文字，丟給 Node 不會有任何反應。

它得再補一層**步驟定義**，把每一句話對應到一段程式碼，測試框架才有辦法照著順序跑。

所以精確說法是，這份文件**驅動測試執行**，而不是文件自己會跑。

後面我們會來實際跑跑看。%( •̀ ω •́ )✧%

### Gherkin 不等於 user story

路人：「等等，所以 Gherkin 不就是 user story 換個寫法？%(´・ω・\`)%」

鱈魚：「剛好相反，它是 user story **沒講完的那一半**。%( •̀ ω •́ )%」

Ron Jeffries 提過 user story 的[三個 C](https://agilealliance.org/glossary/three-cs/)。

* **Card**：卡片上那句「身為誰、想要什麼」，故意寫得很短
* **Conversation**：拿著卡片去跟人討論
* **Confirmation**：討論完之後，講定怎樣才算做完

卡片刻意模糊，用途是**提醒你去找人聊**，不是拿來當規格。Gherkin 待在第三個 C，是那場對話**談完之後**的產物。%(´,,•ω•,,)%

| | User Story | Gherkin Scenario |
|---|---|---|
| 回答 | 誰要什麼、為什麼 | 什麼情況下會發生什麼 |
| 精確度 | 刻意模糊 | 刻意具體 |
| 能不能驅動測試 | 不能 | 接上步驟定義就能 |
| 數量 | 一張卡 | 一張卡通常對應好幾個 Scenario |
| 壽命 | 做完就歸檔 | 要一直活著 |

最後一列最容易忽略，user story 拿來排程，做完就歸檔；feature 檔得比那張卡活得久。

所以 feature 檔要按**行為領域**分，不能按 story 或 sprint 分，不然衝刺一結束就滿地孤兒檔案。%(´\_ゝ\`)%

## 這套做法有名字

用人話寫規則、開工前先講好、寫成可執行的驗收條件，這些都不是誰臨時想出來，背後有兩套發展了二十幾年的方法論，ATDD 和 BDD。

這兩個詞常一起出現，很多人分不清楚，還常看到「BDD 由 ATDD 演化而來」這種說法。它們其實是**同期長出來的兄弟**，各自從不同痛點出發，最後在同一個地方會合。%(´,,•ω•,,)%

### ATDD

ATDD 全名是 Acceptance Test Driven Development，驗收測試驅動開發。

Kent Beck 在 2002 年的《Test-Driven Development: By Example》就提過，只是當時覺得不太實際。同年 Ward Cunningham 做出 [FIT](http://fit.c2.com/)，讓客戶自己寫驗收測試，這條路才真的跑起來。

主張是**開工前先把「什麼叫做做完」講清楚，寫成具體的驗收條件**。

實務上最有名的做法叫「三個朋友」（Three Amigos），開工前由三種角色一起坐下來討論。

* **業務代表**（PM）說明想要什麼
* **開發**說明技術上做得到什麼
* **測試**負責問各種「那如果⋯⋯呢」

回頭看看那 1200 元。

> 「如果客服分三次退，每次都退 400 呢？」

路人：「這種案例我自己也想得到啊，開會幹嘛？%(´・ω・\`)%」

鱈魚：「對，你想得到，這跟有沒有跑 ATDD 一點關係都沒有。%ヽ(́◕◞౪◟◕‵)ﾉ%」

路人：「...%(´・ω・\`)%」

說實話 **ATDD 不會讓你變聰明**，會問出那句話的還是人，流程沒辦法自動思考。

細心的工程師自己泡咖啡時就想到了，而開了會卻全場沒人提很常見。

不過 PM 想流程、業務想實際操作，多個腦袋湊在一起，比一個人埋頭寫程式更容易冒出那句話。

這是機率，不是保證。%乁( ◔ ௰◔)「%

當然可以請 AI 一起幫忙想，不過最終只有人有辦法跟客戶確認。

### BDD

BDD 全名是 Behavior Driven Development，行為驅動開發，由 Dan North 提出，而它的親爸爸其實是 **TDD**。

事情是這樣。North 教 TDD 時一直被問同樣幾個問題，這該不該叫 test？要測到多細？先測哪個？

他後來想通了，這些根本不是技術問題，問題出在 `test` 這個字。

於是 2003 年他寫了 [JBehave](https://jbehave.org/) 取代 JUnit，把整套詞彙從「測試」換成「行為」，2006 年才發表〈[Introducing BDD](https://dannorth.net/introducing-bdd/)〉這篇經典。

後來受 DDD 的通用語言（Ubiquitous Language）啟發，他和 Chris Matts 把驗收條件的格式定成 Given-When-Then，這才長成今天的樣子。

::: tip Dan North 和 Chris Matts 是誰？
[Dan North](https://dannorth.net/about/)（現名 Daniel Terhorst-North）是英國軟體顧問，寫程式、帶團隊三十幾年，BDD 由他起頭，也提過 Deliberate Discovery 這類概念，現在自己開顧問公司。

[Chris Matts](https://papachrismatts.uk/) 是業務分析師，長年在投資銀行做交易與風險管理系統。他提出 Feature Injection，先找出價值，再回推該做哪些功能，剛好補上 BDD 缺的需求分析那半邊。
:::

所以兩條路的起點不同，ATDD 想解決「**怎麼讓客戶參與驗收**」，BDD 想解決「**test 這個字讓工程師搞不清楚在幹嘛**」。

一個往前推到需求端，一個往外推到業務端，最後在 Given-When-Then 會合。%(ゝ∀・)b%

實務上的差別在於，ATDD 沒有規定驗收條件要寫成什麼樣子，純文字、表格、便利貼都行。而 BDD 主張用**統一的語言描述系統行為**，也就是前面那套 Given-When-Then。

補充一下，連續出現同一種步驟時，第二句之後可以用 `And` 接下去，讀起來比較順。想表達反向條件則用 `But`，兩個都是 [Gherkin 官方規格](https://cucumber.io/docs/gherkin/reference/)裡的關鍵字。

兩者可以一起用，用 ATDD 的精神開會，用 BDD 的格式記錄。%( •̀ ω •́ )✧%

總結一下，概念就是：

* **想到**靠人，流程只能提高機率
* **不忘記**靠工具，這件事真的保證得了

不過學術定義是一回事，具體要怎麼做我覺得比較重要，接下來看看可以怎麼實作。

## 導入 vitest-cucumber

回到剛剛那份 `.feature` 檔，該幫它接上步驟定義，讓它真的跑起來了。

JavaScript 圈最有名的 BDD 工具是 [Cucumber](https://cucumber.io/)，不過官方的 `@cucumber/cucumber` 有自己一整套 runner 和設定，跟 Vitest 是兩個世界。

既然專案已經在用 Vitest，那就用 [vitest-cucumber](https://vitest-cucumber.miceli.click/)，它讓 `.feature` 檔直接驅動 Vitest 測試，不用多養一套測試框架。%( •̀ ω •́ )✧%

安裝只要一行，也不用改設定檔。

```bash
npm install -D @amiceli/vitest-cucumber
```

接著把 feature 檔實作出來，`refund.spec.ts`

```ts
import { describeFeature, loadFeature } from '@amiceli/vitest-cucumber'
import { expect } from 'vitest'
import { createOrder, getRefundedAmount, type Order } from '../order'
import { type RefundResult, submitRefund } from '../refund-service'

const feature = await loadFeature('features/refund.feature')

describeFeature(feature, ({ Rule }) => {
  Rule('累計退款金額不得超過訂單金額', ({ RuleScenario }) => {
    RuleScenario('分次退款直到超出訂單金額', ({ Given, And, When, Then }) => {
      let order: Order
      let result: RefundResult

      Given('顧客有一筆 1000 元的已付款訂單', () => {
        order = createOrder({ total: 1000 })
      })

      And('這筆訂單已經退款過 800 元', () => {
        submitRefund(order, 800)
        expect(getRefundedAmount(order)).toBe(800)
      })

      When('客服再申請退款 400 元', () => {
        result = submitRefund(order, 400)
      })

      Then('系統應該拒絕這筆退款', () => {
        expect(result.accepted).toBe(false)
      })

      And('訂單的累計退款金額應該還是 800 元', () => {
        expect(getRefundedAmount(order)).toBe(800)
      })
    })
  })
})
```

跑起來一樣紅，抓到一樣的 bug。

修法也不難，把那個一直沒接上的函數接回去就好。

```ts
export function checkRefund(order: Order, amount: number): RefundResult {
  if (order.status !== 'paid') {
    return { accepted: false, reason: 'ORDER_NOT_REFUNDABLE' }
  }

  const refundableAmount = order.total - getRefundedAmount(order) // [!code ++]

  if (amount <= 0 || amount > order.total) { // [!code --]
    return { accepted: false, reason: 'INVALID_AMOUNT' } // [!code --]
  } // [!code --]
  if (amount <= 0 || amount > refundableAmount) { // [!code ++]
    return { accepted: false, reason: 'INVALID_AMOUNT' } // [!code ++]
  } // [!code ++]

  return { accepted: true, amount }
}
```

有趣的是，這行補上去之後，Stryker 才終於**有東西可以突變**。%(´,,•ω•,,)%

## 前端也能用

前端用瀏覽器跑 e2e 測試，同樣能套用這套概念。

Gherkin 描述的是**行為**，商業規則跟你用什麼技術實作完全無關。

Playwright 這邊的套件叫 [playwright-bdd](https://vitalets.github.io/playwright-bdd/)，先把 `.feature` 編譯成測試檔，再交給 Playwright 原生的 runner 跑。

```bash
npm install -D playwright-bdd
```

設定檔把 `defineBddConfig` 的回傳值交給 `testDir` 就好，`playwright.config.ts`

```ts
import { defineConfig } from '@playwright/test'
import { defineBddConfig } from 'playwright-bdd'

const testDir = defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'features/steps/**/*.ts',
})

export default defineConfig({
  testDir,
  use: { baseURL: 'http://localhost:5173' },
})
```

接著是 UI 版的 Scenario，`features/refund-admin.feature`

```gherkin
Feature: 客服後台退款
  身為 客服人員
  我想要 在後台對訂單分次退款
  以便 處理單件瑕疵的狀況

  Rule: 累計退款金額不得超過訂單金額

    Scenario: 超額退款要在畫面上被擋下來
      Given 客服打開訂單 A001 的退款頁面
      And 這筆訂單金額是 1000 元
      And 這筆訂單已經退款過 800 元
      When 客服輸入退款金額 400 元
      And 客服送出退款
      Then 畫面應該提示可退金額只剩 200 元
      And 退款紀錄應該還是只有一筆
```

`Rule` 跟前面那份一模一樣，只有 `Scenario` 從「申請退款」變成「填欄位、按按鈕」。%( •̀ ω •́ )✧%

步驟實作在 `features/steps/refund-admin.ts`

```ts
import { expect } from '@playwright/test'
import { createBdd } from 'playwright-bdd'

const { Given, When, Then } = createBdd()

Given('客服打開訂單 {word} 的退款頁面', async ({ page }, orderId: string) => {
  await page.goto(`/admin/orders/${orderId}/refund`)
})

Given('這筆訂單金額是 {int} 元', async ({ page }, total: number) => {
  await expect(page.getByTestId('order-total')).toHaveText(`${total}`)
})

Given('這筆訂單已經退款過 {int} 元', async ({ page }, refundedAmount: number) => {
  await expect(page.getByTestId('refunded-amount')).toHaveText(`${refundedAmount}`)
})

When('客服輸入退款金額 {int} 元', async ({ page }, amount: number) => {
  await page.getByLabel('退款金額').fill(`${amount}`)
})

When('客服送出退款', async ({ page }) => {
  await page.getByRole('button', { name: '送出退款' }).click()
})

Then('畫面應該提示可退金額只剩 {int} 元', async ({ page }, remaining: number) => {
  await expect(page.getByRole('alert')).toHaveText(`可退金額只剩 ${remaining} 元`)
})

Then('退款紀錄應該還是只有一筆', async ({ page }) => {
  await expect(page.getByTestId('refund-row')).toHaveCount(1)
})
```

先產生測試檔再跑。

```bash
npx bddgen && npx playwright test
```

有個地方要注意，playwright-bdd 走官方 Cucumber.js 路線，**步驟全域註冊、用 Cucumber Expression 比對文字**，跟 vitest-cucumber 的巢狀 callback 不一樣。

所以 `And` 開頭的步驟要用 `Given` 定義，因為 `And` 會沿用前一句的關鍵字。`{word}`、`{int}` 這些參數寫法也是 Cucumber Expression 的標準語法。

## Gherkin 到底好在哪

好不好其實也取決於怎麼用、團隊怎麼合作等等，不過 Gherkin 確實有幾項好處。

vitest-cucumber 會拿 `.spec.ts` 對照 `.feature`，少實作一個 Scenario、步驟文字對不上、把 `When` 寫成 `Then`，通通直接報錯。

**規格與測試可以綁在一起**，不會有那種文件寫 A、程式做 B 的經典慘案。%( •̀ ω •́ )✧%

再來看看兩種寫法的差異。

| 比較項目 | Vitest 流程測試 | vitest-cucumber |
|---------|----------------|-----------------|
| 誰看得懂 | 只有工程師 | PM 和 QA 都看得懂 |
| 規則放哪 | 藏在 `it` 字串裡，或只在腦袋裡 | 獨立的 `.feature` 檔 |
| 規則會不會過期 | 會，改了實作忘了改描述 | 不會，對不上直接報錯 |
| 補一個邊界案例 | 要動程式碼 | 在 Examples 加一行 |
| 額外成本 | 無 | 多一層步驟要維護 |

未來回溯需求與邏輯時，不管是新接手的工程師還是 AI Agent，直接看 `.feature` 檔會比看測試程式碼更快更清楚。

### 業務邏輯可讀性較高

講可讀性太抽象，兩種寫法擺在一起就知道了。%(´,,•ω•,,)%

下面兩份測試測的是同一份退款邏輯，內容完全等價。

先看 Vitest 版。

```ts
describe('退款流程', () => {
  let order: Order

  beforeEach(() => {
    order = createOrder({ total: 1000 })
    vi.spyOn(paymentGateway, 'refund').mockResolvedValue({ status: 'ok' })
  })

  it('部分退款後，可退餘額要跟著減少', () => {
    submitRefund(order, 300)

    expect(getRefundedAmount(order)).toBe(300)
    expect(order.refundList).toHaveLength(1)
  })

  it('超額退款要被擋下來', () => {
    submitRefund(order, 800)
    const result = submitRefund(order, 400)

    expect(result.accepted).toBe(false)
    expect(getRefundedAmount(order)).toBe(800)
  })

  it('金流失敗時不應該留下退款紀錄', () => {
    vi.spyOn(paymentGateway, 'refund').mockImplementation(() => {
      throw new Error('gateway down')
    })

    expect(() => submitRefund(order, 300)).toThrow()
    expect(order.refundList).toHaveLength(0)
  })

  it('退滿訂單金額後，訂單要標記為已全額退款', () => {
    submitRefund(order, 1000)

    expect(order.status).toBe('refunded')
  })
})
```

再看 vitest-cucumber 版，規格與實作分成兩份檔案，先是 `refund.feature`

```gherkin
Feature: 訂單退款
  身為 客服人員
  我想要 對訂單分次退款
  以便 處理單件瑕疵的狀況

  Scenario: 部分退款後，可退餘額要跟著減少
    Given 顧客有一筆 1000 元的已付款訂單
    When 客服申請退款 300 元
    Then 訂單的累計退款金額應該是 300 元
    And 訂單應該有 1 筆退款紀錄

  Scenario: 超額退款要被擋下來
    Given 顧客有一筆 1000 元的已付款訂單
    And 這筆訂單已經退款過 800 元
    When 客服再申請退款 400 元
    Then 系統應該拒絕這筆退款
    And 訂單的累計退款金額應該還是 800 元

  Scenario: 金流失敗時不應該留下退款紀錄
    Given 顧客有一筆 1000 元的已付款訂單
    And 金流服務目前無法連線
    When 客服申請退款 300 元
    Then 系統應該回報退款失敗
    And 訂單不應該有任何退款紀錄

  Scenario: 退滿訂單金額後，訂單要標記為已全額退款
    Given 顧客有一筆 1000 元的已付款訂單
    When 客服申請退款 1000 元
    Then 訂單狀態應該是已全額退款
```

接著是 `refund.spec.ts`

```ts
const feature = await loadFeature('features/refund.feature')

describeFeature(feature, ({ Scenario }) => {
  Scenario('部分退款後，可退餘額要跟著減少', ({ Given, When, Then, And }) => {
    let order: Order

    Given('顧客有一筆 1000 元的已付款訂單', () => {
      order = createOrder({ total: 1000 })
    })

    When('客服申請退款 300 元', () => {
      submitRefund(order, 300)
    })

    Then('訂單的累計退款金額應該是 300 元', () => {
      expect(getRefundedAmount(order)).toBe(300)
    })

    And('訂單應該有 1 筆退款紀錄', () => {
      expect(order.refundList).toHaveLength(1)
    })
  })

  Scenario('超額退款要被擋下來', ({ Given, And, When, Then }) => {
    let order: Order
    let result: RefundResult

    Given('顧客有一筆 1000 元的已付款訂單', () => {
      order = createOrder({ total: 1000 })
    })

    And('這筆訂單已經退款過 800 元', () => {
      submitRefund(order, 800)
    })

    When('客服再申請退款 400 元', () => {
      result = submitRefund(order, 400)
    })

    Then('系統應該拒絕這筆退款', () => {
      expect(result.accepted).toBe(false)
    })

    And('訂單的累計退款金額應該還是 800 元', () => {
      expect(getRefundedAmount(order)).toBe(800)
    })
  })

  Scenario('金流失敗時不應該留下退款紀錄', ({ Given, And, When, Then }) => {
    let order: Order

    Given('顧客有一筆 1000 元的已付款訂單', () => {
      order = createOrder({ total: 1000 })
    })

    And('金流服務目前無法連線', () => {
      vi.spyOn(paymentGateway, 'refund').mockImplementation(() => {
        throw new Error('gateway down')
      })
    })

    When('客服申請退款 300 元', () => {
      expect(() => submitRefund(order, 300)).toThrow()
    })

    Then('系統應該回報退款失敗', () => {
      expect(order.status).toBe('paid')
    })

    And('訂單不應該有任何退款紀錄', () => {
      expect(order.refundList).toHaveLength(0)
    })
  })

  Scenario('退滿訂單金額後，訂單要標記為已全額退款', ({ Given, When, Then }) => {
    let order: Order

    Given('顧客有一筆 1000 元的已付款訂單', () => {
      order = createOrder({ total: 1000 })
    })

    When('客服申請退款 1000 元', () => {
      submitRefund(order, 1000)
    })

    Then('訂單狀態應該是已全額退款', () => {
      expect(order.status).toBe('refunded')
    })
  })
})
```

不難看出 Gherkin 版本比較囉唆，但好處是**把檢查範圍縮小**。

**一句話配一條斷言。**

Vitest 版的一個 `it` 塞了兩三條斷言，標題「超額退款要被擋下來」同時涵蓋它們，沒有一條跟標題一對一，你得自己在腦中拆哪句對應哪一半。

Gherkin 版的每個步驟只負責一句話，那句中文就正對著底下唯一那行 `expect`，對不上就會直接跳出來。

**每一行的身分都標好了。**

`Given` 是前置條件、`When` 是動作、`Then` 才負責驗證。Vitest 版的佈景和重點混在同一區塊，你得先讀懂程式碼才分得出來，除非你讀程式碼比讀文字還快，那當我沒說。%(́⊙◞౪◟⊙‵)%

### PM 自己就能加測試案例

現在人人都用 AI 寫 Code 了，假設 PM 某天說：「我想確認幾種分次退款的組合對不對。」

以前這句話代表你要開編輯器，現在他自己就能在表格裡加一行。

```gherkin
  Rule: 累計退款金額不得超過訂單金額

    Scenario Outline: 各種分次退款的組合
      Given 顧客有一筆 1000 元的已付款訂單
      And 這筆訂單已經退款過 <已退> 元
      When 客服再申請退款 <本次> 元
      Then 退款結果應該是 <結果>

      Examples:
        | 已退 | 本次 | 結果 |
        | 0    | 1000 | 通過 |
        | 800  | 200  | 通過 |
        | 800  | 400  | 拒絕 |
        | 1000 | 1    | 拒絕 |
```

[`Scenario Outline`](https://cucumber.io/docs/gherkin/reference/#scenario-outline) 是**範本**，`<已退>`、`<本次>`、`<結果>` 這種角括號寫法是佔位符，名稱直接對應底下 `Examples` 表格的欄位。

表格有幾列就跑幾次，每次把那列的值填進去，等於一口氣寫了四條 Scenario。%( •̀ ω •́ )✧%

實作端把 `Scenario` 換成 `RuleScenarioOutline`，callback 第二個參數就是這次跑到的那一列。

```ts
RuleScenarioOutline('各種分次退款的組合', ({ Given, And, When, Then }, variables) => {
  // ...

  And('這筆訂單已經退款過 <已退> 元', () => {
    const refundedAmount = Number(variables['已退'])
    if (refundedAmount > 0) {
      submitRefund(order, refundedAmount)
    }
  })

  Then('退款結果應該是 <結果>', () => {
    expect(result.accepted).toBe(variables['結果'] === '通過')
  })
})
```

[`variables`](https://vitest-cucumber.miceli.click/features/scenario-outline/) 是個物件，key 就是 `Examples` 的欄位名，值一律是**字串**，所以 `已退` 要自己 `Number()` 轉成數字，`結果` 則是拿 `'通過'` 這串中文去比對。

那張表格同時是規格、測試案例和驗收清單，三個身分一次滿足。%ԅ(´∀\` ԅ)%

## 如果只有工程師要看呢？

路人：「如果專案只有我一個人，PM 不看、沒有 QA，那不就完全不用導入？%(´・ω・\`)%」

鱈魚：「還是有別的好處啦。%(｢･ω･)｢%」

大致上是這樣沒錯，[Cucumber 官方](https://cucumber.io/blog/bdd/bdd-vs-tdd/)講得很直接，TDD 一個人就能做，BDD 的前提是一群人先對話。

不過還是有兩個理由讓我沒完全放棄它。

**第一：三個月後的你就是那個熟悉的陌生人。**

聽起來很像甚麼言情小說標題，但是這種情況真的不稀奇。%(◉◞౪◟◉ )%

回去看半年前寫的測試，你會完全想不起來當初為什麼那樣判斷。

`.feature` 檔記下的是**當初定了甚麼規則**，而 `it` 的字串裝不下這些細節。

**第二：「不准出現程式碼名詞」這條約束的價值。**

被迫用領域語言描述行為，你會一直想「使用者到底想幹嘛」，而不是「這函數該回傳什麼」。

視角換了，看到的東西也會不一樣。%◝( •ω• )◟%

話說回來，只為了這兩點，成本效益還是有點勉強。

維護這些案例與文件的成本真的很高，看了就累。%*(┐「﹃ﾟ｡)*%

但最近多出來一位新同事，讓我重新評估了這件事。%(´,,•ω•,,)%

## 好同事：AI agent

沒錯，就是 AI。

以前 BDD 要湊齊三種角色才划算，現在其中一位可能是 agent，而 Gherkin 剛好人和 AI **兩邊都讀得懂**。

### 一、驗收條件被刪會很顯眼

有沒有遇過請 AI 修個 bug，它跑完測試發現紅了，很貼心地把期望值改成實際輸出，回報「已修復，測試全綠」。%ლ(・´ｪ\`・ლ)%

驗收條件獨立成檔就沒那麼好動手，少實作一條 `Scenario` 就報錯，真要拿掉得連那句中文一起刪，而 diff 上少一段商業規則，比少一行 `expect` 顯眼太多。%( ˘•ω•˘ )%

不過也就到這裡了，步驟裡的 `expect` 被註解掉，或是 `toBe(false)` 換成 `toBeDefined()`，`.feature` 檔的內容管不到，也無法限制。%(;´༎ຶД༎ຶ\`)%

這招叫**寬鬆斷言**（overly general assertion，[上一篇](/blog-program/what-is-mutation-testing-and-stryker)有詳細說明），不過突變測試抓的到，所以不是大問題。%(ﾉ>ω<)ﾉ%

剩下的確認與檢查工作就是你的任務了。%(ゝ∀・)b%

甚麼？你希望檢查和確認也不用做？記得出事的時候不要只會說都是 AI 寫錯。%( ・ิω・ิ)%

### 二、feature 檔是最好的需求輸入

Gherkin 的結構是「狀態 → 動作 → 結果」，剛好是 LLM 最擅長處理的形式。

丟一份 feature 檔給 agent 說「把這個實作出來」，比丟一段散文需求精確太多，前提、動作、期望值全都結構化了，沒有模糊空間。%(ゝ∀・)b%

### 三、agent 的領域知識索引

agent 每次讀專案都要重新理解商業規則，讀幾千行測試碼很貴，還容易漏。

`.feature` 檔把散落各處的商業規則集中成十幾個檔案，agent 讀完就掌握了整個領域，token 省得不是一點半點。

### 四、錨點不會跟著工作一起漂

跑久的 agent 最常見的毛病是飄移，做著做著就忘了原本要幹嘛，最後交出一份很認真但方向錯掉的東西。%(´\_ゝ\`)%

意圖只寫在測試程式碼裡，**錨點和工作就是同一個檔案**，agent 改著改著連錨點一起改掉。

`.feature` 檔放在外面，改實作時它動都不動，重新對焦也只花一百多個 token。

「系統應該拒絕這筆退款」這句話又沒什麼模糊空間，agent 想自我說服「這樣應該也算完成了」都很難。

甚麼？你的 AI 自我說服成功？請蛋雕那個 AI。%⎝(・ω´・⎝)%

`Scenario` 也天生適合當任務邊界，步驟固定、完成條件明確，而飄移多半就是停止條件太模糊。

### 可是我覺得 Gherkin 很難寫 QQ

的確，Gherkin 要寫得好其實不容易，人自己寫都會歪，何況 AI。%( ˘•ω•˘ )%

常見的歪法有這幾種。

* 一個 `Scenario` 塞好幾種行為
* 用操作步驟取代狀態，寫「點設定、點權限、點下拉選單」，不寫「使用者具有編輯者權限」
* `Then` 寫成看不到的結果，例如「登入成功」
* 資料用 `foo`、`bar`，不用實際金額和名字
* 一個步驟用「並」、「然後」黏兩個動作

好在 Automation Panda 大神已經把[整套規則](https://automationpanda.com/2026/04/27/bdd-gherkin-guidelines-for-ai-coding-and-testing/)寫成一份 [gherkin-guidelines.md](https://github.com/AutomationPanda/gherkin-guidelines-for-ai)，直接丟進專案當 context 檔就好，Claude Code、Cursor、Copilot 都吃得下。%( •̀ ω •́ )✧%

::: tip Automation Panda 是誰？
本名 Andrew Knight，美國測試自動化工程師，長期在 BDD 與 Gherkin 圈子寫作演講，部落格 [Automation Panda](https://automationpanda.com/) 累積了大量 Python 測試與 BDD 的實務文章。
:::

## 但是別急著全部改寫

講了這麼多好話，也要說說壞話，不然像業配。%(｢･ω･)｢%

看過不少團隊導入 Cucumber 之後放棄，通常都踩到這四個坑。

**一、拿去測工具函數**

`formatDate`、`deepClone` 這種東西，直接 Vitest 三行寫完，套 Gherkin 只是自找麻煩。BDD 描述的是**使用者行為**，不是函數簽章。

**二、步驟寫成程式碼的翻譯**

看過這種 feature 檔嗎？

```gherkin
      Given 初始化 RefundService
      When 呼叫 submitRefund 方法並傳入 order 與 amount
      Then 回傳值的 accepted 屬性應該等於 false
```

這完全是本末倒置。PM 看到只會更困惑，等於付了 Gherkin 的成本，好處一點也沒拿到。%ლ（´口\`ლ）%

判斷標準很簡單，**feature 檔裡不應該出現任何程式碼名詞**。

**三、`Then` 寫得含糊**

```gherkin
      Then 退款流程應該正常運作
```

看起來有驗東西，其實什麼都沒驗，因為「正常運作」沒人能判斷真假。有沒有覺得眼熟？這就是 `toBeDefined()` 的 Gherkin 版本，**規格層的寬鬆斷言**。%( ˘•ω•˘ )%

寫程式時知道要用 `toBe(false)`，寫規格時同一條標準照樣成立，`Then` 要寫成**看得出來的結果**。

```gherkin
      Then 系統應該拒絕這筆退款   // [!code ++]
      And 訂單的累計退款金額應該還是 800 元   // [!code ++]
```

而且這種洞比程式碼裡的更貴，因為規格是四關的最上層，它含糊了，底下每一關都跟著含糊。%(°ㅂ°)%

**四、寫完就沒有下文**

feature 檔寫完之後沒人看、沒人討論、也沒拿去餵 agent，那就只是把 `it` 改成 `Scenario`，ATDD 的精神一點也沒沾到。

判斷方式很簡單，問問自己這份檔案**寫給誰看**。答案要是「沒有誰」，那就別寫了。%( ˘•ω•˘ )%

所以務實的做法是分層對待。

| 層級 | 工具 | 負責回答 |
|------|------|---------|
| 單元測試 | Vitest | 這個函數寫對了嗎 |
| 整合測試 | Vitest | 模組串起來還是對的嗎 |
| 突變測試 | Stryker | 我寫的測試夠不夠嚴格 |
| 流程測試 | vitest-cucumber | 這條商業規則真的成立嗎 |
| 前端 E2E 測試 | playwright-bdd | 使用者知道規則守住了嗎 |

前三層守的是「**程式碼有沒有寫錯**」，後兩層守的是「**我們有沒有想錯**」。

各層各司其職，數量從上往下遞減，但越往下，一條測試的價值越高。%(ゝ∀・)b%

## 總結 🐟

* 單元、整合、突變測試都**假設規格沒問題**，規格少講一條，三關全滅，只有流程測試擋得住。
* 流程測試難在**要寫哪幾條**跟**規則會不會蒸發**。前者只能靠人挖，開會只是提高機率，而**工程師往往比 PM 更早撞到規格的洞**，撞到就回去問。
* 後者交給 **Gherkin**，用人話寫、獨立成檔、跟著測試一起跑，那份人話**得是測試的執行來源**。同一條 `Rule`，vitest-cucumber 驗 domain、playwright-bdd 驗畫面。
* 好處集中在協作，多了 agent 如虎添翼，`.feature` 檔同時是需求輸入、領域索引與不會漂的錨點。想寫得好，可以參考 [gherkin-guidelines.md](https://github.com/AutomationPanda/gherkin-guidelines-for-ai)。

那寫了流程測試之後，是不是就再也不會出包了呢？

當然不是，還有第三方 API 亂噴、時區、閏年、使用者用你想都想不到的方式操作系統⋯⋯不過那又是另一個故事了。%乁( ◔ ௰◔)「%

路人：「是有多少故事！%╭(°A ,°\`)╮%」

有錯誤還請多多指教，感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

---

---
url: /blog-ocean-world/check-images-ready.md
description: 確保圖片都乖乖載入完成，一個都不能少！順便玩玩看 Vitest 的 Browser Mode(・∀・)９
---

![check-images-ready](/check-images-ready.webp){.cover}

# 甚麼？圖片還沒好喔！Σ(ˊДˋ;)

最近開發網頁列印功能時，發現使用者列印當下，圖片可能還沒出現，導致頁面不完整。%(◞‸◟ )%

怎麼辦哩？來做一個圖片載入完成的檢查吧！%(・∀・)９%

## 釐清需求

先來釐清需求，這個功能的目的是：

1. 確保指定 DOM 下所有圖片都載入完成
2. 如果圖片不可見則忽略
3. 需考慮 CSS background-image

## 實作

熟悉 Web 開發的人，應該都知道圖片載入完成可以透過 `load` 事件來處理。

知道這點後，其實就很簡單了，讓我們一步一步來。

這裡以 Vue 為例，建立一個名為 `useImagesReady` 的 Composition API。

### 取得目標的 HTML 元素

我們的參數支援直接使用 Vue 元件，所以要先處理一下，讓我們可以取得目標的 HTML 元素。

`composables\use-images-ready.ts`

```ts
interface UseImagesReadyParams {
  /** 不指定則為目前元件 */
  target?: MaybeElement;
  /** 強制延遲（ms），保險起見
   * @default 0
   */
  forceDelay?: number;
  /** 是否包含 background-image
   * @default true
   */
  includeBackgroundImages?: boolean;
}

/** 偵測目標下所有圖片是否載入完成
 *
 * 目前不考慮動態新增的圖片
 */
export function useImagesReady(params: UseImagesReadyParams = {}) {
  const {
    target,
    forceDelay = 0,
    includeBackgroundImages = true,
  } = params

  const totalImages = ref(0)
  const isReady = ref(false)
  /** 取得目前元件實例 */
  const instance = getCurrentInstance()

  onMounted(() => {
    const rootElement = pipe(
      toValue(target),
      (value) => {
        if (value && '$el' in value) {
          return value.$el
        }

        return value
          ?? instance?.vnode?.el
          ?? instance?.proxy?.$el
          ?? document.documentElement
      },
      (value) => {
        if (!value) {
          return undefined
        }

        if (value instanceof HTMLElement) {
          return value
        }

        throw new Error(
          '[useImagesReady] 取得目標元素異常，請確認 target 是否為 HTMLElement 或 Vue 元件',
        )
      },
    )

    if (!rootElement) {
      isReady.value = true
      console.warn('[useImagesReady] 目標元素不存在，無法偵測圖片載入狀態')
    }
  })

  return {
    isReady,
    totalImages,
  }
}
```

::: tip 那個 `pipe` 是甚麼咚咚？
不知道的朋友們可以來這裡[看看](/blog-program/remeda-pipe)
:::

### 取得所有圖片

接著是取得圖片部分，先新增一個判斷 image 是否可見的 function。

若其父元素隱藏，則圖片一定也看不到，所以要一路找上去，把列祖列宗都找出來 %ლ（´∀\`ლ）%。

```ts
function isElementVisible(el: HTMLElement | null) {
  /** 一路往父層檢查 */
  while (el) {
    const style = getComputedStyle(el)
    if (style.display === 'none' || style.visibility === 'hidden') {
      return false
    }
    el = el.parentElement
  }
  return true
}
```

::: tip 怎麼不用 `offsetParent`？%ლ(╹ε╹ლ)%
研究中有找到 `offsetParent` 這個屬性，當父元素 `display: none` 時會是 `null`，就可以不用一路往上找。

只是父元素為 `position: fixed` 也會是 `null`，這樣會誤判，所以不行。%ლ(╹ε╹ლ)%

[HTMLElement: offsetParent property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent)
:::

接著取得目標元素下的所有圖片。

```ts
const imageElements = Array.from(rootElement.querySelectorAll('img'))
  .filter((img) => !!img.src && isElementVisible(img))
```

接著取得背景圖片並轉換成 `HTMLImageElement`，最後合併到 `imageElements`。

```ts
const backgroundImageElements = Array.from(
  includeBackgroundImages
    ? rootElement.querySelectorAll('*')
    : [],
).reduce((list, el) => {
  if (!(el instanceof HTMLElement) || !isElementVisible(el)) {
    return list
  }

  const bgValue = getComputedStyle(el).getPropertyValue('background-image')
  if (bgValue && bgValue !== 'none') {
    // 只處理 url 的背景圖片
    const url = bgValue.match(/url\(["']?([^"']+)["']?\)/)
    if (!url || !url[1]) {
      return list
    }
    const img = new Image()
    img.src = url[1]
    list.push(img)
  }

  return list
}, [] as HTMLImageElement[])

const imageElements = Array.from(rootElement.querySelectorAll('img'))
  .filter((img) => !!img.src && isElementVisible(img))
  .concat(backgroundImageElements)
```

### 圖片載入事件

圖片到齊了，剩下就是處理載入事件了，這裡我們使用 VueUse 的 [`useEventListener`](https://vueuse.org/core/useEventListener/)。

`composables\use-images-ready.ts`

```ts
export function useImagesReady(params: UseImagesReadyParams = {}) {
  // ...

  onMounted(() => {
    // ...

    totalImages.value = imageElements.length

    if (totalImages.value === 0) {
      isReady.value = true
      return
    }

    let loadedCount = 0

    async function checkCompletion() {
      if (loadedCount === totalImages.value) {
        await promiseTimeout(forceDelay)
        isReady.value = true
      }
    }

    function handleEvent() {
      loadedCount++
      checkCompletion()
    }

    imageElements.forEach((img) => {
      if (img.complete) {
        loadedCount++
        return
      }

      useEventListener(img, 'load', handleEvent, { once: true })
      useEventListener(img, 'error', handleEvent, { once: true })
    })

    checkCompletion()
  })

  return {
    isReady,
    totalImages,
  }
}
```

這樣就完成了，當所有圖片載入完成（或錯誤）後，`isReady` 會變成 `true`。

雖然還有一些情境與邊界問題還未考慮，不過這樣已經很夠用惹。%ԅ(´∀\` ԅ)%

完整程式可以在[這裡取得](https://github.com/Codfisher/cod-aquarium/blob/main/composables/use-images-ready.ts)

## 來個測試

先前都用 Playwright 測試，這次來試試看 Vitest 的 [Browser Mode](https://vitest.dev/guide/browser/)。%(｡･∀･)ﾉﾞ%

Browser Mode 會直接在瀏覽器中執行測試，不是模擬環境，可以更接近實際使用情境。

與 Playwright 最大的差別在於不用開啟頁面，可以直接測試 Vue 元件。

Vitest 會在內部自動處理，開發者用起來就如同平常寫單元測試一樣單純。

::: tip
Playwright 其實也可以測試元件，不過此功能正在實驗中。

而因單元測試很常使用 Vitest，如果測試都能在 Vitest 完成，整合性更高、更方便。

[Playwright test-components](https://playwright.dev/docs/test-components)
:::

[安裝與設定](https://vitest.dev/guide/browser/#installation)基本上依照官網步驟即可。

這裡我使用 Vitest 的 VSCode [擴充套件](https://marketplace.visualstudio.com/items?itemName=vitest.explorer)來執行測試。

### 建立輔助 function

第一步來做一個產生基本內容的 Vue 元件吧，這裡我們直接使用 `h` function 建立，就不用獨立 `.vue` 檔案了。

`composables\use-images-ready.spec.ts`

```ts
type Images = Array<{ src: string; id?: string; style?: string }>
function createTestComponent(
  images: Images,
  slots: VNode[] = [],
) {
  return defineComponent({
    setup() {
      const {
        isReady,
        totalImages,
      } = useImagesReady()

      return () => h('div', null, [
        h('h1', '測試元件'),
        ...images.map((img) => h('img', img)),
        ...slots,

        h('div', { id: 'status' }, isReady.value ? 'Ready' : 'Loading'),
        h('div', { id: 'totalImages' }, `total: ${totalImages.value}`),
      ])
    },
  })
}
```

測試用的圖片我使用 [Picsum](https://picsum.photos/) 這個隨機圖片服務。

建立一個 `getImageSrc` function 取得圖片 URL。

```ts
const sizeList = range(1, 10).map(
  (i) => `${i * 20}`,
) as [string, string, ...string[]]

function getImageSrc(params?: { width: number; height: number }) {
  if (!params) {
    const sizes = sample(sizeList, 2)
    return `https://picsum.photos/${sizes.join('/')}`
  }

  const { width, height } = params
  return `https://picsum.photos/${width}/${height}`
}
```

### 建立測試

現在來建立第一個測試。

```ts
import type { VNode } from 'vue'
import { page } from '@vitest/browser/context'
import { map, pipe, range, sample } from 'remeda'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { render } from 'vitest-browser-vue'
import { defineComponent, h, nextTick } from 'vue'
import { useImagesReady } from './use-images-ready'

// ...

/** 負責斷言 Ready */
function expectReady(screen: ReturnType<typeof render>) {
  return expect.element(screen.getByText('Ready'), {
    /**
     * 不斷檢查元素是否存在，直到超過 timeout 或找到元素
     *
     * https://vitest.dev/guide/browser/assertion-api.html#:~:text=expect.poll%20and%20expect.element%20APIs
     */
    interval: 100,
  }).toBeInTheDocument()
}

describe('useImagesReady', () => {
  it('如果沒有圖片，isReady 應該立即設為 true', async () => {
    const screen = render(createTestComponent([]))
    await expect.element(screen.getByText('測試元件')).toBeInTheDocument()
    await expectReady(screen)
  })
})
```

執行測試後，沒有意外的話會開啟瀏覽器並顯示測試結果，如下圖。

![browser-ui](/check-images-ready/browser-ui.png)

讓我們新增更多測試。

```ts
// ...

describe('useImagesReady', () => {
  it('如果沒有圖片，isReady 應該立即設為 true', async () => {
    // ...
  })

  it('1 張圖片載入後，文字從 Ready 變 Loading', async () => {
    const data = [
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data))
    await expect.element(screen.getByText(`total: ${data.length}`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('2 張圖片載入後，文字從 Ready 變 Loading', async () => {
    const data: Images = [
      { src: getImageSrc() },
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data))
    await expect.element(screen.getByText(`total: ${data.length}`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('hidden 的圖片會被忽略', async () => {
    const data: Images = [
      { src: getImageSrc() },
      { src: getImageSrc(), style: 'display: none;' },
      { src: getImageSrc(), style: 'visibility: hidden;' },
    ]

    const screen = render(createTestComponent(data))
    await expect.element(screen.getByText(`total: 1`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('父層元素 hidden 的圖片也應被被忽略', async () => {
    const data: Images = [
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data, [
      h('div', { style: 'display: none;' }, [
        h('img', { src: getImageSrc() }),
      ]),
      h('div', { style: 'visibility: hidden;' }, [
        h('img', { src: getImageSrc() }),
      ]),
    ]))
    await expect.element(screen.getByText(`total: ${data.length}`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('更父層元素 hidden 的圖片也應被被忽略', async () => {
    const data: Images = [
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data, [
      h('div', { style: 'display: none;' }, [
        h('div', [
          h('div', [
            h('img', { src: getImageSrc() }),
          ]),
        ]),
      ]),
    ]))
    await expect.element(screen.getByText(`total: ${data.length}`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('須包含 background-image 圖片', async () => {
    const data: Images = [
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data, [
      h('div', {
        style: [
          'width: 100px',
          'height: 100px',
          `background-image: url(${getImageSrc()})`,
        ].join(';'),
      }),
    ]))
    await expect.element(screen.getByText(`total: 2`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })

  it('父層元素隱藏，要忽略 background-image 圖片', async () => {
    const data: Images = [
      { src: getImageSrc() },
    ]

    const screen = render(createTestComponent(data, [
      h('div', { style: 'display: none;' }, [
        h('div', {
          style: [
            'width: 100px',
            'height: 100px',
            `background-image: url(${getImageSrc()})`,
          ].join(';'),
        }),
      ]),
      h('div', { style: 'visibility: hidden;' }, [
        h('div', {
          style: [
            'width: 100px',
            'height: 100px',
            `background-image: url(${getImageSrc()})`,
          ].join(';'),
        }),
      ]),
    ]))
    await expect.element(screen.getByText(`total: 1`)).toBeInTheDocument()
    await expect.element(screen.getByText('Loading')).toBeInTheDocument()

    await expectReady(screen)
  })
})
```

![all test](/check-images-ready/all-test.png)

測試順利過關！%( ‧ω‧)ノ╰(‧ω‧ )%

完整測試程式可以在[這裡取得](https://github.com/Codfisher/cod-aquarium/blob/main/composables/use-images-ready.spec.ts)

Vitest Browser Mode 體驗真滴很不錯，不過還在實驗中，不清楚會不會有奇怪的問題。

期待正式釋出的那一天。%(ゝ∀・)b%

## 總結 🐟

* 測試圖片載入狀態的功能，確保列印時圖片都載入完成
* 使用 Vue 的 Composition API 實作 `useImagesReady`
* 使用 `useEventListener` 偵測圖片載入事件
* 使用 Vitest 的 Browser Mode 進行測試

---

---
url: /blog-vue/solve-fetch-waterfall-with-data-loader.md
description: 元件層層嵌套，API 一個等一個？來看看 Vue Data Loader 怎麼解決 fetch 瀑布流問題。(ﾉ>ω<)ﾉ
---

![solve-fetch-waterfall-with-data-loader](/solve-fetch-waterfall-with-data-loader.webp){.cover}

# 用 Vue Router 的 Data Loader 解決 fetch 瀑布流問題

大家好，我是鱈魚。(｡･∀･)ﾉﾞ

會寫這篇其實是很久以前看到 Vue Router 新增 [Data Loader](https://router.vuejs.org/data-loaders/)。

由於專案幾乎都標配了 TanStack Query，慧根不足的我，實在是想不到有甚麼具體情境需要 Data Loader。%(´・ω・\`)%

直到最近某次與 AI 討論時，AI 提到 fetch 瀑布流（Waterfall）問題，才讓我重新想到 Data Loader 並來實際實驗看看。

所謂的 fetch 瀑布流（Waterfall），就是指嵌套元件中的 API 請求需要一個個排隊，導致畫面跟著一塊塊載入的現象。

這樣說太抽象了，來看看具體範例。%◝( •ω• )◟%

## 什麼是 fetch 瀑布流？

以下是一個簡單的三層巢狀元件，需要的 ID 資料已存在網址上，UI 卻只能一個個載入。

你說這不就是設計不良？方便展示的範例啦，難保不會遇到這種情況嘛。%(́⊙◞౪◟⊙‵)%

```vue
<!-- PostPage.vue -->
<script setup lang="ts">
import { useAsyncState } from '@vueuse/core'
import { useRoute } from 'vue-router'

const route = useRoute()
const postId = Number(route.params.id) // 從網址取得 postId

const { state: post } = useAsyncState(() => fetchPost(postId), undefined) // 需耗時 1 秒
</script>

<template>
  <!-- 實務上往往為了顯示 Loading 畫面而使用外層 v-if -->
  <div v-if="post">
    <h1>{{ post.title }}</h1>

    <!-- 等上層 1 秒才開始掛載 -->
    <post-comment-list :post-id="postId" />
  </div>
  <div v-else>
    載入中⋯
  </div>
</template>
```

```vue
<!-- PostCommentList.vue -->
<script setup lang="ts">
import { useAsyncState } from '@vueuse/core'

const props = defineProps<{ postId: number }>()

const { state: commentList } = useAsyncState(
  () => fetchCommentList(props.postId), // 再等 1 秒
  undefined,
)
</script>

<template>
  <!-- 留言載入時，一樣用 v-if 處理狀態 -->
  <ul v-if="commentList">
    <li v-for="comment in commentList" :key="comment.id">
      {{ comment.content }}
    </li>

    <!-- 一樣等上層 1 秒才開始掛載 -->
    <post-related-list :post-id="postId" />
  </ul>
</template>
```

```vue
<!-- PostRelatedList.vue -->
<script setup lang="ts">
import { useAsyncState } from '@vueuse/core'

const props = defineProps<{ postId: number }>()

const { state: relatedList } = useAsyncState(
  () => fetchRelatedPosts(props.postId), // 又等 1 秒
  [],
)
</script>
```

API 沒有順序耦合，可以同時發起，但只要子元件被 `v-if`（或 `Suspense`）擋住，**父元件還沒拿到資料，子元件根本無從建立**，瀑布流就這樣產生了：

```
User     ████████░░░░░░░░░░░░░░░░  1s
Post     ░░░░░░░░████████░░░░░░░░  1s
Comment  ░░░░░░░░░░░░░░░░████████  1s
                            總耗時：3s
```

三個各 1 秒的 API，因為排隊累加，總共花了 3 秒。%( ˘•ω•˘ )%

## 常見的解法

最直覺的解法，就是全在最外層父元件用 `Promise.all` 一次打完：

```ts
const [user, postList, commentList] = await Promise.all([
  fetchUser(1),
  fetchPostList(1),
  fetchCommentList(1),
])
```

這雖然解決了瀑布流，卻會引發新問題：

* **資料與元件脫鉤**：原本各元件自行抓資料，現在全堆在父元件。
* **props 滿天飛**：子元件不能自己要資料，只能仰賴父元件層層餵進來。

有沒有辦法既讓元件獨立抓自己的資料，又同時做到平行載入呢？

## Vue Router 的 Data Loader

[Data Loader](https://router.vuejs.org/data-loaders/) 是 `unplugin-vue-router` 提供的功能，核心精神是**讓「資料請求」與元件同檔共存，卻不受元件生命週期束縛，由路由在換頁前提早平行觸發**。

如此一來，Loader 一樣寫在子元件檔案中，不需要拉到父元件，資料歸屬一目了然，元件獨立性完整保留。

::: tip Data Loader 詳細說明
由於這篇文章並非介紹 Data Loader，關於 Data Loader 具體用法與詳細說明，還請大家參考[官方文件](https://router.vuejs.org/data-loaders/)。
:::

以下是宣告並呼叫 Loader 的簡易範例。

```vue
<!-- PostCommentList.vue -->
<script lang="ts">
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'

// 1. 在子元件宣告 Loader。參數直接從路由 (to.params.id) 來，不用等父元件傳 props！
export const useCommentListLoader = defineBasicLoader('/posts/:id', async (to) => fetchCommentList(Number(to.params.id)))
</script>

<script setup lang="ts">
// 2. 拿資料囉！由於路由切換前早就提早打過 API，這裡的資料是「瞬間」備妥的！
const { data: commentList } = useCommentListLoader()
</script>

<template>
  <ul>
    <li v-for="comment in commentList" :key="comment.id">
      {{ comment.content }}
    </li>
    <post-related-list />
  </ul>
</template>
```

這種做法不但維持「元件自管資料」的乾淨架構，多個 Loader 還會在跳轉瞬間**一起幫你平行抓好資料**：

```
Post     ████████░░░░░░░░░░░░░░░░  1s
Comment  ████████░░░░░░░░░░░░░░░░  1s
Related  ████████░░░░░░░░░░░░░░░░  1s
                            總耗時：1s
```

同樣三支 API，從 3 秒縮短到 1 秒。%=͟͟͞͞( •̀д•́)%

::: tip defineBasicLoader 為什麼要放在非 setup 的 `<script>` 中？
因為 loader 必須寫在**模組層級 (module level)**，路由器才有辦法在「切換頁面（元件建立前）」階段，掃描到它並提前執行。

`<script setup>` 裡頭的程式碼屬於元件層級，一定要進到頁面、建立元件時才會跑，這就白白錯失了「換頁前預先平行抓取資料」的最佳時機。
:::

## Data Loader 如何處理資料依賴？

你可能會想：「如果 B API 必須使用 A API 抓回來的資料，也就是 API 之間有順序耦合呢？改用 Data Loader 就能平行嗎？」

有時依賴確實避不掉，就像身上的油怎麼樣都甩不掉。%(╥ω╥\`)%

但 Loader 有趣的部分是它發生於**切換頁面之前（導航階段）**，因此你能直接在 Loader 裡串聯等待：

```ts
export const useDashboardLoader = defineBasicLoader('/dashboard', async () => {
  const user = await fetchMe()
  // 等待 fetchMe 回傳後再去抓文章
  const posts = await fetchPostList(user.id)
  return { user, posts }
})
```

雖然從網路看依舊是瀑布流，但優勢在於所有等待都集中在換頁前的「最頂層全局進度條」，等畫面真正切換時資料已備齊，大幅減少版面跳動（Layout Shift）問題。

不過 Basic Loader 每次導航都會重新執行，沒有跨導航的快取機制。

::: tip 需要跨導航快取？試試 Colada Loader
[Colada Loader](https://router.vuejs.org/data-loaders/colada/) 基於 `@pinia/colada`，除了保有平行載入的能力，還額外提供：

* **快取**：透過 `staleTime` 控制資料新鮮度，期限內不重發請求
* **去重複**：同一時間多處呼叫相同 Loader，只會發出一次請求

```ts
import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada'

export const useMeLoader = defineColadaLoader('/dashboard', {
  key: () => ['me'],
  async query() {
    return fetchMe()
  },
  staleTime: 1000 * 60 * 5, // 5 分鐘內不重新請求
})
```

即使多個 Loader 都需要 `fetchMe`，也只會發出一次請求，其餘直接拿快取，用過 TanStack Query 的朋友應該會覺得很熟悉。

Colada Loader 也支援 SSR，在 Nuxt 上可以保證 Hydration 不會觸發額外的 fetch 操作。
:::

甚麼？你說叫後端濃縮成一支 API？成功的話，還請分享一下你抓到他什麼把柄。%(́⊙◞౪◟⊙‵)%

## 總結 🐟

* 瀑布流是嵌套元件中的 API 請求需要一個個排隊，導致畫面跟著一塊塊載入的現象。
* 在最外層使用 `Promise.all` 確實能解決，但資料邏輯卻死綁在父元件，犧牲元件獨立性。
* Data Loader 讓載入動作跟著元件走，由路由器提早平行執行，兼顧效能與程式碼乾淨度。

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。

有錯誤或任何想法還請多多指教。%( ´∀\`)~♥%

---

---
url: /blog-vue/vue-v-once-preserve-canvas-ref.md
description: 註冊在 DOM 的事件莫名失效？來看看如何解決這個問題。(´・ω・`)
---

![vue-v-once-preserve-canvas-ref](/vue-v-once-preserve-canvas-ref.webp){.cover}

# 神隱的 DOM ref

大家好，我是鱈魚。(｡･∀･)ﾉﾞ

最近在開發 [CodStack](/aquarium/codstack/) 時，遇到一個詭異的問題：明明 `canvas` 有綁 `ref`，Babylon.js 也正常初始化，但只要開啟右鍵選單，原本註冊在 canvas 的事件就失效了。

讓我們來研究研究。

## 重現問題

我把 3D 場景初始化的內容放在 `use-babylon-simple` composable 中，簡化後的結構如下：

```typescript
export function useBabylonSimple(
  canvasRef: MaybeRefOrGetter<HTMLCanvasElement | null>,
) {
  let engine: Engine | null = null
  let scene: Scene | null = null

  // 省略初始化過程

  const canvasSize = reactive(useElementSize(canvasRef))
  watch(canvasSize, () => {
    engine?.resize()
  })
}
```

其中 `useElementSize` 偵測 canvas 的尺寸變化，並在尺寸變化時調用 `engine.resize()` 方法。

可以注意到不管你怎麼調整寬度，場景會自動調整尺寸，方塊不會扁掉。%◝( •ω• )◟%

接下來讓我們把 `canvas` 放進 Nuxt UI 的 `UContextMenu` 元件中，讓我們可以開啟右鍵選單。

```vue
<template>
  <u-context-menu :items="contextMenuItems">
    <canvas ref="canvasRef" class="w-full h-full outline-none block" />
  </u-context-menu>
</template>
```

現在會發現鬼故事發生了，**開啟右鍵選單前**改變寬度一切正常，但**開啟右鍵選單後**改變寬度會發現方塊扁掉了！%╭(°A ,°\`)╮%

::: warning 所以說那個問題呢？
結果文章上線後，我發現此問題**僅在 dev 模式下發生**，prod 模式不受影響，不確定具體原因。%(´ー\`)%

如果大家知道到底發生了甚麼事，還請不吝分享。%( ´∀\`)~♥%
:::

## 為什麼會壞掉？

其實我不知道到底發生甚麼事，以下是和 AI 一起抽絲剝繭、嘗試驗證的心得。%ヽ(́◕◞౪◟◕‵)ﾉ%

**根本原因是 Nuxt UI 與 reka-ui 的 `as-child` 機制導致 `ref` 永久遺失。**

Nuxt UI 的 `UContextMenu` 在內部對 trigger 使用了 `as-child` 模式。

`as-child` 是 reka-ui（Nuxt UI 底層的 headless 元件庫）提供的一種渲染模式。一般情況下，元件會用自己的標籤（例如 `<span>`）包裹 slot 內容：

```html
<!-- 沒有 as-child：Primitive 渲染成 <span> 包裹 slot -->
<span data-state="closed" @contextmenu="...">
  <canvas />
</span>
```

加上 `as-child` 後，元件不會產生自己的 wrapper 元素，而是將所有 attrs（`data-state`、事件處理、樣式等）**直接合併到 slot 的第一個子元素上**：

```html
<!-- 有 as-child：attrs 直接合併到 canvas -->
<canvas data-state="closed" @contextmenu="..." />
```

這樣的好處是不會產生多餘的 DOM 層級，讓開發者能完全控制渲染結構。而在實作上，reka-ui 的 `Slot` 元件透過 Vue 的 `cloneVNode` 來實現這個合併，**每次 render 都會產生一個全新的 cloned VNode**。

當選單開啟時，`data-state` 從 `"closed"` 變為 `"open"`，觸發 `ContextMenuTrigger` 重新渲染，`Slot` 隨之重新執行 `cloneVNode`。

透過實測我們發現了一個關鍵事實：**canvas 的 DOM 元素完全沒被替換**。用原生 `ResizeObserver` 直接綁定在初始元素上，開啟選單後持續改變寬度，observer 依然正常觸發，證明 DOM 元素從頭到尾都是同一個。

真正的問題是 **`ref` 永久遺失**：Vue 在 patch 時 unset 了舊 VNode 的 ref（`canvasRef = null`），但 `cloneVNode` 產生的新 VNode **沒有攜帶 ref**，所以 Vue 無法將 ref 設定回來。`canvasRef` 從此永遠停留在 `null`。

由於 `useResizeObserver` 監聽的是 `canvasRef`（而非 DOM 元素本身），ref 變成 `null` 後 observer 自然就沒有對象可以觀察，最終造成：

1. **`useElementSize` 不再響應尺寸變化**：使 `engine.resize()` 不再被觸發
2. **畫面比例失真**：引擎持續以舊的畫布尺寸渲染，但 CSS 已經改變了 canvas 的顯示大小，方塊就被拉伸變形了

總解一下因果關係：

1. Slot 的 cloneVNode 產生的新 VNode 遺失了 ref
2. Vue unset 舊 ref 後無法 set 回來
3. canvasRef 永久為 null
4. useResizeObserver 失去觀察目標。

```vue
<template>
  <div class="flex flex-col gap-4">
    <div class="text-sm font-medium">
      Debug：追蹤 ref 與 ResizeObserver 行為
    </div>

    <div class="flex flex-wrap items-center gap-3">
      <label class="shrink-0 text-sm">
        調整寬度
      </label>

      <USlider
        v-model="resizePercent"
        :min="50"
        :max="100"
        class="flex-1 accent-primary"
      />
    </div>

    <div class="text-xs opacity-50">
      步驟：1. 拖曳寬度 → 2. 右鍵開啟選單 → 3. 再拖曳寬度，觀察哪些 observer 停止觸發
    </div>

    <div
      class="transition-all"
      :style="{ width: `${resizePercent}%` }"
    >
      <UContextMenu :items="menuItems">
        <div
          ref="targetRef"
          class="w-full h-20 rounded-lg border border-black/5 dark:border-white/5 bg-primary/10 flex items-center justify-center text-sm"
        >
          沒有 v-once
        </div>
      </UContextMenu>
    </div>

    <!-- log 輸出 -->
    <div class="flex flex-col gap-1 max-h-80 overflow-y-auto rounded-lg bg-black/5 dark:bg-white/5 p-3">
      <div class="text-xs font-medium opacity-50 mb-1">
        事件 Log（新的在上面）
      </div>
      <div
        v-for="(log, index) in logs"
        :key="index"
        class="text-xs font-mono"
        :class="{
          'text-red-500': log.type === 'error',
          'text-yellow-500': log.type === 'warn',
          'text-green-500': log.type === 'success',
          'text-blue-500': log.type === 'native',
          'opacity-60': log.type === 'info',
        }"
      >
        {{ log.message }}
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import type { ContextMenuItem } from '@nuxt/ui/.'
import { useElementSize, useResizeObserver } from '@vueuse/core'
import { computed, onBeforeUnmount, ref, useTemplateRef, watch } from 'vue'

const targetRef = useTemplateRef('targetRef')

interface LogEntry {
  type: 'info' | 'warn' | 'error' | 'success' | 'native';
  message: string;
}

const logs = ref<LogEntry[]>([])

function addLog(type: LogEntry['type'], message: string) {
  logs.value.unshift({ type, message })
  if (logs.value.length > 80) {
    logs.value.length = 80
  }
}

// ===== 1. 追蹤 ref 變化（sync watcher 捕捉中間狀態） =====
let previousElement: HTMLElement | null = null
watch(targetRef, (newElement) => {
  const isSameDOM = newElement === previousElement
  if (newElement === null) {
    addLog('warn', `ref → null`)
  }
  else {
    addLog(
      isSameDOM ? 'info' : 'error',
      `ref → element（${isSameDOM ? '同一個 DOM ✓' : '不同的 DOM ✗'}）`,
    )
  }
  if (newElement) {
    previousElement = newElement
  }
}, { flush: 'sync' })

// ===== 2. VueUse useResizeObserver =====
let vueUseCount = 0
useResizeObserver(targetRef, () => {
  vueUseCount++
  addLog('info', `[VueUse useResizeObserver] 觸發 #${vueUseCount}`)
})

// ===== 3. VueUse useElementSize =====
const elementSize = useElementSize(targetRef)
watch(() => elementSize.width.value, (width) => {
  if (width > 0) {
    addLog('success', `[VueUse useElementSize] width = ${Math.round(width)}`)
  }
})

// ===== 4. 原生 ResizeObserver（完全繞過 VueUse） =====
let nativeObserver: ResizeObserver | null = null
let nativeCount = 0

watch(targetRef, (element) => {
  if (!element)
    return

  // 只在第一次綁定，之後不再重建
  if (nativeObserver)
    return

  nativeObserver = new ResizeObserver(() => {
    nativeCount++
    addLog('native', `[原生 ResizeObserver] 觸發 #${nativeCount}`)
  })
  nativeObserver.observe(element)
}, { immediate: true })

onBeforeUnmount(() => {
  nativeObserver?.disconnect()
})

// ===== 控制 =====
const resizePercent = ref(100)

const menuItems = computed<ContextMenuItem[][]>(() => [
  [
    { label: 'Action A', icon: 'material-symbols:select-all-rounded' },
    { label: 'Action B', icon: 'material-symbols:flip-camera-ios-outline-rounded' },
  ],
])
</script>

```

就結論而言，這似乎是 reka-ui 的 `Slot` 元件實作上的 bug，導致 `ref` 永久遺失。

搜尋了一下，似乎還真的有人遇到類似的問題，還有相關討論：

* [\[Bug\]: ref not working properly in custom-wrapped Tooltip with asChild prop](https://github.com/unovue/reka-ui/issues/1580)
* [\[Bug\]: DropdownMenuContent as-child > ref element is not updated when closed](https://github.com/unovue/reka-ui/issues/694)
* [Another implementation of asChild](https://github.com/unovue/reka-ui/discussions/1324)

如果各位大大知道更多資訊，還請不吝分享。%( ´∀\`)~♥%

## 如何除靈

所以要怎麼除靈呢？只能改變 template 結構嗎？的確也可以，只是有一個更簡單的解決方案。%( •̀ ω •́ )✧%

那就是出場次數堪比日本製壓縮機，聊天紀錄永遠輪迴在「下次約」，我們那個極度少見的朋友：**`v-once`**！%ヽ(•̀∀•̀ヽ )%

路人：「你這樣是歧視 v-once。%ლ(╹ε╹ლ)%」

鱈魚：「不然你問各位讀者，有用過的舉手，我數數看 %(´・ω・\`)%」

`v-once` 的作用是告訴 Vue：「這個節點只渲染一次，之後的更新都跳過」。

前面提到問題的根源在於 `Slot` 元件每次 render 都會對 slot 內容執行 `cloneVNode`，而 clone 出來的新 VNode 遺失了 `ref`，導致 Vue unset 舊 ref 後無法 set 回來。

加上 `v-once` 後，Vue 會在首次渲染時快取這個 VNode。後續 `Slot` 呼叫 `slots.default()` 取得的是**快取的 VNode**，而非重新建立的新 VNode。因此即使 `cloneVNode` 再次執行，clone 的來源始終是同一個帶有 ref 的 VNode，`ref` 不會被 unset，自然也就不會遺失。

用法很簡單，就是加上一個 `v-once` 指令。

```vue
<template>
  <context-menu :items="contextMenuItems">
    <canvas v-once ref="canvasRef" class="w-full h-full outline-none block" />
  </context-menu>
</template>
```

以下是使用 `v-once` 前後的對比，可以看到使用 `v-once` 後，即可開啟選單且不管怎麼調整寬度，方塊都不會扁掉。%(\*´∀\`)~♥%

::: warning 所以說那個問題呢？
如同剛剛提到的現象，此問題**僅在 dev 模式下發生**，prod 模式不受影響，所以大家應該看不出差別。%(›´ω\`‹ )%

如果大家知道到底發生了甚麼事，還請不吝分享。%( ´∀\`)~♥%
:::

## 什麼時候適合用 v-once

`v-once` 在以下情境非常實用：

* **第三方函式庫接管的 DOM 元素**：canvas（WebGL）、地圖容器、影片播放器等
* **不需要 Vue 響應式更新的靜態內容**：一次性渲染的大量列表項目
* **放在會頻繁更新的父元件 slot 裡的穩定元素**：就像本文的案例

反過來說，如果元素本身的 attribute 或內容需要隨資料變化，就不適合用 `v-once`，因為加上去之後此 DOM 的內容就再也不會更新了。

如同那些被作者棄坑的作品，再也不會更新了。%(╥ω╥\`)%

## 總結 🐟

* 使用 `as-child` 模式的元件（如 Nuxt UI 的 `UContextMenu`），底層的 reka-ui `Slot` 元件會在每次 render 時對 slot 內容執行 `cloneVNode`，導致 **`ref` 永久遺失**
* 這是 reka-ui 的[已知問題](https://github.com/unovue/reka-ui/issues/1580)，`cloneVNode` 沒有正確保留原始 VNode 的 `ref`
* `v-once` 讓 Vue 快取 VNode，使 `Slot` 每次拿到的都是同一個帶有 `ref` 的 VNode，避免 ref 被 unset
* `v-once` 適合用在由第三方函式庫（Babylon.js、Three.js 等）接管、不需要 Vue 響應式更新的 DOM 元素上
* 注意 `v-once` 會讓該元素上所有的動態綁定失效，只適合用在不需要 Vue 更新的元素

---

---
url: /blog-program/for-each-and-for-loop.md
description: 常聽到別人說特定情境下 forEach 比 for 迴圈還慢，剛好有個好機會，讓我來試試看吧。ԅ(´∀` ԅ)
---

![for-each-and-for-loop](/for-each-and-for-loop.webp){.cover}

# 聽說 forEach 比 for 迴圈慢？

常聽到別人說：某些情況下 `forEach` 比 `for` 迴圈還慢。

babylon.js 的 Particle System 文件中，[更新大量粒子](https://doc.babylonjs.com/features/featuresDeepDive/particles/particle_system/customizingParticles/)的迴圈預設也都是使用 `for` 迴圈。

最近酷酷的元件做了一個[下雪背景](https://chillcomponent.codlin.me/components/bg-snow/)，粒子數量與計算量相對得多。

剛好藉這個機會來實測看看不同迴圈的實際效果。%ԅ(´∀\` ԅ)%

::: tip
以下實驗基於 Google Chrome v131.0.6778.110

超不嚴謹，僅針對此元件情境，請不要當作正式結論。( ﾟ∀。)
:::

## 實測

基於原本的[程式碼](https://gitlab.com/side_project/chill-component/-/blob/main/src/components/bg-snow/bg-snow-worker.ts?ref_type=heads#L97)，加上 `performance.now` 計算執行時間，且每運行 100 次再輸出一次，避免 devtool 炸掉。

```ts
let count = 0
particleSystem.updateFunction = function (particles) {
  const startTime = performance.now()

  // 計算 staticMap 與粒子是否有碰撞
  for (const id in staticMap) {
    // ...
  }

  const endTime = performance.now()

  if (count % 100 === 0) {
    console.log({
      particles: particles.length,
      time: endTime - startTime,
    })
  }
  count++
}
```

### for

```text
{particles: 1159, time: 0.5}
{particles: 1185, time: 1}
{particles: 1170, time: 0.5999999046325684}
{particles: 1195, time: 1}
{particles: 1200, time: 1.2000000476837158}
{particles: 1194, time: 0.7000000476837158}
{particles: 1201, time: 0.6999999284744263}
{particles: 1182, time: 1.1999999284744263}
```

可以看到原本粒子數量最多大約在 1200 左右，執行時間在 0.5 ~ 1.2 ms 之間。

### forEach

現在來看看 `forEach` 的執行時間。

::: tip
staticMap 的 `for` 部分維持不變，因為這次只比較矩陣 `forEach` 與 `for` 的差異。
:::

```ts
particleSystem.updateFunction = function (particles) {
  const startTime = performance.now()
  // 計算 staticMap 與粒子是否有碰撞
  for (const id in staticMap) {
    const bounding = staticMap[id]
    if (!bounding)
      continue

    /** 依照文件作法更新粒子
     *
     * https://doc.babylonjs.com/features/featuresDeepDive/particles/particle_system/customizingParticles/
     */
    particles.forEach((particle, index) => {
      // ...
    })
  }

  // ...
}
```

來看看結果

```text
{particles: 1163, time: 1.100000023841858}
{particles: 1168, time: 1.2000000476837158}
{particles: 1184, time: 1.2000000476837158}
{particles: 1180, time: 1}
{particles: 1171, time: 1}
{particles: 1161, time: 1.2000000476837158}
{particles: 1174, time: 1.1999999284744263}
{particles: 1166, time: 1.2999999523162842}
```

可以注意到耗時多了一點點，執行時間在 1 ~ 1.3 ms 之間。

### for of

再來試試看 `for of`。

```ts
particleSystem.updateFunction = function (particles) {
  const startTime = performance.now()
  // 計算 staticMap 與粒子是否有碰撞
  for (const id in staticMap) {
    const bounding = staticMap[id]
    if (!bounding)
      continue

    /** 依照文件作法更新粒子
     *
     * https://doc.babylonjs.com/features/featuresDeepDive/particles/particle_system/customizingParticles/
     */
    let index = -1
    for (const particle of particles) {
      index++
      // ...
    }
  }

  // ...
}
```

結果：

```text
{particles: 1189, time: 1.2000000476837158}
{particles: 1186, time: 1.5}
{particles: 1185, time: 1.5}
{particles: 1182, time: 1.100000023841858}
{particles: 1190, time: 0.7999999523162842}
{particles: 1188, time: 1.100000023841858}
{particles: 1187, time: 1.399999976158142}
{particles: 1185, time: 2.1999999284744263}
{particles: 1181, time: 1.1999999284744263}
{particles: 1186, time: 1}
```

和 `for` 差不多，但是偶而會跑出 2 ms 的時間。

## 暴風雪！

差異不大好像不夠精彩，讓我們把粒子數量加好加滿，變成暴風雪看看！ლ（´∀\`ლ）

![snowstorm](/for-each-and-for-loop/snowstorm.png)

超多雪！ᕕ( ﾟ ∀。)ᕗ

`for`

```text
{particles: 97970, time: 360.10000002384186}
{particles: 98122, time: 340}
{particles: 98118, time: 342.7000000476837}
{particles: 98035, time: 355.2000000476837}
{particles: 98069, time: 348.60000002384186}
```

`forEach`

```text
{particles: 98275, time: 304.09999990463257}
{particles: 98491, time: 273.5}
{particles: 98092, time: 356}
{particles: 97463, time: 472.7000000476837}
{particles: 98080, time: 342}
```

`for of`

```text
{particles: 99365, time: 122.20000004768372}
{particles: 99052, time: 181.59999990463257}
{particles: 98330, time: 289.3000000715256}
{particles: 97579, time: 390.7999999523163}
{particles: 98233, time: 329.3000000715256}
```

粒子數量大約在 98k 左右，可以看到結果很有趣：

* `for` 與 `forEach` 時間差不多，但是 `for` 比較穩定
* `for of` 最快，但偶而會變慢。

以上就是這次的超不專業的不嚴謹實驗。੭ ˙ᗜ˙ )੭

究竟誰比較快，會因為情境、runtime、瀏覽器最佳化與程式寫法而有所不同，最好應該實際跑過 benchmark 再做選擇。

## 總結 🐟

* 元素數量不多時，`forEach` 與 `for` 差異不大。
* 性能會因情境、runtime、瀏覽器最佳化與程式寫法而有所不同，最好應該實際跑過 benchmark 再做選擇。

---

---
url: /blog-ocean-world/markdown-it-custom-syntax.md
description: 顏文字換行會原地變為一坨亂碼，該怎麼辦呢？(PД`q｡)
---

![markdown-it-custom-syntax](/markdown-it-custom-syntax.webp){.cover}

# 臉被切到了怎麼辦！來自定義 markdown 語法吧

段落文字太長時，在句尾的顏文字很容易被換行，像這樣 (＃°
Д°)

一秒便變成了一坨不知所云的亂碼。%( ´•̥̥̥ ω •̥̥̥\` )%

原本解法是像這樣 `<span class="text-nowrap">(>'-'<)</span>`，把顏文字用 HTML 包起來。

有效，但是實在不夠~~懶人~~優雅。%( ・ิω・ิ)%

既然此部落格基於 markdown 寫作，那麼就來調整一下 markdown-it 吧！%◝(≧∀≦)◟%

## 自定義語法

markdown-it 設計之初就考慮到了擴展性，自定義語法小菜一碟。

查了一圈 markdown 還沒被使用的符號，看起來 `%` 還不錯，所以預計使用 % 符號建立一個決不換行的區塊。

也就是 `%(>'-'<)%` 自動變為 `<span class="text-nowrap">(>'-'<)</span>`

首先建立一個 plugin。

`.vitepress\plugin\markdown-it-nowrap.ts`

```ts
import type MarkdownIt from 'markdown-it'

const RULE_NAME = 'nowrap_span'
const MARKER = '%'

/** 緊跟在數字後面的 % 是百分比（4.2%、100%），不是標記 */
function isPercentSign(source: string, markerIndex: number) {
  const previousChar = source[markerIndex - 1]
  return previousChar !== undefined && previousChar >= '0' && previousChar <= '9'
}

/** 使用 MARKER 包圍文字，即可建立不換行的元素
 * https://vitepress.dev/guide/markdown#advanced-configuration
 *
 * 內文的百分比會跟標記衝突，例如「掉 4.2%。[連結](url) 差 50%」，
 * 兩個百分比之間的文字（含連結）會整段被當成顏文字吞掉，
 * 所以數字後面的 % 一律視為百分比，且顏文字不跨行。
 *
 * @param md
 */
export function markdownItNowrap(md: MarkdownIt) {
  /** 解析 % 區塊
   *
   * 顏文字僅用於 inline 內容，所以註冊在 inline ruler 之前
   */
  md.inline.ruler.before('emphasis', RULE_NAME, (state, silent) => {
    const start = state.pos
    const markerLength = MARKER.length

    // 如果不是 %，直接跳過
    if (state.src.slice(start, start + markerLength) !== MARKER) {
      return false
    }

    if (isPercentSign(state.src, start)) {
      return false
    }

    let end = state.src.indexOf(MARKER, start + markerLength)
    while (end !== -1 && isPercentSign(state.src, end)) {
      end = state.src.indexOf(MARKER, end + markerLength)
    }
    if (end === -1) {
      return false
    }

    // 顏文字不會跨行，跨行代表這個 % 沒有配對
    if (state.src.slice(start, end).includes('\n')) {
      return false
    }

    if (!silent) {
      const token = state.push(RULE_NAME, '', 0)
      token.content = state.src.slice(start + markerLength, end).trim()
    }

    state.pos = end + markerLength
    return true
  })

  /** 渲染自定義區塊內容 */
  md.renderer.rules[RULE_NAME] = (tokens, idx) => {
    if (!tokens[idx]?.content) {
      return ''
    }

    return `<span class="text-nowrap">${tokens[idx].content}</span>`
  }
}

```

接著依照[文件指示](https://vitepress.dev/guide/markdown#advanced-configuration)，在 vitepress 使用 plugin。

`.vitepress\config.mts`

```ts
// ...

// https://vitepress.dev/reference/site-config
export default ({ mode }: { mode: string }) => {
  // ...

  return withMermaid({
    title: '鱈魚的魚缸',
    // ...

    markdown: {
      lineNumbers: true,
      config(md) {
        md.use((md) => markdownItBaseImg(md, mode))
        md.use(markdownItNowrap) // [!code ++]
      },
    },

    // ...
  })
}
```

完工！

現在被 % 包圍的文字都會自動變成帶有 text-nowrap class 的 `span` 了！

![nowrap-span](/markdown-it-custom-syntax/nowrap-span.png)

對原理有興趣的讀者們，歡迎來[看看這篇文章](https://ithelp.ithome.com.tw/articles/10354983)。%◝( •ω• )◟%

## 總結 🐟

* markdown-it 可自由擴展自定義語法
* 透過自定義語法讓顏文字不會被換行

---

---
url: /blog-vue/vue-directive-and-effect-scope.md
description: Directive 內沒有自動解除響應式資料與副作用的魔法呦 (・∀・)
---

![vue-directive-and-effect-scope](/vue-directive-and-effect-scope.webp){.cover}

# 自動解除的魔法呢？Vue Directive 和 Effect Scope

Vue 除了元件與 Composition API 外，還有很方便的自定義 [Directive](https://cn.vuejs.org/guide/reusability/custom-directives)。

前陣子的新作 - [彈珠檯](https://chillcomponent.codlin.me/components/util-pinball/)，就用了自定義指令，可以將 DOM 變成彈珠檯的中的機關，像這樣：

```vue
<template>
  <div
    v-pinball-mech
    class="wall absolute bottom-0 left-0 h-4 w-full rounded-full"
  />
</template>
```

其中有個需要取得 DOM 尺寸與位置的邏輯，這裡取簡化後的核心程式碼：

```ts
export const vPinballMech: Directive = {
  mounted(el) {
    if (!(el instanceof HTMLElement)) {
      console.warn('v-pinball-mech 只能用於 HTMLElement')
      return
    }

    const bounding = reactive(useElementBounding(el))

    const id = store.add({
      options,
      ...bounding,
    })

    watch(bounding, (value) => {
      store.update(id, value)
    }, { deep: true })
  },
}
```

當元素綁定後，在 `store` 新增此元素，配合 `useElementBounding` 取得元素尺寸並用 `watch` 同步尺寸變化。

不過當元件移除時，指令中 `watch` 與 `useElementBounding` 並不會自動解除呦。%( ﾟ ∀。)%

## 真的會這樣嗎？

要證明這件事，其實也相當簡單，來個 [`useIntervalFn`](https://vueuse.org/shared/useIntervalFn/)：

正常情況下 `useIntervalFn` 會在 Effect Scope 停止時自動解除。

```ts
export const vPinballMech: Directive = {
  mounted(el, binding) {
    useIntervalFn(() => {
      console.log('cod')
    }, 1000)
  },
}
```

可以注意到即使元件被移除，`cod` 仍然會不斷出現。

為甚麼會這個樣子呢？這個我們可以反過來想，Vue 元件移除時如何清理響應式資料與副作用呢？

相關概念其實曾經在[這篇文章](/blog-vue/vue-watch-may-cause-a-memory-leak)提過。

主要是 Vue 會在元件建立自動產生元件範圍的 [Effect Scope](https://cn.vuejs.org/api/reactivity-advanced#effectscope) 並在移除時自動停止 Effect Scope。

而 Directive 並沒有自己的 Effect Scope，所以裡面的響應式資料不會被自動清理。

所以怎麼知道 Directive 沒有 Effect Scope ？很簡單，使用 `getCurrentScope` 即可：

```ts
export const vPinballMech: Directive = {
  mounted(el) {
    if (!(el instanceof HTMLElement)) {
      console.warn('v-pinball-mech 只能用於 HTMLElement')
      return
    }

    const currentScope = getCurrentScope()
    console.log('currentScope: ', currentScope)

    // ...
  },
}
```

會注意到 console 結果是 `currentScope: undefined`。

你說為甚麼 Directive 內可以取得來源元件，卻沒有 Effect Scope？%(´・ω・\`)%

具體原因我也不清楚，就看有沒有大大知道為甚麼了。

## 所以該怎麼辦呢？

解決方法其實很簡單，就是自己建一個 Effect Scope，然後自己的 Scope 自己關。%ლ（´∀\`ლ）%

不過不知道為甚麼在 `mounted` 之外的地方呼叫 `scope.stop()` 都沒有效（無效的程式碼在[這裡](https://gitlab.com/side_project/chill-component/-/blob/develop/src/components/util-pinball/v-pinball-mech.ts?ref_type=heads)）

所以改成在 `mounted` 中持續判斷 DOM 是否依然存在，不存在則解除。

```ts
export const vPinballMech: Directive = {
  mounted(el) {
    if (!(el instanceof HTMLElement)) {
      console.warn('v-pinball-mech 只能用於 HTMLElement')
      return
    }

    const scope = effectScope()

    scope.run(() => {
      const bounding = reactive(useElementBounding(el))

      const id = store.add({
        options,
        ...bounding,
      })

      watch(bounding, (value) => {
        store.update(id, value)
      }, { deep: true })

      useIntervalFn(() => {
        // 檢查元素是否還在 DOM 中，否則停止 effect scope
        if (!el.isConnected) {
          scope.stop()
        }
      }, 100)
    })
  },
}
```

現在在元件被移除後，響應式資料與副作用都會自動解除了。%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

## 總結 🐟

* Vue Directive 自身沒有 Effect Scope，所以裡面的響應式資料與副作用不會被自動清理。
* 可自行建立 Effect Scope，並在適當時機停止。

---

---
url: /blog-program/make-mistakes-invisible-with-sentry.md
description: 系統上線後常常遇到前端錯誤不好追蹤問題，使用者很難說得清楚發生甚麼事，Sentry 可以協助記錄錯誤，並且提供更多資訊，讓開發者更容易追蹤問題。
---

![make-mistakes-invisible-with-sentry](/make-mistakes-invisible-with-sentry.webp){.cover}

# 藉由 Sentry 讓錯誤無所遁形吧！

系統上線後常常遇到前端錯誤不好追蹤、難以重現。

使用者也很難說得清楚花黑噴。( ´•̥̥̥ ω •̥̥̥\` )

鱈魚：「只好默默地忽略。ԅ( ˘ω˘ԅ)」

路人：「不要亂教啊！Σ(ˊДˋ;)」

這個時候 Sentry 就可以登場了！

## Sentry 是什麼？

Sentry 是一個開源的錯誤追蹤工具，可以幫助開發者追蹤錯誤，並且提供更多資訊，讓開發者更容易追蹤問題。

不只有 JavaScript，還支援 Python、Java、PHP、Ruby 等等多個語言，甚至支援 Unity、Unreal Engine 等等。

由於目前看來 Sentry 市占率最高還可以自託管，所以優先來試試 Sentry。

## 設定 Sentry

以下我們以 Vue 為例，依照[文件指示](https://docs.sentry.io/platforms/javascript/guides/vue/#install)安裝、設定。

主要修改 main.js，加入 Sentry 初始化設定。

```ts
import * as Sentry from '@sentry/vue'
import { createApp } from 'vue'
import { createRouter } from 'vue-router'

const app = createApp({
  // ...
})
const router = createRouter({
  // ...
})

Sentry.init({
  app,
  dsn: 'https://xxxxxxxxxxxx@o4507587449978880.ingest.us.sentry.io/4507824142942208',
  integrations: [
    Sentry.browserTracingIntegration({ router }),
    Sentry.replayIntegration(),
  ],

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,

  // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
  tracePropagationTargets: ['localhost', /^https:\/\/yourserver\.io\/api/],

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
})

app.use(router)
app.mount('#app')
```

接著設定自動上傳 sourcemaps，就可以在每次執行 npm run build，都會自動上傳 sourcemaps。

執行設定引導精靈：

```bash
npx @sentry/wizard@latest -i sourcemaps
```

並根據提示設定，就大功告成了！

## 紀錄、查看錯誤

讓我們實際觸發錯誤，建立一個會 throw error 的按鈕。

```vue
<template>
  <div class="flex flex-col items-start gap-4 p-4">
    <q-btn
      icon="home"
      class="w-40"
      no-caps
      @click="throwError"
    >
      產生意外錯誤
    </q-btn>
  </div>
</template>

<script setup lang="ts">
function throwError() {
  throw new Error('錯誤測試')
}
</script>
```

Sentry 捕捉到錯誤後，會列在 Issues 中。

![issues](/make-mistakes-invisible-with-sentry/issues.png)

## 錯誤報告

點進去後可以看到詳細錯誤內容。

![error-reports](/make-mistakes-invisible-with-sentry/error-reports.png)

### 裝置資訊

可以看看究竟甚麼裝置跑出小蟲蟲。( •̀ ω •́ )✧

![device-info](/make-mistakes-invisible-with-sentry/device-info.png)

### 錯誤程式碼

有上傳 sourcemaps 的話，可以精準地知道發生錯誤的程式碼。

![error-code](/make-mistakes-invisible-with-sentry/error-code.png)

### 麵包屑

詳細記錄操作流程，還可以記錄每個步驟耗時多久、API 花費時間等等。

![breadcrumbs](/make-mistakes-invisible-with-sentry/breadcrumbs.png)

### 畫面錄影

最厲害的部分來了，不只有文字紀錄，甚至還有畫面錄影喔！ˋ( ° ▽、° )

![video-recording](/make-mistakes-invisible-with-sentry/video-recording.gif){format="gif"}

## 其他細節

### 手動抓取錯誤

除了自動抓取錯誤外，也可以手動記錄錯誤或訊息。

[Usage | Sentry for Vue](https://docs.sentry.io/platforms/javascript/guides/vue/usage/)

### 更詳細的記錄

[Enriching Events | Sentry for Vue](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/)

可以針對事件提供額外的 context，更方便 debug。

以下舉幾個例子：

* [附件](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/attachments/)：可以儲存螢幕截圖或特定檔案。
* [等級](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/level/)：紀錄特定等級的事件，方便分級追蹤。
* [tag](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/tags/)：方便分類紀錄。
* [使用者](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/identify-user/)：可以記錄錯誤來自哪個使用者。

## 總結 🐟

* Sentry 可以幫助開發者追蹤錯誤，讓開發者更容易追蹤問題
* Sentry 可以自託管，也有提供免費方案
* 除了錯誤訊息，還有裝置細節、操作錄影等等非常詳盡的資訊

Sentry 還有其他很多功能，不過目前這樣對我來說很足夠了，歡迎大家更深入的嘗試。

整體用起來真的很不錯，很強很方便。(´▽\`ʃ♡ƪ)

不過如果你的網頁有 SEO 需求，要注意 Sentry 會影響 SEO 跑分，因為需要額外載入 JS 資源，導致 TTFB 變差。

所以我只有在 App 或後台網頁才會使用 Sentry。

以上內容，希望對大家有幫助。

有問題還請多多指教。(oﾟvﾟ)ノ

---

---
url: /blog-vue/vue-h-function-makes-quasar-dialog-easier-to-reuse.md
description: Quasar Dialog 的 Invoking custom component 很好用，但是有些困擾的地方，一起來看看有甚麼辦法吧。
---

![vue-h-function-makes-quasar-dialog-easier-to-reuse](/vue-h-function-makes-quasar-dialog-easier-to-reuse.webp){.cover}

# 藉由 Vue h function 讓 Quasar Dialog 更簡單複用

大家好，我是鱈魚。（＾∀＾●）ﾉｼ

Quasar 是一個基於 Vue 的全端框架，具體內容可以看看[官方文件介紹](https://quasar.dev/introduction-to-quasar#what-is-quasar)。

不過目前我主要還是把 Quasar 當 UI 套件用。(╯▽╰ )

## Quasar 的 Invoking custom component

Quasar 的 Dialog 有一個很有趣的功能，在文件稱為「[Invoking custom component](https://quasar.dev/quasar-plugins/dialog#invoking-custom-component)」，也就是可以以命令式（imperative）呼叫任何自定義的 Dialog 元件。

這在建立複雜的後台系統很方便，除了元件可以作為 Dialog 重複使用，更可以保持 template 乾淨，不會充滿大量與目前元件邏輯無關的 html 內容，讓程式碼更簡潔、內聚一點。

但是有個小困擾，文件表示必須先將元件包裹於 q-dialog 並調用 useDialogPluginComponent，

也就是說我有一個 CreateForm 元件要變成 Dialog，要建立一個新元件：

`CreateFormDialog.vue`

```vue
<template>
  <q-dialog ref="dialogRef" @hide="onDialogHide">
    <create-form>
      <!--
        ...content
        ... use q-card-section for it?
      -->
    </create-form>
  </q-dialog>
</template>

<script setup>
import { useDialogPluginComponent } from 'quasar'
import CreateForm from './components/create-form.vue'

const props = defineProps({
  // ...your custom props
})

defineEmits([
  ...useDialogPluginComponent.emits
])

const { dialogRef, onDialogHide, onDialogOK, onDialogCancel } = useDialogPluginComponent()

function onOKClick() {
  onDialogOK()
}
</script>
```

接著使用 $q.dialog 呼叫：

```ts
$q.dialog({
  component: CreateFormDialog,
})
```

成功把 CreateForm 變成 Dialog 開啟了！ˋ( ° ▽、° )

不過這樣會導致每有一個元件想以 Dialog 形式開啟，就會多一個 xxxDialog.vue 的變體元件，實在是有點麻煩且多餘。

但是我們知道，其實 Vue 內部的 VDOM 都是透過 h function 建立，所以其實我們可以利用 h function 簡化這個過程。

::: tip
h function 就是所謂的渲染函數，詳細說明可以[看看官方文件](https://cn.vuejs.org/guide/extras/render-function.html)
:::

h function 的寫法很簡單，其參數依順序如下：

1. type：除了 html tag 外，也可以是 Vue 的元件。
2. props：DOM 的參數，也可以是元件的 prop。
3. children：此 DOM 的子元素，也可以是元件的 slot

```ts
import { h } from 'vue'

const vnode = h(
  'div', // type
  { id: 'foo', class: 'bar' }, // props
  [
    /* children */
  ]
)
```

換句話說，剛剛的程式碼：

```ts
$q.dialog({
  component: CreateFormDialog,
})
```

可以透過 h function 改寫成：

```ts
$q.dialog({
  component: h(
    QDialog,
    {},
    { default: () => h(CreateForm) }
  )
})
```

鱈魚：「這樣就不用一直建立 Dialog 變體元件了！(≧∇≦)ﾉ」

路人：「這樣程式碼看起來很可怕欸。(ﾟДﾟ\*)ﾉ」

鱈魚：「也是捏，讓我們重構、封裝一下。(｡･∀･)ﾉﾞ」

## 重構、封裝

首先第一步，讓我們建立協助提取元件型別的實用 function。

::: tip 推薦官方工具
推薦使用官方的 [vue-component-type-helpers](https://www.npmjs.com/package/vue-component-type-helpers)
:::

`src/types/utils.type.ts`

```ts
/** 提取 Vue Component 之內部 props
 *
 * 會將 style、class、event 全部取出來
 */
export type ExtractComponentProps<TComponent> = TComponent extends new () => {
  $props: infer P;
}
  ? P
  : never

/** 提取 Vue Component slots */
export type ExtractComponentSlots<TComponent> = TComponent extends new () => {
  $slots: infer P;
}
  ? P
  : never
```

接著建立基於 Quasar 的 utils 工具。

主要有 2 個 function：

* wrapWithDialog：用於將指定元件使用 QDialog 包起來。
* openUsingDialog：將 wrapWithDialog 包裹後的元件，使用 Dialog 開啟。

`src/common/utils-quasar.ts`

````ts
import { Dialog, QDialog, QDialogProps } from 'quasar'
import { Component, h } from 'vue'
import { ExtractComponentProps, ExtractComponentSlots } from '../types'

/** 將 Vue SFC 元件包装為 QDialog，可以更簡單配合 $q.dialog 使用
 *
 * @param component Vue SFC 元件
 * @param props SFC 內所有參數，包含 class、style、event 等等
 * @param dialogProps QDialog 原本參數
 *
 * @example
 * ```typescript
 * const component = wrapWithDialog(EditForm, {
 *   data,
 *   onSubmit() {
 *     dialog.hide();
 *   },
 * });
 *
 * const dialog = $q.dialog({ component });
 * ```
 *
 * @example
 * ```typescript
 * $q.dialog({
 *   component: wrapWithDialog(
 *     BrandLog,
 *     {
 *       data,
 *       class: 'w-full'
 *     },
 *     {
 *       fullHeight: true,
 *     }
 *   ),
 * });
 * ```
 */
export function wrapWithDialog<Comp extends Component>(
  component: Comp,
  props?: ExtractComponentProps<Comp>,
  dialogProps?: QDialogProps,
  slots?: ExtractComponentSlots<Comp>
) {
  return h(QDialog, dialogProps, {
    default: () => h(component, props ?? {}, slots ?? {}),
  })
}

/** 使用 Quasar Dialog 開啟元件
 *
 * @param component Vue SFC 元件
 * @param props SFC 內所有參數，包含 class、style、event 等等
 * @param slots SFC 插槽
 * @param dialogProps QDialog 原本參數
 * @returns
 *
 * @example
 * ```typescript
 * const dialog = openUsingDialog(EditForm, {
 *   data,
 *   onSubmit() {
 *     dialog.hide();
 *   },
 * });
 * ```
 */
export function openUsingDialog<Comp extends Component>(
  component: Comp,
  props?: ExtractComponentProps<Comp>,
  dialogProps?: QDialogProps,
  slots?: ExtractComponentSlots<Comp>
) {
  return Dialog.create({
    component: wrapWithDialog(component, props, dialogProps, slots),
  })
}
````

現在我們可以把剛剛的程式碼：

```ts
$q.dialog({
  component: h(
    QDialog,
    {},
    { default: () => h(CreateForm) }
  )
})
```

改寫成這樣：

```ts
openUsingDialog(CreateForm)
```

是不是整潔很多啊！♪( ◜ω◝و(و

而且因為有加上型別推導，所以使用時會有很完整的型別提示。

![型別提示](/vue-h-function-makes-quasar-dialog-easier-to-reuse/type-hints.png)

現在可以配合元件事件撰寫邏輯了。( •̀ ω •́ )✧

Vue 會自動將元件 emit 的事件名稱加上 on 前綴，所以：

* update:modelValue 會變成 onUpdate:modelValue
* cancel 會變成 onCancel

```ts
function openCreateForm() {
  const dialog = openUsingDialog(CreateForm, {
    'onUpdate:modelValue': function (data) {
      alert(`送出資料: ${data.name}`)
      dialog.hide()
    },
    onCancel() {
      dialog.hide()
    }
  })
}
```

以上用法讓大家參考參考，如果有問題還不吝指教，鱈魚感謝大家！( ´ ▽ \` )ﾉ

更完整的範例請見[範例程式碼](https://stackblitz.com/~/github.com/Codfisher/quasar-imperative-dialog?file=src/App.vue)。

## 總結 🐟

* 透過 h function 簡化 Quasar Dialog 的 Invoking custom component 用法
* 將 h function 封裝，更容易使用

---

---
url: /blog-program/do-you-want-to-do-a-side-project.md
description: 分享一下鱈魚的 Side Project 靈感與發想。(๑•̀ㅂ•́)و✧
---

![do-you-want-to-do-a-side-project](/do-you-want-to-do-a-side-project.webp){.cover}

# 要不要來點 Side Project 啊？ԅ(´∀\` ԅ)

到底要不要做 Side Project 是一個老生常談的問題。%( •̀ ω •́ )✧%

其實廣義來說，任何工作以外的事情都可以算是 Side Project，例如學習一門新技術、寫部落格、練習運動等等。

本文的 Side Project 定義為「與專業相關，但非上班時間做的任何專案」，並聚焦於 Web（Vue）與 JavaScript 領域。%(｡･∀･)ﾉﾞ%

其他領域我就不知道了，需要請教其他大大。%(´,,•ω•,,)%

## 💭 為甚麼要做 Side Project？

來說說我覺得 Side Project 的好處！%(๑•̀ㅂ•́)و✧%

不過這些好處因人而異，每個人標準不同，參考參考即可。

### 創造機會

先不說程式就像學外語一樣，多寫多思考，可以增進程式閱讀速度，也可以縮短將思緒轉換為程式碼的時間。

工作開發專案時，如果想要導入新技術或工具，通常需要考慮供應商綁定、開發流程、團隊接受度等等問題。

所以會保守看待，不會輕易導入，自己練習就不用擔心這些問題啦。

可以放飛自我，在練習的過程中累積經驗。%ヾ(⌐■\_■)ノ♪%

### 做好準備

> 機會是留給準備好的人

這句話雖然很老梗，但依然正確。

當機會不講武德的出現時，除了自己沒自信接，別人也可能不敢交給你，Side Project 就是一個很不錯的練習機會。

也可以趁機練習「軟實力」部分：

1. 找資料：如何快速搜尋並有效率的篩選相關資訊

2. 分析問題：快速定位問題並提出解決方案

3. 歸納、統整文件：將解決方案或使用說明整理成文件，讓他人能夠快速理解

內容很少很簡單無所謂，重點是練習的過程。%(๑•̀ㅂ•́)و✧%

### 單純喜歡

\~~以上是寫報告用的正經理由，看看就好，我自己的主要原因也是這個%( ﾟ ∀。)%。~~

沒有甚麼動機能夠比「有興趣」來得更有動力了。%(´,,•ω•,,)%

就像是小時候躲在被子裡偷完 PSP，或者是再怎麼累都能夠凌晨爬起來偷玩電腦一樣。

不用別人講自己會非常勤奮，但是別人要求的進度或項目總是會能拖就拖，不看到死線絕不開工。%ᕕ( ﾟ ∀。)ᕗ%

## 💡 靈感哪裡來？

不用擔心別人做過，重點是自己的練習與實踐，過程中一定會有各種收穫，甚至新靈感。

以下從門檻高至低介紹，希望大家能夠找到自己喜歡的部分。%(｡･∀･)ﾉﾞ%

### 解決日常問題

記錄下你或周圍朋友、家人常遇到的問題，思考可以怎麼應用技術解決這些問題。

不過使用的技術可能會相對複雜，例如伺服器、資料庫、雲端託管等等，需要更多的背景知識，不過這也是一個很好的學習機會。

反正做壞了也沒人會怪你，放手做做看吧。%ლ（´∀\`ლ）%

\~~有人酸你，那是他 G8，不是你的問題~~。ᕕ( ﾟ ∀。)ᕗ

::: tip
前端可以練習使用 Firestore 儲存資料，就可以再沒有後端的情況下儲存資料，完成一個完整的應用程式喔。%( •̀ ω •́ )✧%
:::

### 從模仿開始

模仿是一個很好的開始，可以從中學習到很多東西，但是門檻高低不一，需要斟酌斟酌。%(◜௰◝)%

#### 做一個網頁版小畫家

這個有點難度，不過可以先從一個簡單的功能開始，例如圖片編輯、濾鏡等等。

最後目標挑戰一下打造一個網頁版 Photoshop。

可以玩到很多很有趣的圖學知識和一些網頁性能的技巧。

[Photopea](https://www.photopea.com/) 就是一個很好的例子，來玩玩看吧！%ˋ( ° ▽、° )%

#### 模仿某個 UI 套件

例如 [Quasar](https://quasar.dev/)、[Vuetify](https://vuetifyjs.com/en/) 等等，也可以挖挖看原始碼學習，不過在沒有說明的情況下，很不容易看懂就是了。%( ・ิω・ิ)%

#### 實作 utility libraries 某個的 API

例如 [VueUse](https://vueuse.org/) 這類套件，裡面很有趣且實用的 API，找一個自己覺得有趣的 API 實作看看。

實作的過程不只可以學到一些少見的[瀏覽器 APIs 知識](https://developer.mozilla.org/en-US/docs/Web/API)，還可以臨摹開源大神們的寫作習慣與 API 設計風格，進而增進自己的程式能力。

以下舉幾個很有趣的 API：

* [`useElementByPoint`](https://vueuse.org/core/useElementByPoint/)：取得滑鼠所在位置的元素
* [`useMagicKeys`](https://vueuse.org/core/useMagicKeys/)：註冊各類快捷鍵、組合鍵
* [`onLongPress`](https://vueuse.org/core/onLongPress/)：長按事件
* [`onClickOutside`](https://vueuse.org/core/onClickOutside/)：點擊元素外部事件
* [`useRefHistory`](https://vueuse.org/core/useRefHistory/)：記錄 ref 的歷史數值
* [`makeDestructurable`](https://vueuse.org/shared/makeDestructurable/)：讓物件變為可以矩陣解構或物件解構
* [`useVModel`](https://vueuse.org/core/useVModel/)：簡化元件定義 v-model 過程。（不過現在有 [defineModel](https://vuejs.org/api/sfc-script-setup.html#definemodel)，這個 API 可以功臣身退了）

查看原始碼前先想想看這些 API 如何實現？又考慮了哪些邊界情境呢？%( •̀ ω •́ )✧%

::: tip
我的[酷酷的元件](https://chillcomponent.codlin.me/components/)內就大量使用了 VueUse API

歡迎來玩玩看。%(/≧▽≦)/%
:::

### 從興趣出發

這個動機最強，但是也是門檻不一，因為簡單可以很簡單，要複雜也能很複雜。

以下是一些我曾經看過的酷酷題目。%(⌐■\_■)y%

#### 寶可夢圖鑑

可以查閱各種寶可夢資訊的網站，進階一點可以挑戰模糊搜尋、圖片辨識等等功能。

#### 網頁調音器

分享者本身的興趣是音樂，融合自身專長打造了一個網頁調音器，方便快速校正吉他。

超酷超強！(≖‿ゝ≖)✧

#### 生成式藝術

英文為 Creative Code，利用程式碼產生各種有趣的圖形或者藝術品。

[Creative Coding TW](https://creativecoding.in/) 有很多有趣的資訊與作品，大家可以參考參考。

#### 梗圖編輯器

方便快速製作梗圖的網站，一言不合就梗圖。XD

例如：[Meme 梗圖倉庫](https://memes.tw/)、[Meme Generator](https://imgflip.com/memegenerator) 等等。

#### 網頁自動化

這裡的例子為 [Automa](https://www.automa.site/)，他是一個瀏覽器外掛，使用節點拖拉的方式，可以很輕鬆、直覺的實現自動化網頁操作。

#### 桌面自動化

網頁可以自動化，桌面當然也可以自動化，做個像是按鍵精靈的東西，可以幫你自動化一些重複性工作，~~刷個遊戲甚麼的~~。%∠( ᐛ 」∠)\_%

目前找到較為成熟的套件為 [Nut.js](https://nutjs.dev/)，歡迎大家多多補充！%(´▽\`ʃ♡ƪ)%

## 🧰 練習技術或套件

最後就是門檻最低、相對容易開始的部分，我會依序介紹 JS 生態圈中的套件並附上連結。

大家一起來看看吧。( ´ ▽ \` )ﾉ

### 動畫

動畫是網頁設計不可或缺的一部分，以下是一些常見的動畫套件。

#### 動畫控制

* [GSAP](https://gsap.com)、[Anime.js](https://animejs.com)

可以控制各種 DOM 或屬性動畫，例如 CSS、SVG 等等。

GSAP 功能最多也最強大，不過進階功能要收費，Anime.js 功能雖然沒那麼多，但是用到目前為止覺得很夠用。

#### 精緻動畫

* [Lottie](https://lottiefiles.com)、[Rive](https://rive.app)

有獨立的動畫製作工具，方便設計、管理極為複雜的動畫，並在網頁提供尺寸更小（相較影片）、自定義程度更高且效果一致的動畫。

#### 動畫工具

* [Theatre.js](https://www.theatrejs.com)

方便直接在網頁上調整、設計特殊元素動畫，例如 three.js 內的 3D 物件，定位上比較接近工程師。

### 多媒體

#### 聲音

* [Tone.js](https://tonejs.github.io)

可以製作各種音樂、音效，並融合於各種網頁互動。

#### 繪圖

* [p5.js](https://p5js.org)、[PixiJS](https://pixijs.com)

可以製作各種 HTML、CSS 難以實現的複雜繪圖。

p5.js 比較像是在畫布上作畫，Pixi 則是將將畫布視為一個場景，加入各類物體進行繪製。

很推薦大家看看這本電子書：《[Nature of Code](https://natureofcode.com/introduction/)》

書中基於 p5.js 開發，介紹了很多有趣的知識與開發技巧，並用程式碼實現自然界的各種現象。

例如物理模擬、生物遺傳等等，超級有趣！%◝(≧∀≦)◟%

#### 3D

* [Three.js](https://threejs.org)、[Babylon.js](https://www.babylonjs.com)

開發製作各種酷炫的 3D 互動、遊戲等等。

::: tip
先前曾經用 Babylon.js 製作[精靈球工作臺](https://side_project.gitlab.io/pokeball-workshop/)
:::

#### 遊戲

* [Phaser](https://phaser.io)、[PlayCanvas](https://playcanvas.com)、[GDevelop](https://gdevelop.io)

可以製作各種網頁遊戲，但是門檻可能會高一點。

不過因為好玩，所以通常更有動力。%(´,,•ω•,,)%

::: tip
我先前出的書：《[Arduino自造趣：結合 JavaScript x Vue x Phaser 輕鬆打造個人遊戲機(iThome鐵人賽系列書)](https://www.books.com.tw/products/0010942459?sloc=main)》，最後一章的[貓狗大戰遊戲](https://youtu.be/OpayalfQ124?si=XeiACQL9xzPhdxzP\&t=170)就是使用 Phaser 開發的呦。( •̀ ω •́ )✧
:::

### 其他領域

JS 得利於瀏覽器與 V8 引擎的發揚光大，觸角也延伸至其他領域。

不過這個部分需要其他領域的相關知識，有興趣再加減嘗試看看囉。%ヾ(◍'౪\`◍)ﾉﾞ%

::: danger
且記「JS 可以實現，不代表適合用 JS」，如果要深入實作或者打造產品，還請選用合適的語言。

例如：機器學習 Python 資源最多；嵌入式系統就看廠商 SDK 語言，通常都是 C/C++。
:::

#### 機器學習

* [TensorFlow.js](https://www.tensorflow.org/js?hl=zh-tw)、[Transformers.js](https://github.com/xenova/transformers.js)、[ml5.js](https://ml5js.org)

在瀏覽器上實現臉部、語音、骨架辨識等等有趣的功能。

#### 嵌入式系統

* [Johnny-Five](https://johnny-five.io)、[DeviceScript](https://microsoft.github.io/devicescript/)

用來控制或開發各種微控制器或單晶片，例如 Arduino、ESP8266、ESP32 等等。

不過 Johnny-Five 需要電腦（Node.js）與硬體持續通訊，DeviceScript 則直接撰寫 TypeScript，編譯後燒入硬體的韌體中。

#### IoT

* [MQTT.js](https://github.com/mqttjs)、[matter.js](https://github.com/project-chip/matter.js/)、[Aedes](https://github.com/moscajs/aedes)

可以製作 IoT 應用程式，例如智慧家居、智慧農業等等。

我曾經使用 Aedes 建立一個分散式系統，可以遙控並收集數百台 IoT 裝置資料，非常有趣。ヾ(◍'౪\`◍)ﾉﾞ

#### 外掛

* [瀏覽器外掛](https://developer.chrome.com/docs/extensions?hl=zh-tw)、[VSCode 外掛](https://code.visualstudio.com/api)

製作瀏覽器外掛、VSCode 外掛或各類開發工具的外掛，提升工作~~~或摸魚~~效率。%ᕕ( ﾟ ∀。)ᕗ%

#### 桌面應用程式

* [Electron](https://www.electronjs.org)

可以使用前端生態系，建立 UI 豐富的跨平台桌面應用程式。

缺點是記憶體消耗較高、程式體積也大。 %(́◉◞౪◟◉‵)%

::: tip
知名的 [VSCode、Slack、Notion 等等](https://www.electronjs.org/apps)的桌面版程式，就是用 Electron 開發。
:::

#### 手機應用程式

* [Capacitor](https://capacitorjs.com)、[NativeScript](https://nativescript.org)

可以用網頁技術開發手機應用程式，因為有一層轉換框架，所以一定會受限於框架本身。

如果框架沒有提供對應功能，就必須自己實作原生模組，這部分就需要原生開發知識。

但是若只是一些簡單的資料展示，沒有性能需求的應用程式，可以考慮使用。

Capacitor 基於 WebView，其實就是 APP 內嵌網頁。優點是可以使用前端現有生態圈，缺點就是性能會比原生差得多。（我自己實測 Android 14 很順，iOS 17.4 會有點卡）

NativeScript 則是編譯為原生程式碼，性能會比 Capacitor 好，但是限制也比 Capacitor 來得多。

#### Headless CMS

* [Directus](https://directus.io)、[Strapi](https://strapi.io)

可以快速建立 CMS、產生資料 API，而且內建一個管理後台。

讓使用者可以在沒有專職後端的情況下，建立一個資料單純的簡易系統。

如果前端想要跨足後端領域，個人認為這是一個很不錯的起頭。

可以從中學習到 API 設計、資料規劃、權限規劃等等後端常見的入門知識。

Directus 後台基於 Vue 開發，Strapi 後台則是基於 React 開發，兩者都有很高的客製化能力。

## 🛠 實用資源

分享給大家一些我常看的電子報或網站。%(◍′ω\`◍)%

### 電子報

英文的話有 [JavaScript Weekly](https://javascriptweekly.com/)、[Frontend Focus](https://frontendfoc.us/)、[Node Weekly](https://nodeweekly.com/)，可以收到各種 JS 或前端生態圈的最新消息與技術發展。

中文的話則是 [ExplainThis](https://www.explainthis.io/zh-hant)、[Star Rocket 科技創業週報](https://blog.starrocket.io/star-rocket-newsletter/)、[VK 科技閱讀時間](https://vickyho.com/)，可以看到各類科技圈的大小事。

### 參考資料

有空我會逛逛 [Codrops](https://tympanus.net/codrops/)、[Awwwards](https://www.awwwards.com/collections/)、[Codepen Spark](https://codepen.io/spark)。

以上網站集結了全世界的優秀作品和技術探討，很適合作為靈感或臨摹的參考。

### 部屬平台

常用的部署資源則有 `Cloudflare`、`Firebase`、`Zeabur`。

::: tip
Zeabur 是台灣的雲端服務商，來推一下自家人。%(/≧▽≦)/%
:::

## 總結 🐟

* 建立靈感庫，以免忘記點子
* 不用擔心別人做過，重點是自己的練習與實踐，過程一定會有各種收穫，甚至新靈感
* 先求有再求好，否則永遠無法開始
* 別怕做不出來，慢慢研究，例如：[派對動物](https://www.youtube.com/watch?v=PPWyUhT6gRk\&ab_channel=%E9%B1%88%E9%AD%9A)就是我 2020 年想到的點子，直到 2023 才有能力做出來。%(´,,•ω•,,)%
* 有餘力的話可以把過程寫成文章，除了當學習筆記，也可以作為作品集

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。%(´▽\`ʃ♡ƪ)%

一起來做 Side Project 吧！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

---

---
url: /blog-ocean-world/detached-dom-elements.md
description: 使用虛擬列表時，記憶體不斷上升，甚至爆炸，該怎麼辦呢？
---

![detached-dom-elements](/detached-dom-elements.webp){.cover}

# 說好的虛擬呢？記憶體爆炸啦！

某個專案回報網頁會越來越卡，甚至崩潰。

查了一下是因為記憶體用量像鱈魚的體重一樣越來越高，都不知道是鯨魚還是鱈魚了。

鱈魚：「旁白不要給我亂念劇本 %ლ（´ 口\`ლ）%」

嘗試重現了一下，發現在虛擬滾動列表中，反覆滾動會讓記憶體不斷上升，而且還沒有辦法釋放。

讓我們來看看是怎麼回事。

## 虛擬滾動

若頁面一次載入太多元素，可能會導致頁面卡頓，甚至崩潰。

這時候我們可以透過虛擬滾動來解決這個問題。

虛擬滾動只會顯示可見區域的元素，同時也會預先載入（Overscan）可見區域外的一些元素，避免快速捲動時出現大量空白。

下方是一個虛擬滾動的互動說明，可以清楚看到可視區域、渲染區域和未渲染區域。

UI 套件可能會有內建虛擬滾動元件，如果沒有且需求簡單，則可以使用 VueUse 的 `useVirtualList`。

使用上非常簡單：

```vue
<template>
  <div
    v-bind="containerProps"
    class="overflow-auto p-2 border border-gray-300 dark:border-gray-600 rounded opacity-80"
  >
    <div v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="mb-2 flex items-center justify-center h-10 bg-gray-200/50 dark:bg-gray-700/50"
      >
        Row {{ item.index }}
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useVirtualList } from '@vueuse/core'

const allItems = Array
  .from({ length: 50000 })
  .map((_, index) => ({ index, value: `${index}` }))

const { list, containerProps, wrapperProps } = useVirtualList(
  allItems,
  { itemHeight: 40 },
)
</script>

```

結果如下：

可以看到 50000 列資料輕輕鬆鬆啦！%( •̀ ω •́ )✧%

## 問題重現

不難注意到虛擬列表會不斷建立、銷毀 DOM 元素，如果我們反覆滾動，記憶體就會不斷上升。

讓我們快速滾動列表並打開 DevTools 使用 Performance Monitor（效能監視器）查看記憶體與 DOM 的變化。

![dom-is-released-normally](/detached-dom-elements/dom-is-released-normally.webp)

可以注意到即使 DOM 元素一度衝到接近 40000 個，也會在特定時間點釋放並不會無限上升。

所以到底是怎麼回事呢？%(́⊙◞౪◟⊙‵)%

反覆交叉嘗試後，發現問題出在 `input` 元素，沒錯，就是那個樸實無華的輸入框。%(◉◞౪◟◉ )%

只要在剛剛的虛擬列表中加入 `input` 元素，記憶體就會不斷上升，不會自動釋放，直到記憶體爆炸。

```vue {14-17,36}
<template>
  <div
    v-bind="containerProps"
    class="overflow-auto p-2 border border-gray-300 dark:border-gray-600 rounded opacity-80"
  >
    <div v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="mb-2 flex items-center justify-center h-[40px] bg-gray-200/50 dark:bg-gray-700/50"
      >
        Row {{ item.index }}

        <input
          v-model="value"
          class=" outline ml-4"
        >
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useVirtualList } from '@vueuse/core'
import { ref } from 'vue'

const allItems = Array
  .from({ length: 99999 })
  .map((_, index) => ({ value: `${index}` }))

const { list, containerProps, wrapperProps } = useVirtualList(
  allItems,
  { itemHeight: 40 },
)

const value = ref('codfish')
</script>

```

一樣不斷滾動列表，並查看 Performance Monitor。

![dom-is-not-released](/detached-dom-elements/dom-is-not-released.webp)

可以看到 DOM 數量不斷上升，完全沒有釋放的跡象。%(;´༎ຶД༎ຶ\`)%

鱈魚：「真相出爐了，兇手就是 `input`！%ヽ(●\`∀´●)ﾉ%」

同事：「可是一樣的範例，我的電腦沒有這個問題欸%(´･ω･\`)%」

鱈魚：...%ヽ(́⊙◞౪◟⊙‵)ﾉ%

使用不同瀏覽器交叉測試後，發現內鬼是瀏覽器外掛（例如：密碼管理工具），關閉外掛後就沒問題了。%( ˘•ω•˘ )%

所以其實此問題可能一直都在，只是因為大量的 `input` 在虛擬滾動中反覆建立、銷毀，放大了問題才會注意到，所以該怎麼辦呢？

鱈魚：「這個簡單，關閉外掛或只能用乾淨瀏覽器，不要拉倒 %(・∀・)９%」

同事：「PM 在你後面，他非常火 %╭(°A ,°\`)╮%」

我們沒辦法控制客戶的瀏覽器環境，只能調整 `input` 出現的時機了。

可以改成開啟編輯模式時才顯示 `input` 或使用像 [Popup Edit](https://quasar.dev/vue-components/popup-edit) 這種點擊後顯示浮動 `input` 的元件。

最後改成 Popup Edit 方案，不但問題解決惹，性能也提升了一點，用起來更流暢惹。%ԅ( ˘ω˘ԅ)%

## 總結 🐟

* 虛擬列表可以確保大量資料顯示時，不會造成頁面卡頓。
* 某些瀏覽器外掛會導致問題，調整 `input` 出現的時機，避免大量建立、銷毀 `input` 元素。

---

---
url: /blog-vue/problem-with-accidentally-modifying-pinia-data.md
description: 有時候使用 Pinia 會遇到資料意外變更問題，這其實不是鳳梨的錯，讓我們看看怎麼回事吧。( ´ ▽ ` )ﾉ
---

![拿著鳳梨的鱈魚](/problem-with-accidentally-modifying-pinia-data.webp){.cover}

# 誰偷了我的鳳梨！聊聊意外修改 Pinia 資料問題

相信大家用 Vue 3 後應該都改用 Pinia 了吧？沒用過的人趕快試試看吧。(´,,•ω•,,)

Pinia 最簡單的用法就像這樣：

`counter.ts`

```ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useStore = defineStore('counter', () => {
  const n = ref(0)

  return { n }
})
```

接著在要使用的地方呼叫 useStore：

`App.vue`

```vue
<script setup lang="ts">
import { useStore } from './counter.ts'

const store = useStore()

function increment() {
  store.n++
}
</script>

<template>
  <button @click="increment">
    Increment {{ store.n }}
  </button>
</template>
```

其實像這樣直接操作 `store.n` 的方式，方便歸方便，~~苓膏龜苓膏~~。

但不是個好做法，這種方式容易讓資料流混亂，想像一下你有多個元件都使用 `store.n`，然後想改就改。…( ・ิω・ิ)

比較推薦的方式通常為由 store 提供一個修改資料的 function，例如：

`counter.ts`

```ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

interface User {
  name: string;
  price: number;
}

export const useStore = defineStore('counter', () => {
  const user = ref<User>({
    name: 'cod',
    price: 100,
  })

  function updateUser(data: Partial<User>) {
    user.value = {
      ...user.value,
      ...data,
    }
  }

  return {
    user,
    updateUser,
  }
})
```

呼叫的部份改為：

`App.vue`

```vue
<script setup lang="ts">
import { useStore } from './counter.ts'

const store = useStore()

function increment() {
  const price = store.user.price + 1
  store.updateUser({ price })
}
</script>

<template>
  <button @click="increment">
    price: {{ store.user.price }}
  </button>
</template>
```

這樣如果未來要新增邏輯、權限甚至重構，都容易得多。

但是問題來了，有時候流程中會有「確認」的按鈕，也就是要按下確認後，才修改 store 的資料。

假設有一個負責修改 User 資料的元件：

`UserCard.vue`

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useStore } from './counter.ts'

const store = useStore()
const user = ref(store.user)

function increment() {
  user.value.price++
}
function cancel() {
  user.value = store.user
}
function submit() {
  store.updateUser(user.value)
}
</script>

<template>
  <div>
    <button class="button" @click="increment">
      遞增
    </button>
    <button class="button" @click="submit">
      確認
    </button>

    <div>
      current price: {{ user.price }}
    </div>
  </div>
</template>

<style>
.button {
  margin: 0px 4px;
}
</style>
```

`App.vue`

```vue
<script setup lang="ts">
import { useStore } from './counter.ts'

import UserCard from './UserCard.vue'

const store = useStore()
</script>

<template>
  <div>
    store price: {{ store.user.price }}
  </div>

  <hr>

  <user-card />
</template>
```

目前畫面如下圖。

![Untitled](/problem-with-accidentally-modifying-pinia-data/Untitled.png){width="200px" height="145px"}

這時候你會發現出事啦！╭(°A ,°\`)╮

按下遞增的時候，不只元件內的 user 數值發生變化，連 store 的數值也一起變啦！Σ(ˊДˋ;)

熟悉 JS 的朋友們一定都知道發生甚麼事，這是因為直接指派物件是 Call by Reference，所以：

```ts
const user = ref(store.user)
```

這個部分的程式會讓 user 依舊指向 store 的 user，結果就意外改到鳳梨裡面的資料了。(›´ω\`‹ )

這時候聰明的讀者們一定也想到解法，在 ref 的時候拷貝一次不就行了？

`UserCard.vue`

```vue
<script setup lang="ts">
// ...
const user = ref(clone(store.user))

function clone<Data>(data: Data): Data {
  return JSON.parse(JSON.stringify(data))
}
</script>
```

這時候會發現世界恢復和平了，資料一切正常！◝( •ω• )◟

鱈魚：「但是阿。(´● ω ●\`)」

路人：「怎麼那麼多但是？…(›´ω\`‹ )」

實際上協作開發的時候難保大家都會注意到這件事情，所以保險起見，可以在 Pinia 提供資料時先拷貝一次。

`counter.ts`

```ts
import { defineStore } from 'pinia'
import { computed, ref } from 'vue'

interface User {
  name: string;
  price: number;
}

function clone<Data>(data: Data): Data {
  return JSON.parse(JSON.stringify(data))
}

export const useStore = defineStore('counter', () => {
  const user = ref<User>({
    name: 'cod',
    price: 100,
  })

  function updateUser(data: Partial<User>) {
    user.value = {
      ...user.value,
      ...data,
    }
  }

  return {
    user: computed(() => clone(user.value)),
    updateUser,
  }
})
```

這樣即使元件中使用

```ts
const user = ref(store.user)
```

也不會意外修改 Pinia 中的資料了！✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

當然還有其他方式：

* [readonly](https://vuejs.org/api/reactivity-core.html#readonly)

  不過在 TypeScript 中會讓型別變得複雜，使用上會稍微有點麻煩

* [immutable.js](https://immutable-js.com/)

  功能強大，但有額外的學習、依賴成本

就看大家喜歡哪一種了。♪( ◜ω◝و(و

以上程式可以來這裡取得：[範例程式](https://play.pinia.vuejs.org/#eNqtVc1OGzEQfhVrL9kI8IJAVEoDoqUcygFQaW97cXYnYNj1WrY3BEU59AH6Chw49hH6PlXbt+j4J94FKpRDL4k9nvk83+eZ2UXyTko6ayEZJWNdKC4N0WBaSSomrg7yxOg8OcwFr2WjDPmiQR0zVZKpamoyoNnKYCEGb3MRPRek1XBpGgVkGb2LphUGFDV6YF2LRmi8zjkdRP90iDjjzCeDV+PGQC0rZgB3hIxLPnMLEkKl4gWMyGLh9xSBFHVGsly6iMyHuPW1ItlqHelYyzjrXZNsJp7IVs0kvdGNQIEWNigPB6gL3unzyBPJBWfWkieZW1PQ9dZENXc2mRt03ly5HqFUWQkz0zSV3mKS+7BrY6QeZVlRCvQvoeIzRQWYTMg6exFztE/36U5W8UmGF2VclDB/eg1GbJVQr4O+cj3apjt79I1Dne0G0NqiWlCUcomyGI3PNuVXz0QpmlryCtS5NByf9Yk4rKqau1NnM6qFmGJxDcXtP+w3eu6zvlCA8s2gR8swdQXGH59cnsEc1/Gwbsq2Qu9XDj+BbqrW5ujd3reixLR7fi7bj+6Nubj6rE/mBoRekbKJOjWcv5P5+BXqXbq7dLenYtcJKGFsmRKmXDzrGldN2C7RScF0k1i5WwNldLP959rPwk4Z1r4tbp+IYDX2hzYK+WBvkVXHiLaegEILJpWLaSsKS4AUVSNg/IEZdpiW+Dsidj30fx5R4YhQgpxenp9RyZSG1C39FXx67+KGtpEdNMxd7r7f41w46PNNB0GSwSZJh+Tg0F8UQxS6I3PXsodp0NcTw8hyEJ4vMNvZ3naG5dB3euTWSswMLEigdsHwmVnlcYerh3MjZMaq1mYZbIRQ6meLOwgXOquFCns3cBzpqFIPcxQfLvUkndZphzocBpwuUU8ElUQuWDn9ibve0HYl86xQ/s+Ufv46aTeA7XGvprgoFNQgDNJ2enSU/aje2PDFEiN0O6l5dA/A3ev1JPOB630xxpPWGFfjTGtUym/zhBwVFS9u0RIzdRL6J/7z9eHn40NAyHzM2oCeSA/t1+OP39+/vUALhi5XrP5WKcyk94V78W3rvm7d6smXDLfa3Fd2SUOuTtEaJxMXI7It52RPzqOIwTdZ/gUMSr+N)

## 總結 🐟

* 小心 call by reference 導致意外修改 Pinia 資料
* Pinia 提供資料時先拷貝一次，避免意外修改

---

---
url: /blog-ocean-world/js-highlight-api.md
description: 在 JavaScript 實作網頁文字搜尋關鍵字的 highlight 效果
---

![js-highlight-api](/js-highlight-api.webp){.cover}

# 越暗的地方你越亮，透過 JS 標記關鍵字吧

製作關鍵字篩選資料功能時常常想，如果能像瀏覽器內建的關鍵字搜尋功能那樣，標記符合的關鍵字，使用體驗應該會更好。

研究了一輪，發現還真的可以做到，讓我們一步一步來實作看看吧！

不知道甚麼是文字標記效果？那就先體驗看看成果。%( ´ ▽ \` )ﾉ%

可以注意到 table 內的文字會自動標記符合的關鍵字！%(≖‿ゝ≖)✧%

## 關鍵字過濾

首先讓我們做一個基本的 table 元件，讓使用者可以輸入關鍵字來篩選資料。

可以看到當我們輸入關鍵字時，table 會自動篩選出符合的資料。

如果能夠再標記符合的關鍵字，可以大幅提升使用體驗。%( •̀ ω •́ )✧%

所以應該怎麼做呢？將關鍵字使用 `<mark>` 標籤包起來嗎？

這的確是最經典的做法，但現在有更容易的方法了！%( ‧ω‧)ノ╰(‧ω‧ )%

## Highlight API

現在可以使用 [Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/Highlight) 實現！%─=≡Σ((( つ•̀ω•́)つ%

不過目前（2025/08/26）支援度為「Baseline 2025 Newly available」，如果有舊瀏覽器需求，就只能乖乖回去用 `<mark>` 標籤了。%( ˘･з･)%

所以該怎麼使用呢？概念為：

1. 取得要標記的文字目標 DOM
2. 使用 `Range` 設定標記範圍
3. 使用這個 `Range` 建立一個 `Highlight` 物件。
4. 將這個 `Highlight` 物件透過 CSS.highlights.set 註冊到瀏覽器，並指定名稱為 `'my-custom-highlight'`。
5. 設定 `::highlight(my-custom-highlight)` 樣式內容

以下是範例程式：

`content\blog-ocean-world\js-highlight-api\text-highlight.vue`

```vue
<template>
  <div class="text-highlight w-full border border-gray-200 dark:border-gray-700 rounded p-4">
    這段文字的鱈魚會被標記
  </div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue'

onMounted(() => {
  const parentNode = document.querySelector('.text-highlight')
  if (!parentNode) {
    throw new Error('Cannot find .text-highlight element')
  }

  const textNode = parentNode.firstChild
  if (!textNode) {
    throw new Error('Cannot find text node')
  }

  const range = new Range()
  range.setStart(textNode, 6)
  range.setEnd(textNode, 8)

  const highlight = new Highlight(range)

  // @ts-expect-error TS 誤判
  CSS.highlights.set('my-custom-highlight', highlight)
})
</script>

<style lang="sass">
::highlight(my-custom-highlight)
  background-color: #ffeb3b
</style>

```

實際效果如下：

可以注意到文字不需要被 `<mark>` 包起來，Highlight API 會自動幫我們標記符合的關鍵字。

這樣就不用調整 HTML 結構了，是不是很方便啊！%∠( ᐛ 」∠)\_%

## 來個封裝

知道怎麼用了，現在讓我們把這個功能封裝成 `useTextHighlight`，讓使用更簡單、方便。

### 需求與規格

第一步當然是來個需求分析：

1. 產生唯一名稱避免互相影響，並注入對應的 CSS：

   ```css
   ::highlight(highlight-xxxxx) {
     background-color: yellow;
     color: black;
   }
   ```

2. 關鍵字或 DOM 有變動時：
   1. 走訪容器裡的所有文字節點
   2. 找出每個文字節點中「關鍵字」的所有出現位置。
   3. 對每個命中的片段建立 `Range`，加到 `Highlight` 裡。
   4. 最後使用 `CSS.highlights.set` 將 `Highlight` 註冊到瀏覽器

3. 功能（元件）移除時自動移除標記與樣式

### 定義參數

```ts
interface UseTextHighlightOptions {
  /** 搜尋目標，會標記以下文字節點 */
  target?: MaybeElementRef;
  /** 標記底色 */
  background?: MaybeRefOrGetter<string>;
  /** 標記文字顏色 */
  color?: MaybeRefOrGetter<string>;
  /** 額外的觸發條件，變動時會更新標記
   *
   * 可確保外部依賴資料更新後也會更新標記
   */
  triggerOn?: MaybeRefOrGetter;
  /** 強制延遲指定時間後再執行
   *
   * 若 target DOM 更新自動偵測無效，可以使用此參數
   */
  delay?: number;
}
export function useTextHighlight(
  keyword: MaybeRefOrGetter<string>,
  options: UseTextHighlightOptions = {},
) {}
```

### 目標元素與樣式

接著取得目標元素並產生唯一名稱與樣式：

```ts
const highlightName = `highlight-${Math.random().toString(36).slice(2)}`

const targetEl = computed<HTMLElement | SVGElement>(() => {
  const target = toValue(options.target)
  if (!target) {
    return document.documentElement
  }

  if (target instanceof Element) {
    return target
  }

  if (target.$el instanceof HTMLElement) {
    return target.$el
  }

  throw new Error('Invalid target')
})

const style = computed(() => {
  const background = toValue(options.background) ?? '#ffeb3b'
  const color = toValue(options.color) ?? 'inherit'

  return `::highlight(${highlightName}) {
    background: ${background};
    color: ${color};
  }`
})
useStyleTag(style)
```

[`useStyleTag`](https://vueuse.org/core/useStyleTag/) 是 VueUse 的功能，可以動態產生 `<style>` 標籤並插入樣式。

### 建立 `Highlight`

建立 `Highlight` 物件與自動清除邏輯：

```ts
const highlightSet = new Highlight()
tryOnMounted(() => {
  CSS.highlights.set?.(highlightName, highlightSet)
})
tryOnBeforeUnmount(() => clear())

function clear() {
  CSS.highlights.delete?.(highlightName)
  highlightSet.clear?.()
}
```

這個部分就與前面介紹的 `Highlight` API 用法相同。

### 產生標記

再來是最重要的部分了，讓我們加入尋找文字、產生標記的邏輯：

```ts
async function highlight(keyword: string) {
  // @ts-expect-error TS 誤報
  highlightSet.clear?.()

  if (!keyword)
    return

  // 確保 DOM 已更新
  await nextTick()
  await promiseTimeout(options.delay ?? 0)

  const nodeIterator = document.createNodeIterator(
    targetEl.value,
    NodeFilter.SHOW_TEXT,
    {
      acceptNode(node) {
        const parentElement = node.parentElement
        // 排除不該進去的區塊
        if (!parentElement || /^(?:SCRIPT|STYLE|NOSCRIPT|TEXTAREA|TITLE|IFRAME)$/.test(parentElement.tagName)) {
          return NodeFilter.FILTER_REJECT
        }

        return NodeFilter.FILTER_ACCEPT
      },
    },
  )

  let node = nodeIterator.nextNode()
  while (node) {
    if (!(node instanceof Text)) {
      node = nodeIterator.nextNode()
      continue
    }

    const txt = node.data
    let index = txt.toLocaleLowerCase().indexOf(keyword.toLocaleLowerCase())

    while (index !== -1) {
      const range = new Range()
      range.setStart(node, index)
      range.setEnd(node, index + keyword.length)

      // @ts-expect-error TS 誤報
      highlightSet.add?.(range)
      index = txt.indexOf(keyword, index + keyword.length)
    }
    node = nodeIterator.nextNode()
  }
}
```

* 使用 `NodeIterator` 只抓文字節點（SHOW\_TEXT），並用 `acceptNode` 過濾掉不該搜尋的標籤。
* 每個命中片段用 `Range` 設定起訖位置並放入 `Highlight`。

### 觸發與更新

核心邏輯完成，最後就是觸發更新的部分：

```ts
watchThrottled(() => ({
  keywordValue: toValue(keyword),
  waitFor: toValue(options.triggerOn),
}), async ({ keywordValue }) => {
  highlight(keywordValue)
}, {
  throttle: 100,
  leading: true,
  trailing: true,
})

useMutationObserver(targetEl, () => {
  highlight(toValue(keyword))
}, {
  childList: true,
  characterData: true,
  subtree: true,
})
```

這個部分很單純，基本上就是當 `keyword`、`triggerOn` 或 `target` 變動時更新標記。

以上我們完成了 `useTextHighlight` 功能了！完整程式碼可以在[這裡取得](https://github.com/Codfisher/cod-aquarium/tree/main/web/composables/use-text-highlight.ts)。%◝( •ω• )◟%

### 成果

把此功能加入剛剛做的 table 中。

`content\blog-ocean-world\js-highlight-api\highlight-table.vue`

```vue
<template>
  <div ref="tableRef">
    <filter-table v-model="keyword" />
  </div>
</template>

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue'
import { useTextHighlight } from '../../../web/composables/use-text-highlight'
import FilterTable from './filter-table.vue'

const tableRef = useTemplateRef('tableRef')

const keyword = ref('')
useTextHighlight(keyword, {
  target: tableRef,
})
</script>

```

輸入文字看看吧！

簡單易用，體驗大幅提升！

還可以自由調整標記顏色：

`content\blog-ocean-world\js-highlight-api\highlight-color.vue`

```vue
<template>
  <div ref="tableRef">
    <div class="flex items-center gap-1 border border-gray-200 dark:border-gray-700 rounded p-2 mb-2">
      <label>背景顏色</label>
      <input
        v-model="style.backgroundColor"
        type="color"
      >
      <label class="ml-2">文字顏色</label>
      <input
        v-model="style.color"
        type="color"
      >
    </div>

    <filter-table v-model="keyword" />
  </div>
</template>

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue'
import { useTextHighlight } from '../../../web/composables/use-text-highlight'
import FilterTable from './filter-table.vue'

const tableRef = useTemplateRef('tableRef')

const keyword = ref('')
const style = ref({
  backgroundColor: '#ffff00',
  color: '#000000',
})
useTextHighlight(keyword, {
  target: tableRef,
  background: () => style.value.backgroundColor,
  color: () => style.value.color,
})
</script>

```

可以注意到不同元件的標記完全不會互相干擾！%◝(≧∀≦)◟%

## 總結 🐟

* 標記相符的關鍵字，可以提升使用者體驗
* 使用 Highlight API 可以更方便地實現文字標記效果
* 封裝成 `useTextHighlight`，可以在不同場景中重複使用

---

---
url: /blog-ocean-world/implement-sticky-using-js.md
description: CSS sticky 好用，但是有限制，讓我們想辦法突破限制吧。
---

![implement-sticky-using-js](/implement-sticky-using-js.webp){.cover}

# 那些黏不起來的元素，讓我們加點 JS 吧！

大家有沒有這種經驗？

快樂的在 CSS 中設定了 `position: sticky`，給了它 `top: 0` 的承諾、加上背景顏色怕它迷失，甚至提高了 `z-index` 把它捧在手心

結果使用者隨手一滑，它就這麼頭也不回地就走了，徒留一片空白的寂寞。%( ´•̥̥̥ ω •̥̥̥\` )%

鱈魚：「你說是不是很沒良心？%゜・(PД\`q｡)・゜%」

路人：「...你說的還是 CSS 嗎？%(´・ω・\`)%」

## 甚麼是 sticky

sticky 是一種特殊的定位方式，結合了 relative 和 fixed 的特性。

當元素滾動到指定位置時，會「黏住」並固定在視窗或滾動容器內的某個位置，直到其父容器的邊界不可見為止。

嘗試滾動上面這個範例，可以發現 sticky 元素會黏在視窗的頂部，不會像 relative、absolute 元素一樣滾出視窗。

好用是很好用，但是 CSS sticky 也有限制，像是多層滾動區域無法正常工作：

雖然外層被捲動，導致內容看不見很合理，但是我就想要他黏住怎麼辦呢？

## 萬用 sticky

CSS 老弟沒辦法，我們還有 JS 大哥啊！%◝( •ω• )◟%

讓我們透過 JavaScript 來實現萬用 sticky 效果吧。

概念不複雜，過程如下：

1. 找出目標元素所有的「可捲動祖先」
2. 計算「多層可視區交集」
3. 最後使用 translate 模擬 sticky 效果

重點在於「可視區交集」，因為內容其實被好幾層容器「裁切」後才看得到，所以元素要滾到哪，取決真正的「可視範圍」

可視範圍即為每一層 scroll 容器的可視區交集，你說甚麼叫做可視區交集？

讓我們具象化一下：%✨◝( •ω• )◟✨%

這樣是不是比較清楚多了？知道概念後，讓我們來實作吧%( ´ ▽ \` )ﾉ%

## 實作

讓我們一步一步來實作吧

### 工具函式

首先我們需要一些工具函式來幫助我們取得滾動容器、計算可視區交集等等。

```ts
/** 取得所有可捲動的祖先元素 */
function getScrollableParents(el: Element | null) {
  const result: Array<HTMLElement | Window> = []
  if (!el)
    return [window]

  let parent = el.parentElement
  while (parent) {
    const style = getComputedStyle(parent)
    const oy = style.overflowY
    const ox = style.overflowX

    const scrollY = (oy === 'auto' || oy === 'scroll' || oy === 'overlay')
      && parent.scrollHeight > parent.clientHeight

    const scrollX = (ox === 'auto' || ox === 'scroll' || ox === 'overlay')
      && parent.scrollWidth > parent.clientWidth

    if (scrollY || scrollX)
      result.push(parent)
    parent = parent.parentElement
  }

  result.push(window)
  return result
}

interface RectLike {
  top: number;
  bottom: number;
  left: number;
  right: number;
  width: number;
  height: number;
}

/** 取得 window viewport，用於初始可視區 */
function windowRect(): RectLike {
  return {
    top: 0,
    left: 0,
    bottom: window.innerHeight,
    right: window.innerWidth,
    width: window.innerWidth,
    height: window.innerHeight,
  }
}

/** 計算兩個 Rect 的交集 */
function intersectRect(a: RectLike, b: RectLike): RectLike {
  const top = Math.max(a.top, b.top)
  const left = Math.max(a.left, b.left)
  const bottom = Math.min(a.bottom, b.bottom)
  const right = Math.min(a.right, b.right)
  const width = Math.max(0, right - left)
  const height = Math.max(0, bottom - top)
  return { top, left, bottom, right, width, height }
}

/** 取所有 scrollable 元素的「可視區交集」 */
function getEffectiveRootRect(parentEl: HTMLElement) {
  const parents = getScrollableParents(parentEl)
  let rect = windowRect()
  for (const p of parents) {
    if (p === window)
      continue
    rect = intersectRect(rect, (p as Element).getBoundingClientRect())
    if (rect.height <= 0 || rect.width <= 0)
      break
  }
  return rect
}
```

### Vue 指令

這裡將 sticky 效果封裝成 Vue 指令，在目標元素上加上 `v-sticky` 就可以使用，相當方便。

首先定義指令參數與取得參數的 function：

```ts
/** number 表示 top 值 */
type StickyValue =
  | number
  | {
    top?: number;
    bottomPadding?: number;
  }

function getOptions(value: StickyValue | undefined) {
  if (typeof value === 'number')
    return { top: value, bottomPadding: 0 }
  return {
    top: value?.top ?? 0,
    bottomPadding: value?.bottomPadding ?? 0,
  }
}
```

接著是核心邏輯：更新與還原。

```ts
const oriStyle = {
  translate: el.style.translate,
  willChange: el.style.willChange,
};

let appliedY = 0;
let rafId = 0;

const update = async () => {
  if (rafId) return;

  // 用 requestAnimationFrame 省去多餘的更新
  rafId = requestAnimationFrame(() => {
    rafId = 0;
    if (!el.isConnected) return;

    const parentRect = parentEl.getBoundingClientRect();
    const rootRect = getEffectiveRootRect(parentEl);
    const elRect = el.getBoundingClientRect();

    /** 扣掉目前位移，原始 top 位置 */
    const naturalTop = elRect.top - appliedY;
    const deltaInParent = naturalTop - parentRect.top;

    const minTop = rootRect.top + opts.top;
    let nextY = Math.max(0, minTop - naturalTop);

    // 卡在父元素底部，不要超出去
    const maxYRaw =
      parentRect.height - (deltaInParent + elRect.height) - opts.bottomPadding;
    const maxY = Math.max(0, maxYRaw);
    nextY = Math.min(nextY, maxY);

    if (Math.abs(nextY - appliedY) > 0.5) {
      appliedY = nextY;
      el.style.translate = `0px ${appliedY}px`;
    }
  });
};

const restore = () => {
  if (rafId) cancelAnimationFrame(rafId);
  rafId = 0;
  el.style.translate = oriStyle.translate;
  el.style.willChange = oriStyle.willChange;
};
```

最後完成整個指令：

```ts
interface StickyInstance {
  scope: ReturnType<typeof effectScope>;
  setOptions: (value: StickyValue) => void;
  restore: () => void;
}
const KEY = Symbol('vSticky')
/** 取得存在元素上的上下文資料 */
function getContext(el: HTMLElement): StickyInstance | undefined {
  return (el as any)[KEY]
}
/** 將上下文資料存到元素上，讓 updated/beforeUnmount 調用同一個上下文資料 */
function setContext(el: HTMLElement, instance: StickyInstance) {
  (el as any)[KEY] = instance
}

/** 突破 CSS sticky 限制
 *
 * 用 translate 模擬 sticky，支援多層 scroll + 動態出現的 scroll area
 */
export const vSticky: Directive<HTMLElement, StickyValue> = {
  mounted(el, binding) {
    const parentEl = el.parentElement
    if (!parentEl) {
      console.warn('v-sticky 父元素不能為空')
      return
    }

    const scope = effectScope()
    let opts = getOptions(binding.value)

    const oriStyle = {
      translate: el.style.translate,
      willChange: el.style.willChange,
    }

    let appliedY = 0
    let rafId = 0

    const update = async () => {
      if (rafId)
        return

      /** 用 requestAnimationFrame 省去多餘的更新 */
      rafId = requestAnimationFrame(() => {
        rafId = 0
        if (!el.isConnected)
          return

        const parentRect = parentEl.getBoundingClientRect()
        const rootRect = getEffectiveRootRect(parentEl)
        const elRect = el.getBoundingClientRect()

        /** 扣掉目前位移，原始 top 位置 */
        const naturalTop = elRect.top - appliedY
        const deltaInParent = naturalTop - parentRect.top

        const minTop = rootRect.top + opts.top
        let nextY = Math.max(0, minTop - naturalTop)

        // 卡在父元素底部，不要超出去
        const maxYRaw = parentRect.height - (deltaInParent + elRect.height) - opts.bottomPadding
        const maxY = Math.max(0, maxYRaw)
        nextY = Math.min(nextY, maxY)

        if (Math.abs(nextY - appliedY) > 0.5) {
          appliedY = nextY
          el.style.translate = `0px ${appliedY}px`
        }
      })
    }

    const restore = () => {
      if (rafId)
        cancelAnimationFrame(rafId)
      rafId = 0
      el.style.translate = oriStyle.translate
      el.style.willChange = oriStyle.willChange
    }

    scope.run(() => {
      el.style.willChange = 'translate'

      // capture 抓到「任何元素」的 scroll（包含後來才出現的內層 scroll area）
      useEventListener(document, 'scroll', update, { passive: true, capture: true })
      useEventListener(window, 'resize', update, { passive: true })

      useMutationObserver(parentEl, update, {
        subtree: true,
        childList: true,
        attributes: true,
        attributeFilter: ['class', 'style'],
      })

      useResizeObserver(parentEl, update)
      useResizeObserver(el, update)

      update()
    })

    // 存起來讓 updated/beforeUnmount 用
    setContext(el, {
      scope,
      setOptions: (v: StickyValue) => opts = getOptions(v),
      restore,
    })
  },

  updated(el, binding) {
    const ctx = getContext(el)
    ctx?.setOptions(binding.value)
  },

  beforeUnmount(el) {
    const ctx = getContext(el)

    ctx?.restore()
    ctx?.scope.stop()
  },
}
```

* `useEventListener`、`useXxxxObserver` 用於監聽事件並觸發更新
* `effectScope` 用於管理指令的生命週期，先前的[文章有提過](/blog-vue/vue-directive-and-effect-scope)

## 成果

在目標元素上加上 `v-sticky`，不管在哪個滾動容器中，都能正常黏住。

```vue
<template>
  <div class="h-[40vh] card border-gray-100 dark:border-gray-800">
    <div class="h-[50vh] card border-gray-200 dark:border-gray-700">
      <div class="h-[60vh] card border-gray-300 dark:border-gray-600">
        <div class="h-[70vh] card border-gray-400 dark:border-gray-500">
          <div class="h-[80vh] card border-gray-500 dark:border-gray-400">
            <div
              v-sticky
              class="sticky top-0 text-center p-4 rounded-lg bg-blue-400 text-white"
            >
              我是內容 ヽ(́◕◞౪◟◕‵)ﾉ
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { vSticky } from '../../../web/directives/v-sticky'
</script>

<style scoped>
.card {
  border-width: 3px;
  padding: 40px;
  padding-left: 20px;
  border-radius: 8px;
  overflow-y: auto;
}
</style>

```

再也不用擔心黏不住了！%✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡%

## 總結 🐟

完整程式碼可以[在此取得](https://github.com/Codfisher/cod-aquarium/tree/web/directives/v-sticky.ts)

* CSS sticky 好用，但是有限制
* 使用 JavaScript 實現萬用 sticky 效果，突破 CSS sticky 限制

目前尚未考慮 x 軸的 sticky，有興趣的朋友可以自己改改看喔。%( ´ ▽ \` )ﾉ%

---

---
url: /column-chill-components/01-origin.md
description: 小廢物們背後的技術亮點
---

![chill-components](/chill-components.webp){.cover}

# 酷酷元件背後的星點 - EP01：前言

當初開發酷酷元件的初衷很單純：「一半是為了好玩，一半則是為了技術的練習與實驗」。

雖說這些元件多半只是「小廢物」，除了偶爾能在生成式藝術的背景裡露個臉，工作上難得派上用場。

然而背後所蘊藏的技術、設計思維與實作概念，卻意外的有用，甚至成為探索技術邊界的鑰匙。

在這個專欄中，我將分享這些元件背後的技術亮點，並介紹它們如何在實際應用中發揮作用。%(・∀・)９%

也歡迎大家留言、私訊或[寫信](mailto:hi@codlin.me)給我，分享你對這些元件的看法或使用經驗喔。%(\*´∀\`)~♥%

技術名稱同[酷酷元件的技術星圖](https://chillcomponent.codlin.me/tech-starmap.html)，歡迎大家來探索。

---

---
url: /blog-vue/about-vue-component-splitting.md
description: 關於 Vue 元件拆分那檔事
---

![img](/img.webp){.cover}

# 關於 Vue 元件拆分那檔事

以下情況不考慮到處複用

* 此業務邏輯元件只出現第一次：除非 UI 有此元件設計系統
* 只有外觀長得像，但是 domain 完全不相關

## 總結 🐟

---

---
url: /blog-vue/about-vue-data-flow.md
description: Vue 資料流實作筆記，還請大家多多指教 (*´∀`)~♥
---

![about-vue-data-flow](/about-vue-data-flow.webp){.cover}

# 關於 Vue 資料流那檔事

實際開發時，常常會遇到怎麼規劃資料流的問題。

::: tip 強烈推薦 TypeScript
有 TypeScript 協助檢查，直接少一大半問題 %(´,,•ω•,,)%
:::

此文筆記了一些曾經遇過的情境，不是規範指南，希望大家可以多多討論，一起進步。%(\*´∀\`)~♥%

可能某天會發現寫法不好、考量不夠周到，所以本文會持續不定期更新。%(´,,•ω•,,)%

::: tip 軟體開發沒有銀彈
[軟體開發沒有銀彈](https://zh.wikipedia.org/zh-tw/%E6%B2%A1%E6%9C%89%E9%93%B6%E5%BC%B9)，沒有絕對的對錯，只有適不適合，實務上要根據專案規模、需求持續調整。
:::

接下來讓我們根據情境或 Vue API （Vue 3）來討論資料流的概念與實作吧。%੭ ˙ᗜ˙ )੭%

## 依 API

Vue 中基本傳遞資料的方式有 Prop（emit）、Provide、Store

其實官方文件已經有很詳細的[說明](https://vuejs.org/v2/guide/components.html#Passing-Data-with-Props)，這裡只是根據實務經驗整理一下。

我自己列了一個簡易的流程圖，簡化思考。

```mermaid
---
title: Vue 的 Prop、Provide、Store 使用時機
---

flowchart TD
    A((開始)) --> B{是否跨多個元件？}

    B --否--> R1
    B --是--> C{皆為兄弟元件嗎？}

    C --是--> R2
    C --否--> D{中途有多個元件
    只為轉發而宣告 Prop 嗎？}

    D --否--> R1
    D --是--> E{傳遞方向可預期嗎？
    例：僅有後代元件使用}

    E --是--> R3
    E --否--> F{狀態的用途範疇明確嗎？
    例如：User 登入資訊}

    F --是--> R4
    F --否--> 請重新探討架構

    R1[Prop]
    R2[使用父元件管理 Prop]
    R3[Provide]
    R4[Store]
```

### 經典的 Prop

Prop 的目的在於元件不用管外部狀態如何，只關心內部資料如何使用。

透過固定的資料定義，讓元件可以任意拔插。

當然實作上很常遇到「隨著各種追加需求，參數瘋狂增加，為了向下相容，導致參數越來越歪」的問題。

這個未來有機會再另開文章，筆記一下元件設計問題。...(›´ω\`‹ )

::: tip Vue 3.5 之後可以直接解構 Prop
以前解構 Prop 會失去響應性，只能乖乖寫 `props.xxx` 或是用 `toRefs`。

3.5 起 [Reactive Props Destructure](https://github.com/vuejs/rfcs/discussions/502) 轉正並預設啟用，直接解構就好，順便還能寫預設值。

```vue
<template>
  <p>{{ message }} x {{ count }}</p>
</template>

<script setup lang="ts">
const { count = 0, message = 'hello' } = defineProps<{
  count?: number;
  message?: string;
}>()
</script>
```

不過要注意解構出來的變數本質是 getter，丟進 `watch` 或 composable 時記得包成 getter，例如 `watch(() => count, ...)`。%(´,,•ω•,,)%
:::

### 甚麼時候使用 store？

這裡的 store 指的是 Vuex、Pinia 這類的狀態管理套件，其資料為全域共享。

除了全域共享外，個人覺得 store 與 Prop 最大的不同在於：「在元件內部依賴指定資料」

意思是此元件不能獨立運作，必須依賴 store 才能正常運作。

好不好需要看情況討論，我的心得是：

* 基礎元件（或稱 [Atom 元件](https://medium.com/@kevinkurniawan97/atomic-design-with-vue-fa1b50a1251e)）不要依賴應用領域狀態

  Button、Input 這類基礎元件內部不要依賴 User 資訊、購物車這種業務資料或外部 API，最好使用 Prop 傳遞

* 傳遞深度未知、需全域共享且領域清晰的資料才用 store

  User 登入資訊、購物車資訊等等

如果需共享的資料來自於外部 API，也可以考慮使用 [Tanstack Query](https://tanstack.com/query/v5/docs/framework/vue/overview#motivation)（舊稱 Vue Query）或 [Pinia Colada](https://pinia-colada.esm.dev/)，不只省去 store，還有很多實用功能。%ˋ( ° ▽、° )%

Pinia Colada 是 Vue 生態自己長出來的方案，比 Tanstack Query 輕，也與後面會提到的 Data Loader 官方整合。API 相當接近，官方甚至有[遷移指南](https://pinia-colada.esm.dev/cookbook/migration-tvq.html)可以參考。

#### Vue 3 不需要 store？

有看過有人說「Vue 3 的響應式系統配合 ES Module，就可以共享資料了，根本不需要使用 store」

這個可以分成兩個部分來看：

* 專案不一定需要 store
* 我不想要用 Pinia、Vuex 作為 store management 方案

不是每個專案規模都需要 store，如果網頁只是一個很簡單的一頁式活動頁面，還真的不需要。

簡單專案中使用 store，反而可能會讓專案變得更複雜。

但是「使用 Pinia、Vuex 以外的 store management 方案」，這個就需要思考了。

的確可以「Vue 3 響應式系統配合 ES Module」實現資料共享，我在[酷酷元件的落雪元件](https://chillcomponent.codlin.me/components/bg-snow/)中就是這樣實作。

這麼做是因為此為內聚性高的獨立元件，若要求使用者在使用此元件前，必須先安裝 Pinia，這樣就太過於繁瑣了。

但若是一般網頁專案，在不確定專案會不會持續增長的情況下，還是建議使用 Pinia。

因為隨著專案成長，你可能會開始需要解決以下問題：

* 如何除錯
* [HMR 問題](https://pinia.vuejs.org/cookbook/hot-module-replacement.html)（保留、更新資料等等）
* [如何測試](https://pinia.vuejs.org/cookbook/testing.html)
* 如何加入 plugin
* 追蹤資料變更

甚至 SSR 相關問題等等。

以上問題解決後會發現：恭喜！重工了一個 Pinia！%ヽ(́◕◞౪◟◕‵)ﾉ%

但是沒辦法使用 Pinia 現有生態系（各種外掛、工具），後續接手的人可能會很痛苦。

Pinia 已設計得相當簡易了，除非你的情境真的很不適合 Pinia，不然還是乖乖用吧。%(´● ω ●\`)%

### Provide？

Provide 的用法在[官方文件](https://vuejs.org/guide/components/provide-inject)解釋得很清楚。

主要目的是解決層層傳遞的問題，但是也有與 store 類似的問題，就是依賴耦合問題。

::: tip
從[實作的角度](https://github.com/vuejs/pinia/blob/2071db285569a3119cf62c5be16a63fb7b681b1d/packages/pinia/src/createPinia.ts#L29)來看，store 就是依靠 Provide 從 App 層注入，實現所有元件資料共享功能。
:::

我自己只有在「依賴方向明確，深度未知的強耦合的元件」才會使用 Provide。

例如：

#### Quasar 的 QForm

Quasar 的 [`QForm`](https://quasar.dev/vue-components/form#child-communication) 與 [`useFormChild`](https://quasar.dev/vue-composables/use-form-child)，其內部實作就是使用 Provide。

只要 `QForm` 內部含有 `QField` 或使用 `useFormChild` 之元件，無論元件多深層，提交時若有錯誤，都會自動阻擋，相當方便。

#### 酷酷元件的 card-futuristic

此[元件](https://chillcomponent.codlin.me/components/card-futuristic/)由多個子元件組成，父子元件為強耦合關係。

作為容器的父元件使用 Provide 提供綁定邏輯給子元件，[子元件綁定](https://gitlab.com/side_project/chill-component/-/blob/main/src/components/card-futuristic/use-card-part.ts)完成後由父元件統一調度動畫。

藉此實現酷炫、複雜的動畫效果。

#### 遞迴元件

深度未知最特殊的情境是遞迴元件，例如 Tree、多層選單、留言串。

這種元件的深度由資料決定，你根本不知道會長幾層。使用者多加一層分類，Prop 鏈就得跟著長一節。

```vue
<!-- tree-node.vue，自己呼叫自己 -->
<template>
  <li>
    {{ node.label }}

    <ul v-if="node.childList?.length">
      <tree-node
        v-for="child in node.childList"
        :key="child.id"
        :node="child"
      />
    </ul>
  </li>
</template>

<script setup lang="ts">
defineProps<{ node: TreeNode }>()
</script>
```

節點自己的資料（`node`）用 Prop 沒問題，它本來就只屬於這一層。

但是「目前選到哪個節點」、「點擊後要通知誰」這種**整棵樹共用**的東西，用 Prop 傳就是災難。%( ˘ω˘ )%

狀態本人住在根節點。

```vue
<!-- tree-root.vue -->
<template>
  <ul>
    <tree-node
      v-for="node in nodeList"
      :key="node.id"
      :node="node"
      :selected-id="selectedId"
      @select="selectedId = $event"
    />
  </ul>
</template>

<script setup lang="ts">
import { ref } from 'vue'

defineProps<{ nodeList: TreeNode[] }>()

const selectedId = ref<string>()
</script>
```

`tree-node` 則是收下來，用一份、再往下傳一份。

```vue
<!-- tree-node.vue，Prop 版本 -->
<template>
  <li :class="{ active: node.id === selectedId }">
    <span @click="emit('select', node.id)">
      {{ node.label }}
    </span>

    <ul v-if="node.childList?.length">
      <tree-node
        v-for="child in node.childList"
        :key="child.id"
        :node="child"
        :selected-id="selectedId"
        @select="emit('select', $event)"
      />
    </ul>
  </li>
</template>

<script setup lang="ts">
defineProps<{
  node: TreeNode;
  selectedId?: string;
}>()

const emit = defineEmits<{
  select: [id: string];
}>()
</script>
```

這樣寫可以動，但是事件得一層一層冒上去，第 8 層的點擊真的會跑 8 次 `emit` 才抵達根節點。

不過層層 `emit` 不算甚麼大問題，比較大的問題其實是重繪。

假設再追加拖曳排序，多了一個 `draggingId`，真正在意的只有被拖的節點與游標底下那個。

但是它從根節點一路往下傳，於是拖曳過程每移動一下，整棵樹就重繪一次。%( ﾟдﾟ)%

改用 Provide 就沒這些問題了，先定義一把有型別的鑰匙。

```ts
// tree-key.ts
import type { InjectionKey, Ref } from 'vue'

export const treeKey = Symbol('tree') as InjectionKey<{
  selectedId: Readonly<Ref<string | undefined>>;
  select: (id: string) => void;
}>
```

根節點提供一次。

```vue
<!-- tree-root.vue -->
<script setup lang="ts">
import { provide, readonly, ref } from 'vue'
import { treeKey } from './tree-key'

const selectedId = ref<string>()

function select(id: string) {
  selectedId.value = id
}

provide(treeKey, {
  selectedId: readonly(selectedId),
  select,
})
</script>
```

節點自己拿。

```vue
<!-- tree-node.vue，Provide 版本 -->
<template>
  <li :class="{ active: node.id === selectedId }">
    <span @click="select(node.id)">
      {{ node.label }}
    </span>

    <ul v-if="node.childList?.length">
      <tree-node
        v-for="child in node.childList"
        :key="child.id"
        :node="child"
      />
    </ul>
  </li>
</template>

<script setup lang="ts">
import { inject } from 'vue'
import { treeKey } from './tree-key'

defineProps<{ node: TreeNode }>()

const { selectedId, select } = inject(treeKey)!
</script>
```

* 點擊直接呼叫 `select`，不用冒泡，也就沒有轉發鏈這回事
* 每個節點各自訂閱用得到的東西，`draggingId` 只會更新真的有讀它的節點
* 型別由 `InjectionKey` 一路帶到底，跟 Prop 版本一樣完整

#### Provide 注意事項

Provide 用起來很快樂，也要注意一些細節，不然很容易翻車。%⎝(・ω´・⎝)%

##### 善用 `InjectionKey` 而不是字串

字串鍵沒有型別，打錯也不會有人告訴你。

```ts
import type { InjectionKey, Ref } from 'vue'

export const cartKey = Symbol('cart') as InjectionKey<{
  itemList: Readonly<Ref<CartItem[]>>;
  addItem: (item: CartItem) => void;
}>
```

`provide` 與 `inject` 用同一把鑰匙，型別自動對上，IDE 也會幫忙提示。

##### 資料提供 `readonly`、變更走 function

直接把 ref 丟出去，等於任何後代都能改，出事時完全不知道誰動的手。

```ts
import { readonly, ref } from 'vue'

const itemList = ref<CartItem[]>([])

provide(cartKey, {
  itemList: readonly(itemList), // [!code ++]
  addItem,
})
```

想改資料就呼叫提供者給的 function（本例子為 `addItem`），變更邏輯集中在一處，要加驗證、加 log 都方便。

如此 Provide 才算是「有作用域的依賴注入」，不然它就只是一個藏起來的全域變數而已。%(´,,•ω•,,)%

#### 可是隱式依賴很可怕

也有人認為 Provide 會有「隱式依賴」問題。

元件檔案打開來看不出它需要什麼，必須知道自己被誰包著才能跑，抽出來重用就直接爆炸。%╭(°A ,°\`)╮%

這派的主張是寧可忍受 Prop 一路傳，也要讓依賴顯式可見，至少改壞的時候 TypeScript 會叫。

我覺得兩邊都有道理，實務上的折衷是把 inject 包成 composable，並且想清楚「缺了它會怎樣」。

如果元件沒有它就完全沒有意義，則應該附上明確的錯誤訊息。

```ts
function useCart() {
  const cart = inject(cartKey)

  if (!cart) {
    throw new Error('useCart 必須在 cart-provider 內部使用')
  }

  return cart
}
```

但是更理想的情況是準備回退方案，讓元件少了 provider 也能自己撐著。

`inject` 本來就支援預設值，第三個參數表示「預設值是個 factory」，這樣每個元件才會拿到自己的一份，不會共用同一個物件。

```ts
function useTree() {
  return inject(treeKey, () => createStandaloneTree(), true)
}
```

前面提到的 `useFormChild` 就是這種設計，欄位放在 `QForm` 外面照樣能用，只是不參與整體驗證而已。

### 命令式資料流：defineExpose 與 useTemplateRef

前面聊的都是宣告式，資料變了畫面跟著變，但是有些情境天生就是命令式。

例如「按下按鈕讓表單重置」、「跳到影片第 30 秒」、「開啟時自動 focus 輸入框」。

這時候可以由子元件 `defineExpose`，父元件用 `useTemplateRef` 拿到實例後直接呼叫。

```vue
<!-- 子元件 -->
<script setup lang="ts">
function reset() {
  // 重置邏輯
}

defineExpose({ reset })
</script>
```

```vue
<!-- 父元件 -->
<script setup lang="ts">
import { useTemplateRef } from 'vue'

const formRef = useTemplateRef('form')

function onCancel() {
  formRef.value?.reset()
}
</script>
```

::: tip
`useTemplateRef` 是 Vue 3.5 新增的 API，比以前「宣告同名 ref」的寫法更明確，型別也更完善。
:::

判斷情境大概如下：

* **動作型可以**，`focus()`、`reset()`、`play()`、`scrollTo()` 這種一次性動作
* **狀態查詢型不行**，如果你在父元件寫 `formRef.value.isValid`，那就該改用 Prop 或 emit

因為狀態查詢代表資料流反了，而且 template ref 不保證何時有值，掛載前後拿到的東西不一樣，很容易踩雷。%( ›´ω\`‹ )%

## 依情境

接下來根據情境來討論資料流的概念與實作。

### 兄弟元件溝通

如果資料只需在兩三個元件間共享且傳遞深度很淺，就不建議使用 store，而是由父元件提供資料。

若元件很深層則可在父元件使用 Provide 提供資料。

例如：拆分成多個 tab 的表單，由父元件提供資料給各分頁即可。

```vue
<template>
  <div>
    <tab-step1
      v-model="data"
      name="step-1"
    />
    <tab-step2
      v-model="data"
      name="step-2"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import TabStep1 from './TabStep1.vue'
import TabStep2 from './TabStep2.vue'

const data = ref({})
</script>
```

### 表單狀態該由誰持有？

上面那個範例只傳了 `data`，但是實務上表單還有一堆狀態，例如驗證錯誤、哪些欄位被動過、有沒有未儲存的變更。

我自己的分法是這樣。

* **驗證狀態**由容器持有，因為送出時要一次看全部
* **dirty / touched** 由欄位自己判斷，容器只負責彙總

::: tip dirty 與 touched 是甚麼？
表單套件常見的兩個詞，dirty 指值被改過（跟初始值不同），touched 指使用者碰過（聚焦後又離開）。

dirty 看值，touched 看互動，所以離開頁面要不要跳「尚未儲存」看 dirty，錯誤訊息要不要現在就顯示則看 touched，避免一進畫面就滿江紅。%( ˘ω˘ )%
:::

如果每個分頁自己記自己的錯誤，送出時容器就得反過來去撈每一頁的狀態，通常會變成這樣。

```ts
const step1Ref = useTemplateRef('step1')
const step2Ref = useTemplateRef('step2')

function submit() {
  if (!step1Ref.value?.validate())
    return
  if (!step2Ref.value?.validate())
    return
  // ...
}
```

這就是前面說過的「狀態查詢型」命令式操作，資料本來該由下往上送，現在變成上面伸手去撈。

而且分頁一旦改成 `v-for` 動態渲染，容器還得自己維護一份 ref 清單，愈長愈歪。%( ›´ω\`‹ )%

反過來由容器提供註冊機制，欄位掛載時自己登記，送出時容器一次收割，就乾淨多了。

這也正是前面提到 Quasar `QForm` 與 `useFormChild` 的作法，不想自己造輪子的話，vee-validate、FormKit 這類套件也是把這件事包好了。%( ´ ▽ \` )b%

### 元件內更新或觸發事件不要優先使用 watch

在使用 watch 修改或觸發事件前，先想想有沒有其他方案，真的沒有才用 watch。

詳細說明請參考先前文章：[Vue watch 前先小等一下](https://codlin.me/blog-vue/hang-tight-for-a-sec-before-you-start-watch)

### v-model 與資料流

大家應該都是知道 `v-model` 其實是個語法糖。

元件結構單純時，使用 `v-model` 很容易且簡單，且元件內部實作使用 `defineModel` 爽到不行。%(´,,•ω•,,)%

但是資料開始複雜時，通常不會希望部分資料變更就立即向外部傳遞。

因為若互動元件有複雜的操作邏輯（例：拖動排序、表單驗證），多餘的響應與傳遞，除了性能損耗外，可能會導致操作邏輯出現不自然的跳動或其他副作用。

這個時候就可以考慮把 `v-model` 拆成回 `:model-value` 與 `@update:modelValue` 分別處理。

自行處理資料流，選擇更恰當的時機觸發響應並傳遞資料。%( •̀ ω •́ )✧%

::: tip
不適合使用 `defineModel` 的場合，我自己會選擇使用 `shallowRef` 配合 `triggerRef` 實作。

除了減少不必要的副作用，因為 `triggerRef` 實際由自己掌控，也更容易追蹤資料變更。%ԅ(´∀\` ԅ)%
:::

### Composable 共享資料？

有人說可以使用 Composable 共享資料，只要把資料放在 Composable 的 function 外面就可以，像這樣：

```ts
const data = ref(0) // [!code ++]

export function useSharedData() {
  const data = ref(0) // [!code --]
  return { data }
}
```

實際上這個與使用 ES Module 共享資料的方式相同，[官方文件](https://vuejs.org/guide/scaling-up/state-management#simple-state-management-with-reactivity-api)也有提到這種用法。

但是這樣做一樣會遇到先前提到的問題（如何除錯、追蹤資料變更等等）。

::: tip
這樣寫有另一個風險，不過只有 SSR 會遇到，有另外寫了一篇詳細筆記，有興趣的朋友可以參考[AI 可能會寫的 Vue Composable 地雷，你踩過了嗎？](https://codlin.me/blog-vue/vue-composable-outer-variable-trap)
:::

所以我自己的約定是，共享資料統一交給 store，Composable API 專注於組合、邏輯複用。

開發時 store 一定是全域共享，Composable API 則可放心使用，不用怕污染。

避免到處都有全域共享資料，後續接手的人可能會一頭霧水。

如果 Composable 需要共享資料，則在內部使用 store 即可。

::: tip
Pinia 也可以寫成 [setup 風格](https://pinia.vuejs.org/cookbook/composables.html#Setup-Stores)（或稱 Composable API 風格），所以若 Composable 需要共享資料，可以直接使用 setup store 即可。
:::

#### 善用 [`MaybeRefOrGetter`](https://vuejs.org/api/utility-types#maybereforgetter)

傳遞 Composable API 參數時，若同時支援傳入一般數值、`ref` 或 `getter`，可以增加彈性。

不過大家可能會說：「這樣要判斷 3 種情境，很麻煩欸！%(°口°〃)%」

這時候可以使用 Vue 提供的 [`toValue`](https://vuejs.org/api/reactivity-utilities#tovalue)，輕鬆解決。

::: tip
v3.3 版本前的朋友，可以考慮使用 VueUse 提供的 [`toValue`](https://vueuse.org/shared/toValue/#tovalue)。
:::

所以有甚麼好處呢？例如 VueUse 的 [`useIntervalFn`](https://vueuse.org/shared/useIntervalFn/)。

用法與 `setInterval` 相同：

```ts
useIntervalFn(() => {
  // 定時任務
}, 1000)
```

但是如果你把 `1000` 改成 ref 或 getter，就可以動態改變間隔時間。

```ts
const interval = ref(1000)

useIntervalFn(() => {
  // 定時任務
}, interval)
```

這樣就會在 `interval` 變更時，自動調整間隔時間。

官方文件也有這方面的說明，可以參考[這裡](https://vuejs.org/guide/reusability/composables#accepting-reactive-state)。

### 切換頁面傳值

切換 router 有時候需要傳遞資料，一般來說優先使用以下方法：

* query string 或 path params
* Vue Router 之 [`Passing Props`](https://router.vuejs.org/guide/essentials/passing-props.html)

不過有時候可能會需要傳遞複雜一點的物件資料。

例如：從「商品列表」轉跳至「商品細節」，除了 path params 加上商品 ID 外，如果同時傳遞列表頁中的商品資料，細節頁面就不用特別在讀取一次商品資料。

這個時候就可以使用 `history.state` 來傳遞資料。

商品列表頁跳轉邏輯可能如下：

```ts
async function toProductDetail(product: Product) {
  router.push({
    name: 'product-detail',
    state: {
      /**
       * state 不能傳遞複雜類型，structuredClone 確保轉為一般物件
       *
       * [Release Note](https://github.com/vuejs/router/releases/tag/v4.1.0)
       */
      product: structuredClone(product),
    }
  })
}
```

商品細節頁取得資料邏輯可能如下：

```ts
const productId = useRouteParams('id')

function isProduct(data: any): data is Product {
  // 驗證資料是否為 Product
}

const {
  isLoading,
  state: product,
} = useAsyncState(async () => {
  const data = history.state?.product

  if (isProduct(data)) {
    return data
  }

  // 沒有 product 資料，從 API 取得
  return getProduct(productId.value)
}, undefined)
```

::: tip
[history.state 相關功能正在 RFC 中](https://github.com/vuejs/rfcs/discussions/400)，未來可能新增更多 API 支援，大家可以關注關注。
:::

### 傳遞成本也是資料流的一部分

最後補一個容易被忽略的角度，資料流的選擇會直接影響效能。

`ref` 與 `reactive` 都是深層響應，丟一個上萬筆的陣列進去，Vue 會很敬業地幫你把每一層都變成 Proxy。

如果這份資料只會整包替換，不會單獨改某一筆，那用 `shallowRef` 就好。

```ts
const itemList = shallowRef<Item[]>([])

// 整包換掉，一樣會觸發更新
itemList.value = await fetchItemList()
```

地圖實例、圖表實例、Three.js 物件這種第三方實例，則用 `markRaw` 明確告訴 Vue 不要碰。

::: tip
`shallowRef` 與 `ref` 的差別，可以參考先前文章 [Vue 的 shallowRef 是啥？和 ref 有甚麼差別？](https://codlin.me/blog-vue/vue-shallow-ref-and-ref)
:::

順帶一提，Vue 3.6 把 `@vue/reactivity` 改為基於 [alien-signals](https://github.com/stackblitz/alien-signals)，開銷更低、在龐大元件樹下也更耐操。%ヾ(◍'౪\`◍)ﾉﾞ%

### 進階資料載入

進階取得資料的方式除了剛剛提到的 [Tanstack Query](https://tanstack.com/query/v5/docs/framework/vue/overview#motivation)，Vue Router 團隊還開發了 [Data Loaders](https://router.vuejs.org/data-loaders/)。

Data Loader 乍看之下 API 與 Tanstack Query 相當接近，最大的差別在於 Data Loader 與 Vue Router 深度整合，將資料載入整合至導航週期。

可以在路由守衛中取得資料，執行更複雜的導航邏輯。

詳細說明可以參考作者的[說明影片](https://www.youtube.com/watch?v=VkSGxuAJwv8\&ab_channel=%E5%89%8D%E7%AB%AF%E5%9C%88)，有相當深入淺出的介紹。

::: warning 這段已經過期囉
原本這裡寫著「截至 2025/01/15，Data Loader 還在 RFC 階段」，現在情況不一樣了。

`unplugin-vue-router` 已於 2026/02/24 [併入 vuejs/router](https://github.com/posva/unplugin-vue-router)，倉庫封存，typed routes 與 Data Loader 都進了 Vue Router 核心。

想看實際用法的話，可以參考先前文章[用 Vue Router 的 Data Loader 解決 fetch 瀑布流問題](https://codlin.me/blog-vue/solve-fetch-waterfall-with-data-loader)。%( ˘ω˘ )%
:::

## 總結 🐟

* 元件優先關心 Prop 來的資料，基礎元件不要依賴業務領域狀態
* 依賴方向明確、深度未知、強耦合才用 Provide，搭配 InjectionKey 與 readonly，缺了 provider 要明確報錯或給回退方案
* 遞迴元件的共用狀態交給 Provide，省下層層 emit 與整棵樹重繪
* 命令式資料流只拿來做動作，會想查狀態就代表資料流反了
* 表單的欄位值與驗證狀態由容器持有，欄位不要自己留副本
* 善用 MaybeRefOrGetter，增加 Composable API 彈性
* 跳轉頁面傳遞資料還有 history.state 這個選擇

以上是我自己的心得，不過一樣老話一句，如果你很清楚你在做甚麼，也沒什麼一定不可以就是了。%(・∀・(・∀・(・∀・\*)%

大家如果有不同的想法，還請不吝告訴我。%(´▽\`ʃ♡ƪ)%

也推薦大家閱讀以下文章：

* [Effective State Management](https://michaelnthiessen.com/effective-state-management)
* [Vue 官方文件，Cross-Request State Pollution](https://vuejs.org/guide/scaling-up/ssr#cross-request-state-pollution)
* [Pinia Colada，Why?](https://pinia-colada.esm.dev/why.html)
* [Vue 官方文件，Provide / Inject](https://vuejs.org/guide/components/provide-inject)

---

---
url: /public/minespace/sounds/CREDITS.md
---
# 音效來源

這個資料夾裡的音檔各有出處與授權，加新檔案時請一併補在這裡。
沒有記載的檔案是先前留下的，來源待補。

## wheat-wind.mp3

* **原名**：WIND, Wind through Wheatfield
* **作者**：Uganda
* **來源**：<https://freesound.org/people/Uganda/sounds/38976/>
* **授權**：CC0 1.0（公眾領域貢獻，不需標示、可商用）
* **原始描述**：風穿過麥田，帶著細碎的爆裂聲，背景有幾聲鳥。
* **處理**：原檔 1 分 44 秒。取第 10 到 70 秒，
  再把第 6 到 10 秒交叉淡入到結尾，做成 60 秒的無縫循環
  （`acrossfade`，兩端收在同一個取樣點上，接回去聽不出接縫）。
  接著補 19 dB 增益並過限幅器（`alimiter` 的 level 要關掉，
  它預設會把輸出自動正規化回 0 dB，壓多少都沒用），
  最後轉成單聲道 32 kHz / 56 kbps。
* **音量**：平均 −24.0 dB、峰值 −0.9 dB
* **加音檔一定要量音量**
  這裡踩過一次：先前選的另一份錄音（szelestamas / 620099，
  質地其實更準、而且完全沒有鳥）平均只有 −49.8 dB，
  比這個資料夾其他音檔輕了將近 30 dB。規格全部對齊、檔案也正常，
  但乘上音源的 volume 與距離衰減之後等於沒有聲音。
  這個資料夾的音檔平均落在 −19 到 −25 dB 之間，新加的要落進這個範圍。
  量法：`ffmpeg -i 檔名.mp3 -af volumedetect -f null -`
* **用在**：麥浪田的麥稈摩擦（`wheat-rustle-*`）

## jigoku-lava.mp3

* **原名**：Lava Loop 3
* **作者**：Fission9
* **來源**：<https://freesound.org/people/Fission9/sounds/474851/>
* **授權**：CC0 1.0（公眾領域貢獻，不需標示、可商用）
* **處理**：原檔為 48 kHz / 24 bit / 立體聲 WAV，
  轉成單聲道 32 kHz / 56 kbps MP3 以對齊本資料夾其他音檔的規格。
  長度維持原本的 39.6 秒未裁切——作者標明它完美循環，
  裁掉任何一段都會在接點留下一下可以聽出來的頓挫。
* **用在**：地獄谷裂縫裡的熔岩（`jigoku-churn-*`）

---

---
url: /column-shader-notes/01-shader-intro.md
description: 從 JavaScript 開發者的角度出發，一起來看看 Shader 的核心概念吧！(｢･ω･)｢✧
---

![shader-notes](/shader-notes.webp){.cover}

# 鱈魚的 Shader 筆記 - EP01：甚麼是 Shader

大家好，我是鱈魚。%(｡･∀･)ﾉﾞ%

其實大部分的視覺效果或特效用 SVG Filter、Canvas2D API，甚至用 HTML + CSS 也能實現

曾經我也很熱衷使用[純 CSS 實現各種視覺效果](https://codepen.io/collection/GoqZzQ)，所以為甚麼還要學 Shader 呢？

原因很單純，就是早晚會撞到效能天花板。%( ˘･з･)%

沒辦法強迫大家用超強機器，效能要好只能靠 GPU，而 GPU 只認識 Shader，所以還是只好乖乖來研究 Shader 惹。%ԅ( ˘ω˘ԅ)%

剛好最近很常做[基於 Shader 的效果](https://chillcomponent.codlin.me/components/bg-starry-sea/)，想說還是來寫個筆記，以免自己金魚腦，常常忘記。

如果你已經熟悉 JavaScript，那你離 Shader 只差幾個關鍵觀念的距離。

讓我們從 JS 開發者的視角，一步步搞懂 Shader 到底在幹嘛。%(•̀ω•́)✧%

路人：「JS 不熟，只會框架怎麼辦？%(◜௰◝)%」

鱈魚：「那就來幫我點廣告，一起熱鬧熱鬧也好 %(„ಡωಡ„)%」

::: tip 關於 Shader 語言
瀏覽器有兩套圖形 API，各自有不同的 Shader 語言：

* **WebGL** → **GLSL**（OpenGL Shading Language）
* **WebGPU** → **WGSL**（WebGPU Shading Language）

兩者核心觀念（渲染管線、Vertex/Fragment Shader、Uniform 等）幾乎一樣，只是語法不同。

本文以 **WebGL + GLSL** 為主，未來有機會再聊聊 WGSL。
:::

## GPU 與 CPU 的思維差異

Shader 與一般的 JS 程式有個關鍵差異要注意。%( •̀ ω •́ )✧%

一般 JS 程式走 CPU 的思路：「一步一步，一個一個來」，但 GPU 是「一口氣處理所有像素」。

鱈魚：「和鱈魚和油魚一樣，差一個字差很多 %(・∀・)９%」

路人：「隨便拉，看起來都很肥 %(。-\`ω´-)%」

鱈魚：「我說那個尊重呢？%(╥ω╥\`)%」

甚麼意思哩？可以看看以下示意圖。

CPU 要一格一格慢慢塗，GPU 則是一口氣全部塗完。%( •̀ ω •́ )✧%

## Shader 是什麼？

瀏覽器畫畫面時，背後有一條「渲染管線」。

Shader 就是管線中**可以用程式自訂**的步驟。

WebGL2 只有兩種 Shader：

| 類型            | 用途               | 執行頻率       |
| --------------- | ------------------ | -------------- |
| Vertex Shader   | 決定每個頂點的位置 | 每個頂點跑一次 |
| Fragment Shader | 決定每個像素的顏色 | 每個像素跑一次 |

WebGPU / OpenGL 4.x+ / Vulkan / DirectX 還有其他 Shader 類型：

| 類型                | 用途                                                        |
| ------------------- | ----------------------------------------------------------- |
| Geometry Shader     | 可以新增或刪除頂點，例如把一個點變成一個三角形              |
| Tessellation Shader | 把粗糙的網格細分成更多三角形，用於地形、曲面等              |
| Compute Shader      | 通用 GPU 運算，不一定和圖形渲染有關（物理模擬、粒子系統等） |
| Mesh Shader         | 較新的概念，取代 Vertex + Geometry 的組合，效能更好         |

簡單來說，Vertex Shader 圈出哪些像素可以畫，接著讓 Fragment Shader 決定像素要畫甚麼顏色。%(*´ω`)人(´ω`*)%

### Vertex Shader：決定形狀與位置

所以 Vertex Shader 怎麼圈出哪些像素可以畫呢？答案是給他一堆點（頂點）。

路人：「可以撐起地球那種嗎？」

鱈魚：「那是支點 %(́⊙◞౪◟⊙‵)%」

在 JavaScript 準備好頂點座標後，GPU 會對每個頂點各跑一次 Vertex Shader。

```glsl
attribute vec2 a_position;

void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
}
```

`a_position` 是從 JavaScript 傳進來的頂點座標（Attribute），每個頂點跑一次。

`gl_Position` 是 GLSL 的內建變數，用來告訴 GPU「這個頂點放在哪」。`vec4` 的四個值分別是 x、y、z、w。

簡單說，z 控制深度（誰擋住誰），w 和透視投影有關（近大遠小）。2D 用不到這些，所以 z 固定 `0.0`、w 固定 `1.0` 就好。詳細原理會在 [EP02](./260407.02-vertex-shader) 說明。

準備好頂點資料後，JavaScript 會呼叫 `gl.drawArrays(mode, first, count)` 告訴 GPU「開始畫」。

第一個參數 `mode` 決定 GPU 怎麼連接這些頂點。

常見的繪圖模式有：

**點**

`gl.POINTS`：每個頂點畫一個點，大小由 `gl_PointSize` 決定。

**線**

`gl.LINES`：每 2 個頂點連一條線。

**三角形**

`gl.TRIANGLES`：每 3 個頂點組一個獨立三角形，最通用。需要 6 個頂點才能拼出四邊形。

本文的互動編輯器用的是 `gl.TRIANGLES`，用兩個三角形拼出一個覆蓋整個畫面的四邊形：

有了這個全螢幕四邊形，Fragment Shader 就能在畫面上的每個像素執行。

現在看不太懂沒關係，[EP02](./260407.02-vertex-shader) 我們會詳細介紹 Vertex Shader，以及如何用它來繪製各種圖形。%ヾ(◍'౪\`◍)ﾉﾞ%

### Fragment Shader：決定像素顏色

Vertex Shader 決定了頂點圍出的區域後，GPU 會自動把那個區域內的每個像素都交給 Fragment Shader 處理。

不同的繪圖模式，Fragment Shader 執行的範圍也不同：

* **`POINTS`**：每個頂點周圍 `gl_PointSize × gl_PointSize` 的正方形區域
* **`LINES`**：每條線段涵蓋的像素
* **`TRIANGLES`**：三角形內部的所有像素

本文用兩個三角形拼成全螢幕四邊形，所以 Fragment Shader 會在畫面上的**每一個像素**都跑一次。

每個像素執行時，可以透過 `gl_FragCoord.xy` 知道「我是畫面上哪一個像素」，然後透過 `gl_FragColor` 決定最終顏色。

```glsl
precision mediump float;

void main() {
  gl_FragColor = vec4(0.2, 0.6, 1.0, 1.0);
}
```

`precision mediump float` 是 WebGL 的 Fragment Shader 必須宣告的浮點精度。有三種可以選：

| 精度      | 用途                       |
| --------- | -------------------------- |
| `lowp`    | 省電，但容易出現色階斷層   |
| `mediump` | 夠用於大部分 2D 效果       |
| `highp`   | 精準計算距離、座標時必須用 |

## GLSL 語法速成

WebGL Shader 使用的語言叫 **GLSL**（OpenGL Shading Language），語法長得跟 C 很像。

### 型別對照

| JS / TS | GLSL | 說明 |
|---------|------|------|
| `number` | `float` | 浮點數（GLSL 沒有整數混用，`1` 要寫成 `1.0`） |
| `number` | `int` | 整數 |
| `boolean` | `bool` | 布林值 |
| — | `vec2` | 二維向量 `vec2(x, y)` |
| — | `vec3` | 三維向量 `vec3(r, g, b)` 或 `vec3(x, y, z)` |
| — | `vec4` | 四維向量 `vec4(r, g, b, a)` |

### 向量操作

向量是 GLSL 最強大的特色之一，一行就能做到 JS 需要好幾行的事。

```glsl
vec3 color = vec3(1.0, 0.5, 0.3);

// Swizzling：隨意取出分量重組
vec2 rg = color.rg;     // vec2(1.0, 0.5)
vec3 bgr = color.bgr;   // vec3(0.3, 0.5, 1.0)

// 向量運算：整組一起算
vec3 a = vec3(1.0, 2.0, 3.0);
vec3 b = vec3(4.0, 5.0, 6.0);
vec3 c = a + b;  // vec3(5.0, 7.0, 9.0)
vec3 d = a * 2.0; // vec3(2.0, 4.0, 6.0)
```

同樣的邏輯用 JS 來寫的話：

```js
const color = [1.0, 0.5, 0.3]

// 取出分量要自己 index
const rg = [color[0], color[1]]
const bgr = [color[2], color[1], color[0]]

// 向量運算要用迴圈或 map
const a = [1.0, 2.0, 3.0]
const b = [4.0, 5.0, 6.0]
const c = a.map((value, i) => value + b[i])
const d = a.map((value) => value * 2.0)
```

### 常用內建函式

| GLSL 函式 | 對應概念 | 說明 |
|-----------|---------|------|
| `mix(a, b, t)` | 線性插值 | `a * (1-t) + b * t`，`t` 在 0~1 之間 |
| `step(edge, x)` | 階梯函式 | `x < edge ? 0.0 : 1.0` |
| `smoothstep(a, b, x)` | 平滑階梯 | 在 a~b 之間平滑過渡 |
| `length(v)` | 向量長度 | `sqrt(v.x² + v.y²)` |
| `clamp(x, min, max)` | 限制範圍 | 等同 `Math.min(Math.max(x, min), max)` |
| `sin(x)` / `cos(x)` | 三角函式 | 和 JS 的 `Math.sin` 一樣 |
| `abs(x)` | 絕對值 | 和 JS 的 `Math.abs` 一樣 |

## Fragment Shader：你的第一個像素函式

理論夠多了，讓我們來動手看看吧！%(・∀・)９%

Fragment Shader 核心概念相當簡單：

每個 pixel 都會問自己兩個問題：

1. **我在哪裡？** → `gl_FragCoord.xy`（像素座標）
2. **我要什麼顏色？** → `gl_FragColor = vec4(r, g, b, a)`

就醬！ヾ(◍'౪\`◍)ﾉﾞ

整個 Fragment Shader 說穿了就是一個函式：「給定座標，回傳顏色」。

來試試你的第一個 Shader，下方的編輯器可以直接修改程式碼，改完會即時更新畫面。

試著把 `vec4(0.2, 0.6, 1.0, 1.0)` 裡的數字改成其他值看看。

小提醒：

* GLSL 的顏色值範圍是 `0.0` ~ `1.0`，不是 CSS 的 `0` ~ `255`。所以 `vec4(1.0, 0.0, 0.0, 1.0)` 就是純紅色。

* `vec4` 的第四個值是 alpha（透明度），但你可能會發現改成 `0.0` 畫面完全沒有變化。

  因為 WebGL 預設把 alpha 預乘進顏色（`premultipliedAlpha`），加上沒有開啟透明混合（Blending），alpha 在這裡不會有任何效果。

* `gl_FragColor` 只能用 `vec4`，不能直接塞 `vec3` 進去，不像 JS 會自動轉型。

  寫 `gl_FragColor = vec3(0.2, 0.6, 1.0)` 會直接編譯錯誤。

### 座標正規化與 UV

直接用 `gl_FragCoord` 也可以，不過座標會是實際的像素值（例如 800、600），用起來有幾個痛點：

* 畫布大小一變，效果就跑版（800px 寫好的圓心座標，換成手機 375px 就偏了）
* 很多數學函式（`sin`、`smoothstep`）在 0~1 的範圍內最好用
* 別人的 Shader 範例幾乎都用正規化座標，不轉換就看不懂

所以通常我們會把座標「正規化」到 `0.0 ~ 1.0` 的範圍，這個正規化後的座標習慣叫做 **UV**。

```glsl
vec2 uv = gl_FragCoord.xy / u_resolution;
```

這樣不管畫布多大，`uv.x` 和 `uv.y` 都會在 0 到 1 之間，同一段程式碼到處都能用。

來看看用 UV 座標做出漸層效果有多簡單。

把座標值當成顏色值，就自動產生了漸層。%(ゝ∀・)b%

## Uniform：JS 與 Shader 的溝通橋樑

到目前為止，Shader 都只是自己跟自己玩。

實際上需要從 JS 傳資料進去，例如「現在過了幾秒」或「滑鼠在哪裡」。

這時候就要用 **Uniform**。

`uniform` 這個字在 GLSL 裡是個修飾詞，代表「這個值從外部（JS）傳進來，而且**每個 pixel 都拿到同樣的值**」。

本文的互動編輯器已經幫你注入了三個常用的 uniform：

| Uniform | 型別 | 說明 |
|---------|------|------|
| `u_time` | `float` | 從啟動開始經過的秒數 |
| `u_resolution` | `vec2` | 畫布寬高（像素） |
| `u_mouse` | `vec2` | 滑鼠在畫布上的位置 |

來試試用 `u_time` 做動畫效果。

## 常見圖形

學會了基礎概念，來看看幾個經典的 Shader 圖形怎麼做。

下方的編輯器提供了幾個預設範例，可以切換來看，也可以直接修改試玩。%◝( •ω• )◟%

### 畫圓的原理

記得 Shader 繪製都要從像素的視角出發。%(｢･ω･)｢%

所以畫圓的重點在於判斷目前的 pixel 距離圓心有多遠。

來逐行拆解上面「圓形」預設範例的程式碼。

#### 第一步：UV 正規化

```glsl
vec2 uv = gl_FragCoord.xy / u_resolution;
```

把像素座標除以畫布尺寸，得到 `0.0 ~ 1.0` 的 UV 座標，前面介紹過了。

#### 第二步：把原點移到畫面中心

```glsl
vec2 center = uv - 0.5;
```

UV 的原點在左下角 `(0, 0)`，減掉 `0.5` 後原點就移到畫面正中間了。

這時候座標範圍會變成 `-0.5 ~ 0.5`，中心點是 `(0, 0)`。

#### 第三步：修正長寬比

不過有個小陷阱，UV 的 x 和 y 都是 `0.0 ~ 1.0`，但畫布通常不是正方形。

假設畫布是 600×300，那 x 方向的 `0.3` 實際上代表 180px，y 方向的 `0.3` 只有 90px。用 `length()` 算出來的「圓」看起來會變成橢圓。

解法很簡單，把 x 乘上長寬比，讓 x 和 y 在像素層面等比：

```glsl
center.x *= u_resolution.x / u_resolution.y;
```

以 600×300 的畫布為例，長寬比是 `2.0`，所以 `center.x` 會拉伸為兩倍，讓 x 方向和 y 方向的距離單位一致。

這樣 `length()` 算出來的距離就會維持等比，圓就是圓了。%(•̀ω•́)✧%

#### 第四步：計算距離

```glsl
float dist = length(center);
```

`length()` 就是畢氏定理（`sqrt(x² + y²)`），算出目前像素到中心點 `(0, 0)` 的距離。

#### 第五步：用 step 判斷圓的邊界

```glsl
float circle = step(dist, 0.3);
```

`step(edge, x)` 的規則很簡單：`x >= edge` 回傳 `1.0`，否則 `0.0`。

所以 `step(dist, 0.3)` 就是在問「`0.3` 有沒有 `>=` dist」：

* 圓內（dist < 0.3）→ `0.3 >= dist` 成立 → `1.0`
* 圓外（dist >= 0.3）→ `0.3 >= dist` 不成立 → `0.0`

也就是圓內得到 `1.0`，圓外得到 `0.0`。%( •̀ ω •́ )✧%

#### 第六步：用 mix 混色

```glsl
vec3 color = mix(
  vec3(0.1, 0.1, 0.2),   // 背景色
  vec3(0.2, 0.8, 0.6),   // 圓的顏色
  circle
);
```

`mix(a, b, t)` 是線性插值，公式是 `a * (1 - t) + b * t`。

* `circle = 1.0`（圓內）→ 取第二個顏色，藍綠色
* `circle = 0.0`（圓外）→ 取第一個顏色，深色背景

#### 第七步：輸出

```glsl
gl_FragColor = vec4(color, 1.0);
```

把 `vec3` 的顏色加上 alpha `1.0`，組成 `vec4` 輸出。

你可能會想問：「為甚麼第五到七步不直接用 `if-else` 就好？比 `step` + `mix` 更直覺不是嗎？」%(´・ω・\`)%

```glsl
if (dist < 0.3) {
  gl_FragColor = vec4(0.2, 0.8, 0.6, 1.0);
} else {
  gl_FragColor = vec4(0.1, 0.1, 0.2, 1.0);
}
```

的確更直覺沒錯，不過使用 `step` + `mix` 避開 `if` 是為了避免 **branch divergence** 的問題。

GPU 會把像素分成一小組一小組，同一組裡的像素**強制同步（lockstep），每個時鐘週期都執行同一條指令**。

::: tip
NVIDIA 叫 **warp**，32 個一組；AMD 叫 **wavefront**，64 個
:::

如果遇到 `if-else`，warp 裡有些像素走 `if`、有些走 `else`，但大家被綁在一起沒辦法各走各的，GPU 只好**兩條路都跑**。

以畫圓為例，假設一個 warp 裡有 20 個像素在圓內、12 個在圓外：

1. 先讓 32 個像素全部執行 `if` 分支（塗藍綠色），但圓外那 12 個會被遮罩住，算完後丟棄
2. 再讓 32 個像素全部執行 `else` 分支（塗背景色），換圓內那 20 個被遮罩住

等於每個像素都跑了兩條路的指令，花了兩倍時間，`step` 是純數學運算，不需要分支，GPU 一口氣就算完了。

所以 Shader 裡盡量避免使用 `if-else`，能用純數學運算就用數學運算。%(⌐■\_■)✧%

理解了每一行之後，來看看完整的畫圓流程圖：

最終效果就是半徑內被塗成藍綠色，半徑外被塗成深色背景，整體看起來就是一個圓。%(ゝ∀・)b%

### 挑戰時間

試試看能不能改出這些效果：

1. 讓圓形跟著時間移動（提示：圓心加上 `sin(u_time)` 位移）
2. 畫出同心圓（提示：對 distance 做 `sin` 或 `fract`）
3. 把硬邊圓改成柔和邊緣（提示：用 `smoothstep` 取代 `step`）

## 總結 🐟

* Shader 是在 GPU 上執行的小程式，分為 **Vertex Shader**（處理位置）和 **Fragment Shader**（處理顏色）
* GPU 的思維是「每個 pixel 同時獨立計算」，不是 CPU 的「一步一步來」
* 透過 **Uniform** 可以從 JS 傳入時間、滑鼠位置等動態資料

### 推薦學習資源

* [The Book of Shaders](https://thebookofshaders.com/)：最經典的 Shader 互動教學
* [Shadertoy](https://www.shadertoy.com/)：Shader 界的 CodePen，大量範例可以拆來學

以上就是從 JS 開發者角度的 Shader 入門，有錯誤還請多多指教。

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。%(\*´∀\`)~♥%

---

---
url: /column-shader-notes/02-vertex-shader.md
description: 從 Attribute 到 Varying，搞懂 Vertex Shader 怎麼控制每個頂點的位置、大小與顏色！(｢･ω･)｢✧
---

![shader-notes](/shader-notes.webp){.cover}

# 鱈魚的 Shader 筆記 - EP02：認識 Vertex Shader

大家好，我是鱈魚。%(｡･∀･)ﾉﾞ%

[上一篇](./01-shader-intro)我們認識了 Fragment Shader，學會讓每個像素自己決定顏色。

不過當時的頂點都是固定的全螢幕四邊形，Vertex Shader 只負責把座標原封不動丟出去，毫無存在感。%(´ー\`)%

現在讓我們來認識 Vertex Shader，學會怎麼控制每個頂點的位置、大小和顏色。

先來看看最終成品：

畫面上每個點的位置、大小、顏色全都不一樣，這些全靠 Vertex Shader 搞定。

要做到這個效果，我們需要搞懂四個核心概念：

1. **Attribute**：讓每個頂點擁有專屬資料
2. **繪圖模式**：決定頂點要連成什麼形狀
3. **gl\_PointSize**：控制點的大小
4. **Varying**：讓資料從 Vertex Shader 傳到 Fragment Shader

讓我們一關一關來。%(•̀ω•́)✧%

## 第一關：Attribute

### 為什麼需要 Attribute？

EP01 介紹過 Uniform，它從 JS 傳資料到 Shader，特色是**每個頂點拿到的值都一樣**。

但如果要讓每個頂點出現在不同位置呢？用 Uniform 做不到，因為所有頂點都會拿到同一組座標，全部擠在一起。

這時候就需要 **Attribute**。

| 特性 | Uniform | Attribute |
|------|---------|-----------|
| 資料來源 | JS 傳入 | JS 傳入 |
| 每個頂點的值 | 全部一樣 | 各自不同 |
| 宣告方式 | `uniform vec2 u_xxx` | `attribute vec2 a_xxx` |
| 常見用途 | 時間、滑鼠位置、畫布尺寸 | 頂點座標、顏色、大小 |

簡單說，Uniform 是廣播，Attribute 是點名發資料。%(・∀・)９%

### JS 端怎麼傳 Attribute？

Attribute 資料存在 JS 這邊，但 Shader 跑在 GPU 上。兩邊記憶體不共通，所以不能直接丟變數過去。

想像你要寄包裹給 GPU，流程大概是這樣：

1. **準備箱子**（建立 Buffer）
2. **把箱子放上輸送帶**（綁定到 ARRAY\_BUFFER）
3. **往箱子裡塞資料**（bufferData）
4. **在箱子上貼標籤**，告訴 GPU「裡面是什麼、怎麼讀」（vertexAttribPointer）

一步一步來。%( •̀ ω •́ )✧%

#### Step 1、2、3：建立 Buffer 並塞資料

```js
// 準備箱子
const buffer = gl.createBuffer()

// 放上輸送帶
gl.bindBuffer(gl.ARRAY_BUFFER, buffer)

// 塞入 3 個頂點的座標（每個頂點 2 個 float：x, y）
const positionList = new Float32Array([
  -1.0, // 頂點 1 左下（x）
  -1.0, // 頂點 1 左下（y）
  1.0, // 頂點 2 右下（x）
  -1.0, // 頂點 2 右下（y）
  -1.0, // 頂點 3 左上（x）
  1.0, // 頂點 3 左上（y）
])
gl.bufferData(gl.ARRAY_BUFFER, positionList, gl.STATIC_DRAW)
```

`Float32Array` 裡的數字是攤平的一維陣列，每 2 個一組就是一個頂點的 `(x, y)`。

試著新增或修改下方的頂點資料，觀察右邊攤平後的陣列怎麼對應：

`gl.STATIC_DRAW` 用於提示 GPU 這筆資料不會常常更新，方便做快取最佳化。如果會頻繁更新就用 `gl.DYNAMIC_DRAW`，不過用錯也不會壞，只是效能差一點。

#### Step 4：貼標籤，讓 GPU 知道怎麼讀

資料塞進去了，但 GPU 還不知道這堆數字代表什麼。這一步就是告訴它：「這個 Buffer 對應 Shader 裡的 `a_position`，每次讀 2 個 float 當一組」。

```js
// 找到 Shader 裡 a_position 的位置
const location = gl.getAttribLocation(program, 'a_position')

// 啟用這個 attribute
gl.enableVertexAttribArray(location)

// 告訴 GPU 怎麼讀：每個頂點讀 2 個 float
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0)
```

`vertexAttribPointer` 的第二個參數 `2` 代表「每個頂點讀 2 個 float」，對應 Shader 裡的 `vec2`。如果是 `vec3` 就填 `3`，`float` 就填 `1`。

整理一下兩邊的對應關係：

| JS 端 | Shader 端 | 說明 |
|-------|-----------|------|
| `Float32Array([-1, -1, 1, -1, ...])` | `attribute vec2 a_position` | 資料內容 ↔ 變數宣告 |
| `getAttribLocation(program, 'a_position')` | `a_position` | 透過名字找到彼此 |
| `vertexAttribPointer(loc, 2, ...)` | `vec2` | 每個頂點讀幾個 float |

簡單說，JS 負責「準備資料、說明格式」，Shader 負責「接收並使用」。兩邊靠 **attribute 的名字**（如 `a_position`）連結在一起。%(ゝ∀・)b%

整個流程一圖總結：

### gl\_Position 的 z 和 w

EP01 提過 `gl_Position = vec4(x, y, z, w)`，當時 z 和 w 都直接帶常數，現在來搞懂它們各自在幹嘛。

#### z 控制深度

z 決定「誰在前面、誰被擋住」。GPU 用 z 值做深度測試（depth test），z 越小越靠近鏡頭。2D 場景不需要遮擋，所以固定 `0.0`。

#### w 控制透視縮放

`vec4(x, y, z, w)` 其實是數學上的**齊次座標**（homogeneous coordinates），多出來的 w 讓平移、旋轉、縮放、投影都能用同一套矩陣乘法搞定。

GPU 會在最後一步把 x、y、z 全部**除以 w**，這步叫做透視除法（perspective division）。

```glsl
// GPU 內部做的事
螢幕座標 = (x/w, y/w, z/w)
```

做 3D 透視投影時，投影矩陣會把「離鏡頭的距離」塞進 w。離越遠 → w 越大 → 除完後座標越小 → 物體看起來越小，自然產生近大遠小的效果。

2D 不需要透視，所以 w 固定 `1.0`（除以 1 嘛，就是除了個寂寞 %(´・ω・\`)%）。

總結來說 z 負責排序，w 負責縮放。齊次座標和投影矩陣的推導是一整塊大主題，之後有機會再開一篇來聊 %(´∀\`)%

### 動手試試：Attribute

下方的範例使用 `gl.POINTS` 模式繪製頂點。

可以試試看：

* 新增或修改頂點資料
* Vertex Shader：微調位置與尺寸。
* Fragment Shader：修改顏色。

## 第二關：繪圖模式

### 頂點怎麼連成形狀？

有了頂點座標，接下來 GPU 要決定「這些點怎麼連」。

這由 `gl.drawArrays(mode, first, count)` 的第一個參數 `mode` 決定。EP01 提過 `POINTS`、`LINES`、`TRIANGLES`，這裡完整介紹所有模式。

**點**

`gl.POINTS`：每個頂點畫一個點。

**線**

| 模式 | 規則 | 說明 |
|------|------|------|
| `LINES` | 每 2 個一組 | 1-2 一條、3-4 一條，奇數個會忽略最後一個 |
| `LINE_STRIP` | 前後相連 | 1-2、2-3、3-4... 像折線圖 |
| `LINE_LOOP` | 前後相連 + 首尾相接 | 和 LINE\_STRIP 一樣，最後再從尾連回頭 |

**三角形**

| 模式 | 規則 | 說明 |
|------|------|------|
| `TRIANGLES` | 每 3 個一組 | 1-2-3 一個、4-5-6 一個，不共用頂點 |
| `TRIANGLE_STRIP` | 前後共用 | 1-2-3、2-3-4、3-4-5... 每個新頂點和前兩個組成三角形 |
| `TRIANGLE_FAN` | 扇形展開 | 1-2-3、1-3-4、1-4-5... 第一個頂點是共用的中心 |

### 動手試試：繪圖模式

下方用同一組五邊形頂點，切換不同繪圖模式看看實際效果。

切換模式前可以先仔細想想，猜猜看會跑出什麼圖案。%੭ ˙ᗜ˙ )੭%

::: tip 點不夠會怎麼樣？
頂點數不能整除時，多餘的頂點會被忽略，目前只有 5 個頂點，所以：

* `LINES` 模式只能配成 2 條線（4 個頂點），
* `TRIANGLES` 模式只能組成 1 個三角形（3 個頂點）。
  :::

是不是很有趣啊！%ԅ(´∀\` ԅ)%

## 第三關：gl\_PointSize

### 控制點的大小

`gl.POINTS` 模式下，每個點預設只有 1 像素，幾乎看不到。

在 Vertex Shader 裡可以透過內建變數 `gl_PointSize` 設定點的大小（單位是像素）：

```glsl
void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
  gl_PointSize = 20.0;  // 每個點 20px
}
```

不過這樣每個點都一樣大，有點無聊。

如果想讓每個點大小不同，只要再加一個 Attribute 就好：

```glsl
attribute vec2 a_position;
attribute float a_size;    // 每個頂點專屬的大小

void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
  gl_PointSize = a_size;   // 用 Attribute 的值
}
```

JS 端再多開一個 Buffer 塞大小資料：

```js
const sizeList = new Float32Array([20.0, 35.0, 15.0, 45.0, 28.0])
// 建立 Buffer、綁定、塞資料、設定 vertexAttribPointer...
// 流程和 a_position 一樣，只是 size 參數改成 1（每個頂點讀 1 個 float）
```

概念相同，意思是如果以後需要追加顏色、透明度，只要 Buffer 開好開滿，想傳幾組就傳幾組！%ᕕ( ﾟ ∀。)ᕗ%

不過 Shader 裡能同時使用的 attribute 數量有上限，WebGL 保證至少 16 個，一般夠用了 %(ゝ∀・)b%

### gl\_PointCoord：點內部的座標

`gl.POINTS` 模式有個限定的 Fragment Shader 內建變數：`gl_PointCoord`。

`gl.POINTS` 模式下，每個點在螢幕上佔一個正方形區域（大小由 `gl_PointSize` 決定）。`gl_PointCoord` 就是這個正方形內部的相對座標，範圍 `0.0 ~ 1.0`，左上角 `(0, 0)`，右下角 `(1, 1)`。

注意 `gl_PointCoord` 和 JS 傳入的頂點座標（`a_position`）完全無關。

`a_position` 決定點畫在畫布哪裡，`gl_PointCoord` 則是點內部每個像素的座標。

利用 `gl_PointCoord` 可以在方形的點裡畫出圓形：

```glsl
void main() {
  vec2 center = gl_PointCoord - 0.5;
  float dist = length(center);

  // 丟棄圓外的像素
  if (dist > 0.5) discard;

  gl_FragColor = vec4(0.2, 0.8, 0.6, 1.0);
}
```

`gl_PointCoord - 0.5` 把座標原點移到正方形中心，`length()` 算出離中心的距離。

超過 `0.5` 就在圓外，用 `discard` 丟棄。

`discard` 是 GLSL 的關鍵字，作用是「這個 fragment 不畫了，蛋雕！%੭ ˙ᗜ˙ )੭%」。

::: tip Fragment 和 Pixel 不一樣喔
嚴格來說，Fragment Shader 處理的是 **fragment**，不是 pixel。

fragment 是「可能成為 pixel 的候選人」，還要通過深度測試、alpha 測試等關卡才能變成最終螢幕上的 pixel。

就像面試過了不代表拿到 offer，中間還有好幾關 %(´・ω・\`)%

不過入門階段暫時把 fragment 想成像素也沒問題，之後接觸深度測試、stencil 測試時自然會更清楚兩者的差異。
:::

### 動手試試：gl\_PointSize

下方範例用了 `a_position` 和 `a_size` 兩個 Attribute，搭配 `gl_PointCoord` 畫出柔和邊緣的圓點。

重點在 Fragment Shader 這行：

```glsl
float alpha = 1.0 - smoothstep(0.35, 0.5, dist);
```

`smoothstep(edge0, edge1, x)` 會在 `edge0` 到 `edge1` 之間產生平滑的 0→1 過渡，所以：

* `0.35`（edge0）：dist 小於此值時，`smoothstep` 回傳 `0`，alpha 為 `1.0`，完全不透明
* `0.5`（edge1）：dist 大於此值時，`smoothstep` 回傳 `1`，alpha 為 `0.0`，完全透明
* 兩者之間就是柔和漸變的區間

間距越大，邊緣越朦朧；兩個值越接近，邊緣越銳利。

* 把 `0.35` 改成 `0.1`，漸層範圍變大，圓點像水母一樣軟趴趴
* 改成 `0.49`，幾乎沒有漸層，邊緣硬得像餅乾 %(´∀\`)%

不過光在 Shader 裡設定 alpha 還不夠，WebGL 預設不處理透明度，需要在 JS 端手動開啟 **Alpha Blending**：

```js
// 這段寫在 JS 的繪製流程中，通常放在 gl.drawArrays() 之前
gl.enable(gl.BLEND)
gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
```

`blendFunc` 設定混合公式，`SRC_ALPHA` 和 `ONE_MINUS_SRC_ALPHA` 就是最常見的「正常透明度」效果。

如果沒開，Shader 算出的 alpha 會完全沒有效果，寫了個寂寞 %(´;ω;\`)%

## 第四關：Varying

### 從 Vertex 到 Fragment 的橋樑

到目前為止，Fragment Shader 的顏色都直接寫死在程式碼裡，如何讓每個頂點有不同顏色呢？

顏色是 Fragment Shader 的工作，但「每個頂點不同」的資料只有 Attribute 能做到，而 Attribute 只能在 Vertex Shader 裡使用。

怎麼辦？用 **Varying** 當作中間人。%(•̀ω•́)✧%

```glsl
// ── Vertex Shader ──
attribute vec2 a_position;
attribute vec3 a_color;
varying vec3 v_color;      // 宣告 varying

void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
  v_color = a_color;        // 把顏色交給 varying
}
```

```glsl
// ── Fragment Shader ──
precision mediump float;
varying vec3 v_color;       // 同名的 varying

void main() {
  gl_FragColor = vec4(v_color, 1.0);
}
```

兩邊都宣告同名同型別的 `varying`，就可以 Vertex Shader 寫入，Fragment Shader 讀取。

簡單來說就是 JS 傳給 Vertex Shader，Vertex Shader 再傳給 Fragment Shader，接力賽的概念 %( ‧ω‧)ノ╰(‧ω‧ )%

### GPU 自動插值

Varying 最神奇的地方在於 GPU 會自動做**插值**。

假設三角形的三個頂點分別設定紅、綠、藍三種顏色，三角形內部的每個 fragment 會根據自己和三個頂點的距離，自動混合出過渡色。

不需要寫任何混色的程式碼，GPU 的 rasterizer 會自動算出對應比例，這是 fixed function（固定管線功能），不能用 Shader 改寫。

這就是為什麼 OpenGL 入門教學常常以「彩色三角形」當作 Hello World。%(ゝ∀・)b%

::: tip 其實不是單純的線性插值
預設的插值模式是**透視校正插值**（perspective-correct interpolation），會把頂點的 w 分量納入計算，確保 3D 透視場景下的插值結果看起來正確。

我們目前 w 都是 `1.0`，所以效果和線性插值完全一樣，未來有機會再來詳細比較 %(´∀\`)%
:::

### 動手試試：Varying

經典的彩色三角形，三個頂點分別是紅、綠、藍。

試試以下改法：

* 切到 Vertex Shader，把 `v_color = a_color` 改成 `v_color = vec3(1.0, 1.0, 0.0)`，三個頂點都傳同一色，整個三角形變成純黃色，插值無事可做
* 改成 `v_color = vec3(a_position, 0.0)`，把座標當顏色用，左下偏黑、右下偏紅、上方偏綠，座標值直接反映在色彩上 %(°ω°)ﾉ%
* 切到 Fragment Shader，把 `gl_FragColor = vec4(v_color, 1.0)` 改成 `gl_FragColor = vec4(1.0 - v_color, 1.0)`，顏色反轉，原本的紅變成青、綠變成洋紅

## 組合技：回到成品

學完四關，再回頭看看開頭的成品。切到 Vertex Shader 分頁，逐行解讀：

```glsl
attribute vec2 a_position;   // Attribute：每個頂點的座標
attribute float a_size;      // Attribute：每個頂點的大小
attribute vec3 a_color;      // Attribute：每個頂點的顏色

varying vec3 v_color;        // Varying：傳給 Fragment Shader

void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
  gl_PointSize = a_size;     // 控制點的大小
  v_color = a_color;         // 把顏色交出去
}
```

Fragment Shader 負責用 `gl_PointCoord` 把方形的點畫成圓形，再從 `v_color` 取得顏色：

```glsl
precision mediump float;

varying vec3 v_color;

void main() {
  vec2 center = gl_PointCoord - 0.5;
  float dist = length(center);

  if (dist > 0.5) discard;

  float alpha = 1.0 - smoothstep(0.3, 0.5, dist);
  gl_FragColor = vec4(v_color, alpha);
}
```

### 挑戰時間

試試看能不能改出這些效果：

1. 讓點的位置隨 `u_time` 移動（提示：`gl_Position.x += sin(u_time)` 之類的）
2. 讓點的大小隨時間脈動（提示：`gl_PointSize = a_size + sin(u_time) * 10.0`）
3. 讓顏色隨時間變化（提示：在 Fragment Shader 裡對 `v_color` 加上 `sin(u_time)` 的偏移）

## 總結 🐟

* **Attribute**讓每個頂點擁有專屬資料，和 Uniform 的「全部一樣」互補
* **繪圖模式**決定 GPU 怎麼連接頂點：POINTS、LINES、TRIANGLES 等，90% 的時候用 TRIANGLES 就好
* **gl\_PointSize**在 POINTS 模式下控制點的大小，搭配 `gl_PointCoord` 可以在點內部畫圓
* **Varying**是 Vertex Shader 傳資料給 Fragment Shader 的橋樑，GPU 會自動做線性插值

下一篇我們會用這些概念組合出真正的粒子系統，讓大量的點動起來，產生煙霧飄散的效果。敬請期待！%(ノ>ω<)ノ%

以上就是 Vertex Shader 核心概念的介紹，有錯誤還請多多指教。

感謝您讀到這裡，如果您覺得有收穫，歡迎分享出去。%(\*´∀\`)~♥%

---

---
url: /aquarium/codmarbles.md
description: 此專案沒有偉大的技術願景，純粹就是我想看東西滾來滾去而誕生的專案。(ゝ∀・)b
---