chrome.history · Chrome 擴展開發文檔

# chrome.history chorme.history 模塊被用于和瀏覽器所訪問的頁面記錄交互。你可以添加、刪除、查詢瀏覽器的歷史記錄。如果您想覆寫歷史頁面，請查看 [Override替代頁](override.html). ## Manifest 您必須在擴展Manifest文件中定義"history"許可，以便使用history API. 如下所示： ``` { "name": "My extension", ... **"permissions": [ "history" ]**, ... } ``` ## 過渡類型 History API用一種過渡類型來描述瀏覽器是如何訪問的特定的URL。例如：如果URL是在用戶訪問頁面時，點擊鏈接跳轉訪問的，此時的過渡類型為 "link"。如下的列表詳細定義了各種過渡類型。. | 過渡類型 | 描述 | | --- | --- | | "link" | 用戶通過點擊頁面中的鏈接，跳轉至本URL | | "typed" | 用戶通過地址欄輸入網址，來訪問本URL。這種類型也適用于顯式的導航動作。與之相反，你可以參閱[generated](#tt_generated)，它適用于用戶沒看到（不知道）網址URL的情況。 | | "auto_bookmark" | 用戶通過界面的推薦到達本URL。例如，通過點擊菜單項打開的頁面。 | | "auto_subframe" | 子框架導航。這種類型是指那些非頂層框架自動加載的內容。例如，如果一個頁面由許多包含廣告的子框架構成，那些廣告鏈就擁有這種過渡類型。用戶可能沒有意識到頁面中的這些內容是個單獨的框架，所以他們也可能根本沒有在意這些URL（請查閱 [manual_subframe](#tt_manual_subframe))。 | | "manual_subframe" | 此種類型是為用戶顯式請求的子框架導航以及在前進/后退列表中的生成導航入口的子框架導航所設置。由于用戶更關心所請求框架被加載的效果，因此顯式請求的框架可能會比自動載入的框架更為重要。 | | "generated" | 用戶通過在地址欄輸入，而選擇一個不像網址的入口到達的URL頁面。例如，匹配結果中可能包含Google搜索結果頁的URL, 但是它可能以"Google 搜索"的形式展現。這類導航和 [typed](#tt_typed) 導航是有差異的，因為用戶沒有輸入或者看到最終的URL。請參閱 [keyword](#tt_keyword)。 | | "start_page" | 頁面是在命令行中被指定（打開），或者其本身就是起始頁。 | | "form_submit" | 用戶提交的表單。請注意，某些情況，諸如表單運用腳本來提交，不屬于此種類型。 | | "reload" | 用戶通過點擊刷新按鈕或者在地址欄輸入回車鍵來刷新頁面屬于此種類型。會話重置，重開標簽頁都屬于此種類型。 | | "keyword" | URL通過可替代的關鍵字，而不是默認的搜索引擎產生。請查閱[keyword_generated](#tt_keyword_generated) 。 | | "keyword_generated" | 相應由關鍵字生成的訪問。請查閱 [keyword](#tt_keyword)。 | ## 示例請查看 [history 樣例目錄](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/history/) 和 [history API 測試目錄](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/test/data/extensions/api_test/history/) 中如何使用 API 的例子。如果想獲取源代碼中的樣例及幫助，請查看 [樣例](samples.html)。 ## API reference: chrome.history ### Properties <a></a> #### getLastError chrome.extensionlastError ### Methods #### addUrl void chrome.history.addUrl(, object `details`) Undocumented. 在當前歷史記錄中添加一條過渡類型為"link"的URL。 #### Parameters `details`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 要添加的URL。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function The callback _parameter_ should specify a function that looks like this: If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function(Type param1, Type param2) {...}; ``` This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### deleteAll void chrome.history.deleteAll(, function `callback`) Undocumented. 刪除歷史記錄中的所有條目。 #### Parameters `callback`_( optional enumerated Type array of function )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function 回調函數的_參數_應當如下定義： If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function() {...}; ``` This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### deleteRange void chrome.history.deleteRange(, object `range`, function `callback`) Undocumented. 刪除特定日期范圍內的所有歷史記錄條目。頁面本身只會在所有訪問均在所設定日期的范圍內才會被刪除。 #### Parameters `range`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `startTime`_( optional enumerated Type array of number )_ Undocumented. 條目添加起始時間，以紀元開始的毫秒數表示。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `endTime`_( optional enumerated Type array of number )_ Undocumented. 條目添加終止時間，以紀元開始的毫秒數表示。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated Type array of function )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function 回調函數的_參數_應當如下定義： If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function() {...}; ``` This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### deleteUrl void chrome.history.deleteUrl(, object `details`) Undocumented. 刪除指定URL 的所有歷史記錄。 #### Parameters `details`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 要刪除的URL。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function The callback _parameter_ should specify a function that looks like this: If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function(Type param1, Type param2) {...}; ``` This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### getVisits void chrome.history.getVisits(, object `details`, function `callback`) Undocumented. 獲取訪問特定URL的所有信息。 #### Parameters `details`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 需要獲取訪問信息的URL。URL 必須與歷史記錄搜索的返回值格式一致。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated Type array of function )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function 回調函數的_參數_應當如下定義： If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function(array of VisitItem results) {...}; ``` `results`_( optional enumerated Type array of [VisitItem](history.html#type-VisitItem) array of paramType paramType )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### search void chrome.history.search(, object `query`, function `callback`) Undocumented. 搜索歷史中，匹配條件的最后一次訪問的頁面。 #### Parameters `query`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `text`_( optional enumerated Type array of string )_ Undocumented. 歷史服務的文字查詢。若想獲取所有頁面的信息，把此參數設置為空。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `startTime`_( optional enumerated Type array of number )_ Undocumented. 限制結果訪問日期至此日期之后, 以紀元開始的毫秒數表示。. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `endTime`_( optional enumerated Type array of number )_ Undocumented. 限制結果訪問日期至此日期以前, 以紀元開始的毫秒數表示。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `maxResults`_( optional enumerated Type array of integer )_ Undocumented. 所獲取結果的最大數目。默認值為100。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated Type array of function )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### Returns #### Callback function 回調函數的_參數_應當如下定義： If you specify the _callback_ parameter, it should specify a function that looks like this: ``` function(array of HistoryItem results) {...}; ``` `results`_( optional enumerated Type array of [HistoryItem](history.html#type-HistoryItem) array of paramType paramType )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. ### Events #### onVisitRemoved chrome.history.onVisitRemoved.addListener(function(object removed) {...}); Undocumented. 當一條或著多條URL從歷史服務中刪除，此事件觸發。當所有訪問被移除后，此條URL從來歷史記錄中被移除。 #### Parameters `removed`_( optional enumerated Type array of object )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `allHistory`_( optional enumerated Type array of boolean )_ Undocumented. 如需刪除所有歷史記錄，則設置成 True。如果設置成true, 所有url 為空。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `urls`_( optional enumerated Type array of Type array of string paramType )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### onVisited chrome.history.onVisited.addListener(function(HistoryItem result) {...}); Undocumented. 當URL 被訪問時，此事件被觸發。并提供相應URL的HistoryItem數據。 #### Parameters `result`_( optional enumerated [HistoryItem](history.html#type-HistoryItem) array of paramType )_ Undocumented. Description of this parameter from the json schema. This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. ### Types #### HistoryItem `paramName`_( optional enumerated Type array of object )_ Undocumented. 封裝歷史查詢結果的對象。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `id`_( optional enumerated Type array of string )_ Undocumented. 條目的唯一標識符。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 用戶所訪問的URL。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `title`_( optional enumerated Type array of string )_ Undocumented. 歷史頁面的標題。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `lastVisitTime`_( optional enumerated Type array of number )_ Undocumented. 頁面被載入的最后時間, 以紀元開始的毫秒數表示。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `visitCount`_( optional enumerated Type array of integer )_ Undocumented. 用戶訪問此頁面的次數。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `typedCount`_( optional enumerated Type array of integer )_ Undocumented. 用戶通過地址欄輸入訪問目的頁面的次數。 #### VisitItem `paramName`_( optional enumerated Type array of object )_ Undocumented. 封裝URL訪問的對象。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `id`_( optional enumerated Type array of string )_ Undocumented. 條目的唯一標識符。 `visitId`_( optional enumerated Type array of string )_ Undocumented. 訪問的唯一標識符。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `visitTime`_( optional enumerated Type array of number )_ Undocumented. 訪問的時間，以紀元開始的毫秒數表示。 `referringVisitId`_( optional enumerated Type array of string )_ Undocumented. 訪問來源的 visit_id 。 This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `transition`_( optional enumerated Type array of string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", "keyword_generated"] )_ Undocumented. 訪問來源的[過渡類型](history.html#transition_types)。