野生大熊猫

Pjax中文文档
pjax = pushState + ajaxpjax是一个jQuery插件,使用ajax和pushState提供...
扫描右侧二维码阅读全文
03
2018/01

Pjax中文文档

pjax = pushState + ajax

pjax是一个jQuery插件,使用ajax和pushState提供一个快速浏览体验真正的永久链接页面标题,后退按钮。

pjax作品由服务器通过ajax获取HTML和替换内容 一个容器元素的加载HTML页面上。 然后更新 在浏览器中使用pushState当前URL。 这将导致更快的页面 导航,有两个原因:

  • 没有页面资源(javascript、CSS)得到可重复或中时;
  • 如果服务器配置为pjax,它只能使部分页面 内容,从而避免潜在的昂贵的完整布局呈现。

这个项目的状态

jquery-pjax是基本上没有维护在这一点上。 它可能会继续 获得重要的bug修复,但是其特性是冻结这是不太可能 它将新特性或增强。

安装

pjax取决于jQuery 1.8或更高版本。

npm

$ npm install jquery-pjax

独立的脚本

在您的web页面下载,包括jquery.pjax.js:

curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js

使用

$.fn.pjax

最简单和最常见的用法pjax看起来像这样:

$(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')

服务器端配置

理想情况下,您的服务器应该检测pjax通过观察特殊的请求X-PJAX HTTP报头,只呈现HTML替换的内容 容器元素(#pjax-container in our example) 在我们的示例中)没有剩下的 页面布局。 这里是一个例子在Ruby on Rails如何可以做到这一点:

def index
  if request.headers['X-PJAX']
    render :layout => false
  end
end

如果你想要一个更比Rails pjax查看自动的解决方案Turbolinks.

检查是否有一个pjax插件你最喜欢的服务器框架。

也看看RailsCasts # 294:玩PJAX。

参数

$.fn.pjax 函数概要:

$(document).pjax(selector, [container], options)
  1. selector 是一个字符串用于点击事件的代表团。
  2. container 选择器是一个字符串,惟一地标识pjax容器。
  3. options 是一个对象的键下面描述。
pjax 选项
键值默认描述
timeout650ajax超时强制全面刷新后以毫秒为单位
pushtrue使用pushState添加一个浏览器历史记录导航条目
replacefalse替换URL不增加浏览器历史记录条目
maxCacheLength20最大缓存大小前容器的内容
version 一个字符串或函数返回当前pjax版本
scrollTo0垂直位置后滚动导航。 为了避免滚动的位置改变,通过false.
type"GET"see [$.ajax][]
dataType"html"see [$.ajax][]
container CSS选择器元素的内容应该被取代
urllink.href一个字符串或函数,它返回ajax请求的URL
targetlink最终,relatedTarget值pjax事件
fragment CSS选择器的片段提取从ajax响应

您可以更改默认值在全球范围内通过编写的对象:

$.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]')
    var containerSelector = '#' + container.id
    $.pjax.click(event, {container: containerSelector})
  })
}

请注意使用显式的$.support.pjax警卫。 我们没有使用$.fn.pjax所以我们应该避免这种事件处理程序,除非浏览器绑定pjax会使用。

$.pjax.submit

通过pjax提交一个表单。

$(document).on('submit', 'form[data-pjax]', function(event) {
  $.pjax.submit(event, '#pjax-container')
})

$.pjax.reload

向服务器发起请求当前URL使用pjax机制和取代反应的容器。 不添加浏览器历史条目。

$.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头
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 总是火灾后ajax,不管结果
pjax:end xhr, options
事件生命周期浏览器后退/前进导航
pjax:popstate 事件direction 属性: "back"/"转发"
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()
})

高级配置

重新初始化插件/部件新页面的内容

pjax的目的是获取和插入新内容 没有 刷新页面。 然而,其他设置为jQuery插件或库 在页面加载事件(如反应DOMContentLoaded)将不接 这些变化。 因此,它通常是一个好主意来配置这些插件 重新启动更新页面内容的范围。 可以这样:

$(document).on('ready pjax:end', function(event) {
  $(event.target).initializeMyPlugin()
})

这将使$.fn.initializeMyPlugin()被称为文档级别的 正常的页面加载,在容器任何pjax导航(后水平 点击一个链接或回去后在浏览器中)。

响应类型强制重载

默认情况下,pjax将迫使一个完整的重新加载页面的如果它收到一个 来自服务器的响应:

  • 页面内容,包括<html>fragment选择不明确 配置。 Pjax假定服务器的响应没有正确 为pjax配置。 如果fragmentpjax选项,pjax将提取 基于内容的选择器。
  • 空白的页面内容。 Pjax假定服务器无法交付 适当的pjax内容。
  • HTTP响应代码是4 xx或5 xx,表明一些服务器错误。

影响浏览器的URL

如果服务器需要影响到URL后将会出现在浏览器的URL pjax导航(如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

部署部署、碰撞不断强迫客户做一个完整的版本重新加载下一个请求新布局和资产。

Last modification:January 3rd, 2018 at 07:40 pm
If you think my article is useful to you, please feel free to appreciate

2 comments

  1. 某草

    机翻差评 ̄﹃ ̄

    1. 野生大熊猫
      @某草

      哈哈哈。这是我自用的

Leave a Comment