Главная › Справочники › Справочник jQuery API › jQuery Core ›

jQuery()

Варианты использования метода jQuery():

jQuery( selector, [ context ] )

Принимает строку, содержащую селектор CSS в качестве аргумента, которая используется для определения набора элементов в дереве HTML-документа. Возвращает объект jQuery.

jQuery( selector, [ context ] )

Появилась в версии 1.0.

Аргументы:

  • selector — Строка в виде выражения селектора CSS (например, "#page p:first")
  • context — Элемент DOM, документ или jQuery, который нужно использовать в качестве контекста

jQuery( element )

Появилась в версии 1.0.

Аргументы:

  • element — Элемент DOM, который нужно преобразовать в объект jQuery.

jQuery( elementArray )

Появилась в версии 1.0.

Аргументы:

  • elementArray — Массив, содержащий набор элементов DOM, которые нужно преобразовать в объект jQuery.

jQuery( jQuery object )

Появилась в версии 1.0.

Аргументы:

  • jQuery object — Существующий объект jQuery, который нужно клонировать.

jQuery()

Появилась в версии 1.4.

Описание метода jQuery()

Вместо функций jQuery(), можно также использовать $() — это короткий вариант для удобства использования. После передачи селектора CSS в качестве первого аргумента происходит поиск по дереву DOM на элементы, соответствующие указанному селектору, и создается новый объект jQuery, который ссылается на все найденные элементы DOM:

$('div.foo');

Контекст селектора

По умолчанию селекторы обеспечивают поиск по DOM, начиная с корня документа. Однако, можно ограничить область поиска по селектору, передав второй аргумент в функцию $(). Например, внутри обработчика события click мы можем выполнить поиск только по элементам, находящимся внутри нажатого элемента:

$('div.foo').click(function() {
     $('span', this).addClass('bar');
});

Так как мы ограничиваем область поиска селектора "span" контекстом this, то только элементы span, расположенные внутри нажатого элемента получат класс "bar".

Внутри самой библиотеки контекст селектора реализуется с помощью метода .find(), таким образом вызов $('span', this) эквивалентен $(this).find('span').

Использование элементов DOM

Второй и третий варианты использования функции jQuery позволяют нам создать объект jQuery, используя один или несколько элементов DOM, которые мы уже нашли в документе каким-либо способом. Чаще всего такие варианты использования функции jQuery используются для вызова методов jQuery у элементов, которые находятся в контексте какого-либо другого метода jQuery, при этом используется ключевое слово this:

$('div.foo').click(function() {
     $(this).slideUp();
});

В этом примере при нажатии на элементы они будут скрыты с использованием анимации типа slide. Так как обработчик получает ссылку на нажатый элемент в виде обычного элемента DOM (ключевого слова this), то элемент необходимо преобразовать в объект jQuery перед использованием с ним каких-либо методов jQuery.

Когда после вызова Ajax-методов возвращаются данные в формате XML, то можно использовать функцию $() для преобразования этих данных в объект jQuery, с которым в дальнейшем очень удобно работать. После получения объекта jQuery мы можем получить доступ к отдельным элементам структуры XML с помощью метода .find() и других методов jQuery для обхода дерева DOM.

Клонирование объектов jQuery

Когда объект jQuery указан в качестве первого аргумента функции $(), то создается и в дальнейшем используется клон этого объекта. Этот клон объекта jQuery ссылается на те же элементы DOM, что и сам клонируемый объект.

Получение пустого набора

В версии jQuery 1.4 при вызове без аргументов метод jQuery() возвращает пустой набор jQuery. В предыдущих версиях jQuery возвращался набор, содержащий HTML-узел document.

Примеры использования метода jQuery( selector, [ context ] )

Задача: найти все элементы p, которые являются потомками элемента div.

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
</head>
<body>
  <p>one</p> <div><p>two</p></div> <p>three</p>
  <script>$("div > p").css("border", "1px solid gray");</script>
</body>
</html>

Результат: будет найдет только элемент p с текстом two, после чего у него будет изменена граница на серую с помощью метода css.

Задача: найти все элементы input типа radio в первой форме документа.

$("input:radio", document.forms[0]);

Задача: найти все элементы div в документе XML, возвращенным Ajax-методом.

$("div", xml.responseXML);

Задача: изменить цвет фона страницы на чёрный.

$(document.body).css( "background", "black" );

Задача: скрыть все элементы input в конкретной форме.

$(myForm.elements).hide();

jQuery( html, [ ownerDocument ] )

Создает элементы DOM на лету из строки, представляющей собой код HTML. Возвращает объект jQuery.

jQuery( html, [ ownerDocument ] )

Появилась в версии 1.0.

  • html — Строка HTML для создания объекта HTML на лету. Обратите внимание, что это HTML, а не XML.
  • ownerDocument — Документ, в котором будут созданы новые элементы.

jQuery( html, props )

Появилась в версии 1.4.

  • html — Строка, определяющая один элемент HTML (например, "<div/>" или "<div></div>").
  • props — Набор атрибутов, событий и методов, назначаемых новому элементу, в виде ассоциативного массива.

Создание новых элементов

Если строка передается в качестве первого аргумента в функцию $(), то jQuery проверяет её на соответствие HTML формату (например, если в строке есть подстрока вида <tag ... >). Если соответствия HTML не обнаруживается, то строка интерпретируется как селектор CSS. Если же строка распознана как кусок кода HTML, то jQuery пытается создать новые элементы DOM в соответствие с этой строкой, как описано в спецификации HTML. При этом функция jQuery() возвращает объект jQuery, содержащий новые элементы. Над этим объектом можно выполнять любые методы jQuery:

$('<p id="test">My <em>new</em> text</p>').appendTo('body');

Когда HTML более сложный, чем один тег без атрибутов, то создание элементов выполняется с помощью механизма браузера innerHTML. В частности jQuery создает новый элемент <div> и устанавливает его свойство innerHTML в виде строки, переданной в функцию jQuery. Когда первый параметр функции является отдельным единичным тегом, например $('<img />') или $('<a></a>'), то jQuery создает новый элемент с помощью обычной функции JavaScript createElement().

Когда в качестве аргумента передан сложный кусок кода HTML, некоторые браузеры не могут генерировать DOM, которая в точности совпадает с переданным кодом. Например, Internet Explorer до версии 8 будет конвертировать свойства href у ссылок на абсолютные URL, а Internet Explorer до версии 9 неправильно обрабатывает элементы HTML5, если не обеспечить поддержку этих элементов с помощью JavaScript.

Для обеспечения кроссплатформенной совместимости нужно передавать код HTML, соответствующий стандарту HTML. Теги, которые содержат другие элементы, должны быть закрытыми:

$('<a href="http://jquery.com"></a>');

В качестве альтернативы jQuery допускает XML-подобный синтаксис тегов (с добавлением или отсутствием пробела перед слешем):

$('<a/>');

Теги, которые не могут содержать элементы могут быть закрыты в формате HTML 4.0 или XHTML:

$('<img />');
$('<input>');

Начиная с версии jQuery 1.4, можно передавать свойства в качестве второго аргумента. Этот аргумент представляет собой ассоциативный массив свойств, такой же какой нужно передавать в метод .attr(). Кроме того, можно передать любой тип событий, также могут быть вызваны следующие методы jQuery: val, css, html, text, data, width, height или offset. Обратите внимание на то, что Internet Explorer не сможет создать элемент input и потом изменить его тип; вы должны указывать тип, используя конструкцию, например, такого вида '<input type="checkbox" />'.

Примеры использования метода jQuery( html, [ ownerDocument ] )

Задача: Динамически создать элемент div (и все его содержимое) и добавить его в элемент body.

Если рассматривать внутренний механизм функции jQuery, то сначала создается элемент, а замет его свойство innerHTML изменяется на переданную строку HTML кода.

$("<div><p>Hello</p></div>").appendTo("body")

Задача: Создать несколько элементов DOM.

$("<div/>", {
    "class": "test",
    text: "Click me!",
    click: function(){
    $(this).toggleClass("test");
}
}).appendTo("body");

$("<input>", {
    type: "text",
    val: "Test",
    focusin: function() {
    $(this).addClass("active");
},
    focusout: function() {
    $(this).removeClass("active");
}
}).appendTo("form");

jQuery( callback )

Задает функцию, которая будет выполнена после загрузки документа (DOM). Возвращает объект jQuery.

jQuery( callback )

Появилась в версии 1.0.

  • callback— The function to execute when the DOM is ready.

Эта функция ведет себя так же, как и $(document).ready(), в том смысле, что её следует использовать для выполнения внутри нее других операций jQuery, которые нужно выполнить после загрузки DOM. Хотя эта функция возвращает объект jQuery, он редко используется для выполнения каких-либо операций.

Примеры использования метода jQuery( callback )

Задача: Выполнить функцию после загрузки страницы.

$(function(){
  // Страница загружена и документ полностью доступен для манипулирования
});

Задача: Использование короткой версии $ в качестве аргумента функции для его безопасного использования в локальном пространстве, а не в глобальном.

jQuery(function($) {
  // Ваш код теперь использует безопасную переменную $ ...
});