عرض مصدر Next.js/measuring performance

<noinclude>{{DISPLAYTITLE:قياس الأداء في تطبيقات Next.js}}</noinclude>
تتيح لك الأداة [https://nextjs.org/analytics Next.js Analytics] تحليل وقياس أداء الصفحات مستخدمًا مؤشرات مختلفة. فقد تبدأ بتجميع [https://vercel.com/docs/analytics#metrics نقاط التجربة الواقعية] Real Experience Score دون إعدادات عند [https://vercel.com/docs/analytics النشر على Vercel]، كما يمكنك دعم Next.js Analytics إن اخترت [https://vercel.com/docs/analytics#self-hosted الاستضافة الذاتية].

تشرح الأقسام التالية في هذه الصفحة من التوثيق الطبقات المدمجة التي يستخدمها Next.js Analytics.

== استخدام المؤشرات التي تناسبك ==
عليك إولًا إنشاء [[Next.js/custom app|مكوّن <code>App</code>]] مخصص وتعرّف داخله الدالة <code>reportWebVitals</code>:<syntaxhighlight lang="javascript">
// pages/_app.js
export function reportWebVitals(metric) {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp
</syntaxhighlight>تُستدعى هذه الدالة عندما تُحسب القيمة النهائية لأي مؤشر في الصفحة، وبإمكانك عندها عرض النتيجة على الطرفية إو إرسالها إلى وصلة خاصة لتخزينها. يتكوّن الكائن <code>metric</code> الذي يُعاد إلى الدالة من خاصيات عدة هي:

* <code>id</code>: مُعرِّف فريد للمؤشر في سياق الحمل الذي تعرضه الصفحة الحالية.
* <code>name</code>: اسم المؤشر.
* <code>startTime</code>: زمن التسجيل الأول لقيمة الأداء [https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp بالميلي ثانية] إن أمكن.
* <code>value</code>: قيمة أو فترة زمنية لمؤشر الأداء.
* <code>label</code>: نوع المؤشر <code>web-vital</code> (مؤشرات ويب الحيوية) أو <code>custom</code> (مؤشر مخصص)

== مؤشرات الويب الحيوية Web Vitals ==
[https://web.dev/vitals مؤشرات ويب الحيوية] هي مجموعة من المؤشرات المفيدة التي تهدف إلى تقييم تجربة المستخدم لصفحة ويب، ويمكنك قياس جميع المؤشرات التالية:

* [https://academy.hsoub.com/programming/general/%D9%85%D8%AF%D8%AE%D9%84-%D8%A5%D9%84%D9%89-%D9%85%D8%A4%D8%B4%D8%B1-%D8%B2%D9%85%D9%86-%D9%88%D8%B5%D9%88%D9%84-%D8%A3%D9%88%D9%84-%D8%A8%D8%A7%D9%8A%D8%AA-ttfb-%D9%81%D9%8A-%D9%85%D9%88%D9%82%D8%B9-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D9%88%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%AA%D8%AD%D8%B3%D9%8A%D9%86%D9%87-r1562/ زمن وصول البايت الأول Time to First Byte واختصارًا TTFB]
* [https://academy.hsoub.com/programming/general/%D9%85%D8%AF%D8%AE%D9%84-%D8%A5%D9%84%D9%89-%D9%85%D8%A4%D8%B4%D8%B1-%D8%A3%D9%88%D9%84-%D9%85%D8%AD%D8%AA%D9%88%D9%89-%D9%85%D8%B1%D8%A6%D9%8A-fcp-%D9%81%D9%8A-%D9%85%D9%88%D9%82%D8%B9-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D9%88%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%AA%D8%AD%D8%B3%D9%8A%D9%86%D9%87-r1564/ أول محتوى مرئي في نافذة العرض First Contentful Paint واختصارًا FCP]
* [https://academy.hsoub.com/programming/general/%D9%85%D8%AF%D8%AE%D9%84-%D8%A5%D9%84%D9%89-%D9%85%D8%A4%D8%B4%D8%B1-%D8%A3%D8%B6%D8%AE%D9%85-%D9%85%D8%AD%D8%AA%D9%88%D9%89-%D9%85%D8%B1%D8%A6%D9%8A-lcp-%D9%81%D9%8A-%D9%85%D9%88%D9%82%D8%B9-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D9%88%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%AA%D8%AD%D8%B3%D9%8A%D9%86%D9%87-r1561/ أضخم محتوى مرئي في نافذة العرض Largest Contentful Paint ,واختصارًا LCP]
* [https://academy.hsoub.com/programming/general/%D9%85%D8%AF%D8%AE%D9%84-%D8%A5%D9%84%D9%89-%D9%85%D8%A4%D8%B4%D8%B1-%D8%AA%D8%A3%D8%AE%D8%B1-%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D8%AC%D8%A7%D8%A8%D8%A9-%D8%A7%D9%84%D8%A3%D9%88%D9%84%D9%89-fid-%D9%88%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%AA%D8%AD%D8%B3%D9%8A%D9%86%D9%87-%D9%81%D9%8A-%D9%85%D9%88%D9%82%D8%B9%D9%83-r1565/ زمن الاستجابة لأول تفاعل مع الصفحة First Input Delay واختصارًا FID]
* [https://academy.hsoub.com/programming/general/%D9%85%D9%82%D8%AF%D9%85%D8%A9-%D9%81%D9%8A-%D9%85%D8%A4%D8%B4%D8%B1-%D8%A7%D9%86%D8%B2%D9%8A%D8%A7%D8%AD-%D8%A7%D9%84%D9%87%D9%8A%D9%83%D9%84-%D8%A7%D9%84%D8%AA%D8%B1%D8%A7%D9%83%D9%85%D9%8A-cls-%D9%88%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%AA%D8%AD%D8%B3%D9%8A%D9%86%D9%87-%D9%81%D9%8A-%D9%85%D9%88%D9%82%D8%B9%D9%83-r1563/ انزياح الهكيل التراكمي Cumulative Layout Shift واختصارًا CLS]


بإمكانك التعامل مع جميع المؤشرات السابقة من خلال العنوان <code>web-vital</code> للكائن <code>metric</code>:<syntaxhighlight lang="javascript">
export function reportWebVitals(metric) {
  if (metric.label === 'web-vital') {
    console.log(metric) // تُعرض المؤشرات التالية 
                        // ({ id, name, startTime, value, label })
                        // على الطرفية
  }
}
</syntaxhighlight>وهنالك أيضًا خيارات لمعالجة كل مؤشر على حدى:<syntaxhighlight lang="javascript">
export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'FCP':
      // FCP يعالج نتيجة
      break
    case 'LCP':
      // LCP يعالج نتيجة
      break
    case 'CLS':
      // CLS يعالج نتيجة
      break
    case 'FID':
      // FID يعالج نتيجة
      break
    case 'TTFB':
      // TTFB يعالج نتيجة
      break
    default:
      break
  }
}
</syntaxhighlight>تستخدم المكتبة [https://github.com/GoogleChrome/web-vitals web-vitals] التي يؤمنها طرف آخر لقياس هذه المؤشرات. وتعتمد توافقية المتصفح على المؤشر الذي يقيسه، لذلك عليك الاطلاع على [https://github.com/GoogleChrome/web-vitals#browser-support المتصفحات التي تدعمها] هذه الأداة.

== المؤشرات المخصصة Custom metrics ==
إضافة إلى المؤشرات الحيوية السابقة، ستجد بعض المؤشرات المخصصة التي تقيس الزمن الذي تستغرقه الصفحة لكي تُرطَّب وتصيَّر:

* <code>Next.js-hydration</code>: الفترة الزمنية التي تستغرقها صفحة بين بداية ونهاية الترطيب (بالميلي ثانية).
* <code>Next.js-route-change-to-render</code>: الفترة الزمنية التي تستغرقها صفحة ليبدأ تصييرها بعد تغيّر الوجهة (أو المسار).
* <code>Next.js-render</code>: الفترة الزمنية التي تستغرقها صفحة لينتهي تصييرها بعد تغيّر الوجهة (أو المسار).

بإمكانك التعامل مع جميع نتائج هذه المؤشرات باستخدام العنوان <code>custom</code> للكائن <code>metric</code>:<syntaxhighlight lang="javascript">
export function reportWebVitals(metric) {
  if (metric.label === 'custom') {
    console.log(metric) // تُعرض المؤشرات التالية 
                        // ({ id, name, startTime, value, label })
                        // على الطرفية
  }
}
</syntaxhighlight>وهنالك أيضًا خيار لمعالجة كل مؤشر على حدى:<syntaxhighlight lang="javascript">
export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // تعالج نتيجة الترطيب
      break
    case 'Next.js-route-change-to-render':
      // تعالج نتيجة زمن انتهاء التصيير عند تغير الوجهة
      break
    case 'Next.js-render':
      // تعالج زمن بداية التصيير عند تغير الوجهة
      break
    default:
      break
  }
}
</syntaxhighlight>تعمل هذه المؤشرات في جميع المتصفحات التي تدعم الواجهة البرمجية [https://caniuse.com/#feat=user-timing User Timing].

== إرسال البيانات إلى الأداة analytics ==
بإمكانك إرسال بيانات أي مؤشر إلى الوصلة الخاصة بالأداة analytics لقياس وتتبع الأداء الفعلي للمستخدم على موقعك من خلال دالة توصيل. إليك مثالًا:<syntaxhighlight lang="javascript">
export function reportWebVitals(metric) {
  const body = JSON.stringify(metric)
  const url = 'https://example.com/analytics'
  
  //إن كان متاحًا `navigator.sendBeacon()` استخدم 
  //`fetch()` وإلا تراجع إلى 
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
}
</syntaxhighlight>'''ملاحظة''': إن كنت تستخدم Google Analytics، فستسمح لك قيمة <code>id</code> أن تبني توزعًا يدويًا للمؤشرات لتحسب نسبًا مئوية وغيرها إن شئت.<syntaxhighlight lang="javascript">
export function reportWebVitals({ id, name, label, value }) {
// كما في المثال التالي Google Analytics إن هيأت `window.gtag` استخدم 
// https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
window.gtag('event', name, {
 event_category:
   label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
 value: Math.round(name === 'CLS' ? value * 1000 : value), // يجب أن تكون القيم صحيحة
 event_label: id, //فريد بالنسبة للحمل الحالي للصفحة id المعرف
 non_interaction: true, //bounce rate تحاشى التاثير على معدل النشاط 
})
}
</syntaxhighlight>للمزيد، انظر [https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics هذه الصفحة].

== استكشاف ما يؤثر على مؤشرات الويب الحيوية ==
عند استكشاف المشاكل المتعلقة بمؤشرات الويب الحيوية وفحصها، قد نحتاج عادةً إلى أي معلومة تفيدنا في تحديد سبب المشكلة مثلًا قد نحتاج في مؤشر انزياح الهيكل التراكمي CLS إلى معرفة أول عنصر منزاح عندما حصلت مشكلة الانزياح الهيكل أو مثلًا قد نحتاج في مؤشر أضخم محتوى مرئي LCP إلى تحديد العنصر المسؤول عن خلل هذا المؤشر فإن كان العنصر صورةٌ فسيساعدنا معرفة تفاصيله ورابط الصورة تلك إلى تحديد الصورة بالضبط والرجوع إليها وتحسينها.

تعرف عملية تحديد المساهم الأكبر في مشاكل الويب الحيوية باسم "الإرجاع" [https://github.com/GoogleChrome/web-vitals/blob/4ca38ae64b8d1e899028c692f94d4c56acfc996c/README.md#attribution attribution] أي إرجاع المشكلة إلى مسببها، وتساعدنا هذه العملية في معرفة تفاصيل أوسع وأدق عن المشكلة مثل:

* [https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEventTiming PerformanceEventTiming]
* [https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming PerformanceNavigationTiming]
* [https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming PerformanceResourceTiming]

هذه العملية معطلة افتراضيًا في Next.js ويمكنك تفعيلها لكل مؤشر من ملف next.config.js بالشكل التالي:<syntaxhighlight lang="javascript">
// next.config.js
experimental: {
  webVitalsAttribution: ['CLS', 'LCP']
}
</syntaxhighlight>القيم الصالحة لتمريرها إلى <code>webVitalsAttribution</code> هي كل مؤشرات الويب الحيوية <code>web-vitals</code> المحددة في النوع <code>[https://github.com/vercel/next.js/blob/442378d21dd56d6e769863eb8c2cb521a463a2e0/packages/next/shared/lib/utils.ts#L43 NextWebVitalsMetric]</code>.

== استخدام TypeScript ==
يمكنك استخدام النوع المدمج <code>NextWebVitalsMetric</code> في حال استخدمت [[TypeScript]]:<syntaxhighlight lang="javascript">
// pages/_app.tsx

import type { AppProps, NextWebVitalsMetric } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

export function reportWebVitals(metric: NextWebVitalsMetric) {
  console.log(metric)
}

export default MyApp
</syntaxhighlight>

== المصادر ==

* الصفحة [https://nextjs.org/docs/advanced-features/measuring-performance Measuring performance] من توثيق Next.js الرسمي.
[[تصنيف:Next.js|{{SUBPAGENAME}}]]
[[تصنيف:Next.js Advanced Features|{{SUBPAGENAME}}]]