Script

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

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" />
    </>
  )
}

الخصائص (Props)

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

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

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

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

`src`

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

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

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

`strategy`

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

beforeInteractive: التحميل قبل أي كود Next.js وقبل أي عملية ترطيب (hydration) للصفحة.
afterInteractive: (الافتراضي) التحميل مبكرًا ولكن بعد حدوث بعض الترطيب للصفحة.
lazyOnload: التحميل خلال وقت الفراغ في المتصفح.
worker: (تجريبي) التحميل في عامل ويب (web 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}
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}

import Script from 'next/script'

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

مديرو العلامات (Tag managers)
أدوات التحليل (Analytics)

`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 Router). استخدم بحذر.

يتم تفريغ البرامج النصية التي تستخدم استراتيجية worker إلى عامل ويب (web 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 لا يعمل حاليًا مع مكونات الخادم (Server Components) ويمكن استخدامه فقط في مكونات العميل (Client Components). بالإضافة إلى ذلك، لا يمكن استخدام 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 لا يعمل حاليًا مع مكونات الخادم (Server Components) ويمكن استخدامه فقط في مكونات العميل (Client Components).

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

إليك مثالاً حول كيفية إعادة إنشاء تضمين Google Maps 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 لا يعمل حاليًا مع مكونات الخادم (Server Components) ويمكن استخدامه فقط في مكونات العميل (Client Components). لا يمكن استخدام 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) => {
          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