title | description | i18nReady |
---|---|---|
画像 |
Astroでの画像の使い方を学びます。 |
true |
import Since from '/components/Since.astro';
import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";
Astroでは、プロジェクト内にローカルに保存された画像、外部URLにリンクされた画像、CMSやCDNで管理されている画像などについて、これらをサイト上で使用するためのいくつかの方法を提供しています。
ローカル画像は、Astroが変換、最適化、バンドルできるように、可能な限りsrc/
に保存することをおすすめします。/public
ディレクトリのファイルは、常にそのままビルドフォルダにコピーされ、処理されることはありません。
src/
に保存されているローカル画像は、プロジェクト内のすべてのファイル(.astro
、.md
、.mdx
、.mdoc
、その他のUIフレームワーク)で使用できます。画像は、コンテンツと同じ場所など、任意のフォルダに保存できます。
画像に対する処理を避けたい場合や、画像へのリンクを直接公開したい場合は、画像をpublic/
フォルダに保存します。
コンテンツ管理システム(CMS)やデジタルアセット管理(DAM)プラットフォームなど、リモートに画像を保存することもできます。
外部ソースを扱う際の保護を強化するために、設定で指定した許可された画像ソースからのリモート画像のみ処理されます。ただし、リモート画像の表示は常に可能です。
Astroは、APIを使用してリモートからデータを取得したり、画像をそのフルURLパスから表示したりできます。一般的なサービスを組み込む例については、CMSガイドを確認してください。
.astro
ファイルでローカル画像を使用するには、ファイルにインポートする必要があります。リモートとpublic/
の画像はインポートする必要はありません。
astro:assets
からAstro組み込みの<Image />
コンポーネントをインポートして使用すると、画像を最適化できます。また、Astro構文ではHTMLの<img>
タグを直接書くこともできますが、画像処理はスキップされます。
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="巣の中の卵を温めている鳥。"/>
<Image src="/images/bird-in-public-folder.jpg" alt="鳥。" width="50" height="50"/>
<Image src="https://example.com/remote-bird.jpg" alt="鳥。" width="50" height="50"/>
<img src={localBirdImage.src} alt="巣の中の卵を温めている鳥。">
<img src="/images/bird-in-public-folder.jpg" alt="鳥。">
<img src="https://example.com/remote-bird.jpg" alt="鳥。">
src/
フォルダーから動的に画像を読み込むには、次のレシピを参考にしてください:
<RecipeLinks slugs={["ja/recipes/dynamically-importing-images" ]}/>
Astro組み込みの<Image />
コンポーネントを使用して、ローカル画像と設定済みのリモート画像の最適化版を表示できます。
public/
フォルダ内の画像とプロジェクトで明示的に設定されていないリモート画像もImageコンポーネントで使用できますが、最適化処理はおこなわれません。
<Image />
は、ローカルまたは許可されたリモート画像のサイズ、ファイルタイプ、品質を変換して、表示される画像を制御します。生成された<img>
タグには、alt
、loading
、decoding
属性が含まれており、また Cumulative Layout Shift(CLS) を回避するために画像のサイズを推測します。
:::tip[Cumulative Layout Shiftとは?]
Cumulative Layout Shift(CLS)は、ローディング中にページのコンテンツがどれだけ移動したかを測定するためのCore Web Vitalのメトリックです。<Image />
コンポーネントは、ローカル画像の正しいwidth
とheight
を自動的に設定することで、CLSへと最適化します。
:::
---
// Imageコンポーネントと画像をインポートする
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 画像は1600x900
---
<!-- `alt`はImageコンポーネントでは必須です -->
<Image src={myImage} alt="画像の説明。" />
<!-- 出力 -->
<!-- 画像は最適化され、適切な属性が必ず付与されます -->
<img
src="/_astro/my_image.hash.webp"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="画像の説明。"
/>
画像ファイルのsrc
値の形式は、画像ファイルの場所によって異なります。
-
src/
内のローカル画像 - 相対ファイルパスを使用するか、またはインポートエイリアスを設定して**、画像もインポート**する必要があります。インポート名をsrc
値として使用します。--- import { Image } from 'astro:assets'; import myImportedImage from `../assets/my-local-image.png` --- <Image src={myImportedImage} alt="説明文" />
-
public/
フォルダ内の画像 - 画像のpublicフォルダを起点としたファイルパスを使用します。--- import { Image } from 'astro:assets'; --- <Image src="/images/my-public-image.png" alt="説明文" width="200" height="150" />
-
リモート画像 - 画像のフルURLをプロパティ値として使用します。
--- import { Image } from 'astro:assets'; --- <Image src="https://example.com/remote-image.jpg" alt="説明文" width="200" height="150" />
必須のalt
属性を使用して、画像の説明的な代替テキストの文字列を記述します。
画像が単に装飾用である場合(つまり、ページの理解に貢献していない場合)、スクリーンリーダーやその他の支援技術に画像を無視するよう伝えるために、alt=""
を設定します。
これらのプロパティは、画像に使用するサイズを定義します。
ローカル画像をオリジナルのアスペクト比で使用する場合、width
とheight
はソースファイルから自動的に推測されるため、必須ではありません。
ただし、リモート画像とpublic/
フォルダに保存されている画像については、Astroはこれらのファイルを解析できないため、両プロパティは必須となります。
生成する画像のピクセル密度の配列です。
この値を指定すると、<img>
タグのsrcset
属性を生成するために使用されます。この値を使用する場合はwidths
を使用しないでください。
元の画像以上の濃度になる値が指定されると、画像のアップスケーリングを避けるために無視されます。
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---
<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="説明文" />
<img
src="/_astro/my_image.hash.webp"
srcset="
/_astro/my_image.hash.webp 1.5x
/_astro/my_image.hash.webp 2x
"
alt="説明文"
width="800"
height="450"
loading="lazy"
decoding="async"
/>
生成する画像の幅の配列です。
この値を指定すると、<img>
タグのsrcset
属性を生成するために使用されます。また、sizes
プロパティも指定する必要があります。
この値を使用する場合はdensities
を使用しないでください。srcset
属性を生成するために使用できるのは、どちらかひとつの値になります。
元の画像以上の幅が指定されると、画像のアップスケーリングを避けるために無視されます。
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 画像は1600x900
---
<Image
src={myImage}
widths={[240, 540, 720, myImage.width]}
sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
alt="説明文"
/>
<img
src="/_astro/my_image.hash.webp"
srcset="
/_astro/my_image.hash.webp 240w,
/_astro/my_image.hash.webp 540w,
/_astro/my_image.hash.webp 720w,
/_astro/my_image.hash.webp 1600w
"
sizes="
(max-width: 360px) 240px,
(max-width: 720px) 540px,
(max-width: 1600px) 720px,
1600px
"
alt="説明文"
width="1600"
height="900"
loading="lazy"
decoding="async"
/>
オプションで、使用する画像ファイルタイプの出力を指定できます。
デフォルトでは、<Image />
コンポーネントは.webp
ファイルを出力します。
quality
はオプションのプロパティで、次のいずれかの値を取ります。
- フォーマット間で自動的に正規化されるプリセット(
low
、mid
、high
、max
)。 - (フォーマット間で異なる解釈となる)
0
から100
までの数値。
以上のプロパティに加えて、<Image />
コンポーネントは、HTMLの<img>
タグに設定可能なすべてのプロパティを受け付けます。
たとえば、最終的な<img>
要素にclass
を指定できます。
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---
<!-- `alt`はImageコンポーネントにおいて必須です -->
<Image src={myImage} alt="" class="my-class" />
<!-- 出力 -->
<html
src="/_astro/my_image.hash.webp"
width="1600"
height="900"
decoding="async"
loading="lazy"
class="my-class"
alt=""
/>
現在、すべての<Image />
コンポーネントに対してデフォルト値を指定する方法はありません。必須属性は個々のコンポーネントに設定する必要があります。
再利用性を高めるための代替案として、<image />
コンポーネントを別のAstroコンポーネントでラップできます。たとえば以下のようにして、ブログ記事の画像用コンポーネントを作成できます。
---
import { Image } from 'astro:assets';
const {src, ...attrs} = Astro.props;
---
<Image src={src} {...attrs} />
<style>
img :global(img), svg {
margin-block: 2.5rem;
border-radius: 0.75rem;
}
</style>
Astro組み込みの<Picture />
コンポーネントを使用することで、複数のフォーマットやサイズでのレスポンシブな画像を表示できます。
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 画像は1600x900
---
<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="説明文" />
<!-- Output -->
<picture>
<source srcset="/_astro/my_image.hash.avif" type="image/avif" />
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="説明文"
/>
</picture>
<Picture />
コンポーネントでは<Image />
コンポーネントの全てのプロパティと、以下のプロパティが使用できます。
<source>
タグに使用するフォーマットの配列です。この配列の順番で<source>
要素として追加され、表示するフォーマットが決定されます。最適なパフォーマンスのためには、最新のフォーマット(例:webp
やavif
)を最初に追加してみてください。デフォルトでは['webp']
が設定されています。
<img>
タグのフォールバック値として使用するフォーマットです。
それぞれデフォルトとして、静止画像の場合は.png
、アニメーション画像の場合は.gif
、そしてSVGファイルの場合は.svg
が設定されています。
<picture>
タグに追加する属性のオブジェクト。
このプロパティは、外側の<picture>
要素自体に属性を適用するために使用します。直接<Picture />
コンポーネントに適用される属性は、画像変換に使用されるものを除き、内側の<img>
要素に適用されます。
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // 画像は1600x900
---
<Picture src={myImage} alt="説明文" pictureAttributes={{style: "background-color: red;"}} />
<picture style="background-color: red;">
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
alt="説明文"
width="1600"
height="900"
loading="lazy"
decoding="async"
/>
</picture>
Astroテンプレートの構文では、最終的な出力を完全に制御可能な<img>
タグを直接書くこともできます。これらの画像は処理されず、最適化もされません。
すべてのHTMLの<img>
タグのプロパティを記述でき、必須のプロパティはsrc
のみです。
ローカル画像は、.astro
ファイルからの相対パスによりインポートするか、インポートエイリアスを設定して使用する必要があります。これにより、<img>
タグで使用する画像のsrc
やその他のプロパティにアクセスできます。
たとえば、CLSを回避しCore Web Vitalsを改善するために、画像のheight
とwidth
プロパティを使用します。
---
// ローカル画像のインポート
import myDog from `../../images/pets/local-dog.jpg`
---
// 画像のプロパティにアクセス
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="吠える犬。" />
インポートされた画像アセットは、以下のシグネチャと一致します。
interface ImageMetadata {
src: string;
width: number;
height: number;
format: string;
}
public/
にある画像の場合は、src
の値に画像のpublicフォルダを起点としたファイルパスを使用します。
<img src="/images/public-cat.jpg" alt="眠る猫。">
リモート画像の場合は、src
の値に画像のフルURLを使用します。
<img src="https://example.com/remote-cat.jpg" alt="眠る猫。">
<Image />
コンポーネントは、画像を最適化し、また(ローカル画像の場合は)オリジナルのアスペクト比に基づいて幅と高さを推測することでCLSを回避します。
以下のような<Image />
コンポーネントを使用できない場合に、HTMLの<img>
要素を使用してください。
- サポートされていない画像フォーマット
- Astroによる画像の最適化が不要な場合
- クライアントサイドで
src
属性に動的にアクセスして変更する場合
image.domains
とimage.remotePatterns
を使用して、画像の最適化に使用する、許可された画像ソースのURLドメインとパターンのリストを設定できます。この設定は、外部ソースから画像を表示する際にサイトを保護するために追加の安全性を提供します。
他のソースからのリモート画像は最適化されませんが、これらの画像に<Image />
コンポーネントを使用すると、Cumulative Layout Shift(CLS)を防ぐことができます。
たとえば以下の設定では、astro.build
からのリモート画像のみが最適化されます。
// astro.config.mjs
export default defineConfig({
image: {
domains: ["astro.build"],
}
});
以下の設定では、HTTPSホストからのリモート画像のみが許可されます。
// astro.config.mjs
export default defineConfig({
image: {
remotePatterns: [{ protocol: "https" }],
}
});
画像CDNは、Astroのすべての画像オプションと互換性があります。<Image />
コンポーネント、<img>
タグ、またはMarkdown記法のsrc
属性に、画像のフルURLを指定してください。リモート画像の最適化には、許可されたドメインまたはURLパターンを設定する必要があります。
あるいは、CDNがNode.js SDKを提供している場合は、プロジェクトでそれを使用することも可能です。たとえばCloudinaryのSDKは、適切なsrc
をもつ<img>
タグを生成してくれます。
.md
ファイルでは、Markdown標準の![alt](src)
構文を使用します。この構文は、Astroの画像サービスAPIと連携して、ローカル画像と許可されたリモート画像を最適化します。
<!-- src/pages/post-1.md -->
# 私のMarkdownページ
<!-- src/assets/に置かれたローカル画像 -->
<!-- 相対ファイルパスかImportエイリアスを使用します -->
![満天の星空](../assets/stars.png)
<!-- public/images/に置かれた画像 -->
<!-- public/からの相対パスを使用します -->
![満天の星空](/images/stars.png)
<!-- 別のサーバー上のリモート画像 -->
<!-- 画像の完全なURLを使用します -->
![Astro](https://example.com/images/remote-image.png)
ローカル画像の場合<img>
タグはサポートされておらず、また.md
ファイルでは<Image />
コンポーネントは使用できません。
画像の属性をより細かく制御する必要がある場合は、Markdown構文に加えて、Astroの<Image />
コンポーネントや、JSXの<img />
タグを使用可能な.mdx
ファイル形式を使用することをおすすめします。AstroにMDXサポートを追加するには、MDXインテグレーションを使用します。
コンポーネントと画像をインポートすることで、.mdx
ファイル内でAstroの<Image />
コンポーネントとJSXの<img />
タグを使用できます。使い方は.astro
ファイルの場合と同様です。
さらに、インポート不要でMarkdown標準の![alt](src)
構文もサポートされています。
---
title: 私のページタイトル
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';
# 私のMDXページ
// src/assets/に置かれたローカル画像
<Image src={rocket} alt="宇宙に浮かぶロケット。"/>
<img src={rocket.src} alt="宇宙に浮かぶロケット。" />
![宇宙に浮かぶロケット](../assets/rocket.png)
// public/images/に置かれた画像
<Image src="/images/stars.png" alt="満天の星空。" />
<img src="/images/stars.png" alt="満天の星空。" />
![満天の星空](/images/stars.png)
// 別のサーバー上のリモート画像
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)
ブログ記事のカバー画像など、コンテンツコレクションのエントリに関連付けられた画像を、現在のフォルダからの相対パスを使ってフロントマターに宣言できます。
---
title: "私の最初のブログ記事"
cover: "./firstpostcover.jpeg" # "src/content/blog/firstblogcover.jpeg"へと解決されます
coverAlt: "山々の向こうに沈む夕日の写真。"
---
これはブログ記事です
コンテンツコレクションスキーマのimage
ヘルパーにより、Zodを使用して画像のメタデータを検証できます。
import { defineCollection, z } from "astro:content";
const blogCollection = defineCollection({
schema: ({ image }) => z.object({
title: z.string(),
cover: image().refine((img) => img.width >= 1080, {
message: "カバー画像は幅1080ピクセル以上でなければなりません!",
}),
coverAlt: z.string(),
}),
});
export const collections = {
blog: blogCollection,
};
画像はインポートされ、メタデータへと変換されます。これにより、<Image/>
、<img>
、そしてgetImage()
に、src
として渡すことができます。
以下の例は、上記のスキーマから各ブログ記事のカバー写真とタイトルをレンダリングする、ブログのインデックスページを示しています。
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---
{
allBlogPosts.map((post) => (
<div>
<Image src={post.data.cover} alt={post.data.coverAlt} />
<h2>
<a href={"/blog/" + post.slug}>{post.data.title}</a>
</h2>
</div>
))
}
UIフレームワークコンポーネントに画像を追加する場合は、フレームワーク独自の画像構文を使用して画像をレンダリングします(たとえば、JSXの<img />
、Svelteの<img>
などです)。
ローカル画像は、src
などの画像プロパティにアクセスするために最初にインポートする必要があります。
import stars from "../assets/stars.png"
export default function ReactImage() {
return (
<img src={stars.src} alt="満天の星空。" />
)
}
<script>
import stars from '../assets/stars.png'
</script>
<img src={stars.src} alt="満天の星空。" />
<Image />
コンポーネントは、他のAstroコンポーネントと同様に、UIフレームワークコンポーネントでは使用できません。
しかし、.astro
ファイル内のフレームワークコンポーネントに、<Image />
によって生成された静的コンテンツを子要素として渡すか、または名前付きの<slot/>
を使用して渡すことは可能です。
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from "astro:assets"
import stars from "~/stars/docline.png";
---
<ReactComponent>
<Image src={stars} alt="満天の星空。" />
</ReactComponent>
:::caution
getImage()
はサーバー専用のAPIに依存しており、クライアントで使用するとビルドが失敗します。
:::
getImage()
関数は、たとえばAPIルートなど、HTML以外の場所で使用する画像を生成することを目的としています。また、これを使って独自のカスタム<Image />
コンポーネントも作成できます。
<RecipeLinks slugs={["ja/recipes/build-custom-img-component" ]}/>
getImage()
は、(alt
を除く)Imageコンポーネントと同じプロパティをもつオプションオブジェクトを受け取ります。
---
import { getImage } from "astro:assets";
import myBackground from "../background.png"
const optimizedBackground = await getImage({src: myBackground, format: 'webp'})
---
<div style={`background-image: url(${optimizedBackground.src});`}></div>
getImage()
は以下のプロパティをもつオブジェクトを返します。
{
rawOptions: {...}, // オリジナルのパラメータを渡す
options: {...}, // 有効なパラメータを渡す
src: "https//...", // 生成された画像へのパス
srcSet: {
values: [...], // 生成されたsrcsetの値。各エントリーはurlとサイズ記述子を持つ。
attribute: "", // valuesから生成されたsrcset属性
}
attributes: {...} // 画像をレンダリングするために必要な追加のHTML属性(width、height、styleなど)
}
すべてのユーザーが同じように画像を見れるわけではないため、画像を使用する際のアクセシビリティは特に重要です。画像に対して説明的な代替テキストを提供するために、alt
属性を使用してください。
この属性は<Image />
コンポーネントでは必須です。代替テキストが指定されていない場合、<Image />
はエラーをスローします。
画像が単に装飾用である場合(つまり、ページの理解に貢献していない場合)は、alt=""
を設定して、スクリーンリーダーが画像を無視するようにしてください。
Sharpは、astro:assets
で使用されるデフォルトの画像サービスです。
:::note
pnpm
のような厳格なパッケージマネージャーを使用している場合は、Astroの依存関係であるにもかかわらず、プロジェクトにSharpを手動でインストールする必要があるかもしれません。
pnpm add sharp
:::
画像を変換するためにSquooshを使用したい場合は、以下のように設定を更新してください。
import { defineConfig, squooshImageService } from 'astro/config';
export default defineConfig({
image: {
service: squooshImageService(),
},
});
もし使用しているserver
またはhybrid
モードのアダプターが、Astroの組み込みのSquooshおよびSharp画像最適化(Deno、Cloudflareなど)をサポートしていない場合、<Image />
や<Picture />
コンポーネントを使用できるようにno-op画像サービスを設定することができます。Astroはこれらの環境では画像の変換や処理をおこないませんが、Cumulative Layout Shift(CLS)がなくなること、alt
属性が必須であること、一貫したコードの書き心地など、astro:assets
を使用した場合の他の利点は享受することができます。
SquooshとSharpの画像処理を回避するpassthroughImageService()
の設定:
import { defineConfig, passthroughImageService } from 'astro/config';
export default defineConfig({
image: {
service: passthroughImageService()
}
});
Astroプロジェクトで画像を最適化したり、画像を扱ったりするための、サードパーティのコミュニティインテグレーションがあります。
Astro v3.0では、astro:assets
は実験的な機能ではなくなりました。
<Image />
は組み込みのコンポーネントとなり、以前の@astrojs/image
インテグレーションは削除されました。
これらのことと、Astroで画像を使用するためのその他の変更により、以前のバージョンからAstroプロジェクトをアップグレードすると、いくつかの破壊的な変更が発生する可能性があります。
Astro v2.xプロジェクトをv3.0にアップグレードするには、以下の手順に適切に従ってください。
以前にastro:assets
の実験的なフラグを有効にしていた場合は、Astro v3.0ではデフォルトでアセット機能が含まれているため、プロジェクトを更新する必要があります。
実験的なフラグを削除します。
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
assets: true
}
});
必要に応じて、astro/client-image
への参照をastro/client
に置き換えるために、src/env.d.ts
ファイルも更新します。
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />
このImportエイリアスは、astro:assets
にデフォルトで含まれなくなりました。実験的なアセット機能でこのエイリアスを使用していた場合は、相対ファイルパスに変換するか、自分でImportエイリアスを作成する必要があります。
---
import rocket from '~/assets/rocket.png'
import rocket from '../../assets/rocket.png';
---
Astro v3.0では、Astro組み込みのSquooshとSharpによる画像最適化をサポートしていないCloudflare、Deno、Vercel Edge、Netlify Edgeでも、astro:assets
をエラーなしで動作させることができます。Astroはこれらの環境では画像の変換や処理をおこないませんが、Cumulative Layout Shift(CLS)がなくなること、alt
属性が必須であること、一貫したコードの書き心地など、astro:assets
を使用した場合の他の利点は享受することができます。
こうした制約のために以前astro:assets
の使用を避けていた場合でも、もう問題なく使用できるようになりました。この動作を明示的に有効にするために、no-op画像サービスを設定できます。
import { defineConfig } from 'astro/config';
export default defineConfig({
image: {
service: {
entrypoint: 'astro/assets/services/noop'
}
}
});
画像を保存する場所を決めるには、今読んでいるこのガイドを参照してください。astro:assets
がもたらす柔軟性を活用して、画像を保存するための新しいオプションを利用したい場合があるかもしれません。たとえば、プロジェクトのsrc/
からの相対画像は、Markdown、MDX、MarkdocいずれにおいてもMarkdown標準の![alt](src)
構文により参照できるようになりました。
以前は画像をインポートすると、画像のパスを含む単純なstring
が返されました。現在は、インポートされた画像アセットは以下のシグネチャをもつオブジェクトとなります。
interface ImageMetadata {
src: string;
width: number;
height: number;
format: string;
}
(UIフレームワークコンポーネント内の画像を含む)既存の<img>
タグのsrc
属性の更新が必要です。また、インポートした画像から利用できるようになった他の属性も更新できます。
---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="宇宙に浮かぶロケット。" />
<img src={rocket.src} width={rocket.width} height={rocket.height} alt="宇宙に浮かぶロケット。" />
プロジェクトのsrc/
からの相対画像は、Markdown、MDX、MarkdocいずれにおいてもMarkdown標準の![alt](src)
構文により参照できるようになりました。
これにより、画像をpublic/
ディレクトリからプロジェクトのsrc/
に移動し、処理を加えて最適化できます。public/
内の既存の画像とリモート画像は引き続き有効ですが、Astroのビルドプロセスでは最適化されません。
# 私のMarkdownページ
<!-- ローカル画像が可能になりました! -->
![満天の星空。](../../images/stars.png)
<!-- 画像をコンテンツの近くにキープできます! -->
![満天の星空。](./stars.png)
画像の属性をより細かく制御する必要がある場合は、Markdown構文に加えて、Astroの<Image />
コンポーネントやJSXの<img />
タグを使用可能な.mdx
ファイル形式を使用することをおすすめします。AstroにMDXサポートを追加するには、MDXインテグレーションを使用します。
Astro v2.xで画像インテグレーションを使用していた場合は、以下の手順を完了させてください。
-
@astrojs/image
を削除します。インテグレーションを削除するためにアンインストールし、また
astro.config.mjs
ファイルからも削除する必要があります。// astro.config.mjs import { defineConfig } from 'astro/config'; import image from '@astrojs/image'; export default defineConfig({ integrations: [ image(), ] })
-
(必要に応じて)型を更新します。
src/env.d.ts
に@astrojs/image
のための特別な型を設定していた場合、v3へのアップグレードでこのステップが完了していなければ、デフォルトのAstroの型に戻す必要があるかもしれません。```ts title="src/env.d.ts" del={1} ins={2} /// <reference types="@astrojs/image/client" /> /// <reference types="astro/client" /> ``` 同様に、必要に応じて`tsconfig.json`を更新します。 ```json title="tsconfig.json" del={3} ins={4} { "compilerOptions": { "types": ["@astrojs/image/client"] "types": ["astro/client"] } } ```
-
既存の
<Image />
コンポーネントを移行します。新しい組み込みの
<Image />
コンポーネントを使用するために、@astrojs/image/components
からのimport
文をすべてastro:assets
に変更します。現在サポートされていない画像アセットのプロパティを削除します。
たとえば、
aspectRatio
はもうサポートされていません。これは、width
とheight
属性から自動的に推測されるためです。--- import { Image } from '@astrojs/image/components'; import { Image } from 'astro:assets' import localImage from "../assets/logo.png"; const localAlt = "Astroのロゴ"; --- <Image src={localImage} width={300} aspectRatio="16:9" alt={localAlt} />
-
デフォルトの画像サービスを選択します。
Sharpは、
astro:assets
で使用されるデフォルトの画像サービスとなりました。Sharpを使用する場合は、特に設定は必要ありません。画像を変換するためにSquooshを使用したい場合は、以下の
image.service
オプションを使用して設定を更新します。import { defineConfig, squooshImageService } from 'astro/config'; export default defineConfig({ image: { service: squooshImageService(), }, });
ブログ記事のカバー画像など、コンテンツコレクションのエントリに関連付けられた画像を、現在のフォルダからの相対パスによりフロントマターに宣言できるようになりました。
コンテンツコレクションの新しいimage
ヘルパーにより、Zodを使用して画像のメタデータを検証できるようになりました。コンテンツコレクションで画像を使用する方法について、詳しくはこちらを参照してください。
Astro v3.0で、以前の画像をインポートした際の挙動を維持しなければならず、画像URLの文字列が必要な場合は、以下のように画像パスの末尾に?url
を追加してください。
---
import Sprite from '../assets/logo.svg?url';
---
<svg>
<use xlink:href={Sprite + '#cart'} />
</svg>
この方法により、URLの文字列を取得できます。なお、Astroは開発中にsrc/
パスを使用しますが、ビルド時には/_astro/cat.a6737dd3.png
のようなハッシュ化されたパスを生成することに注意してください。
画像オブジェクト自体を直接扱いたい場合は、.src
プロパティにアクセスできます。この方法は、Core Web Vitalsメトリクスのための画像サイズの調整や、CLSの防止などのタスクに最適です。
新しいインポートの挙動に移行する場合は、?url
と.src
の両方を組み合わせることが、シームレスに画像を扱うための正しい方法かもしれません。