Lớp google.script.history (API phía máy khách)
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
google.script.history
là API JavaScript phía máy khách không đồng bộ có thể tương tác
cùng với ngăn xếp nhật ký duyệt web. Chỉ có thể dùng trong ngữ cảnh của một ứng dụng web sử dụng
IFRAME
.
Tính năng này không nhằm sử dụng với thanh bên và hộp thoại trong tiện ích bổ sung hoặc
ngữ cảnh tập lệnh vùng chứa. Để biết thêm thông tin, hãy xem
hướng dẫn sử dụng trình duyệt
nhật ký hoạt động trong ứng dụng web.
Phương thức
Phương thức | Loại dữ liệu trả về | Mô tả ngắn |
push(stateObject, params, hash) |
void |
Đẩy đối tượng trạng thái, tham số URL và phân đoạn URL đã cung cấp vào nhật ký duyệt web
ngăn xếp. |
replace(stateObject, params, hash) |
void |
Thay thế sự kiện hàng đầu trong ngăn xếp nhật ký trình duyệt bằng đối tượng trạng thái đã cung cấp, URL
tham số và phân đoạn URL. |
setChangeHandler(function) |
void |
Thiết lập một hàm callback để phản hồi các thay đổi trong nhật ký duyệt web |
Tài liệu chi tiết
push(stateObject, params, hash)
Đẩy đối tượng trạng thái, tham số URL và phân đoạn URL đã cung cấp vào nhật ký duyệt web
ngăn xếp. Đối tượng trạng thái là một Đối tượng JavaScript đơn giản do nhà phát triển xác định và có thể
chứa mọi dữ liệu liên quan đến trạng thái hiện tại của ứng dụng. Phương thức này tương tự như
pushState()
JavaScript.
Index.html
var now = new Date();
var state = {
'timestamp': now.getTime()
};
var params = {
'options': "none"
};
google.script.history.push(state, params, "anchor1");
Tham số
Tên | Loại | Mô tả |
stateObject | Object | Đối tượng do nhà phát triển xác định
được liên kết với một sự kiện nhật ký duyệt web và xuất hiện lại khi trạng thái bật ra. Giá thông thường
được dùng để lưu trữ thông tin trạng thái ứng dụng (như dữ liệu trang) cho mục đích truy xuất trong tương lai. |
params | Object | Đối tượng chứa tham số URL để
liên kết với trạng thái này. Ví dụ: {foo: “bar”, fiz: “baz”} tương đương với
"?foo=bar&fiz=baz" Ngoài ra, bạn có thể sử dụng mảng:
{foo: [“bar”, “cat”], fiz: “baz”} tương đương với "?foo=bar&foo=cat&fiz=baz" .
Nếu có giá trị rỗng hoặc không xác định, các tham số URL hiện tại sẽ không thay đổi. Nếu trống, các tham số URL sẽ
đã xóa.
|
hash | String | Phân đoạn URL của chuỗi xuất hiện sau
'#' . Nếu có giá trị rỗng hoặc không xác định, mảnh URL hiện tại sẽ không thay đổi. Nếu trống,
Phân đoạn URL bị xóa.
|
replace(stateObject, params, hash)
Thay thế sự kiện trên cùng trong ngăn xếp nhật ký duyệt web bằng trạng thái đã cung cấp (do nhà phát triển xác định)
Đối tượng URL, tham số URL và phân đoạn URL. Mặt khác, quy tắc này giống với
push().
Index.html
var now = new Date();
var state = {
'timestamp': now.getTime()
};
var params = {
'options': "none"
};
google.script.history.replace(state, params, "anchor1");
Tham số
Tên | Loại | Mô tả |
stateObject | Object | Đối tượng do nhà phát triển xác định
được liên kết với một sự kiện nhật ký duyệt web và xuất hiện lại khi trạng thái bật ra. Giá thông thường
được dùng để lưu trữ thông tin trạng thái ứng dụng (như dữ liệu trang) cho mục đích truy xuất trong tương lai. |
params | Object | Đối tượng chứa tham số URL để
liên kết với trạng thái này. Ví dụ: {foo: “bar”, fiz: “baz”} tương đương với
"?foo=bar&fiz=baz" Ngoài ra, bạn có thể sử dụng mảng:
{foo: [“bar”, “cat”], fiz: “baz”} tương đương với "?foo=bar&foo=cat&fiz=baz" .
Nếu có giá trị rỗng hoặc không xác định, các tham số URL hiện tại sẽ không thay đổi. Nếu trống, các tham số URL sẽ
đã xóa.
|
hash | String | Phân đoạn URL của chuỗi xuất hiện sau
'#' . Nếu có giá trị rỗng hoặc không xác định, mảnh URL hiện tại sẽ không thay đổi. Nếu trống,
Phân đoạn URL bị xóa.
|
setChangeHandler(function)
Đặt một hàm callback để phản hồi các thay đổi trong nhật ký duyệt web. Hàm callback
chỉ nên lấy một đối tượng sự kiện duy nhất làm đối số.
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...
});
Tham số
Tên | Loại | Mô tả |
function | Function | phía máy khách
để chạy theo sự kiện thay đổi lịch sử, sử dụng hàm callback
event đối tượng làm đối số duy nhất.
|
Đối tượng sự kiện
Trường |
e.state |
Đối tượng trạng thái liên kết với sự kiện được đẩy ra. Đối tượng này giống hệt với trạng thái
đối tượng được sử dụng trong push() tương ứng hoặc
Phương thức replace() đã thêm trạng thái bật lên
vào ngăn xếp nhật ký.
{"page":2, "name":"Wilbur"}
|
e.location |
Đối tượng vị trí
liên quan đến sự kiện bị đẩy ra
{"hash":"", "parameter":{"name": "alice", "n": "1"}, "parameters":{"name": ["alice"], "n": ["1", "2"]}}
|
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[[["\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*** ** * ** ***"]]