create-apple-notes-mockup
產生看起來像真實 iPhone 螢幕截圖的 Apple Notes 畫面——正確的狀態列、浮動工具列藥丸、粗體標題、帶段落間距的內文、黃色文字游標、自動修正底線、可選的內嵌圖片與核取清單,以及可選的 iOS 鍵盤。
目的
將 JSON 筆記規格轉換為像素級精準的 Apple Notes(iPhone,淺色模式)螢幕截圖——在原生 1180×2556(DPR 2)解析度下輸出 HTML + PNG。此為確定性、無 LLM 的渲染器,create-apple-notes-video-ad 分子會逐幀驅動它來模擬打字動畫,同時也是廣告、社群貼文與故事板中一次性「筆記提醒」場景的獨立工具。協調器負責文案內容;此原子負責精準度(狀態列、智慧型標點、游標、自動修正底線、工具列、鍵盤外觀)。
使用時機
- 需要為廣告、社群貼文、影片場景或產品模型建立假的 Apple Notes 螢幕截圖。
- 需要一系列 Apple Notes 幀(僅標題 → 新增段落 → 游標移動)來驅動打字動畫影片——由
create-apple-notes-video-ad使用。 - 需要在故事板中有一個靜態的「筆記提醒」場景。
如果你要渲染 iMessage 對話串,請改用 skills/atoms/messaging/create-imessage-mockup。
輸入
此技能是確定性的——它不內嵌 LLM。協調器會依照下列 schema 組合出一個筆記 JSON,然後呼叫渲染器。
筆記 JSON schema
{
"title": "Hello",
"body": [
{ "type": "paragraph", "text": "This is a screen recording of me typing on apple notes app." },
{ "type": "paragraph", "text": "Let's see how this feels." }
],
"cursor": "end",
"autocorrect_underline": ["this", "how"],
"status_bar": {
"time": "9:41",
"battery_pct": 87,
"battery_low": false,
"show_focus_glyph": false
},
"show_keyboard": false,
"keyboard_state": {
"suggestions": ["see", "go", "do"],
"shift": "lower",
"letters_row1": "qwertyuiop",
"letters_row2": "asdfghjkl",
"letters_row3": "zxcvbnm"
},
"with_iphone_frame": false
}
title— 字串。粗體顯示標題,單行。body[]— 區塊列表。支援的區塊類型:paragraph—{ "text": "..." }。會自動套用智慧型標點符號('→',"→",...→…,--→–,---→—)。image—{ "src": "<路徑|網址>", "caption": "可選" }。相對路徑會根據規格檔案的目錄解析,並內嵌為 data URI。checklist—{ "items": [{ "text": "...", "checked": true|false }] }。已核取的項目會顯示黃色實心圓圈並加上刪除線;未核取的項目則顯示灰色空心圓圈。divider— 水平分隔線。
cursor—"title" | "end" | null。"title"將黃色游標置於標題結尾;"end"置於最後一段結尾;null則隱藏。autocorrect_underline[]— 區分大小寫的單字列表。每個出現處都會加上 Apple Notes 打字中的黃色底線(<span class="spell">)。status_bar—time、battery_pct(0–100)、battery_low(電池變紅)、show_focus_glyph(時間旁顯示 DND/車輛圖示)。不渲染動態島。show_keyboard—true會疊加 iOS QWERTY 鍵盤與格式化工具列。keyboard_state— 僅在show_keyboard為 true 時使用。shift="lower" | "upper"。with_iphone_frame— 加上薄型深色邊框內嵌(用於主視覺構圖)。
CLI
node render.js --note examples/mid.json
node render.js --note examples/long.json --output ./my-exports/ --name todays-note
node render.js --note my-note.json --with-keyboard
node render.js --note my-note.json --viewport 1080x1920 # 9:16 廣告輸出尺寸
旗標
| 旗標 | 效果 |
|---|---|
--note <路徑> | (必要)符合上述 schema 的 JSON 檔案 |
--with-keyboard | 強制啟用 show_keyboard(覆寫規格) |
--with-iphone-frame | 強制啟用硬體邊框 |
--no-frame | 強制停用硬體邊框 |
--output <目錄> | 日期輸出資料夾的上層目錄;預設為 ./apple-notes-mockup-exports/ |
--name <代號> | 覆寫輸出資料夾的代號 |
--out-html <路徑> / --out-png <路徑> | 直接寫入明確路徑(跳過日期資料夾) |
--viewport 寬x高 | 覆寫渲染視口(預設 1180x2556) |
--dpr N | 裝置像素比(預設 2) |
輸出
<輸出目錄>/<YYYY-MM-DD>-<代號>/
index.html # 完整獨立 HTML(圖片內嵌為 data URI)
screenshot.png # 以選擇的視口 × DPR 渲染的 PNG
spec.json # 輸入的副本,用於再現
預設 <輸出目錄> 為目前工作目錄下的 ./apple-notes-mockup-exports/。
工作流程
- 收到提示或現有的筆記 JSON。
- 如果只給了提示:依照 schema 組合出
note.json,並儲存。 - 執行
node render.js --note <路徑> [--with-keyboard]。 - 開啟產生的 PNG 以確認版面。如果看起來有問題(換行錯誤、游標位置錯誤、電池顏色錯誤),請編輯 JSON 並重新渲染。
設定(一次性)
cd create-apple-notes-mockup
npm install
npx playwright install chromium
儲存庫中附有指向 create-imessage-mockup/node_modules 的符號連結,因此在全新複製時,只有當您希望此技能獨立運作時,才需要執行 npm install。
檔案
| 檔案 | 用途 |
|---|---|
render.js | CLI 入口——解析旗標、解析圖片路徑、產生 HTML、擷取螢幕截圖 |
generate.js | 筆記 JSON → 獨立 HTML 頁面(在此套用智慧型標點與自動修正底線) |
screenshot.js | HTML → PNG,透過 Playwright(Chromium 無頭模式)以 1180×2556、DPR 2 渲染 |
templates/note.css | 所有視覺樣式(狀態列、工具列、內文、核取清單、圖片、鍵盤) |
templates/icons.js | 內嵌 SVG 圖示(返回箭頭、復原、分享、更多、完成勾選、訊號、Wi-Fi、電池、格式化工具列圖示、鍵盤字形) |
assets/samples/sample-landscape.jpg | examples/with-image.json 使用的範例圖片 |
examples/*.json | 6 份涵蓋所有變化的參考筆記(僅標題、打字中、長篇多段落、含核取清單、含圖片、框架1小寫鍵盤) |
tests/run-all.sh | 將每個範例渲染至 tests/output/ 以供視覺審查 |
apple-notes-skill-build.html | 並排審查板,比較參考影片幀與產生的 PNG |
品質檢查
在宣告筆記可出貨之前:
- 標題應渲染為粗體顯示標題,而非一般字重。
- 內文使用 Apple 的智慧型標點——
'應為彎曲,"應為彎曲,…應為單一字元。 - 黃色游標(
#FFCC00)應緊貼目標文字結尾,寬度約 5px。 - 內文段落之間應由一個空白視覺行分隔(無手動
<br>)。 - 自動修正底線應為緊貼標記字詞下方的短黃線,並使用區分大小寫的比對。
- 狀態列:時間靠左,訊號/Wi-Fi/電池靠右。僅當
battery_low: true時電池為紅色。無動態島。 - 滾動遮罩: 狀態列與工具列具有不透明的白色背景,因此由分子驅動器滾動的內文不會穿透顯示。透過在 DevTools 中將
.note平移-300px來驗證,確認標題完全被工具列遮蓋——不會在工具列後方/透過工具列顯示。 - 工具列:浮動返回箭頭藥丸(左)、帶有復原/分享/更多的白色膠囊、黃色完成圓圈(右)。全部帶柔和陰影。
- 鍵盤(啟用時):QWERTY 配置符合
shift的大小寫,建議列顯示 3 個單字,按鍵上方有格式化工具列藥丸,底部有麥克風與地球。 - 圖片區塊應渲染為圓角(約 18px)並遵守內文的左側內距。
- 核取清單:已核取項目為黃色實心圓圈並加上刪除線;未核取項目則為灰色空心圓圈。
失敗模式
| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 內文換行過早或過晚 | 字型寬度與參考不同(Chromium 使用了非 SF 的回退字型) | 以 2px 為步進調整 .note-body 的 font-size,或透過減少左右內距來加寬 .note |
| 標題看起來太細 / 不夠粗 | 主機沒有 SF Pro Display;系統回退到較細的字型 | 設定 font-weight: 900(已為預設值)並檢查 `fc-list |
| "Hello's"、"Let's" 渲染出直引號 | 智慧型標點預處理器未啟用 | 確認 generate.js 中在 escapeHtml 之前已呼叫 smartQuotes() |
| 圖片未渲染(空白區域) | 遠端 URL 被封鎖或相對路徑未解析 | 使用本地檔案路徑;render.js 會將本地圖片內嵌為 base64 |
| 自動修正底線也比對到 "This"(當只預期 "this" 時) | 正規表達式為不區分大小寫 | 正規表達式預設為區分大小寫。請在 autocorrect_underline 中傳遞完全匹配大小寫的字串 |
| 空白段落收合(無游標空間) | <p class="note-paragraph"></p> 沒有內容,高度為零 | CSS 設定 margin: 0 0 84px 0,因此空白段落仍佔一個段落間距;請確定您沒有移除尾端外邊距 |
| 黃色完成圓圈看起來像橘色 | CSS 顏色偏移 | 純 Apple 黃色為 #FFCC00。游標與完成按鈕共用此值;不要改為 #FFC107(Material 琥珀色) |
鍵盤建議 Hello's 渲染出直撇號 | 智慧型引號未套用於建議 | 已在 generate.js 中透過 smartQuotes(s) 確認套用 |
參考
視覺規格是從 apple-notes-typing.MP4(一段 36 秒的 iPhone 螢幕錄影,在淺色模式下於 Apple Notes 中打字)中萃取。請參閱此資料夾中的 apple-notes-skill-build.html 以取得並排驗證——每個範例都會與其目標參考幀並排顯示。