الفئة google.script.history (واجهة برمجة التطبيقات من جهة العميل)

google.script.history هي واجهة برمجة تطبيقات غير متزامنة من جهة العميل يمكنها التفاعل مع حزمة سجلّ المتصفّح. ولا يمكن استخدامها إلا في سياق تطبيق ويب يستخدم IFRAME. ولم يُصمَّم للاستخدام مع الأشرطة الجانبية ومربّعات الحوار في سياق إضافة أو حاوية نص برمجي. للاطّلاع على مزيد من المعلومات، يمكنك الاطّلاع على دليل استخدام سجلّ المتصفّح في تطبيقات الويب.

الطُرق

الطريقة	نوع القيمة التي يتم إرجاعها	وصف قصير
push(stateObject, params, hash)	void	يدفع كائن الحالة المقدّم ومعلَمات عناوين URL وجزء عنوان URL إلى حزمة سجلّ المتصفّح.
replace(stateObject, params, hash)	void	يستبدل الحدث الرئيسي في حزمة سجلّ المتصفّح بكائن الحالة المقدّم ومعلَمات عنوان URL وجزء عنوان URL.
setChangeHandler(function)	void	تتيح هذه السياسة ضبط وظيفة معاودة الاتصال للاستجابة للتغييرات في سجلّ التصفُّح.

الوثائق التفصيلية

push(stateObject, params, hash)

يدفع كائن الحالة المقدّم ومعلَمات عناوين URL وجزء عنوان URL إلى حزمة سجلّ المتصفّح. كائن الحالة هو كائن JavaScript بسيط يحدّده المطوّر ويمكن أن يحتوي على أي بيانات ذات صلة بالحالة الحالية للتطبيق. تُشبه هذه الطريقة طريقة pushState() في JavaScript.

Index.html

var now = new Date();
var state = {
  'timestamp': now.getTime()
};
var params = {
  'options': "none"
};
google.script.history.push(state, params, "anchor1");

المَعلمات

الاسم	Type	الوصف
stateObject	Object	تمثّل هذه السمة كائنًا يحدّده المطوّر ليتم ربطه بحدث في سجلّ التصفُّح ويظهر مرة أخرى عند ظهور الحالة. يُستخدم عادةً لتخزين معلومات حالة التطبيق (مثل بيانات الصفحة) لاستردادها في المستقبل.
params	Object	كائن يحتوي على معلَمات عناوين URL لربطها بهذه الحالة. على سبيل المثال، تساوي {foo: “bar”, fiz: “baz”} السمة "?foo=bar&fiz=baz". ويمكن بدلاً من ذلك استخدام الصفائف: تساوي {foo: [“bar”, “cat”], fiz: “baz”} القيمة "?foo=bar&foo=cat&fiz=baz". وفي حال كانت فارغة أو غير محدّدة، لن يتمّ تغيير مَعلمات عناوين URL الحالية. وفي حال ترك الحقل فارغًا، سيتم محو معلَمات عناوين URL.
hash	String	جزء عنوان URL للسلسلة الذي يظهر بعد الحرف "#" وفي حال كانت فارغة أو غير محدّدة، لن يتم تغيير جزء عنوان URL الحالي. وإذا كان فارغًا، سيتم محو جزء عنوان URL.

---

---

replace(stateObject, params, hash)

يستبدل الحدث الرئيسي في حزمة سجلّ المتصفّح بكائن الحالة (من تحديد المطوّر) ومعلَمات عناوين URL وجزء عنوان URL. وهذا الحقل يتطابق مع push().

Index.html

var now = new Date();
var state = {
  'timestamp': now.getTime()
};
var params = {
  'options': "none"
};
google.script.history.replace(state, params, "anchor1");

المَعلمات

الاسم	Type	الوصف
stateObject	Object	تمثّل هذه السمة كائنًا يحدّده المطوّر ليتم ربطه بحدث في سجلّ التصفُّح ويظهر مرة أخرى عند ظهور الحالة. يُستخدم عادةً لتخزين معلومات حالة التطبيق (مثل بيانات الصفحة) لاستردادها في المستقبل.
params	Object	كائن يحتوي على معلَمات عناوين URL لربطها بهذه الحالة. على سبيل المثال، تساوي {foo: “bar”, fiz: “baz”} السمة "?foo=bar&fiz=baz". ويمكن بدلاً من ذلك استخدام الصفائف: تساوي {foo: [“bar”, “cat”], fiz: “baz”} القيمة "?foo=bar&foo=cat&fiz=baz". وفي حال كانت فارغة أو غير محدّدة، لن يتمّ تغيير مَعلمات عناوين URL الحالية. وفي حال ترك الحقل فارغًا، سيتم محو معلَمات عناوين URL.
hash	String	جزء عنوان URL للسلسلة الذي يظهر بعد الحرف "#" وفي حال كانت فارغة أو غير محدّدة، لن يتم تغيير جزء عنوان URL الحالي. وإذا كان فارغًا، سيتم محو جزء عنوان URL.

---

setChangeHandler(function)

لضبط وظيفة معاودة الاتصال للاستجابة للتغييرات في سجلّ التصفُّح. يجب أن تستخدم دالة الاستدعاء كائن حدث واحدًا فقط كوسيطة.

Index.html

google.script.history.setChangeHandler(function (e) {
  console.log(e.state);
  console.log(e.location.parameters);
  console.log(e.location.hash);

  // Adjust web app UI to match popped state here...
});

المَعلمات

الاسم	Type	الوصف
function	Function	دالة استدعاء من جهة العميل لتشغيلها عند حدوث تغيير في السجلّ، باستخدام كائن الحدث كوسيطة الوحيدة.

كائن الحدث

الحقول
e.state	كائن الحالة المرتبط بالحدث المنبثق. يتطابق هذا الكائن مع كائن الحالة المستخدَم في طريقة push() أو replace() المقابلة التي أضافت الحالة المنبثقة إلى حِزم السجلّ. {"page":2, "name":"Wilbur"}
e.location	كائن موقع جغرافي مرتبط بالحدث البارز {"hash":"", "parameter":{"name": "alice", "n": "1"}, "parameters":{"name": ["alice"], "n": ["1", "2"]}}

---