OpenPress

@open-press/core

useSource

這是一個 React hook，可從 Press 樹狀結構已解析的來源對應表中讀取已註冊的 MDX 來源。它是同步的，可以在 <Press> 內部的任何地方安全地呼叫。

useSource 為一個同步 React Hook，設計用於在 <Press> 渲染樹內安全獲取已解析的 MDX 來源資料結構。

Hook Impl

# useSource(id)

基於來源 ID 提取解析完畢之 MDX AST 及元資料。引擎保證資料填入於渲染週期之前，因此該方法不回傳 null。

import { useSource } from "@open-press/core";
function useSource<T = ResolvedSource>(id: string): T

參數 (Parameters)

Name Type Default Description
id required string 於 `` 宣告之來源 `id`。必須精確大小寫相符。

回傳值 (Returns)

Name Type Default Description
ResolvedSource object 引擎解析完成之來源物件，涵蓋區塊 (blocks)、區塊來源對應 (source maps) 及自訂元資料。支援利用 TypeScript 泛型 `` 強制型別轉換。

例外狀況 (Throws)

Name Type Default Description
Outside Press Boundary Error 呼叫點缺乏 `PressContext`（不在 `` 子樹中）時拋出。
Unknown Source ID Error 傳入之 `id` 未被註冊時拋出，並附帶已註冊來源清單提示。

範例：存取來源元資料

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

function CustomTableOfContents() {
  const story = useSource("story");
  return (
    <ul>
      {story.sections.map((s) => (
        <li key={s.id}>{s.title}</li>
      ))}
    </ul>
  );
}

範例：附帶泛型的強制轉換

import { useSource, type ResolvedSource } from "@open-press/core";

interface StorySource extends ResolvedSource {
  sections: Array<{ id: string; title: string; chapterCount: number }>;
}

function ChapterCounts() {
  const story = useSource<StorySource>("story");
  return story.sections.map((s) => (
    <div key={s.id}>{s.title}: {s.chapterCount} chapters</div>
  ));
}

適用場景與限制

適用情境：

  • 開發底層工具：編寫替代 <Sections> 的自訂文稿分配器。
  • 進階版面元件：建構非標準樹狀結構之目錄 (TOC)。
  • 全域資訊介面：需存取來源彙整資料的自訂頁首、頁尾或統計儀表板。

禁止模式：

  • MDX 區塊內部：MDX 節點已身處編譯管道中，應依賴 Prop drilling，不應反向透過 Hook 重取資料。
  • 非 React 執行期：嘗試在伺服器端腳本或無 <Press> 邊界處呼叫。對於外部腳本，應直接分析 document.json 產物。