الفئة google.script.history (واجهة برمجة التطبيقات من جهة العميل)
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
google.script.history هي واجهة برمجة تطبيقات JavaScript غير متزامنة من جهة العميل يمكنها التفاعل.
باستخدام مكدس سجل المتصفح. لا يمكن استخدامها إلا في سياق تطبيق ويب يستخدم
IFRAME
وهو غير مخصص للاستخدام مع الأشرطة الجانبية ومربعات الحوار في أي وظيفة إضافية أو
سياق الحاوية النصية. لمزيد من المعلومات، يُرجى الاطّلاع على
دليل استخدام المتصفّح
السجلّ في تطبيقات الويب.
تضبط دالة معاودة الاتصال للاستجابة للتغييرات في سجلّ المتصفّح.
الوثائق التفصيلية
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");
المعلمات
الاسم
النوع
الوصف
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");
المعلمات
الاسم
النوع
الوصف
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...
});
المعلمات
الاسم
النوع
الوصف
function
Function
جانب العميل
لتشغيلها عند حدث تغيير السجل، باستخدام
event object كوسيطة وحيدة.
كائن الحدث
الحقول
e.state
عنصر الحالة المرتبط بالحدث الذي تم تمييزه وهذا العنصر مماثل للحالة
الذي يُستخدم في الدالة push() المقابلة أو
replace() الذي أضاف حالة انبثاق
إلى مكدس التاريخ.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003e\u003ccode\u003egoogle.script.history\u003c/code\u003e enables interaction with the browser history stack within web apps using \u003ccode\u003eIFRAME\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eIt provides methods to push, replace, and monitor browser history state, including URL parameters and fragments.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can define custom state objects to store and retrieve application-specific data associated with history events.\u003c/p\u003e\n"],["\u003cp\u003eA change handler can be set to trigger a callback function in response to history changes, allowing dynamic UI updates.\u003c/p\u003e\n"]]],[],null,["# Class google.script.history (Client-side API)\n\n`google.script.history` is an asynchronous client-side JavaScript API that can interact\nwith the browser history stack. It can only be used in the context of a web app that uses\n[`IFRAME`](/apps-script/reference/html/sandbox-mode#properties).\nIt is not intended for use with sidebars and dialogs in an add-on or\ncontainer-script context. For more information, see the\n[guide to using browser\nhistory in web apps](/apps-script/guides/web#web_apps_and_browser_history). \n\n### Methods\n\n| Method | Return type | Brief description |\n|----------------------------------------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------|\n| [push(stateObject, params, hash)](#push(Object,Object,String)) | `void` | Pushes the provided state object, URL parameters and URL fragment onto the browser history stack. |\n| [replace(stateObject, params, hash)](#replace(Object,Object,String)) | `void` | Replaces the top event on the browser history stack with the provided state object, URL parameters and URL fragment. |\n| [setChangeHandler(function)](#setChangeHandler(Function)) | `void` | Sets a callback function to respond to changes in the browser history |\n\nDetailed documentation\n----------------------\n\n### `push(stateObject, params, hash)`\n\nPushes the provided state object, URL parameters and URL fragment onto the browser history\nstack. The state object is a simple JavaScript Object that is defined by the developer and can\ncontain any data relevant to the app's current state. This method is analogous to the\n[pushState()](https://developer.mozilla.org/en-US/docs/Web/API/History_API#The_pushState()_method)\nJavaScript method. \n\n### Index.html\n\n```html\nvar now = new Date();\nvar state = {\n 'timestamp': now.getTime()\n};\nvar params = {\n 'options': \"none\"\n};\ngoogle.script.history.push(state, params, \"anchor1\");\n```\n\n#### Parameters\n\n| Name | Type | Description |\n|---------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `stateObject` | `Object` | An developer-defined object to be associated with a browser history event, and which resurfaces when the state is popped. Typically used to store application state information (such as page data) for future retrieval. |\n| `params` | `Object` | An object containing URL parameters to associate with this state. For example, `{foo: \"bar\", fiz: \"baz\"}` equates to `\"?foo=bar&fiz=baz\"`. Alternatively, arrays can be used: `{foo: [\"bar\", \"cat\"], fiz: \"baz\"}` equates to `\"?foo=bar&foo=cat&fiz=baz\"`. If null or undefined, the current URL parameters are not changed. If empty, the URL parameters are cleared. |\n| `hash` | `String` | The string URL fragment appearing after the '#' character. If null or undefined, the current URL fragment is not changed. If empty, the URL fragment is cleared. |\n\n*** ** * ** ***\n\n*** ** * ** ***\n\n### `replace(stateObject, params, hash)`\n\nReplaces the top event on the browser history stack with the provided (developer-defined) state\nobject, URL parameters and URL fragment. This is otherwise identical to\n[push()](#push(Object,Object,String)). \n\n### Index.html\n\n```html\nvar now = new Date();\nvar state = {\n 'timestamp': now.getTime()\n};\nvar params = {\n 'options': \"none\"\n};\ngoogle.script.history.replace(state, params, \"anchor1\");\n```\n\n#### Parameters\n\n| Name | Type | Description |\n|---------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `stateObject` | `Object` | An developer-defined object to be associated with a browser history event, and which resurfaces when the state is popped. Typically used to store application state information (such as page data) for future retrieval. |\n| `params` | `Object` | An object containing URL parameters to associate with this state. For example, `{foo: \"bar\", fiz: \"baz\"}` equates to `\"?foo=bar&fiz=baz\"`. Alternatively, arrays can be used: `{foo: [\"bar\", \"cat\"], fiz: \"baz\"}` equates to `\"?foo=bar&foo=cat&fiz=baz\"`. If null or undefined, the current URL parameters are not changed. If empty, the URL parameters are cleared. |\n| `hash` | `String` | The string URL fragment appearing after the '#' character. If null or undefined, the current URL fragment is not changed. If empty, the URL fragment is cleared. |\n\n*** ** * ** ***\n\n### `setChangeHandler(function)`\n\nSets a callback function to respond to changes in the browser history. The callback function\nshould take only a single [event object](#eventObject) as an argument.\n\n### Index.html\n\n```html\ngoogle.script.history.setChangeHandler(function (e) {\n console.log(e.state);\n console.log(e.location.parameters);\n console.log(e.location.hash);\n\n // Adjust web app UI to match popped state here...\n});\n```\n\n#### Parameters\n\n| Name | Type | Description |\n|------------|------------|----------------------------------------------------------------------------------------------------------------------------------|\n| `function` | `Function` | a client-side callback function to run upon a history change event, using the [event object](#eventObject) as the only argument. |\n\n#### Event object\n\n| Fields ||\n|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `e.state` | The state object associated with the popped event. This object is identical to the state object that used in the corresponding [push()](#push(Object,Object,String)) or [replace()](#replace(Object,Object,String)) method that added the popped state to the history stack. ``` {\"page\":2, \"name\":\"Wilbur\"} ``` |\n| `e.location` | A [location object](/apps-script/guides/html/reference/url#locationObject) associated with the popped event ``` {\"hash\":\"\", \"parameter\":{\"name\": \"alice\", \"n\": \"1\"}, \"parameters\":{\"name\": [\"alice\"], \"n\": [\"1\", \"2\"]}} ``` |\n\n*** ** * ** ***"]]
