语言: 英文中文

DOM7 - 自定义的DOM库

Framework7 不需要任何第三方的库,包括DOM操作。她有自己的 DOM7 - 一个集成了大部分常用DOM操作的高性能库。你不需要学习任何新的东西,因为她的用法和大名鼎鼎的jQuery几乎是一样的,包括大部分常用的方法和jquery风格的链式调用。

现在有一个全局的Dom7对象,最好把DOM7存储到一个局部变量中,为了防止和其他库冲突,我们推荐使用 $$ 来代替 $。

//Export DOM7 to local variable to make it easy accessable
var $$ = Dom7;

用法示例

$$('.something').on('click', function (e) {
    $$(this).addClass('hello').attr('title', 'world').insertAfter('.something-else');
});

可用的方法

下面这些方法几乎都和 jQuery/Zepto 是一样的:

$$(window).trigger('resize');
Classes
.addClass(className) 给元素增加class
//Add "intro" class to all paragraphs
$$('p').addClass('intro');
.removeClass(className) 删除指定的class
//Add "big" class from all links with "big" class
$$('a.big').removeClass('big');
.hasClass(className) 元素上是否有指定的class:
<p class="intro">Lorem ipsum...</p>
$$('p').hasClass('intro'); //-> true
.toggleClass(className) 有则删除,无则添加:
<!-- Before -->
<h1 class="small">This is first title</h1>
<h2>This is subtitle</h2>                
$$('h1, h2').toggleClass('small');
<!-- After -->
<h1>This is first title</h1>
<h2 class="small">This is subtitle</h2>                
属性
.prop(propName) 获取一个属性值:
var isChecked = $$('input').prop('checked');
.prop(propName, propValue) 设置一个属性值:
//Make all checkboxes checked
$$('input[type="checkbox"]').prop('checked', true);
.prop(propertiesObject) 设置多个属性值:
$$('input').prop({
  checked: false,
  disabled: true
})                
.attr(attrName) 获取一个属性值:
<a href="http://google.com">Google</a>
var link = $$('a').attr('href'); //-> http://google.com
.attr(attrName, attrValue) 设置一个属性值:
//Set all links to google
$$('a').attr('href', 'http://google.com');
.attr(attributesObject) 设置多个属性值:
$$('a').attr({
  id: 'new-id',
  title: 'Link to Google',
  href: 'http://google.com'
}) 
.removeAttr(attrName) 删除属性值:
//Remove "src" attribute from all images
$$('img').removeAttr('src');
.val() 获取选中的元素中的第一个元素的当前值
<input id="myInput" type="text" value="Lorem ipsum"/>
var inputVal = $$('#myInput').val(); //-> 'Lorem ipsum'
.val(newValue) 给选中的元素的每一个都设置指定的值
$$('input#myInput').val('New value here');
数据存储
.data(key, value) 在选中的元素上存储任意数据
$$('a').data('user', {
    id: '123',
    name: 'John',
    email: 'john@doe.com'
});  
.data(key) 如果只有一个参数,则读取指定的值,如果有两个参数 data(key, value) 则是设置值,也可以通过 HTML5 data-* 属性来设置。
var user = $$('a').data('user'); 
//-> {id: '123', name: 'John', email: 'john@doe.com'}

or

<p data-id="123">Lorem ipsum...</p>
var id = $$('p').data('id'); //-> 123
.removeData(key) Remove specified data
$$('a').removeData('user')
Data Set
.dataset() Returns element's data set (set of data- attributes) as plain Object
<div id="my-div" data-loop="true" data-animate-pages="false" data-index="0" data-hello="world">
    ...
</div>
var dataset = $$('#my-div').dataset();
/* 
dataset will contain plain object with camelCase keys and with formatted boolean and number types:
{
    loop: true,
    animatePages: false,
    index: 0,
    hello: 'world'
}
*/
CSS transform, transitions
.transform(CSSTransformString) 添加带前缀的transform 样式:
$$('a').transform('rotate(90deg)')
.transition(transitionDuration) 设置css transition-duration 属性
$$('p').transition(300)
事件
.on(eventName, handler, useCapture) 在选中的元素上绑定事件
$$('a').on('click', function (e) { 
  console.log('clicked'); 
});
$$('input[type="text"]').on('keyup keydown change', function (e) { 
  console.log('input value changed'); 
});
.on(eventName, delegatedTarget, handler, useCapture) 通过代理绑定事件
$$(document).on('click', 'a', function (e) { 
  console.log('link clicked'); 
});
.once(eventName, handler, useCapture) Add event handler function to one or more events to the selected elements that will be executed only once
$$('a').once('click', function (e) { 
  console.log('clicked'); 
});
$$('input[type="text"]').once('keyup keydown change', function (e) { 
  console.log('input value changed'); 
});
.once(eventName, delegatedTarget, handler, useCapture) Live/delegated event handler that will be executed only once
$$(document).once('click', 'a', function (e) { 
  console.log('link clicked'); 
});
.off(eventName, handler, useCapture) 删除事件绑定
function clickHandler(){
    console.log('clicked');
}
// Add event listener
$$('a').on('click', clickHandler);
// Remove event listener
$$('a').off('click', clickHandler);                  
.off(eventName, delegatedTarget, handler, useCapture) 删除通过代理绑定的事件
function clickHandler(){
    console.log('clicked');
}
// Add event listener
$$(document).on('click', 'a', clickHandler);
// Remove event listener
$$(document).off('click', 'a', clickHandler);
.trigger(eventName, eventData) 触发选中元素上的事件,指定所有的事件回调函数
.transitionEnd(callback, permanent) 在选中的元素上增加 transitionEnd 事件回调
$$('a').transitionEnd(function(){ /* do something */ })
.animationEnd(callback) 在选中的元素上增加 animationEnd 事件回调
$$('a').animationEnd(function(){ /* do something */ })
Styles
.width() 获取当前选中元素中的第一个元素的当前计算出来的宽度
var boxWidth = $$('div#box').width();
.outerWidth([includeMargin]) 获取当前选中元素中的第一个元素的当前计算出来的宽度,包括 padding ,border 和 margin(如果 includeMargin 设置为 true)
var outerWidth = $$('div#box').outerWidth(true);
.height() 获取当前选中玄素中的第一个元素的当前计算出来的高度
var boxHeight = $$('div#box').height();
.outerHeight([includeMargin]) 获取当前选中元素中的第一个元素的当前计算出来的高度,包括 padding ,border 和 margin(如果 includeMargin 设置为 true)
var outerHeight = $$('div#box').outerHeight(true);
.offset() 获取当前选中元素的第一个元素相对 document 的位置偏移
var coords = $$('.content').offset(); //-> {top: 100, left: 200}
var top = coords.top; //-> 100
var left = coords.left; //-> 200
.hide() 对选中的元素设置 "display: none"
//hide all paragraphs
$$('p').hide();
.show() 对选中的元素设置 "display: block"
//show all paragraphs
$$('p').show();
.css(property) 获取选中元素中第一个元素的CSS属性值
$$('.content').css('left'); //-> 200px
.css(property, value) 设置全部选中元素中的CSS属性值
$$('.content').css('left', '100px');
.css(propertiesObject) 设置全部选中元素中的多个CSS属性值
$$('a').css({
    left: '100px',
    top: '200px',
    color: 'red',
    width: '300px',
    marginLeft: '17px',
    'padding-right': '20px'
});
Scroll
.scrollTop() 获取选中元素的 scrollTop 值
.scrollTop(position, duration, callback) 在指定时间(duration)内滚动到指定位置(position)。如果时间(duration没有定义),则立刻滚动到指定位置。如果你指定了回调函数,那么他会在滚动完成后执行。
.scrollLeft() 获取选中元素的 scrollLeft 值
.scrollLeft(position, duration, callback) 在指定的时间(duration 毫秒)内滚动到指定的位置(scrollLeft)。如果没有指定时间则立刻滚动到指定位置。如果你指定了回调函数,那么他会在动画完成后执行。
.scrollTo(left, top, duration, callback) 在指定的时间(duration 毫秒)内滚动到指定的位置(scrollLeft, scrollTop)。如果没有指定时间则立刻滚动到指定位置。如果你指定了回调函数,那么他会在动画完成后执行。
Dom 操作
.add(elements) Create a new Dom7 collection with elements added to the set of matched elements:
var links = $$('a');
var divs = $$('div');
links.add('p').addClass('blue');
links.add(divs).addClass('red');
.each(callback) 遍历集合,对其中每一个元素执行回调。
.html() 获得选中的第一个元素的HTML内容
.html(newInnerHTML) 给全部选中元素设置HTML内容
.text() 获得选中的第一个元素的文本内容
.text(newTextContent) 给全部选中元素设置文本内容
.is(CSSSelector) 选中的元素是否符合指定的CSS选择器
.is(HTMLElement) 选中的元素是否是给定的 DOM 元素或者 Dom7 集合
.index() 当前选中的第一个元素在他的所有兄弟节点中的排序
.eq(index) 返回当前选中的元素中的指定序号的元素
.append(HTMLString) 在当前选中元素的每一个后面插入指定内容
.append(HTMLElement) 在当前选中元素的每一个后面插入指定元素
.appendTo(HTMLElement) Insert content/elements, to the end of element specified in parameter
.prepend(newHTML) 在当前选中元素的每一个前面插入指定内容
.prepend(HTMLElement) 在当前选中元素的每一个前面插入指定元素
.prependTo(HTMLElement) Insert content/elements, to the beginning of element specified in parameter
.insertBefore(target) 把当前选中的每一个元素插入到指定的目标之前。目标(target)应该是一个 CSS 选择器或者 HTML 元素 或者 Dom7集合
.insertAfter(target) 把当前选中的每一个元素插入到指定的目标之后。目标(target)应该是一个 CSS 选择器或者 HTML 元素 或者 Dom7集合
.next([selector]) 获得当前选中的每一个元素的下一个直接兄弟元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些兄弟元素。
.nextAll([selector]) 获得当前选中的每一个元素之后的全部兄弟元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些兄弟元素。
.prev([selector]) 获得当前选中的每一个元素的上一个直接兄弟元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些兄弟元素。
.prevAll([selector]) 获得当前选中的每一个元素之前的全部兄弟元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些兄弟元素。
.parent([selector]) 获取选中的每一个元素的父元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些父元素。
.parents([selector]) 获取选中的每一个元素的祖先元素。如果提供了一个选择器(selector),那么会用这个选择器来过滤这些祖先元素。
.find(selector) 在选中的每一个元素的后代中查找指定的元素。
.children(selector) 在选中的每一个元素的直接孩子中查找指定的元素。
.filter(callback) Filter collection of elements
var redLinks = $$('a').filter(function(index, el) {
    return $$(this).hasClass('red');
})                  
.remove() 从DOM中删除选中的元素
快捷方式
.click() Trigger "click" event on collection
.click(handler) Add "click" event handler to collection
.blur() Trigger "blur" event on collection
.blur(handler) Add "blur" event handler to collection
.focus() Trigger "focus" event on collection
.focus(handler) Add "focus" event handler to collection
.focusin() Trigger "focusin" event on collection
.focusin(handler) Add "focusin" event handler to collection
.focusout() Trigger "focusout" event on collection
.focusout(handler) Add "focusout" event handler to collection
.keyup() Trigger "keyup" event on collection
.keyup(handler) Add "keyup" event handler to collection
.keydown() Trigger "keydown" event on collection
.keydown(handler) Add "keydown" event handler to collection
.keypress() Trigger "keypress" event on collection
.keypress(handler) Add "keypress" event handler to collection
.submit() Trigger "submit" event on collection
.submit(handler) Add "submit" event handler to collection
.change() Trigger "change" event on collection
.change(handler) Add "change" event handler to collection
.mousedown() Trigger "mousedown" event on collection
.mousedown(handler) Add "mousedown" event handler to collection
.mousemove() Trigger "mousemove" event on collection
.mousemove(handler) Add "mousemove" event handler to collection
.mouseup() Trigger "mouseup" event on collection
.mouseup(handler) Add "mouseup" event handler to collection
.mouseenter() Trigger "mouseenter" event on collection
.mouseenter(handler) Add "mouseenter" event handler to collection
.mouseleave() Trigger "mouseleave" event on collection
.mouseleave(handler) Add "mouseleave" event handler to collection
.mouseout() Trigger "mouseout" event on collection
.mouseout(handler) Add "mouseout" event handler to collection
.mouseover() Trigger "mouseover" event on collection
.mouseover(handler) Add "mouseover" event handler to collection
.touchstart() Trigger "touchstart" event on collection
.touchstart(handler) Add "touchstart" event handler to collection
.touchend() Trigger "touchend" event on collection
.touchend(handler) Add "touchend" event handler to collection
.touchmove() Trigger "touchmove" event on collection
.touchmove(handler) Add "touchmove" event handler to collection
.resize(handler) Add "resize" event handler to collection
.scroll(handler) Add "scroll" event handler to collection

Utilities

Dom7.each

A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties

Dom7.each(object/array, callback) - iterate through object or array

  • object/array - object or array - to iterate over. Required.
  • callback - function - callback function that will be executed on every object property, or on every array element. Required.
var fruits = ['Apple', 'Orange', 'Pineapple', 'Bannana'];
$$.each(fruits, function (index, value) {
    alert(index + ': ' + element); 
});          
 
//This produces 4 alerts:
0: Apple
1: Orange
2: Pineapple
3: Bannana
var person = {
    firstName: 'John',
    lastName: 'Doe',
    age: 25,
};
$$.each(person, function (key, value) {
    alert(key + ': ' + value);
});
 
//This produces 3 alerts:
firstName: John
lastName: Doe
age: 25          

Dom7.parseUrlQuery

Dom7.parseUrlQuery(url) - parse url query get parameters

  • url - string - url with GET parameters. Required.

Method returns object with query parameters

var query = $$.parseUrlQuery('http://google.com/?id=5&foo=bar');
console.log(query); //-> {id: 5, foo: 'bar'}

Dom7.isArray

Dom7.isArray(obj) - Determine whether the argument is an array

  • obj - object - Object to test whether or not it is an array

returns a Boolean indicating whether the object is a JavaScript array

var fruits = ['Apple', 'Orange'];
console.log($$.isArray(fruits)); //-> true

Dom7.unique

Dom7.unique(array) - Remove duplicates in passed array

  • obj - array - Array to remove duplicates

returns a new unique array

var fruits = ['Apple', 'Orange', 'Apple'];
console.log($$.unique(fruits)); //-> ['Apple', 'Orange'];

Dom7.serializeObject

Dom7.serializeObject(object) - Create a serialized representation of a plain object suitable for use in a URL query string

  • object - object - Object to serialize

returns a new unique array

var params = {foo: 'bar', id: 5};
console.log($$.serializeObject(params)); //-> 'foo=bar&id=5'

Dom7.toCamelCase

Dom7.toCamelCase(string) - Convert hypens-case string to camelCase string

  • string - string - hypens-case string

returns a new camelCase string

var hypensCaseString = 'hello-my-world';
var camelCaseString = $$.toCamelCase(hypensCaseString);
console.log(camelCaseString); //helloMyWorld

Dom7.dataset

Dom7.dataset(el) - Get element's data set (set of data- attributes) as plain Object

  • el - HTMLElement or string (with CSS selector) - element with data- attributes to get dataset from

returns a new plain object with dataset

<div id="my-div" data-loop="true" data-animate-pages="false" data-index="0" data-hello="world">
    ...
</div>
var dataset = $$.dataset('#my-div');
/* 
dataset will create plain object with camelCase keys and with formatted boolean and number types:
{
    loop: true,
    animatePages: false,
    index: 0,
    hello: 'world'
}
*/          

Dom7.requestAnimationFrame

Dom7.requestAnimationFrame(callback) - Cross-browser implementation on requestAnimationFrame

  • callback - function - A parameter specifying a function to call when it's time to update your animation for the next repaint

returns animation request id, that uniquely identifies the entry in the callback list

var animId;
function anim() {
  var left = parseInt($$('#anim').css('left'), 10) + 1;
  $$('#anim').css({left: left + 'px'})
  animId = $.requestAnimationFrame(anim);
}
animId = $.requestAnimationFrame(anim);

Dom7.cancelAnimationFrame

Dom7.cancelAnimationFrame(requestID) - Cancels an animation frame request

  • requestID - number - The ID value returned by the call to $$.requestAnimationFrame() that requested the callback
$.cancelAnimationFrame(animId);

Ajax

$$.ajax(parameters) - Load data from the server

  • parameters - object - Request parameters

returns plain XHR object

Let's look at the list of available parameters

Parameter Type Default Description
async boolean true If you need synchronous requests, set this option to false
method string 'GET' Request method (e.g. "POST", "GET", "PUT")
cache boolean true If set to false, it will force requested pages not to be cached by the browser. Setting cache to false will only work correctly with HEAD and GET requests. It works by appending "_nocache={timestamp}" to the GET parameters
contentType string 'application/x-www-form-urlencoded' Content type. Also could be 'multipart/form-data' and 'text/plain'. For cross-domain requests, setting the content type to anything other than application/x-www-form-urlencoded, multipart/form-data, or text/plain will trigger the browser to send a preflight OPTIONS request to the server
crossDomain boolean undefined If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. When true additional "X-Requested-With: XMLHttpRequest" header will be added to request
data Object or String or Array Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See processData option to prevent this automatic processing. For POST requests could be FormData type
processData boolean true By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false
dataType string 'text' The type of data that you're expecting back from the server. Could be 'text' or 'json'
headers object An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport
xhrFields object An object of fieldName-fieldValue pairs to set on the native XHR object
username string A username to be used with XMLHttpRequest in response to an HTTP access authentication request
password string A password to be used with XMLHttpRequest in response to an HTTP access authentication request
timeout number 0 Set a timeout (in milliseconds) for the request
Callbacks
beforeSend function (xhr) A pre-request callback function that can be used to modify the XHR object before it is sent. Use this to set custom headers, etc
error function (xhr, status) A function to be called if the request fails
success function (data, status, xhr) A function to be called if the request succeeds
complete function (xhr, status) A function to be called when the request finishes (after success and error callbacks are executed)
statusCode object An object of numeric HTTP codes and functions to be called when the response has the corresponding code. For example, the following will alert when the response status is a 404:
$$.ajax({
  url: 'somepage.html',
  statusCode: {
    404: function (xhr) {
      alert('page not found');
    }
  }
})                  

Ajax Events

Each Ajax request produces global Ajax events on document, so you can always intercept and handle them:

Event Target Description
ajaxStart document A pre-request event that can be used to modify the XHR object before it is sent. Use this to set custom headers
ajaxError document Event to be triggered if the request fails
ajaxSuccess document Event to be triggered if the request succeeds
ajaxComplete document Event to be triggered when the request finishes (after success and error events are executed)

For example:

$$(document).on('ajaxComplete', function (e) {
  var xhr = e.detail.xhr;
  console.log('request performed');
});

Shorthand Methods

Dom7.get

$$.get(url, data, success) - Load data from the server using a HTTP GET request

  • url - string - Request url
  • data - object - A plain object or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional

returns plain XHR object

$$.get('blog-post.php', {foo:'bar', id:5}, function (data) {
  $$('.articles').html(data);
  console.log('Load was performed');
});

Dom7.post

$$.post(url, data, success) - Load data from the server using a HTTP POST request

  • url - string - Request url
  • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional

returns plain XHR object

$$.post('auth.php', {username:'foo', password: 'bar'}, function (data) {
  $$('.login').html(data);
  console.log('Load was performed');
});

Dom7.getJSON

$$.getJSON(url, data, success) - Load JSON-encoded data from the server using a GET HTTP request

  • url - string - Request url
  • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional

returns plain XHR object

$$.getJSON('items.json', function (data) {
  console.log(data);
});

Original Request Parameters

Each of Ajax methods returns plain XHR object, which is also available in callbacks. This default XHR object extended with the following properties:

Properties
xhr.requestParameters Object with passed XHR request parameters
xhr.requestUrl String with request URL