HTML Academy · درس

pushState وreplaceState

تحديث عنوان URL في المتصفح دون إعادة تحميل الصفحة بالكامل

pushState وreplaceState درس مجاني في HTML Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في HTML Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة HTML Academy 4 دروس في المجموع.

واجهة History API

تتيح History API للصفحة تغيير عنوان URL الظاهر في شريط العناوين دون بدء عملية انتقال كاملة. وبالاقتران مع العرض من جهة العميل، تتيح هذه الواجهة إنشاء تطبيقات الصفحة الواحدة التي تبدو أصلية دون التضحية بعناوين URL القابلة للحفظ كإشارات مرجعية.

pushState

تضيف history.pushState(state, "", url) إدخالًا جديدًا إلى سجل المتصفح. يتحدث عنوان URL في شريط العناوين فورًا، ولا يُرسل أي طلب إلى الشبكة. ويمكن للمستخدم العودة إلى الإدخال السابق باستخدام زر الرجوع في المتصفح.

history.pushState({ view: "settings" }, "", "/settings");

الوسيط state

الوسيط الأول هو بيانات قابلة للتسلسل تُرفق بالإدخال. يمكنكم قراءتها لاحقًا عبر history.state أو داخل أحداث popstate. استخدموها لتمرير حالة الواجهة، مثل علامة التبويب المفتوحة وموضع التمرير، حتى تؤدي العودة إلى استعادة العرض نفسه بدقة.

وسيط title

الوسيط الثاني هو عنوان الإدخال. عمليًا، تتجاهله جميع المتصفحات الحديثة — لذا اضبط document.title = "..." مباشرةً لتغيير العنوان. مرّر سلسلة فارغة كاصطلاح متّبع؛ فلا تأثير لها.

وسيط url

الوسيط الثالث هو عنوان URL الجديد. تُحل عناوين URL النسبية بالاستناد إلى الصفحة الحالية؛ ويجب أن يكون عنوان URL الجديد من المصدر نفسه (same-origin)، وإلا فسيُطرح SecurityError. لا تجلب المتصفحات عنوان URL — إذ لا يؤدي pushState إلا إلى تحديث شريط العنوان والسجل.

replaceState

يستبدل history.replaceState(state, "", url) إدخال السجل الحالي بدلًا من إضافة إدخال جديد. استخدمه عندما تريد تحديث عنوان URL دون إنشاء خطوة جديدة للتنقل إلى الخلف، مثل تحديث سلسلة استعلام عامل تصفية.

// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);

حالات استخدام pushState

تغييرات مسارات SPA، مثل النقر على رابط تنقّل دون إعادة تحميل كاملة، وفتح نافذة مشروطة بحيث يغلقها زر الرجوع، والانتقال بين خطوات معالج إرشادي. يجب أن تكون كل حالة ذات معنى إدخالًا جديدًا في السجل، حتى يؤدي زر الرجوع الوظيفة التي يتوقعها المستخدمون.

حالات استخدام replaceState

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

تحديث العرض بعد pushState

لا يغيّر pushState سوى عنوان URL — لذلك يجب أن يحدّث الكود DOM بشكل منفصل. النمط المتّبع هو: عرض المحتوى الجديد، ثم استدعاء pushState. وينتج عن الجمع بينهما سلوك SPA.

function navigate(path) {
  renderPage(path);
  history.pushState(null, "", path);
  window.scrollTo(0, 0);
}

تحديثات العنوان والوسوم الوصفية

حدّث document.title ووسوم meta التي تحمل og:title بعد التنقّل، حتى يعكس كل من المشاركة على الشبكات الاجتماعية وعناوين ألسنة المتصفح العرض الحالي. يؤدي نسيان ذلك إلى بقاء العنوان الأصلي في المشاركات اللاحقة — وهو خلل شائع ودقيق في تطبيقات SPA.

استدعاء pushState الأول عند تحميل الصفحة

يؤدي استدعاء pushState قبل تنقّل المستخدم إلى استبدال الإدخال الأولي. لإرفاق حالة بالإدخال الأول للصفحة، استخدم replaceState بدلًا منه — فهو يضيف الحالة دون تغيير عمق السجل.

قيد أمني

يجب أن تكون عناوين URL التي يستخدمها pushState من المصدر نفسه. تؤدي محاولة استخدام pushState مع https://evil.com إلى طرح SecurityError. ويمنع ذلك الصفحات من انتحال شريط العنوان لإيهام المستخدمين بأنهم موجودون على موقع مختلف.

اختبار المعرفة

ما الذي يفعله history.replaceState ولا يفعله history.pushState؟

ملخص

يضيف pushState إدخالًا جديدًا إلى السجل دون إعادة تحميل الصفحة — وهو أساس توجيه SPA. أما replaceState فيحدّث الإدخال الحالي في موضعه لتغييرات عنوان URL الشكلية. يتطلب كلاهما عناوين URL من المصدر نفسه ويتجاهلان وسيط العنوان. حدّث DOM دائمًا بشكل منفصل، وتذكّر تحديث document.title ووسوم meta بعد التنقّل.

الأسئلة الشائعة

هل درس «pushState وreplaceState» مجاني؟

نعم — نص درس «pushState وreplaceState» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة HTML Academy، انتقل إلى CoddyKit PRO. تتضمن دورة HTML Academy 4 دروس في المجموع.

ماذا ستتعلم في «pushState وreplaceState»؟

تحديث عنوان URL في المتصفح دون إعادة تحميل الصفحة بالكامل تتمرن على HTML Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ HTML Academy؟

لا تُشترط خبرة سابقة. HTML Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «pushState وreplaceState»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس HTML Academy هذا؟

نعم. كل درس في HTML Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى HTML Academy