OpenPress

@open-press/core

useSource

これは、Pressのツリー構造で解決されたソースマップから登録済みのMDXソースを読み取るためのReactフックです。同期的なので、<Press>内のどこでも安全に呼び出すことができます。

useSource は、<Press> のレンダリングツリー内で解決済みのMDXソースデータ構造を安全に取得するために設計された同期Reactフックです。

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に依存すべきであり、フックを介してデータを逆方向に再取得すべきではありません。
  • 非Reactランタイム：サーバーサイドスクリプトや <Press> 境界の外側で呼び出そうとする場合。外部スクリプトの場合は、出力された document.json を直接解析する必要があります。