opengraph-image و twitter-image

تتيح لك اتفاقيات ملفات opengraph-image و twitter-image تعيين صور Open Graph و Twitter لمقطع المسار.

هذه الملفات مفيدة لتعيين الصور التي تظهر على الشبكات الاجتماعية وتطبيقات المراسلة عندما يشارك المستخدم رابط موقعك.

هناك طريقتان لتعيين صور Open Graph و Twitter:

استخدام ملفات الصور (.jpg, .png, .gif)
استخدام الكود لإنشاء الصور (.js, .ts, .tsx)

ملفات الصور (.jpg, .png, .gif)

استخدم ملف صورة لتعيين صورة مشتركة لمقطع المسار عن طريق وضع ملف صورة opengraph-image أو twitter-image في المقطع.

سيقوم Next.js بتقييم الملف وإضافة العلامات المناسبة تلقائيًا إلى عنصر <head> لتطبيقك.

اتفاقية الملف	أنواع الملفات المدعومة
`opengraph-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`twitter-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`opengraph-image.alt`	`.txt`
`twitter-image.alt`	`.txt`

`opengraph-image`

أضف ملف صورة opengraph-image.(jpg|jpeg|png|gif) إلى أي مقطع مسار.

<head> output

<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />

`twitter-image`

أضف ملف صورة twitter-image.(jpg|jpeg|png|gif) إلى أي مقطع مسار.

<head> output

<meta name="twitter:image" content="<generated>" />
<meta name="twitter:image:type" content="<generated>" />
<meta name="twitter:image:width" content="<generated>" />
<meta name="twitter:image:height" content="<generated>" />

`opengraph-image.alt.txt`

أضف ملف opengraph-image.alt.txt مصاحب في نفس مقطع المسار مثل صورة opengraph-image.(jpg|jpeg|png|gif) كنص بديل لها.

opengraph-image.alt.txt

About Acme

<head> output

<meta property="og:image:alt" content="About Acme" />

`twitter-image.alt.txt`

أضف ملف twitter-image.alt.txt مصاحب في نفس مقطع المسار مثل صورة twitter-image.(jpg|jpeg|png|gif) كنص بديل لها.

twitter-image.alt.txt

About Acme

<head> output

<meta property="twitter:image:alt" content="About Acme" />

إنشاء الصور باستخدام الكود (.js, .ts, .tsx)

بالإضافة إلى استخدام ملفات الصور الحرفية، يمكنك إنشاء الصور برمجيًا باستخدام الكود.

قم بإنشاء صورة مشتركة لمقطع المسار عن طريق إنشاء مسار opengraph-image أو twitter-image يقوم بتصدير دالة افتراضية.

اتفاقية الملف	أنواع الملفات المدعومة
`opengraph-image`	`.js`, `.ts`, `.tsx`
`twitter-image`	`.js`, `.ts`, `.tsx`

معلومة مفيدة

بشكل افتراضي، يتم تحسين الصور المُنشأة بشكل ثابت (يتم إنشاؤها وقت البناء وتخزينها مؤقتًا) ما لم تستخدم وظائف ديناميكية أو بيانات غير مخزنة مؤقتًا.

يمكنك إنشاء صور متعددة في نفس الملف باستخدام generateImageMetadata.

أسهل طريقة لإنشاء صورة هي استخدام واجهة برمجة التطبيقات ImageResponse من next/server.

import { ImageResponse } from 'next/server'

// تهيئة مقطع المسار
export const runtime = 'edge'

// بيانات وصفية للصورة
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// إنشاء الصورة
export default async function Image() {
  // الخط
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())

  return new ImageResponse(
    (
      // عنصر JSX لـ ImageResponse
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // خيارات ImageResponse
    {
      // لتسهيل الأمر، يمكننا إعادة استخدام إعدادات الحجم
      // المُصدّرة من opengraph-image لتعيين عرض وارتفاع ImageResponse أيضًا.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: await interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

import { ImageResponse } from 'next/server'

// تهيئة مقطع المسار
export const runtime = 'edge'

// بيانات وصفية للصورة
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// إنشاء الصورة
export default async function Image() {
  // الخط
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())

  return new ImageResponse(
    (
      // عنصر JSX لـ ImageResponse
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // خيارات ImageResponse
    {
      // لتسهيل الأمر، يمكننا إعادة استخدام إعدادات الحجم
      // المُصدّرة من opengraph-image لتعيين عرض وارتفاع ImageResponse أيضًا.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: await interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

<head> output

<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="About Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

الخصائص (Props)

تستقبل الدالة المُصدّرة افتراضيًا الخصائص التالية:

`params` (اختياري)

كائن يحتوي على كائن معلمات المسار الديناميكي من المقطع الجذري وصولاً إلى المقطع الذي يوجد فيه opengraph-image أو twitter-image.

export default function Image({ params }: { params: { slug: string } }) {
  // ...
}

export default function Image({ params }) {
  // ...
}

المسار	URL	`params`
`app/shop/opengraph-image.js`	`/shop`	`undefined`
`app/shop/[slug]/opengraph-image.js`	`/shop/1`	`{ slug: '1' }`
`app/shop/[tag]/[item]/opengraph-image.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`
`app/shop/[...slug]/opengraph-image.js`	`/shop/1/2`	`{ slug: ['1', '2'] }`

القيم المُرجعة

معلومة مفيدة: ImageResponse تفي بهذا النوع من القيم المُرجعة.

تصدير التهيئة

يمكنك تهيئة البيانات الوصفية للصورة اختياريًا عن طريق تصدير المتغيرات alt و size و contentType من مسار opengraph-image أو twitter-image.

الخيار	النوع
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - نوع MIME للصورة

`alt`

export const alt = 'My images alt text'

export default function Image() {}

export const alt = 'My images alt text'

export default function Image() {}

<head> output

<meta property="og:image:alt" content="My images alt text" />

`size`

export const size = { width: 1200, height: 630 }

export default function Image() {}

export const size = { width: 1200, height: 630 }

export default function Image() {}

<head> output

<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

`contentType`

export const contentType = 'image/png'

export default function Image() {}

export const contentType = 'image/png'

export default function Image() {}

<head> output

<meta property="og:image:type" content="image/png" />

تهيئة مقطع المسار

opengraph-image و twitter-image هما معالجان متخصصان للمسارات يمكنهما استخدام نفس خيارات تهيئة مقطع المسار مثل الصفحات والتخطيطات.

الخيار	النوع	الافتراضي
`dynamic`	`'auto' \| 'force-dynamic' \| 'error' \| 'force-static'`	`'auto'`
`revalidate`	`false \| 'force-cache' \| 0 \| number`	`false`
`runtime`	`'nodejs' \| 'edge'`	`'nodejs'`
`preferredRegion`	`'auto' \| 'global' \| 'home' \| string \| string[]`	`'auto'`

export const runtime = 'edge'

export default function Image() {}

export const runtime = 'edge'

export default function Image() {}

أمثلة

استخدام بيانات خارجية

يستخدم هذا المثال كائن params والبيانات الخارجية لإنشاء الصورة.

معلومة مفيدة: بشكل افتراضي، سيتم تحسين هذه الصورة المُنشأة بشكل ثابت. يمكنك تهيئة خيارات fetch الفردية أو خيارات مقاطع المسار لتغيير هذا السلوك.

import { ImageResponse } from 'next/server'

export const runtime = 'edge'

export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

import { ImageResponse } from 'next/server'

export const runtime = 'edge'

export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

سجل الإصدارات

الإصدار	التغييرات
`v13.3.0`	تم تقديم `opengraph-image` و `twitter-image`.

On this page