OpenPress

@open-press/core

Frame

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

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

Component Impl

# <Frame>

渲染附帶 data-openpress-* 屬性之 <section> 容器。根 Frame 宣告為頁面位址，嵌套 Frame 則為區域物件。

import { Frame } from "@open-press/core";
<Frame
  frameKey="cover"
  role?="document.cover"
  chrome?={true}
  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 容器內容。通常包含一個或多個 `` 組件。
role string 語意標記。寫入至 `data-frame-role`。根 Frame 會擷取點 (.) 後綴作為 `data-page-kind` 值。
chrome boolean true 介面渲染旗標 (僅限根 Frame)。設為 `false` 時將輸出 `data-frame-chrome="false"` 及 `data-page-footer="false"`，供主題層隱藏框架 UI 使用。
className string 附加至根節點之 CSS 類別。根 Frame 預設包含 `reader-page` 類別。
...rest HTMLAttributes 透傳至底層 `
` 標籤之標準 HTML 屬性。

範例：文件頁面 (Document Page)

<Frame frameKey="ch-2" role="document.content" 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>

執行期 Context 與標記

Context Impl

# FrameContext

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

import { FrameContext } from "@open-press/core";
const frame = useContext(FrameContext);
// -> { frameKey, objectId, 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-role string 對應 `role` 屬性值。
data-page-kind string 由 `role` 點綴後方擷取之短字串 (僅限根 Frame)。
data-frame-chrome "true" | "false" 對應 `chrome` 屬性值 (僅限根 Frame)。
data-page-footer "true" | "false" 同 `data-frame-chrome` 狀態 (僅限根 Frame)。

角色慣例 (Role Conventions)

標準實作採用雙段式命名結構：

  • document.*：長篇文件分配流動 (如 document.cover, document.content)。
  • canvas.*：固定佈局單一視圖 (如 canvas.slide, canvas.card)。
  • manuscript.*：輔助工具內部使用之文稿標籤。