Docs

API 參考

React 元件語法

可編輯 OpenSlideX 簡報的公開元件與檔案結構。

presentation.tsx

import {
  Deck,
  Slide,
  Text,
  definePresentation,
} from "@open-slidex/sdk/react";

export default definePresentation({
  title: "季度更新",
  component: function Presentation() {
    return (
      <Deck title="季度更新">
        <Slide id="slide-01" background="#F7F7F5" canvasWidth={1920} canvasHeight={1080} duration={5} fontSizeUnit="pt" theme="light">
          <Text id="slide-01-title" role="title" x={8} y={8} w={84} h={14} fontFamily="Arial" fontSize={42} fontWeight={700}>
            一個清楚的主張
          </Text>
        </Slide>
      </Deck>
    );
  },
});

原生圖層語法

<Text id="headline" role="title" x={8} y={8} w={62} h={14} fontSize={42} fontWeight={700}>
  清楚的標題
</Text>
<Image id="cover" x={70} y={8} w={22} h={40} src="assets/cover.webp" alt="桌上的產品" fit="cover" />
<Video id="demo" x={8} y={30} w={42} h={48} src="assets/demo.mp4" poster="assets/demo-poster.webp" />
<Shape id="accent" x={54} y={30} w={5} h={48} shape="rectangle" fill="#7C3AED" />
<Chart id="trend" x={62} y={55} w={30} h={23} type="line" data='[{"label":"Q1","value":42},{"label":"Q2","value":58}]' />
<Table id="owners" x={62} y={82} w={30} h={10} cells="市場|負責人;北區|Ava" />
<Svg id="mark" x={8} y={84} w={8} h={8} src="assets/mark.svg" />
<HtmlEmbed id="imported-page" x={20} y={84} w={24} h={8} src="assets/source.html" />

完整 React API 屬性表

這一張表列出目前 OpenSlideX 原生 React API 可序列化、可由 Workbench 與 exporter 辨識的欄位。共用圖層欄位只列一次；各元件頁也保留自己的精簡表格。

API屬性型別／值必要說明
所有原生圖層共用 propsidstring是穩定且唯一的圖層識別字。每個可見的原生圖層都必須提供。
xnumber是相對於投影片畫布左側的位置百分比。
ynumber是相對於投影片畫布頂端的位置百分比。
wnumber是圖層寬度，單位為畫布百分比。
hnumber是圖層高度，單位為畫布百分比。
groupIdstring—在不加入 wrapper 元素的情況下，將原生子圖層編組。
groupNamestring—在 Workbench 顯示的群組名稱。
sharedIdstring—連接相鄰 Morph 投影片中的同型圖層；在同一張投影片內必須唯一。
rotationnumber—順時針旋轉角度。
opacitynumber—圖層不透明度，範圍為 0 到 1。
motionJSON string—版本化的宣告式動作序列 JSON 字串；仍須保留完整的靜態最終畫面。
interactionJSON string—版本化的點擊互動 JSON 字串，可用於投影片導覽或連結。
definePresentationtitlestring是簡報標題，應與 Deck 的 title 一致。
componentReact component是回傳唯一 Deck 根節點的 React 元件。
defineSlideXComponentnamestring是註冊的本機元件所使用的穩定顯示名稱。
componentReact component是簡報呈現時使用的元件實作。
propsliteral prop schema—選用的字面值屬性定義；支援 string、number、boolean 與 required。
propsSchemasafeParse schema—選用的執行期 schema；會以 safeParse 驗證元件 props。
assetReferences(props) => string[]—選用，回傳此元件使用的本機素材路徑。
toMotionDoc(props) => ReactNode—若元件需要展開成可編輯的 MDX 或 PPTX 原生圖層，即為必要。
Decktitlestring是簡報標題；有效的簡報只能有一個 Deck 根節點。
childrenReactNode是一個以上的 Slide 子節點。
Slideidstring是穩定的投影片識別字。
backgroundcolor string—投影片背景顏色。
backgroundImagestring—本機背景圖片路徑。
backgroundFitcover | contain | fill | scale-down—背景圖片填滿畫布的方式。
canvasWidthnumber—目標畫布寬度，通常為 1920。
canvasHeightnumber—目標畫布高度，通常為 1080。
fontSizeUnit"pt"—設定為 pt 時，Text 與 Table 的字級會以 point 計算。
durationnumber—投影片停留時間，單位為秒。
themestring—簡報主題色調，例如 light 或 dark。
slideTransitionstring—前往下一張的轉場；使用 morph 時必須有相容的 sharedId 配對。
transitionDurationnumber—轉場時間，單位為秒。
morphEasingstring—Morph 轉場的 easing。
morphFadeUnmatchedboolean—Morph 時未配對的圖層是否淡出。
morphShapeSoftnessnumber—相容 Shape Morph 的柔化程度。
morphShapePrecisionnumber—Shape Morph 的取樣精度。
morphCurveX1 / morphCurveY1 / morphCurveX2 / morphCurveY2number—morphEasing 為 custom 時使用的控制點。
TextchildrenReactNode是圖層中的文字內容。
role"title" | string—主要投影片標題請使用 title。
fontFamilystring—字型名稱。
fontSizenumber—Slide 設定 fontSizeUnit="pt" 時的字級（point）。
fontWeightnumber | string—字重，例如 400 或 700。
fontStyle"italic"—斜體文字樣式。
colorcolor string—文字顏色。
backgroundcolor string—文字框背景顏色。
radiusnumber—文字框圓角半徑。
lineHeightnumber—行高倍率。
letterSpacingnumber—字距，單位為 point。
textAlignleft | center | right—文字水平對齊。
textVerticalAligntop | middle | bottom—文字在框內的垂直對齊。
listTypebullet | ordered—選用的清單格式。
listStartnumber—有序清單的起始編號。
Imagesrcstring是可攜的本機圖片路徑，通常位於 assets/。
altstring—圖片替代說明。
fitcover | contain | fill | scale-down—圖片內容填滿框架的方式。
cropX / cropYnumber—圖片在框架內的位移，單位為百分比。
scaleX / scaleYnumber—圖片內容在各軸向的縮放比例。
radiusnumber—框架圓角半徑。
filterstring—Paper 圖片濾鏡識別字。
filterPresetstring—所選圖片濾鏡的 preset。
filterDistortion / filterSize / filterAngle / filterContrast / filterSpeed / filterDetailnumber—所選 Paper 濾鏡的細部控制值。
Videosrcstring是本機 MP4/WebM 路徑、直接 URL 或支援的 YouTube URL。
posterstring—播放前或靜態 render 時顯示的圖片。
fitcover | contain | fill | scale-down—影片內容填滿框架的方式。
controlsboolean—是否顯示播放控制項；預設為 true。
loopboolean—是否循環播放；預設為 true。
mutedboolean—是否靜音並啟用 inline autoplay；預設為 true。
radiusnumber—框架圓角半徑。
Shapeshaperectangle | circle | triangle | diamond | star | line | arrow | chevron | hexagon | parallelogram是要繪製的幾何形狀。
fillcolor string—內部填色。
strokecolor string—外框或線條顏色。
strokeWidthnumber—外框或線條寬度。
radius / borderRadiusnumber—圓角矩形的圓角半徑。
cornernumber—連續圓角處理。
points / sidesnumber—星形尖角數或多邊形邊數。
lineStylesolid | dashed | dotted—線條樣式。
arrowStart / arrowEndnone | arrow | circle | bar—線條端點裝飾。
arrowStartSize / arrowEndSizenumber—端點大小百分比。
shapeImageSrcstring—選用；裁切在非線條 Shape 內的圖片。
shapeImageAltstring—Shape 內圖片的說明。
shapeImageFitcover | contain | fill | scale-down—Shape 內圖片填滿幾何形狀的方式。
shapeImageCropX / shapeImageCropY / shapeImageScaleX / shapeImageScaleYnumber—Shape 內圖片的裁切與縮放控制值。
masknone | alpha | luma | clip—Shape 遮罩模式。
operationnone | subtract | intersect | exclude—Shape 布林運算效果。
Charttypebar | line | area | pie | donut | scatter是圖表呈現類型。
dataJSON string是1 到 24 筆資料；每筆都要有有限數值 value，亦可包含 label、x、size、color。
chartDataByTypeJSON string—選用；以圖表類型為 key 的資料集。
chartPresetexecutive | minimal | vivid—視覺 preset。
chartThemelight | dark-gold—圖表專用主題。
paletteaurora | editorial | gilded | ocean | sunset—命名色盤。
colorModepalette | single | emphasis | gradient—顏色分配策略。
emphasisIndexnumber—由 color mode 強調的資料索引。
annotationIndex / annotationText / annotationColornumber | string—選用的註解目標、文字與顏色。
barGapcompact | balanced | airy—長條圖的間距。
barRadius / areaOpacity / donutHolenumber—長條圓角、面積圖填色不透明度或甜甜圈孔徑。
lineSmoothboolean—平滑折線或面積圖路徑。
showAxes / showGrid / showLabelsboolean—顯示座標軸、格線或標籤。
labelMode / labelColorall | value | category | none | color—標籤顯示模式與顏色。
numberFormatauto | integer | decimal | percent | currency | compact—數值格式。
decimals / currencynumber | string—小數位數與幣別代碼或符號。
sortinput | ascending | descending—資料排序方式。
referenceValue / referenceLabel / referenceColornumber | string—選用的參考線數值、標籤與顏色。
chartMotionauto | grow | draw | sweep | pop | none—圖表進場動態。
Tablecellsstring是儲存格資料：直線分隔欄、分號分隔列。
rowsnumber—列數，範圍為 1 到 50。
columns / colsnumber—欄數，範圍為 1 到 50。
columnLabels / rowLabelsstring—序列化的欄或列標籤。
columnWidths / rowHeightsstring—序列化的比例軌道尺寸。
cellOverridesJSON string—由 Workbench 建立的逐格視覺覆寫。
fontFamily / fontSize / fontWeightstring | number—表格字體樣式；fontSize 單位為 point。
color / textColorcolor string—表格文字顏色。
background / backgroundColor / bgcolor string—表格背景顏色。
cellBackground / stripeBackgroundcolor string—儲存格底色與交錯列底色。
borderColor / borderWidth / borderStylecolor | number | solid | dashed | dotted—表格邊框樣式。
textAlign / textVerticalAlignleft | center | right / top | middle | bottom—儲存格對齊。
cellPaddingX / cellPaddingYnumber—儲存格水平與垂直內距，單位為像素。
Svgsrcstring是無 script 的本機 SVG 素材路徑。
stagenumber—SVG 動畫階段索引。
stageDurationnumber—SVG 階段時間，單位為秒。
easingstring—SVG 階段的 easing。
sharedScenestring—選用；跨投影片共用的場景 key。
HtmlEmbedsrcstring是受控的本機 HTML 素材路徑。
pagenumber—要顯示的 HTML 簡報頁碼；從 1 開始。
sharedScenestring—選用；跨投影片共用的場景 key。

從一份有效的文件開始

預設匯出 definePresentation({ title, component })。component 必須 render 一個標題相同的 Deck，並包含一個以上的 Slide；公開元件只從 @open-slidex/sdk/react 匯入。

Deck 與 Slide 建立文件結構；Text、Image、Video、Svg、Chart、Table、Shape 與 HtmlEmbed 則建立 native 圖層。不要在 React 來源中使用 ImageBlock 或 SvgBlock 等內部名稱。

使用固定的版面數值

每個可見 native 圖層都需要穩定且唯一的 id，以及固定的 x、y、w、h。這四個值以投影片畫布的百分比表示。若 Slide 設定 fontSizeUnit="pt"，Text 的 fontSize 以 point 為單位。

若希望屬性能被 Canvas 或 Inspector 顯示與編輯，請使用固定且可序列化的值。運算式、迴圈、spread、hook 與條件式仍屬於程式碼，無法保證能透過視覺編輯完整往返。

讓 sandbox 保持可攜

使用簡報 assets/ 資料夾中已驗證的相對素材。HtmlEmbed 只接受受控、已匯入的本機 HTML；Svg 只接受沒有 script 的本機 SVG。不可使用絕對路徑、Base64、blob URL、任意 HTML、事件處理器、網路呼叫、Node API 或外部 npm import。

Card、Metric、Stack、Group、Title、Icon 與 Notes 都不是支援的 React 元件；請改用上方的 native 圖層。