String.prototype.trim and Array.prototype.reduce methods
(if they are missing) for compatibility with iOS 3.x.
创建插件
Plugins can be written by adding methods as properties of
$.fn:
;(function($){$.extend($.fn,{foo:function(){// `this` refers to the current Zepto collection.// When possible, return the Zepto collection to allow chaining.returnthis.html('bar')}})})(Zepto)
Create a Zepto collection object by performing a CSS selector, wrapping DOM
nodes, or creating elements from an HTML string.
A Zepto collection is an array-like object that has chainable methods for
manipulating the DOM nodes it references. All of the methods in this documentation
are collection methods, except the ones directly on the dollar (Zepto) object,
such as $.extend.
If a context (CSS selector, DOM node or Zepto collection object) is
given, perform the CSS selector only within nodes of the context; this is
functionally the same as calling $(context).find(selector).
When an HTML string is given, use it to create DOM nodes. If an attributes map
is given via argument, apply them to all created elements. For fast single
element creation, use <div> or <div/> forms.
When a function is given, attach it as a handler for the DOMContentLoaded event.
If the page is already loaded, executes the function immediately.
$('div')//=> all DIV elements on the page$('#foo')//=> element with ID "foo"// create element:$("<p>Hello</p>")//=> the new P element// create element with attributes:$("<p />",{text:"Hello",id:"greeting",css:{color:'darkblue'}})//=> <p id=greeting style="color:darkblue">Hello</p>// execute callback when the page is ready:Zepto(function($){alert('Ready to Zepto!')})
jQuery CSS extensions are not supported. However, the optional
“selector” module provides limited support for a few of the most used
pseudo-selectors, and can be dropped in for compatibility with existing code
or plugins.
Zepto will only set the $ global to itself if it is not yet defined. This
allows you to use Zepto with legacy code that uses, for example, Prototype.js.
Just load Prototype first, and Zepto will not touch Prototype’s $ function.
Zepto will always set the Zepto global to itself.
$.camelCase
v1.0+
$.camelCase(string) ⇒ string
Turn a dasherized string into “camel case”. Doesn’t affect already camel-cased
strings.
Iterate over array elements or object key-value pairs. Returning
false from the iterator function stops the iteration.
$.each(['a','b','c'],function(index,item){console.log('item %d is: %s',index,item)})varhash={name:'zepto.js',size:'micro'}$.each(hash,function(key,value){console.log('%s: %s',key,value)})
Zepto.fn is an object that holds all of the methods that are available on
Zepto collections, such as addClass(), attr(), and
other. Adding a function to this object makes that method available on every
Zepto collection.
Here’s an example implementation of Zepto’s empty() method:
True if the object is a window object. This is useful for iframes where each one
has its own window, and where these objects fail the regular obj === window
check.
读取或设置 DOM 元素的 CSS 属性。当 value 参数不存在的时候，返回对象集合中第一个元素的 CSS 属性。当 value 参数存在时，设置对象集合中每一个元素的对应 CSS 属性。
多个属性可以通过传递一个属性名组成的数组一次性获取。多个属性可以利用对象键值对的方式进行设置。
当 value 为空(空字符串，null 或 undefined)，那个 CSS 属性将会被移出。当 value 参数为一个无单位的数字，如果该 CSS 属性需要单位，“px” 将会自动添加到该属性上。
varelem=$('h1')elem.css('background-color')// 读取属性值elem.css('background-color','#369')// 设置属性值elem.css('background-color','')// 移除属性// set multiple properties:elem.css({backgroundColor:'#8EE',fontSize:28})// read multiple properties:elem.css(['backgroundColor','fontSize'])['fontSize']
data
data(name) ⇒ value
data(name, value) ⇒ self
Read or write data-* DOM attributes. Behaves like attr, but prepends
data- to the attribute name.
When reading attribute values, the following conversions apply:
v1.0+
“true”, “false”, and “null” are converted to corresponding types;
number values are converted to actual numeric types;
JSON values are parsed, if it’s valid JSON;
everything else is returned as string.
Zepto's basic implementation of `data()` only stores strings.
To store arbitrary objects, include the optional "data" module
in your custom build of Zepto.
// autolink everything that looks like a Twitter username$('.comment p').html(function(idx,oldHtml){returnoldHtml.replace(/(^|\W)@(\w{1,15})/g,'$1@<a href="http://twitter.com/$2">$2</a>')})
index
index([element]) ⇒ number
获取一个元素的索引值（从 0 开始计数）。当 elemen 参数没有给出时，返回当前元素在兄弟节点中的位置。当 element 参数给出时，返回它在当前对象集合中的位置。如果没有找到该元素，则返回 -1。
$('li:nth-child(2)').index()//=> 1
indexOf
indexOf(element, [fromIndex]) ⇒ number
在当前对象集合中获取一个元素的索引值（从0开始计数）。如果给定 fromIndex 参数，从该位置开始往后查找，返回以 0 开始计数的索引值，如果没找到，则返回 -1。推荐优先使用 index 方法。
Filter the current collection to get a new collection of elements that don’t
match the CSS selector. If another collection is given instead of selector,
return only elements not present in it. If a function is given, return only
elements for which the function returns a falsy value. Inside the function,
the this keyword refers to the current element.
This is a Zepto-provided method that is not part of the jQuery API.
position
v1.0+
position() ⇒ object
Get the position of the first element in the collection, relative to the
offsetParent. This information is useful when absolutely
positioning an element to appear aligned with another.
Returns an object with properties: top, left.
varpos=element.position()// position a tooltip relative to the element$('#tooltip').css({position:'absolute',top:pos.top-30,left:pos.left})
prepend
prepend(content) ⇒ self
Prepend content to the DOM inside each element in the collection. The content
can be an HTML string, a DOM node or an array of nodes.
$('ul').prepend('<li>first list item</li>')
prependTo
prependTo(target) ⇒ self
Prepend elements of the current collection inside each of the target elements. This is
like prepend, only with reversed operands.
Read or set properties of DOM elements. This should be preferred over attr in
case of reading values of properties that change with user interaction over
time, such as checked and selected.
Short and lowercase names such as for, class, readonly and similar will be
mapped to actual properties such as htmlFor, className, readOnly, etc.
push
push(element, [element2, ...]) ⇒ self
Add elements to the end of the current collection.
This is a Zepto-provided method that is not part of the jQuery API.
ready
ready(function($){ ... }) ⇒ self
Attach an event handler for the “DOMContentLoaded” event that fires when the DOM
on the page is ready. It’s recommended to use the $() function instead
of this method.
reduce
reduce(function(memo, item, index, array){ ... }, [initial]) ⇒ value
Identical to Array.reduce that iterates over current collection.
This is a Zepto-provided method that is not part of the jQuery API.
remove
remove() ⇒ self
Remove elements in the current collection from their parent nodes, effectively
detaching them from the DOM.
removeAttr
removeAttr(name) ⇒ self
Remove the specified attribute from all elements in the collection.
Multiple attributes to remove can be passed as a space-separated list.
Remove the specified class name from all elements in the collection. When the
class name isn’t given, remove all class names. Multiple class names can be given in a space-separated string.
removeProp
v1.2+
removeProp(name) ⇒ self
Remove a property from each of the DOM nodes in the collection. This is done
with JavaScript’s delete operator. Note that trying to remove some built-in
DOM properties such as className or maxLength won’t have any affect, since
browsers disallow removing those properties.
replaceWith
replaceWith(content) ⇒ self
Replace each element in the collection–both its contents and the element
itself–with the new content. Content can be of any type described in
before.
scrollLeft
v1.1+
scrollLeft() ⇒ number
scrollLeft(value) ⇒ self
Gets or sets how many pixels were scrolled to the right so far on window or
scrollable element on the page.
scrollTop
v1.0+
scrollTop() ⇒ number
scrollTop(value) ⇒ self [v1.1]
Gets or sets how many pixels were scrolled down so far on window or scrollable
element on the page.
show
show() ⇒ self
Restore the default value for the “display” property of each element in the
array, effectively showing them if they were hidden with hide.
siblings
siblings([selector]) ⇒ collection
Get all sibling nodes of each element in the collection. If CSS selector is
specified, filter the results to contain only elements that match the selector.
size
size() ⇒ number
Get the number of elements in this collection.
slice
slice(start, [end]) ⇒ array
Extract the subset of this array, starting at start index. If end is
specified, extract up to but not including end index.
Get or set the text content of elements in the collection. When no content is
given, returns the text contents of all the elements in the collection, if no element exists, null will be returned. When
content is given, uses it to replace the text contents of each element in the
collection. This is similar to html, with the exception it can’t be
used for getting or setting HTML.
toggle
toggle([setting]) ⇒ self
Toggle between showing and hiding each of the elements, based on whether the
first element is visible or not. If setting is present, this method behaves
like show if setting is truthy or hide otherwise.
Toggle given class names (space-separated) in each element in the collection.
The class name is removed if present on an element; otherwise it’s added. If
setting is present, this method behaves like addClass if setting
is truthy or removeClass otherwise.
unwrap
unwrap() ⇒ self
Remove immediate parent nodes of each element in the collection and put their
children in their place. Basically, this method removes one level of ancestry
while keeping current elements in the DOM.
Get or set the value of form controls. When no value is given, return
the value of the first element. For <select multiple>, an array of values
is returend. When a value is given, set all elements to this value.
Wrap each element of the collection separately in a DOM structure. Structure can
be a single element or several nested elements, and can be passed in as a HTML
string or DOM node, or as a function that is called for each element and returns
one of the first two types.
Keep in mind that wrapping works best when operating on nodes that are part
of the DOM. When calling wrap() on a new element and then inserting the result
in the document, the element will lose the wrapping.
// wrap each button in a separate span:$('.buttons a').wrap('<span>')// wrap each code block in a div and pre:$('code').wrap('<div class=highlight><pre /></div>')// wrap all form inputs in a span with classname// corresponding to input type:$('input').wrap(function(index){return'<span class='+this.type+'field />'})//=> <span class=textfield><input type=text /></span>,// <span class=searchfield><input type=search /></span>// WARNING: will not work as expected!$('<em>broken</em>').wrap('<li>').appendTo(document.body)// do this instead:$('<em>better</em>').appendTo(document.body).wrap('<li>')
wrapAll
wrapAll(structure) ⇒ self
Wrap all elements in a single structure. Structure can be a single element or
several nested elements, and can be passed in as a HTML string or DOM node.
// wrap all buttons in a single div:$('a.button').wrapAll('<div id=buttons />')
Wrap the contents of each element separately in a structure. Structure can be
a single element or several nested elements, and can be passed in as a HTML string
or DOM node, or as a function that is called for each element and returns one of
the first two types.
// wrap the contents of each navigation link in a span:$('nav a').wrapInner('<span>')// wrap the contents of each list item in a paragraph and emphasis:$('ol li').wrapInner('<p><em /></p>')
// The following boolean flags are set to true if they apply,// if not they're either set to `false` or `undefined`.// We recommend accessing them with `!!` prefixed to coerce to a boolean.// general device type$.os.phone$.os.tablet// specific OS$.os.ios$.os.android$.os.webos$.os.blackberry$.os.bb10$.os.rimtabletos// specific device type$.os.iphone$.os.ipad$.os.ipod// [v1.1]$.os.touchpad$.os.kindle// specific browser$.browser.chrome$.browser.firefox$.browser.safari// [v1.1]$.browser.webview// (iOS) [v1.1]$.browser.silk$.browser.playbook$.browser.ie// [v1.1]// Additionally, version information is available as well.// Here's what's returned for an iPhone running iOS 6.1.!!$.os.phone// => true!!$.os.iphone// => true!!$.os.ios// => true$.os.version// => "6.1"$.browser.version// => "536.26"
事件处理
$.Event
$.Event(type, [properties]) ⇒ event
Create and initialize a DOM event of the specified type. If a properties object
is given, use it to extend the new event object. The event is configured to
bubble by default; this can be turned off by setting the bubbles property to false.
An event initialized with this function can be triggered with
trigger.
$.Event('mylib:change',{bubbles:false})
$.proxy
v1.0+
$.proxy(fn, context) ⇒ function
$.proxy(fn, context, [additionalArguments...]) ⇒ function [v1.1.4]
$.proxy(context, property) ⇒ function
$.proxy(context, property, [additionalArguments...]) ⇒ function [v1.1.4]
Get a function that ensures that the value of this in the original function
refers to the context object. In the second form, the original function is read
from the specific property of the context object.
If additional arguments are passed beyond the 2nd argument, they are applied to
every invocation of the wrapped function in front of its actual arguments.
varobj={name:'Zepto'},handler=function(){console.log("hello from + ",this.name)}// ensures that the handler will be executed in the context of `obj`:$(document).on('click',$.proxy(handler,obj))
Returns true if preventDefault() was called for this event instance. This
serves as a cross-platform alternative to the native defaultPrevented property
which is missing or unreliable in some browsers.
// trigger a custom event and check whether it was cancelledvarevent=$.Event('custom')element.trigger(event)event.isDefaultPrevented()
event.isImmediatePropagationStopped
v1.1+
event.isImmediatePropagationStopped() ⇒ boolean
Returns true if stopImmediatePropagation() was called for this event instance.
Zepto implements the native method in browsers that don’t support it (e.g. old
versions of Android).
event.isPropagationStopped
v1.1+
event.isPropagationStopped() ⇒ boolean
Returns true if stopPropagation() was called for this event instance.
Detach event handlers added with on. To detach a specific event handler,
the same function must be passed that was used for on(). Otherwise, just
calling this method with an event type will detach all handlers of that type.
When called without arguments, it detaches all event handlers registered on
current elements.
Add event handlers to the elements in collection. Multiple event types can be
passed in a space-separated string, or as an object where event types are keys
and handlers are values. If a CSS selector is given, the handler function will
only be called when an event originates from an element that matches the selector.
If the data argument is given, this value will be made available as the
event.data property during the execution of the event handler.
Event handlers are executed in the context of the element to which the handler
is attached, or the matching element in case a selector is provided. When an
event handler returns false, preventDefault() and stopPropagation() is called for the current
event, preventing the default browser action such as following links.
If false is passed as argument to this method in place of the callback
function, it’s equivalent to passing a function that returns false.
varelem=$('#content')// observe all clicks inside #content:elem.on('click',function(e){...})// observe clicks inside navigation links in #contentelem.on('click','nav a',function(e){...})// all clicks inside links in the document$(document).on('click','a',function(e){...})// disable following any navigation link on the page$(document).on('click','nav a',false)
Adds an event handler that removes itself the first time it runs, ensuring that
the handler only fires once. See .on() for the explanation of
selector and data arguments.
trigger
trigger(event, [args]) ⇒ self
Trigger the specified event on elements of the collection. Event can either be a
string type, or a full event object obtained with $.Event. If an args
array is given, it is passed as additional arguments to event handlers.
// add a handler for a custom event$(document).on('mylib:change',function(e,from,to){console.log('change on %o with data %s, %s',e.target,from,to)})// trigger the custom event$(document.body).trigger('mylib:change',['one','two'])
Zepto only supports triggering events on DOM elements.
triggerHandler
triggerHandler(event, [args]) ⇒ self
Like trigger, but triggers only event handlers on current
elements and doesn’t bubble.
Perform an Ajax request. It can be to a local resource, or cross-domain via
HTTP access control support in browsers or JSONP.
Options:
type (default: “GET”): HTTP request method (“GET”, “POST”, or other)
url (default: current URL): URL to which the request is made
data (default: none): data for the request; for GET requests it is appended
to query string of the URL. Non-string objects will get serialized with
$.param
processData (default: true): whether to automatically serialize data for
non-GET requests to string
contentType (default: “application/x-www-form-urlencoded”): the Content-Type
of the data being posted to the server (this can also be set via headers).
Pass false to skip setting the default value.
mimeType (default: none): override the MIME type of the response.
v1.1+
dataType (default: none): response type to expect from the server. One of
json, jsonp, script, xml, html, or text.
jsonp (default: “callback”): the name of the JSONP callback query parameter
jsonpCallback (default: “jsonp{N}”): the string (or a function that returns)
name of the global JSONP callback function. Set this to enable browser caching.
v1.1+
timeout (default: 0): request timeout in milliseconds, 0 for no timeout
headers: object of additional HTTP headers for the Ajax request
async (default: true): set to false to issue a synchronous (blocking) request
global (default: true): trigger global Ajax events on this request
context (default: window): context to execute callbacks in
traditional (default: false): activate traditional (shallow) serialization
of data parameters with $.param
cache (default: true): whether the browser should be allowed to cache GET responses.
Since v1.1.4, the default is false for
dataType: "script" or jsonp.
xhrFields (default: none): an object containing properties to be copied over
verbatim to the XMLHttpRequest instance.
v1.1+
If the URL contains =? or dataType is “jsonp”, the request is performed
by injecting a <script> tag instead of using XMLHttpRequest (see JSONP).
This has the limitation of contentType, dataType, headers, and async not
being supported.
Ajax callbacks
You can specify the following callback functions, which are given in order of execution:
beforeSend(xhr, settings): before the request is sent. Provides access to
the xhr object and allows changing the settings.
Return false from the function to cancel the request
success(data, status, xhr): when request succeeds
error(xhr, errorType, error): if there is an error (timeout, parse error,
or status code not in HTTP 2xx)
complete(xhr, status): after the request is complete, regardless of error
or success
Promise callback interface v1.1+
If the optional modules “callbacks” and “deferred” are loaded, the XHR object
returned from $.ajax() calls implements a promise interface for adding
callbacks by chaining:
These methods supersede the success, error, and complete callback options.
Ajax events
These events are fired during the lifecycle of an Ajax request performed with
the default setting of global: true:
ajaxStart(global): fired if no other Ajax requests are currently
active
ajaxBeforeSend (xhr, options): before sending the request; can be
cancelled
ajaxSend (xhr, options): like ajaxBeforeSend, but not cancellable
ajaxSuccess (xhr, options, data): when the response is success
ajaxError (xhr, options, error): when there was an error
ajaxComplete (xhr, options): after request has completed, regardless
of error or success
ajaxStop(global): fired if this was the last active Ajax request
By default, Ajax events are fired on the document object. However, if the
context of a request is a DOM node, the events are fired on that node and will
bubble up the DOM. The only exceptions to this are the global events ajaxStart
& ajaxStop.
$(document).on('ajaxBeforeSend',function(e,xhr,options){// This gets fired for every Ajax request performed on the page.// The xhr object and $.ajax() options are available for editing.// Return false to cancel this request.})$.ajax({type:'GET',url:'/projects',// data to be added to query string:data:{name:'Zepto.js'},// type of data we are expecting in return:dataType:'json',timeout:300,context:$('body'),success:function(data){// Supposing this JSON payload was received:// {"project": {"id": 42, "html": "<div>..." }}// append the HTML to context object.this.append(data.project.html)},error:function(xhr,type){alert('Ajax error!')}})// post a JSON payload:$.ajax({type:'POST',url:'/projects',// post payload:data:JSON.stringify({name:'Zepto.js'}),contentType:'application/json'})
Get JSON data via Ajax GET request. This is a shortcut for the $.ajax
method.
$.getJSON('/awesome.json',function(data){console.log(data)})// fetch data from another domain with JSONP$.getJSON('//example.com/awesome.json?callback=?',function(remoteData){console.log(remoteData)})
Serialize an object to a URL-encoded string representation for use in Ajax
request query strings and post data. If shallow is set, nested objects are
not serialized and nested array values won’t use square brackets on their keys.
If any of the individual value objects is a function instead of a string, the
function will get invoked and its return value will be what gets serialized.
This method accepts an array in serializeArray format, where
each item has “name” and “value” properties.
$.param({foo:{one:1,two:2}})//=> "foo[one]=1&foo[two]=2)"$.param({ids:[1,2,3]})//=> "ids[]=1&ids[]=2&ids[]=3"$.param({ids:[1,2,3]},true)//=> "ids=1&ids=2&ids=3"$.param({foo:'bar',nested:{will:'not be ignored'}})//=> "foo=bar&nested[will]=not+be+ignored"$.param({foo:'bar',nested:{will:'be ignored'}},true)//=> "foo=bar&nested=[object+Object]"$.param({id:function(){return1+2}})//=> "id=3"
Set the html contents of the current collection to the result of a GET Ajax call to the given URL. Optionally, a CSS selector can be specified in the URL, like so, to use only the HTML content matching the selector for updating the collection:
$('#some_element').load('/foo.html #bar')
If no CSS selector is given, the complete response text is used instead.
Note that any JavaScript blocks found are only executed in case no selector is given.
表单方法
serialize
serialize() ⇒ string
Serialize form values to an URL-encoded string for use in Ajax post requests.
serializeArray
serializeArray() ⇒ array
Serialize form into an array of objects with name and value properties.
Disabled form controls, buttons, and unchecked radio buttons/checkboxes are skipped.
The result doesn’t include data from file inputs.
Trigger or attach a handler for the submit event. When no function given,
trigger the “submit” event on the current form and have it perform its submit
action unless preventDefault() was called for the event.
When a function is given, this simply attaches it as a handler for the “submit”
event on current elements.
Effects
$.fx
Global settings for animations:
$.fx.off (default false in browsers that support CSS transitions): set to
true to disable all animate() transitions.
$.fx.speeds: an object with duration settings for animations:
_default (400 ms)
fast (200 ms)
slow (600 ms)
Change existing values or add new properties to affect animations that use
a string for setting duration.
complete: callback function for when the animation finishes
delay: transition delay in milliseconds
v1.1+
Zepto also supports the following CSS transform properties:
translate(X|Y|Z|3d)
rotate(X|Y|Z|3d)
scale(X|Y|Z)
matrix(3d)
perspective
skew(X|Y)
If the duration is 0 or $.fx.off is true (default in a browser that doesn’t
support CSS transitions), animations will not be executed; instead the target
values will take effect instantly. Similarly, when the target CSS properties
match the current state of the element, there will be no animation and the
complete function won’t be called.
If the first argument is a string instead of object, it is taken as a CSS
keyframe animation name.
Zepto exclusively uses CSS transitions for effects and animation. jQuery
easings are not supported. jQuery’s syntax for relative changes (=+10px) is
not supported. See the spec for a list of animatable properties.
Browser support may vary, so be sure to test in all browsers you want to support.
Touch
Touch events
The “touch” module adds the following events, which can be used with on and off:
tap — fires when the element is tapped.
singleTap and doubleTap — this pair of events can be used to detect both single and double taps on the same element (if you don’t need double tap detection, use tap instead).
longTap — fires when an element is tapped and the finger is held down for more than 750ms.
swipe, swipeLeft, swipeRight, swipeUp, swipeDown — fires when an element is swiped (optionally in the given direction)
All these events are also available via shortcut methods on any Zepto collection.
<style>.delete{display:none;}</style><ulid=items><li>List item 1 <spanclass=delete>DELETE</span></li><li>List item 2 <spanclass=delete>DELETE</span></li></ul><script>// show delete buttons on swipe$('#items li').swipe(function(){$('.delete').hide()$('.delete',this).show()})// delete row on tapping delete button$('.delete').tap(function(){$(this).parent('li').remove()})</script>
