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/og.

import { ImageResponse } from 'next/og'

// تكوين قطاع المسار
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/og'

// تكوين قطاع المسار
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" />

الخصائص

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

`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 = 'نص بديل لصورتي'

export default function Image() {}

export const alt = 'نص بديل لصورتي'

export default function Image() {}

<head> output

<meta property="og:image:alt" content="نص بديل لصورتي" />

`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/og'

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/og'

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