Khatt:動畫阿拉伯書法
Khatt 使用 HarfBuzz 排版文字(字母連寫、從右到左、標記正確放置), 將其佈局,並在單一 SVG 檔案內以純 CSS 製作動畫。無需網路、無需安裝: 腳本、字型以及排版引擎都在此資料夾中。
生成圖畫
node scripts/khatt.mjs "النص" --style ruqaa --layout line --effect ink -o out.svg
從此技能資料夾執行,或使用完整路徑指向 scripts/khatt.mjs。
將輸出寫入使用者想要的位置(他們的專案資料夾、桌面等)。
| 選項 | 值 |
|---|---|
--style | ruqaa(日常、傾斜)、naskh(經典書籍字體)、kufi(有稜角)、nastaliq(懸掛式波斯體)、kano(粗蘆葦筆)、blaka(粗體幾何) |
--layout | line、arc、circle(中間有星星的環形)、mirror(經典鏡像 musanna) |
--effect | ink、gold、bleed、mosaic、sand、neon、stars、lantern、rise、stamp、reveal、wave,或一個 .mjs 效果檔案的路徑 |
--palette | paper、night、neon、zellige、desert、clear(透明) |
--ink、--accent、--bg | 覆蓋顏色,例如 --ink "#0b3d2e" --bg none |
--still | 凍結在完成圖畫上(適合 logo 和印刷) |
-o | .svg 輸出檔案本身,.html 輸出可點擊重播的頁面 |
執行 node scripts/khatt.mjs --list 可查看所有選項及其簡短說明。
在文字中使用 \n 換行(最多四行)。
選擇建議
- 名字和英文單字: Khatt 只處理阿拉伯文字。請先音譯 (Sara → سارة、Kamangir → كمنجير),若拼寫可能有多種方式, 請在渲染前向使用者顯示您的拼寫。
- 齋戒月或開齋節: 搭配
lantern或gold效果與night色板,字體選naskh或ruqaa。 - 婚禮和正式卡片:
gold、rise或ink效果;試試--layout mirror。 - Logo:
--still,字體選kufi或blaka,--palette clear。 - 社交媒體貼文: 動畫
.svg可在任何瀏覽器中播放。如需影片, 引導使用者前往工作室(https://m-alkassem.github.io/khatt/),該處可匯出 MP4。 - 短文字效果最佳。長句子:使用
line佈局,兩到三行。
盡可能為使用者開啟結果(例如在 macOS 上執行 open out.html)。
製作新效果
當十二種內建效果都不符合需求時(例如「讓字母燃燒」、「一個擺動的齋戒月燈籠」),
請撰寫一個新效果。從 examples/ripple.mjs 開始。效果只是一個純物件,無需匯入:
export default {
id: "my-effect", name: "My effect", nameAr: "…", blurb: "…",
palette: "night", // 預設色板 ID
loop: false, // true 則持續動畫
render(ctx) {
// 回傳 { css, defs?, body, duration, poster? }
},
};
render(ctx) 會取得:
ctx.pieces:每個字形的條目:d(SVG 路徑)、order(閱讀順序,0 為第一個 字母)、box{x0,y0,x1,y1}、cx、cy。鏡像副本共用相同的 order。ctx.steps、ctx.box(文字框)、ctx.view(整個畫布)、ctx.em(字型大小,100)、ctx.palette(bg、ink、accent)、ctx.rng()(基於 seed 的隨機數生成器)。ctx.stagger(order, spread?):字母的延遲時間,在spread秒數內分散。ctx.sample(piece, count):字母內的隨機點,用於粒子效果。ctx.inside(piece, x, y)、ctx.area(piece)。ctx.anim(name, seconds, { ease, loop, alternate }):用於類別的動畫 CSS。ctx.at(seconds, extraStyle?):設定元素延遲的內聯樣式。ctx.n(number):將數字四捨五入以產生更緊湊的輸出。ctx.p:唯一的字首。用於每個類別、ID 和關鍵影格名稱。
使圖畫在任何影格上都能暫停的規則(靜止畫面和影片匯出依賴於此):
- 每個動畫元素都加上
class="${p}-a ..."和style="${at(seconds)}"。 - 在類別規則中使用
ctx.anim(...)。絕不要自己撰寫animation:簡寫 或設定animation-delay。 - 將關鍵影格命名為
${p}-something。在元素上加上${p}-b即可使其繞自身中心縮放或旋轉。 - 只動畫 CSS 屬性(
opacity、transform、stroke-dashoffset、fill-opacity等)。SMIL<animate>和腳本將無法正確凍結。 - 保持輕量:最多數千個元素。
然後執行它:
node scripts/khatt.mjs "نار" --effect ./my-effect.mjs -o fire.html
如果使用者喜歡,建議他們以 pull request 分享到
https://github.com/M-Alkassem/khatt(效果檔案位於 src/effects/ 中)。