コンテンツ取得の条件と戻り値
記事取得の関数、並び順、絞り込み、ページ送りを具体例で引けます。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 | 続きがあるか |
cacheHint | Astroのキャッシュに渡す情報 |
この例の 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.id | APIなどで保存済みの記事を特定 | 同じ記事の固定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(別タブで開く)が参照先です。