عرض مصدر Next.js/next script

<noinclude>{{DISPLAYTITLE:الواجهة البرمجية للمكون next/script في Next.js}}</noinclude>هذه الصفحة تعرض توثيق الواجهة البرمجية للمكوّن next/script وتساعدك على فهم الخاصيات props المتاحة وكيفية استخدامها، أما للاطلاع أكثر على الميزات ومعلومات الاستخدام فراجع صفحة "[[Next.js/script|التعامل مع السكربتات في Next.js"]] من هذا التوثيق.

== سجل التغييرات ==
{| class="wikitable"
!الإصدار
!التغييرات
|-
|v13.0.0
|تعديل الخاصية <code>beforeinteractive</code> والخاصية <code>afterInteractive</code> لدعم المجلد <code>/app</code>.
|-
|v12.2.4 
|إضافة الخاصية onReady.
|-
|v12.2.2
|السماح بإضافة سكربت next/script مع الخاصية <code>beforeInteractive</code> في الملف <code>document_</code>.
|-
|v11.0.0
|إضافة المكون next/script.
|}

== ملخص الخاصيات ==
إليك ملخص الخاصيات المتاحة التي يأخذها المكون Script:
{| class="wikitable"
|+
!الخاصية
!مثال
!نوع القيمة
!مطلوبة؟
|-
|<code>src</code>
|<code>src="<nowiki>http://example.com/script</nowiki>"‎</code>
|سلسلة نصية
|أجل، إلا إن جرى كتابة محتوى السكربت داخل العنصر.
|-
|<code>strategy</code>
|<code>strategy="lazyOnload"‎</code>
|سلسلة نصية
|لا، اختيارية.
|-
|<code>onLoad</code>
|<code>onLoad={onLoadFunc}</code>
|دالة
|لا، اختيارية.
|-
|<code>onReady</code>
|<code>onReady={onReadyFunc}</code>
|دالة
|لا، اختيارية.
|-
|<code>onError</code>
|<code>onError={onErrorFunc}</code>
|دالة
|لا، اختيارية.
|}

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

===<code>src</code>===
وهي مسار نصي يحدد عنوان URL للسكربت الخارجي. يمكن أن يكون العنوان مطلق أو مسار داخلي.

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

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

===<code>strategy</code>===
وتحدد استراتيجية أو آلية تحميل السكربت، وتوجد أربعة آليات مختلفة يمكن استخدامها:

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

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

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

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

يجدر بك استخدام هذه الاستراتيجية مع السكربتات الحيوية والحرجة التي ينبغي إحضارها وتنفيذها قبل أن يتمكن المستخدم من التفاعل مع أي جزء من الصفحة.<syntaxhighlight lang="javascript">
import Script from 'next/script'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
      <Component {...pageProps} />
    </>
  )
}
</syntaxhighlight>'''ملاحظة''': السكربتات التي تستعمل آلية <code>beforeInteractive</code> ستضاف دومًا داخل العنصر <code>[[HTML/head|head]]</code> من صفحة HTML بغض النظر عن موقعها في التطبيق.

من السكربتات التي ينبغي تحملها وفق هذه الاستراتيجية نجد:
*مكتشفات المؤتمِتات Bot detectors
*مديرو قبول ملفات تعريف الارتباط cookie consent.
====<code>afterInteractive</code>====
تضاف السكربتات التي تستخدم هذه الاستراتيجية إلى في صفحة HTML التي تصل إلى العميل وتُحمَّل بعد بدء أو انتهاء ترطيب Next.js للصفحة (بعد أن تحلل شيفرة JavaScript وتضيف كامل المحتوى). 

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

يمكن إضافة السكربتات التي تتبع هذه الآلية في أي صفحة page أو تخطيط layout وسيُحمَّل ثم يُنفَّذ عند فتح تلك الصفحة (أو مجموعة من الصفحات) في المتصفح.<syntaxhighlight lang="javascript">
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}
</syntaxhighlight>من السكربتات التي تُعد أمثلة جيدة عن هذه الحالة نجد:
*مديرو الوسوم Tag managers
*المحللات Analytics
====<code>lazyOnload</code>====
تضاف السكربتات وفق هذه الاستراتيجية إلى صفحة HTML لطرف العميل أثناء فترة خمول المتصفح browser idle time وتحمَّل بعد إحضار كل موارد الصفحة، وينبغي استخدام هذه الاستراتيجية في الخلفية أو للسكربتات ذات الأولوية المنخفضة التي لا حاجة لتحميها مباشرة قبل أو بعد أن تغدو الصفحة تفاعلية.

يمكن إضافة السكربتات التي تتبع هذه الآلية في أي جزء من أي صفحة وستُحمَّل ثم تُنفَّذ عند فتح تلك الصفحة (أو مجموعة من الصفحات) في المتصفح.<syntaxhighlight lang="javascript">
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}
</syntaxhighlight>من السكربتات التي تُعد أمثلة جيدة عن هذه الحالة نجد:
*الإضافات التي تدعم المحادثات.
*أدوات الارتباط بمواقع التواصل الاجتماعي.

==== <code>worker</code> ====
<blockquote>'''ملاحظة''': لا تزال هذه الاستراتيجية تجريبية وغير مستقرة وقد تسبب أخطاءً غير متوقعة بالإضافة إلى أنها لا تعمل مع المجلد <code>/app</code> لذك استخدمها بحذر.</blockquote>تُسند السكربتات التي تتبع هذه الآلية أو الاستراتيجية إلى عامل ويب web worker لتحميلها وتنفيذها وذلك لتخفيف عبء خيط المعالجة الرئيسي main thread وتركه لمعالجة الموارد المهمة الأساسية.

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

إن أردت استخدام هذه الآلية، فيجب تفعيل الخاصية nextScriptWorkers من ملف الضبط next.config.js:<syntaxhighlight lang="javascript">
module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}
</syntaxhighlight>يجب إضافة السكربتات التي تعتمد هذه الآلية ضمن الصفحات الواقعة داخل المجلد <code>/pages</code> فقط حاليًا:<syntaxhighlight lang="javascript">
import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}
</syntaxhighlight>
===<code>onLoad</code>===
<blockquote>'''ملاحظة''': لا يمكن استخدام  <code>onLoad</code> مع استراتيجة التحميل <code>beforeInteractive</code> ويمكن آنذاك استخدام onRead.</blockquote>تطلب بعض السكربتات الخارجية third-party scripts تنفيذ شيفرة JavaScript بعد انتهاء تحميل السكربت لتهيئة محتوى ما أو استدعاء دالة ما مثلًا، فإذا كنت أضفت سكربتًا خارجيًا مع آلية تحميل <code>afterInteractive</code> أو <code>lazyOnload</code>، فيمكنك تنفيذ شيفرة ما بعد انتهاء تحميل السكربت بتمريرها إلى الخاصية <code>onLoad</code>.

إليك مثالًا عن كيفية استخدام <code>onLoad</code> لتنفيذ دالة من مكتبة lodash بعد انتهاء تحميل المكتبة:<syntaxhighlight lang="javascript">
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,
          })
        }}
      />
    </>
  )
}

</syntaxhighlight>

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

إليك مثال عن إعادة تهئية خدمة خرائط جوجل Google Maps في كل مرة يعاد إضافة المكون:<syntaxhighlight lang="javascript">
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]))
        }}
      />
    </>
  )
}
</syntaxhighlight>

===<code>onError</code>===
<blockquote>'''ملاحظة''': لا يمكن استخدام  <code>onError</code> مع استراتيجة التحميل <code>beforeInteractive</code></blockquote>أحيانًا من الجيد التقاط الخطأ الحاصل نتيجة فشل تحميل سكربت ما، لذا يمكن معالجة مثل هذه الأخطاء عبر الخاصية  <code>onError</code>:<syntaxhighlight lang="javascript">
export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}
</syntaxhighlight>

== المصادر ==

* الصفحة [https://nextjs.org/docs/api-reference/next/script Next/script] من توثيق Next.js الرسمي.
[[تصنيف:Next.js|{{SUBPAGENAME}}]]
[[تصنيف:Next.js API|{{SUBPAGENAME}}]]