README

新闻

2013年6月22日：v1.8Beta 2 发布。修复了问题和未压缩的捆绑文件。
2013年5月31日：v1.8Beta 1 发布。修复了问题。
2013年2月14日：v1.8Alpha 4 发布。修复了问题。
2013年2月5日：v1.8Alpha 3 发布。测试更新。
2013年1月21日：v1.8Alpha 2 发布。纠正了状态变化行为。
2013年1月19日：v1.8Alpha 1 发布。开始对旧 balupton 的问题进行分类。

历史

请参阅 HISTORY.md 文件以获取功能、更改、解决的问题和错误的详细列表

参与

如果有问题无法正常工作或者有浏览器特定的错误，请创建一个问题。我会尽快修复它。如果你有一个不错的解决方案，请发送给我你的 Pull requests！我还会审查 balupton 存储库中的旧问题并尝试解决它们。

目标

尽可能遵循 HTML5 历史API
为所有HTML5浏览器提供跨兼容的体验（它们都对HTML5历史API实现得略有不同，导致不同的行为和有时出现错误 - History.js 确保在整个HTML5浏览器中的体验是预期的/相同的/优秀的）
为所有HTML4浏览器提供向后兼容的体验，使用hash回退（包括对HTML5历史API的 data、title、pushState 和 replaceState 的持续支持），并且可以选择移除HTML4支持，如果它不适合你的应用程序
为HTML4状态到HTML5状态提供向前兼容的体验（因此如果通过HTML5浏览器访问hash回退URL，它将自然转换为它的非哈希URL等价物）
通过适配器为尽可能多的JavaScript框架提供支持；特别是 Dojo、ExtJS、jQuery、MooTools、Right.js 和 Zepto。

快速安装

通过Ajaxify脚本

要使用HTML5历史API、History.js和jQuery将整个网站ajax化，您只需要Ajaxify脚本。就这么简单。

通过Ajaxify扩展

如果您无法访问您的服务器，或者只想先尝试Ajaxify脚本，您可以安装History.js It! Google Chrome扩展，通过Ajaxify在选定的网站上尝试History.js，而无需在您的服务器上实际安装History.js/Ajaxify。

通过Ruby On Rails Gem

如果您正在使用Rails，那么尝试History.js的最简单方法就是使用Wiselinks Gem。Wiselinks集成到Rails应用程序中，并允许您使用三行代码开始使用History.js。

直接安装

直接使用History.js工作

(function(window,undefined){

	// Bind to StateChange Event
	History.Adapter.bind(window,'statechange',function(){ // Note: We are using statechange instead of popstate
		var State = History.getState(); // Note: We are using History.getState() instead of event.state
	});

	// Change our States
	History.pushState({state:1}, "State 1", "?state=1"); // logs {state:1}, "State 1", "?state=1"
	History.pushState({state:2}, "State 2", "?state=2"); // logs {state:2}, "State 2", "?state=2"
	History.replaceState({state:3}, "State 3", "?state=3"); // logs {state:3}, "State 3", "?state=3"
	History.pushState(null, null, "?state=4"); // logs {}, '', "?state=4"
	History.back(); // logs {state:3}, "State 3", "?state=3"
	History.back(); // logs {state:1}, "State 1", "?state=1"
	History.back(); // logs {}, "Home Page", "?"
	History.go(2); // logs {state:3}, "State 3", "?state=3"

})(window);

上述操作在HTML5浏览器中会是什么样子？

注意：这些URL在HTML4浏览器和搜索引擎中也同样有效。因此，无需使用Google “推荐”的hashbang（#!）片段标识符。

它们在HTML4浏览器中会是什么样子？

注意1：这些URL在HTML5浏览器中也有效——我们使用replaceState将HTML4状态转换为HTML5等价状态，这样用户甚至都不会注意到 :-)

注意2：这些URL将在IE6中自动进行URL编码，以防止某些浏览器特定的错误。

注意3：对HTML4浏览器的支持（此hash回退）是可选的 ——为什么根据我应用程序的使用案例，支持HTML4浏览器可能是好是坏

HTML4状态中使用的SUID是什么意思？

SUID（状态唯一标识符）在我们使用状态中的title和/或data时使用。添加SUID允许我们将特定的状态与数据和标题相关联，同时尽可能保持URL简单（不用担心，所有这些都经过测试，工作良好，而且比我所说的要聪明得多）。
如果您没有使用title或data，则我们甚至不包括SUID（因为它根本不需要）——如上所述的状态4所示 :-)
我们还缩小了URL，以确保使用最小的URL。例如，我们将调整http://www.mysite.com/#http://www.mysite.com/projects/History.js以自动变为http://www.mysite.com/#/projects/History.js。（再次经过测试，工作良好，并且更聪明）。
它与域名、子域名、子目录等一起工作——无论你把它放在哪里。它是智能的。
Safari 5也将向URL附加SUID，这是完全透明的，但只是一个可见的副作用。这是修复Safari 5中一个错误所必需的。

有一个可工作的演示吗？

当然有，下载并使用您的浏览器导航到演示目录 :-)
如果您想要的不仅仅是最终用户演示，请打开测试目录并在您的浏览器和编辑器中打开它——它将震撼您的世界，并显示History.js支持的所有广泛的使用案例。

下载与安装

下载History.js并将其上传到您的Web服务器。下载链接：tar.gz或zip

包含History.js

对于Dojo v1.8+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/dojo.history.js"></script>

对于ExtJs v1.8+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/extjs.history.js"></script>

对于jQuery v1.3+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/jquery.history.js"></script>

对于Mootools v1.3+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/mootools.history.js"></script>

对于Right.js v2.2+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/right.history.js"></script>

对于Zepto v0.5+

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/zepto.history.js"></script>

对于其他所有内容

 <script src="http://www.yourwebsite.com/history.js/scripts/bundled/html4+html5/native.history.js"></script>

注意：如果您只想支持HTML5浏览器，而不是HTML4浏览器（因此没有hash回退支持），那么只需将URL中的/html4+html5/部分更改为仅/html5/。请参阅为什么根据我应用程序的使用案例，支持HTML4浏览器可能是好是坏

获取更新

对于提交RSS/Atom更新
- 您可以通过GitHub提交Atom订阅源进行订阅
对于GitHub新闻源更新
- 您可以在 History.js 的右上角点击“观看”按钮，访问其 GitHub 项目页面

获取支持

History.js 由像您这样的人维护。如果您发现一个错误，请将其报告给 GitHub 问题跟踪器。如果您修复了一个错误，请提交一个拉取请求并将您的分支添加到网络维基页面。
如果您需要付费支持和培训，或者有工作机会，请参阅网络维基页面。如果您有资格使用 History.js，请确保将该页面的详细信息也添加进去。
如果您的公司在其项目中使用 History.js，并且希望看到其成长和繁荣（更好的文档、错误修复、升级、维护等），并且希望成为企业赞助商，那么请通过 sponsor@bevry.me 发送电子邮件
如果您想为 History.js 获取免费支持，请在 Stackoverflow 上发布您的问题，并确保在提问时使用 history.js 标签。
如果您创建了一个使用 History.js 的网站，或者知道一个这样的网站，请确保将其添加到展示维基页面。
如果您非常喜欢这个项目，并想给它点赞或喜欢，请确保在推特上提及它，并点击其右上角的项目页面上的“观看”按钮。
对于其他任何问题，请参阅 History.js GitHub 维基网站。

谢谢！每一份帮助都真的会带来变化！

浏览器：已测试且在以下浏览器中工作

HTML5 浏览器

Firefox 4+
Chrome 8+
Opera 11.5+
Safari 5.0+
Safari iOS 4.3+

HTML4 浏览器

IE 6, 7, 8, 9, (10)
Firefox 3
Opera 10, 11.0
Safari 4
Safari iOS 4.2, 4.1, 4.0, 3.2

暴露的 API

函数

状态

History.pushState(data,title,url)
向浏览器推送一个新状态；data 可以是 null 或对象，title 可以是 null 或字符串，url 必须是字符串
History.replaceState(data,title,url)
用新状态替换浏览器中的现有状态；data 可以是 null 或对象，title 可以是 null 或字符串，url 必须是字符串
History.getState()
获取浏览器的当前状态，返回一个包含 data、title 和 url 的对象
History.getStateByIndex
通过索引获取状态
History.getCurrentIndex
获取当前索引
History.getHash()
获取浏览器的当前哈希值

适配器

History.Adapter.bind(element,event,callback)
一个框架无关的事件绑定器，您可以使用此功能或您框架的本地事件绑定器。
History.Adapter.trigger(element,event)
一个框架无关的事件触发器，您可以使用此功能或您框架的本地事件触发器。
History.Adapter.onDomLoad(callback)
一个框架无关的 onDomLoad 绑定器，您可以使用此功能或您框架的本地 onDomLoad 绑定器。

History.back()
在历史记录中后退一次（相当于按浏览器的后退按钮）
History.forward()
通过历史记录前进一次（与点击浏览器的后退按钮相同）
History.go(X)
如果X是负数，则通过历史记录后退X次，如果X是正数，则通过历史记录前进X次

调试

History.log(...)
将消息记录到控制台、日志元素，如果这两个都不存在，则回退到alert
History.debug(...)
与History.log相同，但只有当History.options.debug === true时才会运行

选项

History.options.hashChangeInterval
在hashchange检查之前的时间间隔应该是多长
History.options.safariPollInterval
在safari轮询检查之前的时间间隔应该是多长
History.options.doubleCheckInterval
在我们执行双重检查之前的时间间隔应该是多长
History.options.disableSuid
强制History不附加suid
History.options.storeInterval
在store调用之间我们应该等待多长时间
History.options.busyDelay
在繁忙事件之间我们应该等待多长时间
History.options.debug
如果为真，将启用调试消息记录
History.options.initialTitle
初始状态下的标题是什么
History.options.html4Mode
如果为真，将强制使用HTML4模式（哈希标签）
History.options.delayInit
想要覆盖默认选项并手动调用init。

事件

window.onstatechange
当页面状态改变时触发（不包括hash变化）
window.onanchorchange
当页面锚点改变时触发（不包括状态hash）

已知问题

在压力负载下，Opera 11无法创建历史记录条目（事件触发完美，只是历史事件失败）- 我们对此无能为力
Mercury iOS无法应用URL更改（哈希和HTML5历史API状态）- 我们对此无能为力

兼容性说明

History.js 解决了以下浏览器问题
- HTML5 浏览器
  - Chrome 8在某些情况下，在返回初始状态时可能不包含正确状态数据
  - Safari 5、Safari iOS 4和Firefox 3和4在页面加载带有hash时不会触发onhashchange事件
  - Safari 5和Safari iOS 4在hash更改时不会触发onpopstate事件，而其他浏览器则会触发
  - Safari 5和Safari iOS 4在用replaceState调用/ 错误报告替换hash后，无法返回到正确的状态
  - Safari 5和Safari iOS 4有时在繁忙条件下无法应用状态更改/ 错误报告
  - Google Chrome 8、9、10和Firefox 4在RC之前将始终在页面加载后触发onpopstate / 更改建议
  - Safari iOS 4.0、4.1、4.2具有工作的HTML5历史API - 尽管浏览器的实际后退按钮不工作，因此我们将它们视为HTML4浏览器
  - 所有HTML5浏览器实际上都没有使用pushState和replaceState调用中的title参数
- HTML4 浏览器
  - 旧浏览器如MSIE 6、7和Firefox 2没有onhashchange事件
  - MSIE 6和7有时即使被要求也不应用hash（需要第二次调用apply函数）
  - 非Opera HTML4浏览器有时在hash未urlencoded时不会应用hash
- 所有浏览器
  - 一旦离开网站然后返回（包括页面刷新），状态数据和标题都不会持久化
  - 状态标题永远不会应用到document.title
通过丢弃替换的状态来在HTML4浏览器中模拟ReplaceState功能，因此当访问丢弃的状态时，会使用适当的History.back() / History.forward()调用跳过它
数据持久化和同步工作原理如下：每秒左右，状态的全局唯一标识符（SUIDs）和URL将在存储和本地会话之间同步。当一个新会话打开一个熟悉的状态（通过SUID或URL）并且它在本地上找不到时，它将尝试加载带有该信息的最后已知存储状态。
URL将被尽可能多地去除转义，例如，URL ?key=a%20b%252c 将变成 ?key=a b c。这是为了确保浏览器URL编码的一致性。
更改页面哈希值会导致 onpopstate 事件触发（这是预期的/标准功能）。为了确保HTML5和HTML4浏览器之间的正确兼容性，已创建了以下事件：
- window.onstatechange：这个事件与 onpopstate 事件相同，但它不会为传统锚点触发。
- window.onanchorchange：这个事件与 onhashchange 事件相同，但它不会为状态触发。

许可协议

有关支持，请参阅获取支持部分。

ingenious / history.js

维护者

详细信息