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`

معلومة مفيدة:

يجب ألا يتجاوز حجم ملف twitter-image 5MB، ويجب ألا يتجاوز حجم ملف opengraph-image 8MB. إذا تجاوز حجم ملف الصورة هذه الحدود، فسيفشل البناء.

`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.

opengraph-image.js و twitter-image.js هما معالجان خاصان للمسار يتم تخزينهما مؤقتًا بشكل افتراضي ما لم يستخدما واجهة برمجة تطبيقات ديناميكية أو خيار تكوين ديناميكي.

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

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

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

export const contentType = 'image/png'

// إنشاء الصورة
export default async function Image() {
  // تحميل الخط، process.cwd() هو دليل مشروع Next.js
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  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: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

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

export const contentType = 'image/png'

// إنشاء الصورة
export default async function Image() {
  // تحميل الخط، process.cwd() هو دليل مشروع Next.js
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  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: 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' }`

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

معلومة مفيدة: 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 هما معالجا مسار متخصصان يمكنهما استخدام نفس خيارات تكوين مقطع المسار مثل الصفحات والتخطيطات.

أمثلة

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

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

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

import { ImageResponse } from 'next/og'

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 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,
    }
  )
}

استخدام وقت تشغيل Node.js مع أصول محلية

يستخدم هذا المثال وقت تشغيل Node.js لجلب صورة محلية على نظام الملفات وتمريرها كـ ArrayBuffer إلى السمة src لعنصر <img>. يجب وضع الأصل المحلي بالنسبة إلى جذر مشروعك، وليس موقع ملف المصدر للمثال.

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

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

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

On this page