コンテンツ取得の条件と戻り値

記事取得の関数、並び順、絞り込み、ページ送りを具体例で引けます。URL用IDとデータベースIDも区別します。

目次

ページから記事を読む2つの関数

Astroのページで複数の記事を読むならgetEmDashCollection()、1件読むならgetEmDashEntry()を使います。どちらも表示用のデータを返す関数です。取得に失敗した場合に何を表示するかは、呼び出すページ側で処理を用意します。

以下はEmDash 1.4.0の取得方法です。実際のページ作成は一覧と詳細のチュートリアルへ進んでください。

全ページで共有する情報は、メニューとリンク先やサイト名・ロゴを取得する関数で読めます。

一覧を取得する

Astroファイルの先頭にある---の内側など、サーバーで動く部分に書きます。

import { getEmDashCollection } from "emdash";

const { entries, error, nextCursor, hasMore, cacheHint } =
  await getEmDashCollection("posts", {
    orderBy: { published_at: "desc" },
    limit: 10,
  });
戻り値意味
entries記事の配列
error取得に失敗した場合の情報
nextCursor続きの取得に使う目印
hasMore続きがあるか
cacheHintAstroのキャッシュに渡す情報

この例の limit: 10 は最大10件という指定です。EmDash 1.4.0では、省略すると取得件数に上限が付かず、条件に合う記事をすべて読みます。

記事0件と取得失敗のどちらでもentriesが空になり得るため、errorも確認します。失敗時に「まだ記事がありません」と表示すると、障害を見落とします。

通常は、公開済みを表すpublishedの記事を取得します。読者向けのURLから下書きも読める作りにしないでください。未公開の内容を見るときは、閲覧を許可する情報を付けたプレビューの仕組みを使います。

条件を付ける

const { entries, error } = await getEmDashCollection("posts", {
  where: { category: "coffee", difficulty: "beginner" },
  locale: "ja",
  orderBy: { published_at: "desc" },
  limit: 10,
});

これはcategoryという分類と、difficultyという欄が定義されている場合の例です。where内の複数の条件は、すべて満たすものを選びます。一つの条件に["coffee", "books"]のような配列を指定した場合は、そのいずれかに一致するものを選べます。

localeを省いた場合は、まずアクセス時の言語を使い、それがなければ設定済みの既定言語を使います。本文が日本語で書かれていても、記事の言語がjaで保存されているとは限りません。

並び順の名前に注意する

orderByは、保存されている欄の名前とascまたはdescを組み合わせます。ascは小さい・古い方から、descは大きい・新しい方からです。

システムの日時ではcreated_at、updated_at、published_atを使います。取得したデータ側にあるpublishedAtなどの名前を、そのまま並び順に使うものではありません。

並べ替えと件数の制限は、DB側で行われます。いったん全件を取得してからJavaScriptで並べ替える処理ではありません。記事数が増える場合は、よく検索・並べ替えに使う入力欄に、DBが値を探しやすくするindex(索引)を設けることを検討します。

URL用IDと固定のID

値用途スラッグを変えたとき
entry.id一覧から読者向けURLを作るURL構成に応じて変わる
entry.data.idAPIなどで保存済みの記事を特定同じ記事の固定IDとして使う
entry.data.slug保存されているスラッグ編集で変わる

entry.idには、言語設定に応じた接頭辞が含まれる場合があります。一覧からリンクを作るとき、常にdata.slugへ置き換えてよいとは限りません。

REST APIやMCPから操作するとき、content IDを指定する欄には固定のIDを使います。スラッグと見た目が似ていても用途が違うため、そのAPIが求める値を確認してください。

1件を取得する

import { getEmDashEntry } from "emdash";

const { entry, error } = await getEmDashEntry("posts", "coffee-tools");

2つ目の引数にはスラッグか固定IDを渡せます。URLから受け取る場合は、decodeSlug(Astro.params.slug)で処理します。

先にerrorを確認し、次にentryがあるかを確認します。取得処理が失敗した場合は500、正常に調べた結果、記事がなかった場合は404など、原因に合う応答を返します。

続きの10件を取得する

cursorは、前回の続きから読むための目印です。値の中身を解釈して作り直さず、受け取ったまま渡します。

const cursor = Astro.url.searchParams.get("cursor") ?? undefined;
const result = await getEmDashCollection("posts", {
  limit: 10,
  cursor,
  orderBy: { published_at: "desc" },
});

result.nextCursorがあるときだけ次へ進むリンクを出し、URLへ入れる値はencodeURIComponent()で処理します。条件と並び順を途中で変えると、同じ続きを読める前提が崩れます。

ページ番号で区切る場合は、先頭から何件飛ばすかを指定するoffsetも使えます。1ページ10件で3ページ目を読むなら、最初の20件を飛ばします。cursorとoffsetは一つの取得条件に混ぜず、どちらかの方式に揃えます。全体の件数を表示する方法や、前のページへ戻る操作も、その方式に合わせて作ります。

キャッシュと、変更の反映

キャッシュは取得結果やページを再利用して表示を軽くする仕組みです。対応するAstroのキャッシュを有効にしている場合は、返されたcacheHintを渡す公式の方法があります。

if (Astro.cache?.enabled) Astro.cache.set(cacheHint);

取得できたことだけでなく、記事の編集・公開後に古い表示が残らないことも確認します。公開情報とプレビューの内容を、同じ共有キャッシュへ保存しないようにします。

メニューや分類などの補助関数は公式APIリファレンス(別タブで開く)、取得方法全体はQuerying Content(別タブで開く)が参照先です。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。