簡介
pjax是一個jQuery插件,使用ajax和pushState技術提供快速的瀏覽體驗與真正的永久鏈接、網頁標題、以及瀏覽器的後退前進按鈕操作。
pjax通過抓取HTML從您的服務器通過Ajax和更換容器頁面上的HTML內容會與Ajax。然後更新無需重新加載你的網頁的佈局或任何資源使用pushstate瀏覽器的當前URL(JS,CSS),提供了一個快速的外觀,全頁面加載。但它確實就是Ajax和pushstate。
概述
pjax不是全自動的。您需要設置和指定一個包含在您的頁面上的元素,當您瀏覽您的網站時將被替換。
可以參考下面的HTML代碼結構和標籤:
<!DOCTYPE html>
<html>
<head>
<!-- styles, scripts, etc -->
</head>
<body>
<h1>My Site</h1>
<div class="container" id="pjax-container"> Go to <a href="/page/2">next page</a>. </div>
</body>
</html>
我們要pjax抓取URL/page/2然後替換#pjax-container不管它什麼回來。沒有風格或腳本將被加載,甚至<h1>可以保持不變 – 我們只是想改變#pjax-container元素。
我們會告訴pjax監聽一個標籤和使用#pjax-container作爲目標容器:
$(document).pjax('a', '#pjax-container')
現在在pjax兼容瀏覽器,點擊 “next page” 網頁的內容容器#pjax-container中的內容將被/page/2內容替換。
魔法!差不多你還需要配置你的服務器來尋找pjax請求併發送回pjax具體內容。
pjax的ajax請求會發送一個X-PJAX文件頭,因此,在這個例子中(在大多數情況下)我們希望將頁面的內容返回,而不需要任何與該頭文件的任何請求的佈局。
這是它可能看起來像在Rails上:
def index if request.headers['X-PJAX'] render :layout => false end end
安裝插件
通過bower安裝
$ bower install jquery-pjax
或者,添加jquery-pjax到你的bower.json文件中。
"dependencies": { "jquery-pjax": "latest" }
standalone
pjax可以直接下載到你的應用程序的公共目錄,請確保在此之前你已經加載jQuery。
curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js
注意:不要盜鏈原始腳本的URL,Github不是一個CDN。
依賴關係
需要 jQuery 1.8.x 或者更高版本。
兼容性
pjax 只能工作在高級版本的瀏覽器中,點擊這裏查看瀏覽器對history.pushStateAPI 的兼容情況。 當API不支持pjax進入備用模式:$.fn.pjax的調用將無法運行,並且$.pjax將硬盤加載給定的網址。
用於調試目的,你可以故意甚至瀏覽器是否支持禁用pjaxpushState。只需要調用$.pjax.disable()。看看pjax實際上是支持pushState,調用$.support.pjax。
使用方法
$.fn.pjax
讓我們以最基本的方式來談一談如何使用jQuery.pjax.js:
$(document).pjax('a', '#pjax-container')
這將使所有的鏈接pjax和指定的容器例如:#pjax-container.
如果你把一個現存的網站,你可能不想讓pjax無處不在。而不是使用一個全球性的選擇像A的註釋與pjaxable鏈接data-pjax,使用'a[data-pjax]'到你的選擇器中。
或者試試這個選擇器匹配任何<a data-pjax href=>鏈接插入<div data-pjax>容器。
$(document).pjax('[data-pjax] a, a[data-pjax]', '#pjax-container')
參數
內容提要$.fn.pjax函數是:
$(document).pjax(selector, [container], options)
-
selector是一個字符串,比如要點擊的文本 event delegation.
-
container是一個字符串,選擇唯一標識pjax容器。
-
options下面所描述的一個對象。
pjax 可選參數
參數 | 默認值 | 描述 |
---|---|---|
timeout | 650 | Ajax超時毫秒之後完全刷新是被迫的 |
push | true | 使用 pushState 在導航中添加瀏覽器歷史記錄 |
replace | false | 更換網址不添加瀏覽器歷史記錄 |
maxCacheLength | 20 | 大緩存大小爲以前的容器內容 |
version | 一個字符串或函數返回當前pjax版 | |
scrollTo | 0 | 垂直位置以滾動導航。爲了避免改變滾動位置,通過設置爲false. |
type | "GET" | 網頁請求的方式,詳見 $.ajax |
dataType | "html" | 返回的數據類型,詳見 $.ajax |
container | CSS選擇器的元素,其中的內容應及時更換 | |
url | link.href | 字符串或函數返回的URL ajax請求 |
target | link | 最終relatedTarget的值,通過 pjax events |
fragment | CSS選擇器的碎片從Ajax響應提取 |
您可以通過寫全局更改默認設置$.pjax.defaults對象:
$.pjax.defaults.timeout = 1200
$.pjax.click
這是由$.fn.pjax本身較低水平的功能。它可以讓你獲得更多的控制在pjax事件處理。
本例使用當前點擊上下文來設置一個父級作爲容器:
if ($.support.pjax) { $(document).on('click', 'a[data-pjax]', function(event) { var container = $(this).closest('[data-pjax-container]') $.pjax.click(event, { container: container }) }) }
注意:使用隱形的$.support.pjax保證,我們沒有使用$.fn.pjax因此,我們應該避免結合此事件處理程序,除非瀏覽器實際上是要使用pjax。
$.pjax.submit
通過pjax提交表單。
$(document).on('submit', 'form[data-pjax]', function(event) { $.pjax.submit(event, '#pjax-container') })
$.pjax.reload
啓動一個應用pjax機制服務器當前的URL請求和響應替換容器。不添加瀏覽器歷史條目。
$.pjax.reload('#pjax-container', options)
$.pjax
手動調用pjax。主要用於當你想在一個處理程序,並不是來自於點擊開始pjax請求。如果你可以得到一個點擊event,容器$.pjax.click(event)代替。
function applyFilters() { var url = urlForFilters() $.pjax({url: url, container: '#pjax-container'}) }
事件方法
所有pjax事件除了pjax:click和pjax:clicked從pjax容器,不被點擊的鏈接被解僱。
事件 | 取消 | 參數 | 注意 |
---|---|---|---|
在下面的一個pjaxed鏈接事件生命週期 | |||
pjax:click | ✔︎ | options | 阻止一個鏈接的默認事件,防止阻止pjax事件 |
pjax:beforeSend | ✔︎ | xhr, options | 參見 XHR headers |
pjax:start | xhr, options | ||
pjax:send | xhr, options | ||
pjax:clicked | options | pjax後,已經得到了從點擊一個鏈接開始 | |
pjax:beforeReplace | contents, options | 在內容被替換前,HTML從服務器加載的內容 | |
pjax:success | data, status, xhr, options | 在內容被替換後,HTML 內容從服務器加載 | |
pjax:timeout | ✔︎ | xhr, options | 在選項options.timeout;之後除非取消,否則將很難刷新 |
pjax:error | ✔︎ | xhr, textStatus, error, options | 一個ajax錯誤,將執行原始的網頁刷新,直到網頁加載被取消 |
pjax:complete | xhr, textStatus, options | 總是在pjax執行完成以後調用,不論運行的結果 | |
pjax:end | xhr, options | ||
瀏覽器的後退/前進導航事件生命週期 | |||
pjax:popstate | 事件direction屬性:”back”/”forward” | ||
pjax:start | null, options | 更換內容前 | |
pjax:beforeReplace | contents, options | 就在從緩存替換HTML內容 | |
pjax:end | null, options | 更換內容後 |
pjax:send和pjax:complete如果你正在執行一個加載項,則是一個很好的事件使用。他們只會如果一個實際的XHR請求觸發,如果內容是從緩存中加載:
$(document).on('pjax:send', function() { $('#loading').show() }) $(document).on('pjax:complete', function() { $('#loading').hide() })
取消的一個例子pjax:timeout事件是如果微調正在顯示禁用回退超時行爲:
$(document).on('pjax:timeout', function(event) { // Prevent default timeout redirection behavior event.preventDefault() })
服務器端
服務器配置將在語言和框架之間變化。下面的示例演示如何配置Rails。
def index if request.headers['X-PJAX'] render :layout => false end end
一個X-PJAX請求頭文件 header 設置爲區分正常XHR請求一個pjax請求。在這種情況下,如果請求是pjax,我們跳過佈局HTML只是使容器內的內容。
點擊這裏選擇一個合適的 pjax plugin 爲您最喜愛的服務器框架。
迫使重新加載響應類型
默認情況下,pjax 將迫使頁的全部重新加載,如果它接收到來自服務器下列反應之一:
-
網頁內容引入<html>當fragment選擇沒有明確的配置。Pjax假定服務器的響應沒有被正確配置爲pjax。假如fragmentpjax選項,則pjax只會解壓縮到插入基於該選擇器的DOM的內容。
-
頁面內容是空白的。Pjax assumes that the server is unable to deliver proper pjax contents.
-
HTTP服務器返回 4xx 或 5xx代碼,說明一些服務器錯誤。
影響瀏覽器的網址
如果服務器需要影響,這將出現在pjax導航後瀏覽器的URL的URL(如HTTP重定向工作正常請求),它可以查看X-PJAX-URL頭文件:
def index request.headers['X-PJAX-URL'] = "http://example.com/hello" end
佈局重新加載
佈局可以被強迫做硬重裝時,資產或HTML的變化。
首先設置你的頭在初始佈局版採用了自定義的元標記。
<meta http-equiv="x-pjax-version" content="v123">
然後從服務器端,設置X-PJAX-Version頭文件爲下面的樣子:
if request.headers['X-PJAX'] response.headers['X-PJAX-Version'] = "v123" end
部署一個部署,將該版本常數凸到迫使客戶機做一個完整的重新加載下一個請求獲得新的佈局和資產。