OpenPress

@open-press/core

Frame

一個固定的頁面表面或是在頁面內的嵌套區域。根 Frame 會變成輸出的頁面；嵌套的 Frame 則會變成當前頁面內可選取的物件邊界。

Frame 模組定義渲染內容邊界與資料屬性，將其綁定至 @open-press/core 的頁面幾何分配與標記系統。

Component Impl

# <Frame>

渲染附帶 data-openpress-* 屬性之 <section> 容器。根 Frame 宣告頁面邊界；嵌套 Frame 宣告可選取、可註解、可配置 layout 的區域物件。

import { Frame } from "@open-press/core";
<Frame
  frameKey="cover"
  chrome?={true}
  box?={{ x: 100, y: 80, w: 720, h: 480 }}
  layout?={{ mode: "stack", gap: 32, align: "start" }}
  className?="reader-page--cover"
  ...sectionProps
>
  {/* page or region contents */}
</Frame>

屬性 (Props)

Name Type Default Description
frameKey required string 唯一識別碼。根 Frame 寫入至 `data-openpress-frame-key`。嵌套 Frame 寫入至 `data-openpress-region-frame-key`。禁止包含 `:extended:` 字串。
children required ReactNode 容器內容。文件頁面通常包含 ``；固定版面與簡報 template 通常包含 `Frame`、`Text`、`Line`、`MediaObject` 等 core objects。
chrome boolean true 介面渲染旗標 (僅限根 Frame)。設為 `false` 時將輸出 `data-frame-chrome="false"` 及 `data-page-footer="false"`，供主題層隱藏框架 UI 使用。
box FixedBox 固定版面座標，使用目前 page geometry 的座標系。16:9 slide 預設為 1920 x 1080。支援 number 或 CSS length string。
layout FrameLayout 容器內部的 auto layout 約束。支援 `stack` 與 `grid`，可設定 `gap`、`padding`、`width`、`height`、`clip` 等。
className string 附加至根節點之 CSS 類別。根 Frame 預設包含 `reader-page` 類別。
...rest HTMLAttributes 透傳至底層 `
` 標籤之標準 HTML 屬性。

範例：文件頁面 (Document Page)

<Frame frameKey="ch-2" className="reader-page--content">
  <div className="flex h-full flex-col px-16 py-12">
    <main className="min-h-0 flex-1 text-[22px] leading-relaxed">
      <MdxArea chainId="story" />
    </main>
  </div>
</Frame>

範例：簡報區域 (Slide Region)

<Frame
  frameKey="agenda-list"
  box={{ x: 1080, y: 365, w: 650, h: 430 }}
  layout={{ mode: "stack", gap: 56, align: "start" }}
  className="op-source-deck-agenda-list"
>
  <Text as="p" label="agenda-1">1. Refresher on problem statement</Text>
  <Text as="p" label="agenda-2">2. Update on metrics</Text>
</Frame>

Frame 的 identity 一律來自必要的 frameKey；Text、Line、MediaObject 才使用可編輯 primitive 的 label。

執行期 Context 與標記

Context Impl

# FrameContext

提供 `<MdxArea>` 執行插槽分配作業所需之低階環境資訊。一般組件無需直接消費此 Context。

import { FrameContext } from "@open-press/core";
const frame = useContext(FrameContext);
// -> { frameKey, pageId, consumeArea(chainId) } | null
Symbol Impl

# FRAME_MARKER

渲染器於 AST 遍歷階段使用之內部 Symbol，用於識別元件實例是否為 Frame 類型。

import { FRAME_MARKER } from "@open-press/core";

DOM 資料屬性參考表

渲染系統將自動附加以下 data-* 屬性至底層 <section> DOM 元素，作為選擇器或檢查器之介面：

Name Type Default Description
data-openpress-frame-key string 對應根 Frame `frameKey` 屬性值。
data-openpress-region-frame-key string 對應嵌套 Frame 區域之 `frameKey` 屬性值。
data-openpress-object-id string 系統產生之唯一物件標識符號。
data-frame-chrome "true" | "false" 對應 `chrome` 屬性值 (僅限根 Frame)。
data-page-footer "true" | "false" 同 `data-frame-chrome` 狀態 (僅限根 Frame)。