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"]}} |