الواجهة البرمجية للمكون next/script في Next.js

هذه الصفحة تعرض توثيق الواجهة البرمجية للمكوّن next/script وتساعدك على فهم الخاصيات props المتاحة وكيفية استخدامها، أما للاطلاع أكثر على الميزات ومعلومات الاستخدام فراجع صفحة "التعامل مع السكربتات في Next.js" من هذا التوثيق.

سجل التغييرات

الإصدار	التغييرات
v13.0.0	تعديل الخاصية beforeinteractive والخاصية afterInteractive لدعم المجلد /app.
v12.2.4	إضافة الخاصية onReady.
v12.2.2	السماح بإضافة سكربت next/script مع الخاصية beforeInteractive في الملف document_.
v11.0.0	إضافة المكون next/script.

ملخص الخاصيات

إليك ملخص الخاصيات المتاحة التي يأخذها المكون Script:

الخاصية	مثال	نوع القيمة	مطلوبة؟
src	src="http://example.com/script"‎	سلسلة نصية	أجل، إلا إن جرى كتابة محتوى السكربت داخل العنصر.
strategy	strategy="lazyOnload"‎	سلسلة نصية	لا، اختيارية.
onLoad	onLoad={onLoadFunc}	دالة	لا، اختيارية.
onReady	onReady={onReadyFunc}	دالة	لا، اختيارية.
onError	onError={onErrorFunc}	دالة	لا، اختيارية.

خاصيات مطلوبة

src

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

ملاحظة: الخاصية src مطلوبة إلا إن جرى توفير محتوى السكربت.

خاصيات اختيارية

strategy

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

• beforeInteractive: حمِّل السكربت قبل أن تغدو الصفحة تفاعلية مع المستخدم.
• afterInteractive: (الافتراضية) حمِّل السكربت مباشرة بعد أن تغدو الصفحة تفاعلية.
• lazyOnload: حمّل السكربت خلال فترة توقف التصفح (فترة الراحة).
• worker: حمّل الصفحة في خيط عامل ويب web worker.

beforeInteractive

تضاف السكربتات التي تحمّل وفق هذه الاستراتيجية ضمن شيفرة HTML التي يوّلدها الخادم ثم تحمَّل قبل أي وحدة من وحدات Next.js ثم تُنفَّذ بعدها وفق ترتيبها في الصفحة قبل أي إجراء أي عملية ترطيب hydration أو حقن محتوى الصفحة.

السكربتات التي تتبع هذه الآلية تُجلَب وتحمَّل مسبقًا preload قبل جلب أي شيفرة إضافية من تطبيقك ولكن تنفيذها لن يمنع عملية الترطيب أو حقن المحتوى.

انتبه إلى أنه يجب وضع السكربت الذي يستعمل هذه الآلية ضمن الملف pages/_app.js إذ صُمِّمت هذه الآلية لتحميل سكربتات على مستوى كامل صفحات الموقع، إذ سيحمَّل السكربت مثلًا أثناء تجهيز الصفحة من طرف الخادم server-side وإعدادها.

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

import Script from 'next/script'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
      <Component {...pageProps} />
    </>
  )
}

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

من السكربتات التي ينبغي تحملها وفق هذه الاستراتيجية نجد:

• مكتشفات المؤتمِتات Bot detectors
• مديرو قبول ملفات تعريف الارتباط cookie consent.

afterInteractive

تضاف السكربتات التي تستخدم هذه الاستراتيجية إلى في صفحة HTML التي تصل إلى العميل وتُحمَّل بعد بدء أو انتهاء ترطيب Next.js للصفحة (بعد أن تحلل شيفرة JavaScript وتضيف كامل المحتوى).

هذه الآلية هي الآلية الافتراضية التي يتبعها مكون سكربت Next.js وينبغي استخدامها مع السكربتات التي يمكن تحميلها متى ما أمكن ولكن ليس قبل تحميل شيفرة Next.js.

يمكن إضافة السكربتات التي تتبع هذه الآلية في أي صفحة page أو تخطيط layout وسيُحمَّل ثم يُنفَّذ عند فتح تلك الصفحة (أو مجموعة من الصفحات) في المتصفح.

import Script from 'next/script'

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

من السكربتات التي تُعد أمثلة جيدة عن هذه الحالة نجد:

• مديرو الوسوم Tag managers
• المحللات Analytics

lazyOnload

تضاف السكربتات وفق هذه الاستراتيجية إلى صفحة HTML لطرف العميل أثناء فترة خمول المتصفح browser idle time وتحمَّل بعد إحضار كل موارد الصفحة، وينبغي استخدام هذه الاستراتيجية في الخلفية أو للسكربتات ذات الأولوية المنخفضة التي لا حاجة لتحميها مباشرة قبل أو بعد أن تغدو الصفحة تفاعلية.

يمكن إضافة السكربتات التي تتبع هذه الآلية في أي جزء من أي صفحة وستُحمَّل ثم تُنفَّذ عند فتح تلك الصفحة (أو مجموعة من الصفحات) في المتصفح.

import Script from 'next/script'

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

من السكربتات التي تُعد أمثلة جيدة عن هذه الحالة نجد:

• الإضافات التي تدعم المحادثات.
• أدوات الارتباط بمواقع التواصل الاجتماعي.

worker

ملاحظة: لا تزال هذه الاستراتيجية تجريبية وغير مستقرة وقد تسبب أخطاءً غير متوقعة بالإضافة إلى أنها لا تعمل مع المجلد /app لذك استخدمها بحذر.

تُسند السكربتات التي تتبع هذه الآلية أو الاستراتيجية إلى عامل ويب web worker لتحميلها وتنفيذها وذلك لتخفيف عبء خيط المعالجة الرئيسي main thread وتركه لمعالجة الموارد المهمة الأساسية.

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

إن أردت استخدام هذه الآلية، فيجب تفعيل الخاصية nextScriptWorkers من ملف الضبط next.config.js:

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

يجب إضافة السكربتات التي تعتمد هذه الآلية ضمن الصفحات الواقعة داخل المجلد /pages فقط حاليًا:

import Script from 'next/script'

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

onLoad

ملاحظة: لا يمكن استخدام onLoad مع استراتيجة التحميل beforeInteractive ويمكن آنذاك استخدام onRead.

تطلب بعض السكربتات الخارجية third-party scripts تنفيذ شيفرة JavaScript بعد انتهاء تحميل السكربت لتهيئة محتوى ما أو استدعاء دالة ما مثلًا، فإذا كنت أضفت سكربتًا خارجيًا مع آلية تحميل afterInteractive أو lazyOnload، فيمكنك تنفيذ شيفرة ما بعد انتهاء تحميل السكربت بتمريرها إلى الخاصية onLoad. إليك مثالًا عن كيفية استخدام onLoad لتنفيذ دالة من مكتبة lodash بعد انتهاء تحميل المكتبة:

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

onRead

تطلب بعض السكربتات الخارجية third-party scripts تنفيذ شيفرة JavaScript بعد انتهاء تحميل السكربت وفي كل مرة يضاف فيها مكون في الصفحة (تدعى حالة وصل المكون mounted) مثلًا بعد الانتقال إلى الصفحة، لذا توفر الخاصية onReady إمكانية تنفيذ تلك الشيفرة بعد انتهاء تحميل السكربت وبعدها لاحقًا في كل مرة يضاف فيها مكون إلى الصفحة.

إليك مثال عن إعادة تهئية خدمة خرائط جوجل Google Maps في كل مرة يعاد إضافة المكون:

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

onError

ملاحظة: لا يمكن استخدام onError مع استراتيجة التحميل beforeInteractive

أحيانًا من الجيد التقاط الخطأ الحاصل نتيجة فشل تحميل سكربت ما، لذا يمكن معالجة مثل هذه الأخطاء عبر الخاصية onError:

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}

المصادر

• الصفحة Next/script من توثيق Next.js الرسمي.