کلاس google.script.history (API سمت مشتری)
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
google.script.history یک API جاوا اسکریپت سمت کلاینت ناهمزمان است که می تواند با پشته سابقه مرورگر تعامل داشته باشد. این فقط در زمینه یک برنامه وب که از IFRAME استفاده می کند قابل استفاده است. این برای استفاده با نوارهای کناری و گفتگو در یک متن افزودنی یا اسکریپت کانتینری در نظر گرفته نشده است. برای اطلاعات بیشتر، راهنمای استفاده از سابقه مرورگر در برنامه‌های وب را ببینید.
مستندات دقیق
push(stateObject, params, hash)
شی وضعیت ارائه شده، پارامترهای URL و قطعه URL را روی پشته تاریخچه مرورگر فشار می دهد. شیء حالت یک شیء ساده جاوا اسکریپت است که توسط توسعه‌دهنده تعریف شده است و می‌تواند حاوی هر داده مرتبط با وضعیت فعلی برنامه باشد. این روش مشابه متد pushState() جاوا اسکریپت است.
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)
یک عملکرد برگشت به تماس را برای پاسخ به تغییرات در تاریخچه مرورگر تنظیم می کند. تابع callback باید فقط یک شی رویداد واحد را به عنوان آرگومان دریافت کند.
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 | یک تابع فراخوانی سمت کلاینت برای اجرای یک رویداد تغییر تاریخچه، با استفاده از شی رویداد به عنوان تنها آرگومان. |
شی رویداد
| فیلدها |
|---|
e.state | شیء حالت مرتبط با رویداد ظاهر شده. این شیء مشابه شیء حالتی است که در متد push() یا ()replace مربوطه استفاده می شود که حالت popped را به پشته تاریخ اضافه می کند. {"page":2, "name":"Wilbur"} |
e.location | یک شی مکان مرتبط با رویداد ظاهر شده {"hash":"", "parameter":{"name": "alice", "n": "1"}, "parameters":{"name": ["alice"], "n": ["1", "2"]}} |
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی."],[[["\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*** ** * ** ***"]]
