fastclick README

The project's README from github.com/ftlabs/fastclick. As one markdown file: README.md.

FastClick

FastClick is a simple, easy-to-use library for eliminating the 300ms delay between a physical tap and the firing of a click event on mobile browsers. The aim is to make your application feel less laggy and more responsive while avoiding any interference with your current logic.

FastClick is developed by FT Labs, part of the Financial Times.

Note: As of late 2015 most mobile browsers - notably Chrome and Safari - no longer have a 300ms touch delay, so fastclick offers no benefit on newer browsers, and risks introducing bugs into your application. Consider carefully whether you really need to use it.

Explication en français.

日本語で説明。

Why does the delay exist?

According to Google:

...mobile browsers will wait approximately 300ms from the time that you tap the button to fire the click event. The reason for this is that the browser is waiting to see if you are actually performing a double tap.

Compatibility

The library has been deployed as part of the FT Web App and is tried and tested on the following mobile browsers:

When it isn't needed

FastClick doesn't attach any listeners on desktop browsers.

Chrome 32+ on Android with width=device-width in the viewport meta tag doesn't have a 300ms delay, therefore listeners aren't attached.

<meta name="viewport" content="width=device-width, initial-scale=1">

Same goes for Chrome on Android (all versions) with user-scalable=no in the viewport meta tag. But be aware that user-scalable=no also disables pinch zooming, which may be an accessibility concern.

For IE11+, you can use touch-action: manipulation; to disable double-tap-to-zoom on certain elements (like links and buttons). For IE10 use -ms-touch-action: manipulation.

Usage

Include fastclick.js in your JavaScript bundle or add it to your HTML page like this:

<script type='application/javascript' src='/path/to/fastclick.js'></script>

The script must be loaded prior to instantiating FastClick on any element of the page.

To instantiate FastClick on the body, which is the recommended method of use:

if ('addEventListener' in document) {
	document.addEventListener('DOMContentLoaded', function() {
		FastClick.attach(document.body);
	}, false);
}

Or, if you're using jQuery:

$(function() {
	FastClick.attach(document.body);
});

If you're using Browserify or another CommonJS-style module system, the FastClick.attach function will be returned when you call require('fastclick'). As a result, the easiest way to use FastClick with these loaders is as follows:

var attachFastClick = require('fastclick');
attachFastClick(document.body);

Minified

Run make to build a minified version of FastClick using the Closure Compiler REST API. The minified file is saved to build/fastclick.min.js or you can download a pre-minified version.

Note: the pre-minified version is built using our build service which exposes the FastClick object through Origami.fastclick and will have the Browserify/CommonJS API (see above).

var attachFastClick = Origami.fastclick;
attachFastClick(document.body);

AMD

FastClick has AMD (Asynchronous Module Definition) support. This allows it to be lazy-loaded with an AMD loader, such as RequireJS. Note that when using the AMD style require, the full FastClick object will be returned, not FastClick.attach

var FastClick = require('fastclick');
FastClick.attach(document.body, options);

Package managers

You can install FastClick using Component, npm or Bower.

For Ruby, there's a third-party gem called fastclick-rails. For .NET there's a NuGet package.

Advanced

Ignore certain elements with needsclick

Sometimes you need FastClick to ignore certain elements. You can do this easily by adding the needsclick class.

<a class="needsclick">Ignored by FastClick</a>

Use case 1: non-synthetic click required

Internally, FastClick uses document.createEvent to fire a synthetic click event as soon as touchend is fired by the browser. It then suppresses the additional click event created by the browser after that. In some cases, the non-synthetic click event created by the browser is required, as described in the triggering focus example.

This is where the needsclick class comes in. Add the class to any element that requires a non-synthetic click.

Use case 2: Twitter Bootstrap 2.2.2 dropdowns

Another example of when to use the needsclick class is with dropdowns in Twitter Bootstrap 2.2.2. Bootstrap add its own touchstart listener for dropdowns, so you want to tell FastClick to ignore those. If you don't, touch devices will automatically close the dropdown as soon as it is clicked, because both FastClick and Bootstrap execute the synthetic click, one opens the dropdown, the second closes it immediately after.

<a class="dropdown-toggle needsclick" data-toggle="dropdown">Dropdown</a>

Examples

FastClick is designed to cope with many different browser oddities. Here are some examples to illustrate this:

Tests

There are no automated tests. The files in tests/ are manual reduced test cases. We've had a think about how best to test these cases, but they tend to be very browser/device specific and sometimes subjective which means it's not so trivial to test.

Credits and collaboration

FastClick is maintained by Rowan Beentje, Matthew Caruana Galizia and Matthew Andrews at FT Labs. All open source code released by FT Labs is licenced under the MIT licence. We welcome comments, feedback and suggestions. Please feel free to raise an issue or pull request.

fastclick (ftlabs/fastclick)

Searching Database…

18.5K ·GitHub
Fastclick
archived
这是什么东西?一个来自 FT Labs（金融时报旗下部门）的小型开源 JavaScript 库。它消除了移动端浏览器上物理点击与 click 事件触发之间约 300 毫秒的延迟，让应用用起来不那么卡顿，响应更灵敏。
这是我往网页代码里加的东西,还是需要安装的应用?它是一个 polyfill 库：把 fastclick.js 引入你的页面或 JavaScript 打包文件里，它会在运行时修补浏览器里的点击处理。设备本身不需要安装任何东西。
我怎么把它加到我的网站上?用 npm、Bower 或 Component 安装，或者直接把 fastclick.js 加到页面里。先加载脚本，然后调用 FastClick.attach(document.body)——这是推荐的做法，可以覆盖整个页面。
需要 jQuery 或其他库才能用吗?不需要，纯 JavaScript 就够了。它提供了一个可选的 jQuery 快捷方式；对 CommonJS 用户来说 require('fastclick') 返回的是 FastClick.attach；而 RequireJS 这类 AMD 加载器拿到的则是完整的对象。
现在还值得用它吗?基本不值得了：从 2015 年底开始，Chrome 和 Safari 已经不再有 300 毫秒延迟，所以在较新的浏览器上 FastClick 起不到任何作用，反而可能引入 bug。这个代码库也已经被归档了。
它到底支持哪些移动浏览器?它在 Mobile Safari（iOS 3 及以上）、iOS 5+ 上的 Chrome、Android（ICS）上的 Chrome、Opera Mobile 11.5+、Android 2 起的 Android 自带浏览器以及 PlayBook OS 1+ 上做过测试，并且曾被用在 FT Web App 中。
移动浏览器当初为什么会有 300 毫秒的延迟?浏览器在点击之后会先等大约 300 毫秒再触发 click，以便判断用户是不是想双击缩放。FastClick 的做法是在 touchend 一发生就立刻触发一个合成的 click，跳过这段等待。
它在技术上是怎么消除延迟的?touchend 一触发，它就用 document.createEvent 构造一个合成的 click 并立即派发出去，同时拦截浏览器自己随后发出的那个 click，这样一次点击只会产生一个事件。
needsclick 这个 class 是干什么用的?把它加到你希望 FastClick 不要去碰的元素上：比如那些需要浏览器真实的 click 才能触发聚焦的输入框，或者 Twitter Bootstrap 2.2.2 的下拉菜单——不加的话，这类下拉菜单在触屏设备上会刚打开就立刻关闭。
它在桌面浏览器上会起作用吗?不会，它在桌面浏览器上不挂载任何监听器。另外，当 viewport meta 标签设置了 width=device-width 时，它会跳过 Android 上的 Chrome 32+；IE10/11 则应该改用 CSS 的 touch-action: manipulation。
What are similar projects?skrollr, better-scroll, Respond, lib-flexible, interact.js, swiper, Sortable, hammer.js
Which topics is it in?click, event, polyfill, mobile-web, touch, responsive, javascript-library, deprecated, browser, html, mobile, ios
Creator
ftlabs
Size
0.3 MB
Stars
18.5K
Updated
CommitFeb 12Releasev1.0.6Jan 26
Age
14y
Commits · 90 Days