<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"`	سلسلة نصية	مطلوب إلا إذا تم استخدام برنامج نصي مضمن
`strategy`	`strategy="lazyOnload"`	سلسلة نصية	-
`onLoad`	`onLoad={onLoadFunc}`	دالة	-
`onReady`	`onReady={onReadyFunc}`	دالة	-
`onError`	`onError={onErrorFunc}`	دالة	-

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

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

`src`

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

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

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

`strategy`

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

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

`beforeInteractive`

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

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

يجب وضع البرامج النصية beforeInteractive داخل مكون Document (pages/_document.js) وهي مصممة لتحميل البرامج النصية المطلوبة للموقع بأكمله (أي سيتم تحميل البرنامج النصي عند تحميل أي صفحة في التطبيق من جانب الخادم).

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

pages/_document.js

import { Html, Head, Main, NextScript } from 'next/document'
import Script from 'next/script'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <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:

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

`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 Maps JS في كل مرة يتم فيها تحميل المكون:

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:

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