مكون <Script>

سيساعدك مرجع API هذا على فهم كيفية استخدام الخصائص المتاحة لمكون Script. لميزات الاستخدام، يرجى الاطلاع على صفحة تحسين النصوص البرمجية.

import Script from 'next/script'

export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

import Script from 'next/script'

export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

الخصائص

فيما يلي ملخص للخصائص المتاحة لمكون Script:

الخاصية	مثال	النوع	مطلوب
`src`	`src="http://example.com/script"`	String	مطلوب إلا إذا تم استخدام نص برمجي مضمن
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

الخصائص المطلوبة

يتطلب مكون <Script /> الخصائص التالية.

`src`

سلسلة تحدد مسار URL للنص البرمجي الخارجي. يمكن أن يكون هذا عنوان URL خارجيًا مطلقًا أو مسارًا داخليًا. خاصية src مطلوبة إلا إذا تم استخدام نص برمجي مضمن.

الخصائص الاختيارية

يقبل مكون <Script /> عددًا من الخصائص الإضافية بخلاف تلك المطلوبة.

`strategy`

استراتيجية تحميل النص البرمجي. هناك أربع استراتيجيات مختلفة يمكن استخدامها:

beforeInteractive: التحميل قبل أي كود Next.js وقبل أي عملية ترطيب للصفحة.
afterInteractive: (الافتراضي) التحميل مبكرًا ولكن بعد حدوث بعض الترطيب للصفحة.
lazyOnload: التحميل خلال وقت الخمول في المتصفح.
worker: (تجريبي) التحميل في عامل ويب.

`beforeInteractive`

يتم حقن النصوص البرمجية التي تستخدم استراتيجية beforeInteractive في HTML الأولي من الخادم، وتحميلها قبل أي وحدة Next.js، وتنفيذها بالترتيب الذي توضع فيه قبل أي ترطيب للصفحة.

يتم جلب النصوص البرمجية المحددة بهذه الاستراتيجية مسبقًا قبل أي كود أساسي، لكن تنفيذها لا يعيق ترطيب الصفحة.

يجب وضع النصوص البرمجية beforeInteractive داخل التخطيط الجذري (app/layout.tsx) وهي مصممة لتحميل النصوص البرمجية المطلوبة من قبل الموقع بأكمله (أي سيتم تحميل النص البرمجي عند تحميل أي صفحة في التطبيق من جانب الخادم).

يجب استخدام هذه الاستراتيجية فقط للنصوص البرمجية الحرجة التي يجب جلبها قبل أن يصبح أي جزء من الصفحة تفاعليًا.

import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
    </html>
  )
}

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
    </html>
  )
}

ملاحظة مهمة: سيتم دائمًا حقن النصوص البرمجية مع beforeInteractive داخل head من مستند HTML بغض النظر عن مكان وضعها في المكون.

بعض الأمثلة على النصوص البرمجية التي يجب تحميلها في أقرب وقت ممكن باستخدام beforeInteractive تشمل:

كاشفات الروبوتات
مديرو موافقات ملفات تعريف الارتباط

`afterInteractive`

يتم حقن النصوص البرمجية التي تستخدم استراتيجية afterInteractive في HTML من جانب العميل وسيتم تحميلها بعد حدوث بعض (أو كل) الترطيب على الصفحة. هذه هي الاستراتيجية الافتراضية لمكون Script ويجب استخدامها لأي نص برمجي يحتاج إلى التحميل في أقرب وقت ممكن ولكن ليس قبل أي كود Next.js أساسي.

يمكن وضع النصوص البرمجية afterInteractive داخل أي صفحة أو تخطيط وسيتم تحميلها وتنفيذها فقط عند فتح تلك الصفحة (أو مجموعة الصفحات) في المتصفح.

app/page.js

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}

بعض الأمثلة على النصوص البرمجية المناسبة لـ afterInteractive تشمل:

مديري العلامات
أدوات التحليل

`lazyOnload`

يتم حقن النصوص البرمجية التي تستخدم استراتيجية lazyOnload في HTML من جانب العميل خلال وقت الخمول في المتصفح وسيتم تحميلها بعد جلب جميع الموارد على الصفحة. يجب استخدام هذه الاستراتيجية لأي نصوص برمجية خلفية أو منخفضة الأولوية لا تحتاج إلى التحميل مبكرًا.

يمكن وضع النصوص البرمجية lazyOnload داخل أي صفحة أو تخطيط وسيتم تحميلها وتنفيذها فقط عند فتح تلك الصفحة (أو مجموعة الصفحات) في المتصفح.

app/page.js

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}

أمثلة على النصوص البرمجية التي لا تحتاج إلى التحميل فورًا ويمكن جلبها باستخدام lazyOnload تشمل:

ملحقات دعم الدردشة
أدوات وسائل التواصل الاجتماعي

`worker`

تحذير: استراتيجية worker ليست مستقرة بعد ولا تعمل مع دليل app. استخدم بحذر.

يتم تحميل النصوص البرمجية التي تستخدم استراتيجية worker في عامل ويب لتحرير الخيط الرئيسي وضمان معالجة الموارد الأساسية فقط عليه. بينما يمكن استخدام هذه الاستراتيجية لأي نص برمجي، فهي حالة استخدام متقدمة ولا تضمن دعم جميع النصوص البرمجية الخارجية.

لاستخدام worker كاستراتيجية، يجب تمكين علم nextScriptWorkers في next.config.js:

next.config.js

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

يمكن حاليًا استخدام النصوص البرمجية worker فقط في دليل pages/:

import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

`onLoad`

تحذير: onLoad لا يعمل بعد مع مكونات الخادم ويمكن استخدامه فقط في مكونات العميل. بالإضافة إلى ذلك، لا يمكن استخدام onLoad مع beforeInteractive - فكر في استخدام onReady بدلاً من ذلك.

تتطلب بعض النصوص البرمجية الخارجية من المستخدمين تشغيل كود JavaScript مرة واحدة بعد اكتمال تحميل النص البرمجي لإنشاء المحتوى أو استدعاء دالة. إذا كنت تقوم بتحميل نص برمجي باستخدام استراتيجية التحميل afterInteractive أو lazyOnload، فيمكنك تنفيذ الكود بعد تحميله باستخدام خاصية onLoad.

فيما يلي مثال لتنفيذ طريقة lodash فقط بعد تحميل المكتبة.

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}

`onReady`

تحذير: onReady لا يعمل بعد مع مكونات الخادم ويمكن استخدامه فقط في مكونات العميل.

تتطلب بعض النصوص البرمجية الخارجية من المستخدمين تشغيل كود JavaScript بعد اكتمال تحميل النص البرمجي وفي كل مرة يتم فيها تحميل المكون (على سبيل المثال بعد التنقل بين الصفحات). يمكنك تنفيذ الكود بعد حدث تحميل النص البرمجي عند تحميله لأول مرة ثم بعد كل إعادة تحميل لاحقة للمكون باستخدام خاصية onReady.

فيما يلي مثال لكيفية إعادة إنشاء تضمين خرائط Google JS في كل مرة يتم فيها تحميل المكون:

'use client'

import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}

'use client'

import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}

`onError`

تحذير: onError لا يعمل بعد مع مكونات الخادم ويمكن استخدامه فقط في مكونات العميل. لا يمكن استخدام onError مع استراتيجية التحميل beforeInteractive.

في بعض الأحيان يكون من المفيد اكتشاف فشل تحميل النص البرمجي. يمكن التعامل مع هذه الأخطاء باستخدام خاصية onError:

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('فشل تحميل النص البرمجي', e)
        }}
      />
    </>
  )
}

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('فشل تحميل النص البرمجي', e)
        }}
      />
    </>
  )
}

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

الإصدار	التغييرات
`v13.0.0`	تم تعديل `beforeInteractive` و `afterInteractive` لدعم `app`.
`v12.2.4`	إضافة خاصية `onReady`.
`v12.2.2`	السماح بـ `next/script` مع `beforeInteractive` في `_document`.
`v11.0.0`	تقديم `next/script`.

On this page