iPolloWork 視頻元件開發規範
交付的是能放進影片、透過共用表單調整、跟隨專案主題、可由 AI 加工的元件。不要為一個元件另做編輯器、參數面板、渲染器或主機外掛。
1. 開始前:以當前程式碼契約為準
在 iPolloWork 倉庫根目錄閱讀 AGENTS.md 和維護性規範。先找同類元件,再選擇擴充還是新增。以下路徑均相對倉庫根目錄:
vendor/hyperframes/registry/blocks/world-map/:地圖、主題繼承、結構化資料的參考。vendor/hyperframes/registry/blocks/metric-signal/:資料展示及可選動畫配方的參考。vendor/hyperframes/packages/core/src/registry/types.ts:元件分類及 manifest 契約。vendor/hyperframes/packages/core/src/registry/componentData.ts:共用資料結構及解析規則。vendor/hyperframes/packages/core/schemas/registry-item.json、packages/types/src/hyperframes.ts:註冊項和主機校驗契約。vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts:真實安裝、主題與變數接入方式。
不要複製這些 schema 或建立另一套資料協議。規範與程式碼不一致時,先核對當前消費者,不用舊範例猜測介面。
2. 最小交付結構
通常只需在 vendor/hyperframes/registry/blocks/<slug>/ 放置:
registry-item.json # 元資訊、變數、分類、檔案和能力聲明
<slug>.html # 畫面與動畫
確有需要再加本地圖片、字型、資料或預覽檔案;安裝所需檔案必須在 files 中聲明,路徑保持包內相對路徑。註冊到現有 vendor/hyperframes/registry/registry.json,不另建元件目錄服務。
產品裡統稱「元件」,但底層類型要準確:有獨立畫布和時長的地圖、排行榜等通常是 hyperframes:block;注入已有畫面的片段才是 hyperframes:component。完整專案範本屬於另一種交付,不混用。
3. 變數:少而有用,表單共用
- 在 manifest 的
variables聲明穩定的id、可理解的label、類型及預設值,與 HTML 的data-composition-variables保持一致。 - 沿用現有
string / number / color / boolean / enum類型;數字給合理範圍,列舉給選項,長文字給長度約束。不要擅自增加物件類型。 - 只暴露內容、資料、高亮、必要的佈局等使用者決策;不要把每個 CSS 數值都變成參數。顏色預設來自主題,不能靠使用者逐項配色才能使用。
update: live僅用於能即時更新的參數;改變結構或動畫時按現有機制使用rebuild / reload,聲明必須與實際行為一致。- 接入現有變數更新機制,更新後 DOM 和動畫都應反映新值,並保持主機當前播放位置。不得只更改文字而讓時間線仍指向舊元素。
- 使用共用變數表單和資料表格,不給單個元件新寫一套面板。
motionCueTimes、motionStyle等系統控制欄位不當作普通使用者參數。
4. 資料:給 AI 結構,給使用者表格
地圖、路線、圖表、排行榜等資料元件使用 visualComponent.data,宣告列、語義、行標識、行數限制和綁定。沿用已有 category-value / region-value / point-value / route-value / series-value,選擇真正匹配資料的類型。
AI 面對的標準資料是:
{
"version": 1,
"kind": "region-value",
"rows": [
{ "region": "China", "value": 96 },
{ "region": "Japan", "value": 77 }
]
}
列名由該元件的 columns 決定,不是所有元件固定使用 region。rowId 穩定且唯一,數字保持數字類型;單位、精度、高亮和替換/覆蓋語義按現有契約聲明。
binding.variable 必須對應真實變數。底層可以使用已有 json / key-value-list / route-value-list / label-detail-list 編碼,但由共用適配層轉換;不要求使用者手寫逗號、冒號等字串。不要另設一份互不同步的 JSON 狀態。非法資料給明確提示,不靜默丟行或生成虛構數值。
5. 主題與分類
- 聲明
visualComponent.version: 1、themeMode: inherit,按能力填寫surfaces;首選video,未驗證前不要聲稱支援 PPT 或網頁。 - 分類沿用當前
VISUAL_COMPONENT_CATEGORIES,例如地圖maps、資料data、架構/金字塔diagrams。開頭、結尾還可用已有librarySection定位;不要另造一套分類樹。 - 使用現有主題變數,例如
--ipw-color-bg、--ipw-color-surface、--ipw-color-text、--ipw-color-primary、--ipw-color-border、--ipw-font-display、--ipw-font-body、--ipw-card-radius。 - 允許獨立預覽的預設回退值,但不能覆蓋主機傳入的主題。主題切換後背景、文字、圖形、邊框和字型應協調變化;資料的語義色例外需有明確理由。
- 保持層級清楚、留白合理、中文可讀。必要時用剋制的漸變或玻璃質感,不以特效代替資訊表達。
6. 動畫與時間線
- 預設 HTML + CSS + GSAP;優先複用現有圖形及本地 SVG。只有明確需要真實 3D 時才考慮 Three.js,不為簡單地圖增加重型依賴。
- 沿用現有 composition 根節點、尺寸、時長和安裝機制,註冊到
window.__timelines[compositionId]的暫停 GSAP 時間線,由 HyperFrames 控制播放、暫停與 seek。 - 每個實例的選擇器、狀態和時間線只影響自己。重建時清理舊動畫,不覆蓋其他實例。
- 同一時刻必須得到同一畫面:不要用獨立計時器、自動播放迴圈、未固定的隨機數或 CSS 自執行動畫驅動關鍵內容。真實圖片、音影片遵循現有媒體時間同步方式。
- 動畫服務於講解順序:明確出現、強調、停留、退出;文字和資料留足閱讀時間。避免所有元件同一種入場,也避免為了炫技持續運動。
- 普通元件不強制增加
motionRecipe。需要讓 AI 依照旁白呼叫動畫配方時,才沿用已支援的配方契約;事件、cue 綁定和實際元素一致,容量與文字限制有真實依據,不偽造配音時間。
7. AI 加工空間
用 visualComponent.ai.slots 宣告穩定的可編輯區域,並在 HTML 對應位置添加 data-ipw-ai-slot。instructions 簡要說明用途、輸入規則和需要保留的結構。
支援 AI 取代內容、調整佈局、縮小地圖並在旁邊加說明等局部加工;保持變數 ID、資料綁定、主題繼承及時間線接入不變。不強制所有加工都變成表單參數,也不為 AI 再維護一份畫面。
外部文字按文字處理,不拼入可執行 HTML;不執行輸入資料中的腳本,不嵌入金鑰。引用地圖、字型、圖片等資源保留來源和授權,缺少素材時明確說明,不暗中聯網替換。
8. 驗收與交付
- manifest、HTML 變數、AI slots、資料綁定及安裝路徑一致,通過當前倉庫對應校驗和受影響的測試。
- 在現有 Studio 安裝元件;共用表單能修改實際畫面,資料表格能增刪和編輯合法行。
- 檢查預設、邊界、空值、長中文、錯誤資料和兩種主題;多實例互不影響。
- 檢查從頭播放、中間 seek、拖回起點、參數更新後的 seek;畫面與時間線一致。
- 用真實素材導出一段短影片,確認瀏覽器預覽與輸出一致;不能僅憑截圖聲稱通過。
- 交付元件檔案、必要資源與來源、參數/資料範例、實際測試結果和未驗證項。不複製 Studio,不改現有範本行為,不殘留替代實作。
本規範只指導元件開發。發佈 npm、修改主機外掛、提交 PR 或上傳元件市集需依使用者授權及現有發佈流程另行處理。