點擊之處，
花火綻放。

01 / 安裝

安裝套件

透過 npm 將套件加入你的專案。

npm

npm install shoka-fireworks

02 / 客製與預覽

調配你的煙火色盤

自由增減顏色並即時試放，下方接入程式碼會自動同步。

色彩列表

點選色塊或輸入任意 CSS 顏色值，修改後將在下一朵煙火生效。

互動預覽

即時預覽

在下方畫布中點擊，試試目前配色。

03 / 接入專案

加入你的網站

在瀏覽器端 document.body 就緒後（例如在元件的掛載鉤子中）執行以下程式碼。上方調好的配色已自動填入。

import { fireworks } from "shoka-fireworks";

const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
const cleanup = fireworks({
  shouldPlayAnimation: () => !reducedMotion.matches,
});

// 元件卸載或關閉特效時，呼叫 cleanup() 停止動畫並移除事件監聽。

shouldPlayAnimation 會在每次點擊時檢查 reducedMotion.matches；若開啟了「減少動態效果」，則回傳 false，不再觸發新煙火。

已經綻放的煙火仍會自然播完。如需立即停止所有動畫並移除特效（例如在元件卸載時），請呼叫 cleanup()。

04 / API 參考

`fireworks(config?: FireworkConfig): () => void`

在瀏覽器端 document.body 就緒後呼叫。每次呼叫都會回傳對應的清理函式。

`FireworkConfig`

設定項	型別	預設值	說明
`colors?`	`string[]`	下方 4 種預設柔和色	煙火粒子的 CSS 顏色陣列，至少包含 1 種顏色。
`shouldPlayAnimation?`	`(event: MouseEvent) => boolean`	`() => true`	每次點擊時觸發。回傳 `false` 則當次點擊不放煙火，正在播放的動畫不受影響。

套件本身不會自動偵測「減少動態效果」設定，建議如上方範例所示，在 shouldPlayAnimation 中進行檢查。

預設色盤

[
  "rgba(255,182,185,.9)",
  "rgba(250,227,217,.9)",
  "rgba(187,222,214,.9)",
  "rgba(138,198,209,.9)"
]

清理與卸載

元件卸載或關閉特效時，呼叫 fireworks() 回傳的清理函式，即可停止所有動畫、移除畫布，並解除點擊與視窗縮放事件監聽。

cleanup();

致謝

本函式庫的煙火特效改寫自 Hexo Theme Shoka，謹向原作者霜月琉璃致謝。