Bibliothèque d'utilitaires jq

mdui intègre une bibliothèque utilitaire JavaScript légère, offrant une API et un style d'appel en chaîne similaires à jQuery, mais avec un poids six fois inférieur.

Vous pouvez importer cette fonction utilitaire selon vos besoins :

import { $ } from 'mdui/jq.js';

Cœur

$()

Cette fonction a plusieurs usages :

Passez un sélecteur CSS en paramètre pour obtenir un objet JQ contenant les éléments correspondants.

$('.box');

Passez un élément DOM, un tableau quelconque, une NodeList ou un objet JQ pour obtenir un objet JQ contenant les éléments spécifiés.

$(document);

Passez une chaîne HTML pour obtenir un objet JQ contenant les éléments DOM créés à partir de ce HTML.

$(`<div id="wrapper">
  <span id="inner"></span>
</div>`);

Passez une fonction. Cette fonction est appelée lorsque le DOM est chargé.

$(function () {
  console.log('DOM chargé');
});

Extension

$.extend()

Si un seul objet est passé, ses propriétés sont fusionnées dans l'objet $, ajoutant ainsi de nouvelles fonctionnalités dans l'espace de noms $.

$.extend({
  customFunc: function () {},
});

// On peut alors appeler la fonction personnalisée ainsi
$.customFunc();

Si deux objets ou plus sont passés, les propriétés de tous les objets sont ajoutées au premier objet, et l'objet fusionné est retourné. Les propriétés ayant la valeur undefined ne sont pas fusionnées.

const object = $.extend({ key1: val1 }, { key2: val2 }, { key3: val3 });

// Le premier objet et la valeur retournée sont désormais { key1: val1, key2: val2, key3: val3 }

$.fn.extend()

Étend les méthodes sur la chaîne de prototypes de $.

$.fn.extend({
  customFunc: function () {},
});

// On peut alors utiliser la méthode étendue ainsi
$(document).customFunc();

URL

$.param()

Sérialise un tableau ou un objet en une chaîne de requête URL.

$.param({ width: 1680, height: 1050 });
// width=1680&height=1050

$.param({ foo: { one: 1, two: 2 } });
// foo[one]=1&foo[two]=2

$.param({ ids: [1, 2, 3] });
// ids[]=1&ids[]=2&ids[]=3

Si le paramètre est un tableau, son format doit correspondre à celui retourné par .serializeArray().

$.param([
  { name: 'name', value: 'mdui' },
  { name: 'password', value: '123456' },
]);
// name=mdui&password=123456

Opérations sur les tableaux et objets

$.each()

Parcourt un tableau ou un objet. Retourne le premier paramètre, c'est-à-dire le tableau ou l'objet parcouru.

Le premier paramètre de la fonction de rappel est l'indice du tableau ou la clé de l'objet, le second est la valeur correspondante.

Dans la fonction de rappel, this pointe vers la valeur. Si la fonction de rappel retourne false, le parcours s'arrête.

// Parcours d'un tableau
$.each(['a', 'b', 'c'], function (index, value) {
  console.log(index + ':' + value);
});

// Résultat :
// 0:a
// 1:b
// 2:c

// Parcours d'un objet
$.each({ name: 'mdui', lang: 'zh' }, function (key, value) {
  console.log(key + ':' + value);
});

// Résultat
// name:mdui
// lang:zh

$.merge()

Ajoute les éléments du second tableau au premier et retourne le tableau fusionné.

const first = ['a', 'b', 'c'];
const second = ['c', 'd', 'e'];
const result = $.merge(first, second);

console.log(first); // ['a', 'b', 'c', 'c', 'd', 'e']
console.log(result); // ['a', 'b', 'c', 'c', 'd', 'e']

$.unique()

Supprime les doublons d'un tableau.

const result = $.unique([1, 2, 12, 3, 2, 1, 2, 1, 1, 1, 1]);
console.log(result); // [1, 2, 12, 3]

$.map()

Parcourt un tableau ou un objet et retourne un nouveau tableau composé des valeurs retournées par la fonction de rappel.

Le premier paramètre de la fonction de rappel est la valeur, le second est l'indice ou la clé.

La fonction peut retourner n'importe quelle valeur. Si elle retourne un tableau, ce tableau est aplati. Si elle retourne null ou undefined, la valeur est ignorée. Dans la fonction, this pointe vers l'objet window.

// Parcours d'un tableau
const result = $.map(['a', 'b', 'c'], function (value, index) {
  return index + value;
});
console.log(result); // ['0a', '1b', '2c']

// Si la fonction retourne un tableau, il est aplati
const result = $.map([1, 2, 3], function (value, index) {
  return [value, value + 1];
});
console.log(result); // [1, 2, 2, 3, 3, 4]

// Parcours d'un objet
const result = $.map(
  { name: 'mdui', password: '123456' },
  function (value, key) {
    return key + ':' + value;
  },
);
console.log(result); // ['name:mdui', 'password:123456']

$.contains()

Vérifie si un nœud contient un autre nœud. Retourne true si le parent contient l'enfant, sinon false.

$.contains(document, document.body); // true
$.contains(document.body, document); // false

Vérification des types de données

.is()

Vérifie si au moins un élément de la collection correspond au paramètre. Retourne true si c'est le cas, sinon false.

Le paramètre peut être un sélecteur CSS, un élément DOM, un tableau d'éléments DOM, un objet JQ, ou une fonction de rappel.

Si le paramètre est une fonction de rappel, ses paramètres sont l'indice et l'élément courant. Dans la fonction, this pointe vers l'élément courant. Si la fonction retourne true, l'élément correspond ; si elle retourne false, il ne correspond pas.

$('.box').is('.box'); // true
$('.box').is('.boxss'); // false
$('.box').is($('.box')[0]); // true

// Vérification via la fonction de rappel
$(document).is(function (index, element) {
  return element === document;
});
// true

Accès aux objets

.length

Retourne le nombre d'éléments dans la collection actuelle.

$('body').length; // 1

.each()

Parcourt la collection actuelle et exécute une fonction pour chaque élément. Si la fonction retourne false, le parcours s'arrête.

Le premier paramètre de la fonction est l'indice, le second est l'élément courant. Dans la fonction, this pointe vers l'élément courant.

$('img').each(function (index, element) {
  this.src = 'test' + index + '.jpg';
});

.map()

Parcourt la collection actuelle et exécute une fonction pour chaque élément, retournant une nouvelle collection composée des valeurs retournées.

La fonction peut retourner une valeur simple ou un tableau. Si un tableau est retourné, ses éléments sont ajoutés un par un à la nouvelle collection. Si la fonction retourne null ou undefined, la valeur n'est pas ajoutée.

Les paramètres de la fonction sont l'indice et l'élément. Dans la fonction, this pointe vers l'élément courant.

const result = $('input.checked').map(function (i, element) {
  return element.value;
});

// result est un objet JQ contenant les valeurs des éléments correspondants

.eq()

Retourne une nouvelle collection contenant uniquement l'élément à l'indice spécifié.

$('div').eq(0); // Retourne une collection contenant uniquement le premier élément
$('div').eq(-1); // Retourne une collection contenant uniquement le dernier élément
$('div').eq(-2); // Retourne une collection contenant uniquement l'avant-dernier élément

.first()

Retourne une nouvelle collection contenant uniquement le premier élément de la collection actuelle.

$('div').first(); // Retourne une collection contenant uniquement le premier div

.last()

Retourne une nouvelle collection contenant uniquement le dernier élément de la collection actuelle.

$('div').last(); // Retourne une collection contenant uniquement le dernier div

.get()

Retourne l'élément à l'indice spécifié. Si aucun paramètre n'est fourni, retourne un tableau de tous les éléments.

$('div').get(); // Retourne un tableau de tous les éléments div
$('div').get(0); // Retourne le premier élément div
$('div').get(-1); // Retourne le dernier élément div

.index()

Sans paramètre, retourne l'indice du premier élément de la collection par rapport à ses frères.

Avec un sélecteur CSS, retourne l'indice du premier élément par rapport aux éléments correspondant au sélecteur.

Avec un élément DOM, retourne l'indice de cet élément dans la collection.

Avec un objet JQ, retourne l'indice du premier élément de l'objet dans la collection.

<div id="child">
  <div id="child1"></div>
  <div id="child2"></div>
  <div id="child3"></div>
  <div id="child4"></div>
</div>

$('#child3').index(); // 2
$('#child3').index('#child div'); // 2
$('#child div').index($('#child3').get(0)); // 2

.slice()

Retourne un sous-ensemble de la collection actuelle.

Vous pouvez spécifier les indices de début et de fin (l'élément de fin n'est pas inclus). Si le second paramètre est omis, les éléments de l'indice de début à la fin sont retournés.

// Retourne tous les éléments après le troisième (inclus)
$('div').slice(3);

// Retourne les éléments entre le troisième et le cinquième (3 inclus, 5 exclus)
$('div').slice(3, 5);

.filter()

Filtre les éléments de la collection actuelle correspondant à une expression. Le paramètre peut être un sélecteur CSS, un élément DOM, un tableau d'éléments DOM, ou une fonction de rappel.

Avec une fonction de rappel, ses paramètres sont l'indice et l'élément. this pointe vers l'élément courant. Si la fonction retourne true, l'élément est conservé ; s'il retourne false, il est supprimé.

// Filtre les éléments div ayant la classe .box
$('div').filter('.box');

// Filtre les options sélectionnées
$('#select option').filter(function (index, element) {
  return element.selected;
});

.not()

Filtre les éléments de la collection qui ne correspondent pas à une expression.

Le paramètre peut être un sélecteur CSS, un élément DOM, un tableau d'éléments DOM, un objet JQ, ou une fonction de rappel.

Avec une fonction de rappel, ses paramètres sont l'indice et l'élément. this pointe vers l'élément courant. Si la fonction retourne true, l'élément est supprimé ; s'il retourne false, il est conservé.

// Filtre les éléments div n'ayant pas la classe .box
$('div').not('.box');

// Filtre les options non sélectionnées
$('#select option').not(function (index, element) {
  return element.selected;
});

Classes CSS

.hasClass()

Vérifie si le premier élément de la collection possède une classe CSS spécifiée.

// Vérifie si le premier élément div a la classe .item
$('div').hasClass('item');

.addClass()

Ajoute des classes CSS à chaque élément de la collection. Plusieurs classes peuvent être séparées par des espaces.

Le paramètre peut être une chaîne ou une fonction de rappel retournant des classes. Avec une fonction, ses paramètres sont l'indice et les classes actuelles. this pointe vers l'élément courant.

// Ajoute la classe .item à tous les éléments div
$('div').addClass('item');

// Ajoute les classes .item1 et .item2
$('div').addClass('item1 item2');

// Ajoute les classes retournées par la fonction
$('div').addClass(function (index, currentClassName) {
  return currentClassName + '-' + index;
});

.removeClass()

Supprime des classes CSS de chaque élément. Plusieurs classes peuvent être séparées par des espaces.

Le paramètre peut être une chaîne ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et les classes actuelles. this pointe vers l'élément courant.

Sans paramètre, l'attribut class est supprimé.

// Supprime la classe .item de tous les éléments div
$('div').removeClass('item');

// Supprime les classes .item1 et .item2
$('div').removeClass('item1 item2');

// Supprime les classes retournées par la fonction
$('div').removeClass(function (index, currentClassName) {
  return 'item';
});

.toggleClass()

Si la classe existe, elle est supprimée ; si elle n'existe pas, elle est ajoutée. Plusieurs classes peuvent être séparées par des espaces.

Le paramètre peut être une chaîne ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et les classes actuelles. this pointe vers l'élément courant.

// Bascule la classe .item sur tous les éléments div
$('div').toggleClass('item');

// Bascule les classes .item1 et .item2
$('div').toggleClass('item1 item2');

// Bascule les classes retournées par la fonction
$('div').toggleClass(function (index, currentClassName) {
  return 'item';
});

Attributs de nœuds

.prop()

Obtient la valeur d'une propriété JavaScript du premier élément.

// Obtient la valeur de la propriété checked du premier élément
$('input').prop('checked');

Avec deux paramètres, définit la valeur de la propriété pour tous les éléments.

La valeur peut être de n'importe quel type ou une fonction de rappel retournant une valeur. Avec une fonction, ses paramètres sont l'indice et l'ancienne valeur. this pointe vers l'élément courant.

Si la valeur ou la valeur retournée est undefined, la propriété n'est pas modifiée.

// Définit la propriété checked sur true pour tous les inputs
$('input').prop('checked', true);

// Utilise une fonction pour définir la valeur
$('input').prop('checked', function (index, oldPropValue) {
  return true;
});

Un objet peut être passé pour définir plusieurs propriétés.

// Définit plusieurs propriétés
$('input').prop({
  checked: false,
  disabled: function (index, oldPropValue) {
    return true;
  },
});

.removeProp()

Supprime une propriété JavaScript de tous les éléments.

$('input').removeProp('disabled');

.attr()

Obtient la valeur d'un attribut HTML du premier élément.

// Obtient la valeur d'attribut du premier élément
$('div').attr('username');

Avec deux paramètres, définit la valeur de l'attribut pour tous les éléments.

La valeur peut être une chaîne, un nombre ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne valeur. this pointe vers l'élément courant.

Si la valeur ou la valeur retournée est null, l'attribut est supprimé ; si elle est undefined, l'attribut n'est pas modifié.

// Définit l'attribut username
$('div').attr('username', 'mdui');

// Utilise une fonction
$('div').attr('username', function (index, oldAttrValue) {
  return 'mdui';
});

Un objet peut être passé pour définir plusieurs attributs.

// Définit plusieurs attributs en même temps
$('div').attr({
  username: 'mdui',
  lastname: function (index, oldAttrValue) {
    return 'test';
  },
});

.removeAttr()

Supprime un ou plusieurs attributs HTML de tous les éléments (séparés par des espaces).

// Supprime un attribut
$('div').removeAttr('username');

// Supprime plusieurs attributs
$('div').removeAttr('username lastname');

.val()

Retourne la valeur du premier élément.

Si l'élément est <select multiple="multiple">, un tableau des valeurs sélectionnées est retourné.

// Obtient la valeur du premier élément sélectionné
$('#input').val();

Avec un paramètre, définit la valeur de tous les éléments.

La valeur peut être une chaîne, un nombre, un tableau, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne valeur. this pointe vers l'élément courant.

Pour <input type="checkbox">, <input type="radio">, <option>, la valeur peut être un tableau pour sélectionner les valeurs correspondantes.

Si la valeur est undefined, la valeur de l'élément est effacée.

// Définit la valeur de l'élément sélectionné
$('#input').val('mdui');

// Définit la valeur de l'élément via une fonction de rappel
$('#input').val(function (index, oldValue) {
  return 'mdui';
});

.text()

Retourne le contenu textuel de tous les éléments (y compris leurs descendants).

// Obtient le texte de tous les éléments .box
$('.box').text();

Avec un paramètre, définit le contenu textuel de tous les éléments.

La valeur peut être une chaîne, un nombre, un booléen, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancien texte. this pointe vers l'élément courant.

Si la valeur est undefined, le texte n'est pas modifié.

// Définit le contenu textuel des éléments sélectionnés
$('.box').text('nouveau contenu texte');

// Définit le contenu textuel des éléments via une fonction de rappel
$('.box').text(function (index, oldTextContent) {
  return 'nouveau contenu texte';
});

.html()

Retourne le contenu HTML du premier élément.

// Obtient le contenu HTML du premier élément .box
$('.box').html();

Avec un paramètre, définit le contenu HTML de tous les éléments.

La valeur peut être une chaîne HTML, un élément DOM, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancien HTML. this pointe vers l'élément courant.

Si la valeur est undefined, le HTML n'est pas modifié.

// Définit le HTML des éléments sélectionnés
$('.box').html('<div>nouveau contenu HTML</div>');

// Définit le HTML des éléments via une fonction de rappel
$('.box').html(function (index, oldHTMLContent) {
  return '<div>nouveau contenu HTML</div>';
});

Stockage de données

$.data()

Lit ou stocke des données sur un élément spécifique.

Si la valeur stockée est undefined, cela équivaut à lire la donnée sur l'élément. $.data(element, 'key', undefined) est équivalent à $.data(element, 'key').

Note : Cette méthode ne lit pas les attributs data-*.

// Stocke une donnée, retourne la valeur stockée
$.data(document.body, 'layout', 'dark'); // retourne dark

// Stocke plusieurs données
$.data(document.body, {
  primary: 'indigo',
  accent: 'pink',
}); // retourne { primary: 'indigo', accent: 'pink' }

// Lit une donnée stockée
$.data(document.body, 'layout'); // retourne dark

// Lit toutes les données stockées
$.data(document.body); // retourne { layout: 'dark', primary: 'indigo', accent: 'pink' }

$.removeData()

Supprime les données stockées sur un élément.

Plusieurs noms de clés peuvent être spécifiés (séparés par des espaces ou via un tableau). Sans nom de clé, toutes les données sont supprimées.

// Supprime la donnée avec la clé 'name'
$.removeData(document.body, 'name');

// Supprime les clés 'name1' et 'name2' (méthodes équivalentes)
$.removeData(document.body, 'name1 name2');
$.removeData(document.body, ['name1', 'name2']);

// Supprime toutes les données
$.removeData(document.body);

.data()

Lit ou stocke des données sur les éléments de la collection.

Si la valeur stockée est undefined, elle n'est pas stockée.

Note : Cette méthode lit également les attributs data-*.

// Stocke une donnée
$('.box').data('layout', 'dark');

// Stocke plusieurs données
$('.box').data({
  primary: 'indigo',
  accent: 'pink',
});

// Lit une donnée du premier élément
$('.box').data('layout'); // retourne dark

// Lit toutes les données du premier élément
$('.box').data(); // retourne { layout: 'dark', primary: 'indigo', accent: 'pink' }

.removeData()

Supprime les données stockées sur les éléments de la collection.

Plusieurs noms de clés peuvent être spécifiés (séparés par des espaces ou via un tableau). Sans nom de clé, toutes les données sont supprimées.

Note : Cette méthode ne supprime que les données définies par .data(), pas celles des attributs data-*.

// Supprime la donnée avec la clé 'name'
$('.box').removeData('name');

// Supprime les clés 'name1' et 'name2' (méthodes équivalentes)
$('.box').removeData('name1 name2');
$('.box').removeData(['name1', 'name2']);

// Supprime toutes les données
$('.box').removeData();

Style

.css()

Obtient la valeur d'une propriété CSS du premier élément.

$('.box').css('color');

Avec deux paramètres, définit la propriété CSS pour tous les éléments.

La valeur peut être une chaîne, un nombre, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne valeur. this pointe vers l'élément courant.

Si la valeur est undefined, la propriété n'est pas modifiée. Si elle est null, la propriété est supprimée. Si c'est un nombre, l'unité px est ajoutée automatiquement.

// Définit la couleur du texte
$('.box').css('color', 'red');

// Utilise une fonction
$('.box').css('color', function (index, oldCSSValue) {
  return 'green';
});

// Définit plusieurs propriétés avec un objet
$('.box').css({
  'background-color': 'white',
  color: function (index, oldCSSValue) {
    return 'blue';
  },
});

.width()

Obtient la largeur du premier élément (sans padding, border, margin).

$('.box').width();

Avec un paramètre, définit la largeur de tous les éléments.

La valeur peut être une chaîne, un nombre, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne largeur. this pointe vers l'élément courant.

Si la valeur est null ou undefined, la largeur n'est pas modifiée. Si c'est un nombre, l'unité px est ajoutée.

// Définir la largeur de tous les éléments
$('.box').width('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').width(10);

// Définir la largeur via le retour d'une fonction de rappel
$('.box').width(function (index, oldWidth) {
  return 10;
});

.height()

Obtient la hauteur du premier élément (sans padding, border, margin).

$('.box').height();

Avec un paramètre, définit la hauteur de tous les éléments.

La valeur peut être une chaîne, un nombre, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne hauteur. this pointe vers l'élément courant.

Si la valeur est null ou undefined, la hauteur n'est pas modifiée. Si c'est un nombre, l'unité px est ajoutée.

// Définir la hauteur de tous les éléments
$('.box').height('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').height(10);

// Définir la hauteur via le retour d'une fonction de rappel
$('.box').height(function (index, oldHeight) {
  return 10;
});

.innerWidth()

Obtient la largeur du premier élément (avec padding, sans border, margin).

$('.box').innerWidth();

Avec un paramètre, définit la largeur (avec padding) de tous les éléments.

La valeur peut être une chaîne, un nombre, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne largeur. this pointe vers l'élément courant.

Si la valeur est null ou undefined, la largeur n'est pas modifiée. Si c'est un nombre, l'unité px est ajoutée.

// Définir la largeur (avec padding) de tous les éléments
$('.box').innerWidth('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').innerWidth(10);

// Définir la largeur via le retour d'une fonction de rappel
$('.box').innerWidth(function (index, oldWidth) {
  return 10;
});

.innerHeight()

Obtient la hauteur du premier élément (avec padding, sans border, margin).

$('.box').innerHeight();

Avec un paramètre, définit la hauteur (avec padding) de tous les éléments.

La valeur peut être une chaîne, un nombre, ou une fonction de rappel. Avec une fonction, ses paramètres sont l'indice et l'ancienne hauteur. this pointe vers l'élément courant.

Si la valeur est null ou undefined, la hauteur n'est pas modifiée. Si c'est un nombre, l'unité px est ajoutée.

// Définir la hauteur (avec padding) de tous les éléments
$('.box').innerHeight('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').innerHeight(10);

// Définir la hauteur via le retour d'une fonction de rappel
$('.box').innerHeight(function (index, oldHeight) {
  return 10;
});

.outerWidth()

Obtient la largeur du premier élément (avec padding, border, sans margin). Le paramètre true inclut la marge.

// Avec padding et border
$('.box').outerWidth();

// Avec padding, border et margin
$('.box').outerWidth(true);

Avec un paramètre (et éventuellement true pour la marge), définit la largeur (avec padding, border) de tous les éléments.

Le premier paramètre peut être une chaîne avec unité, un nombre, ou une fonction de rappel retournant une chaîne avec unité ou un nombre. Si le paramètre est une fonction de rappel, le premier argument est l'indice de l'élément, le second est la largeur d'origine. Dans la fonction, this pointe vers l'élément courant.

Si la valeur ou la valeur retournée est null ou undefined, la largeur n'est pas modifiée. Si la valeur est un nombre, l'unité px est ajoutée automatiquement.

// Définir la largeur de tous les éléments
$('.box').outerWidth('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').outerWidth(10);

// Le deuxième paramètre est true, la largeur inclura la marge
$('.box').outerWidth(10, true);

// Définir la largeur via le retour d'une fonction de rappel
$('.box').outerWidth(function (index, oldWidth) {
  return 10;
});

.outerHeight()

Obtient la hauteur du premier élément (avec padding, border, sans margin). Le paramètre true inclut la marge.

// Avec padding et border
$('.box').outerHeight();

// Avec padding, border et margin
$('.box').outerHeight(true);

Avec un paramètre (et éventuellement true pour la marge), définit la hauteur (avec padding, border) de tous les éléments.

Le premier paramètre peut être une chaîne avec unité, un nombre, ou une fonction de rappel retournant une chaîne avec unité ou un nombre. Si le paramètre est une fonction de rappel, le premier argument est l'indice de l'élément, le second est la hauteur d'origine. Dans la fonction, this pointe vers l'élément courant.

Si la valeur ou la valeur retournée est null ou undefined, la hauteur n'est pas modifiée. Si la valeur est un nombre, l'unité px est ajoutée automatiquement.

// Définir la hauteur de tous les éléments
$('.box').outerHeight('20%');

// La valeur est un nombre, l'unité par défaut est px
$('.box').outerHeight(10);

// Le deuxième paramètre est true, la hauteur inclura la marge
$('.box').outerHeight(10, true);

// Définir la hauteur via le retour d'une fonction de rappel
$('.box').outerHeight(function (index, oldHeight) {
  return 10;
});

.hide()

Cache tous les éléments de la collection.

$('.box').hide();

.show()

Affiche tous les éléments de la collection.

$('.box').show();

.toggle()

Bascule l'état d'affichage de tous les éléments.

$('.box').toggle();

.offset()

Obtient les coordonnées du premier élément par rapport au document.

$('.box').offset(); // { top: 20, left: 30 }

Avec un paramètre, définit les coordonnées de tous les éléments.

Le paramètre peut être un objet avec top et left, ou une fonction de rappel retournant un tel objet. Avec une fonction, ses paramètres sont l'indice et les anciennes coordonnées. this pointe vers l'élément courant.

Si la valeur de top ou left est undefined, la valeur correspondante n'est pas modifiée.

// Définit le décalage des éléments sélectionnés
$('.box').offset({ top: 20, left: 30 });

// Définit le décalage via une fonction de rappel
$('.box').offset(function (index, oldOffset) {
  return { top: 20, left: 30 };
});

.offsetParent()

Obtient le parent positionné du premier élément (le premier parent ayant une propriété position relative ou absolute).

$('.box').offsetParent();

.position()

Obtient le décalage du premier élément par rapport à son parent positionné.

$('.box').position(); // { top: 20, left: 30 }

Recherche de nœuds

.find()

Trouve les éléments descendants correspondant au sélecteur CSS dans la collection actuelle.

// Trouver les descendants de #box avec la classe .box
$('#box').find('.box');

.children()

Obtient les enfants directs de la collection actuelle. Un sélecteur CSS peut être passé pour filtrer.

// Trouver tous les enfants directs de #box
$('#box').children();

// Trouver tous les enfants directs de #box qui ont la classe .box
$('#box').children('.box');

.has()

Filtre les éléments de la collection qui contiennent des descendants correspondant au sélecteur ou à l'élément DOM.

// Donner une couleur de fond aux li qui contiennent une ul
$('li').has('ul').css('background-color', 'red');

.parent()

Obtient les parents directs de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Retourner le parent direct de .box
$('.box').parent();

// Retourner le parent direct de .box qui a la classe .parent
$('.box').parent('.parent');

.parents()

Obtient tous les ancêtres de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Retourner tous les ancêtres de span
$('span').parents();

// Retourner tous les ancêtres p de span
$('span').parents('p');

.parentsUntil()

Obtient tous les ancêtres de chaque élément jusqu'à ce qu'un élément correspondant au premier paramètre soit rencontré (l'élément correspondant n'est pas inclus).

Le premier paramètre peut être un sélecteur, un élément DOM, ou un objet JQ.

Un second paramètre (sélecteur) peut être passé pour filtrer les résultats.

Sans paramètre, équivaut à .parents().

// Tous les ancêtres
$('.item').parentsUntil();

// Ancêtres jusqu'à .parent
$('.item').parentsUntil('.parent');

// Ancêtres div jusqu'à .parent
$('.item').parentsUntil('.parent', 'div');

.prev()

Obtient les éléments frères précédents de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Obtenir l'élément frère précédent de .box
$('.box').prev();

// Obtenir l'élément frère précédent qui est un div
$('.box').prev('div');

.prevAll()

Obtient tous les éléments frères précédents de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Obtenir tous les éléments frères précédents
$('.box').prevAll();

// Obtenir tous les éléments frères précédents avec la classe .selected
$('.box').prevAll('.selected');

.prevUntil()

Obtient tous les éléments frères précédents jusqu'à un élément correspondant au premier paramètre (non inclus).

Le premier paramètre peut être un sélecteur, un élément DOM, ou un objet JQ. Un second paramètre (sélecteur) peut être passé pour filtrer les résultats.

Sans paramètre, le fonctionnement est identique à .prevAll().

// Obtenir tous les éléments frères précédents
$('.box').prevUntil();

// Obtenir tous les éléments frères précédents jusqu'à .until
$('.box').prevUntil('.until');

// Obtenir tous les éléments frères div jusqu'à .until
$('.box').prevUntil('.until', 'div');

.next()

Obtient les éléments frères suivants de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Obtenir l'élément frère suivant de .box
$('.box').next();

// Obtenir l'élément frère suivant qui est un div
$('.box').next('div');

.nextAll()

Obtient tous les éléments frères suivants de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Obtenir tous les éléments frères suivants
$('.box').nextAll();

// Obtenir tous les éléments frères suivants avec la classe .selected
$('.box').nextAll('.selected');

.nextUntil()

Obtient tous les éléments frères suivants jusqu'à un élément correspondant au premier paramètre (non inclus).

Le premier paramètre peut être un sélecteur, un élément DOM, ou un objet JQ. Un second paramètre (sélecteur) peut être passé pour filtrer les résultats.

Sans paramètre, le fonctionnement est identique à .nextAll().

// Obtenir tous les éléments frères suivants
$('.box').nextUntil();

// Obtenir tous les éléments frères suivants jusqu'à .until
$('.box').nextUntil('.until');

// Obtenir tous les éléments frères div jusqu'à .until
$('.box').nextUntil('.until', 'div');

.closest()

Remonte depuis l'élément courant et retourne le premier élément correspondant. Le paramètre peut être un sélecteur, un élément DOM, ou un objet JQ.

// Remonter et trouver le premier élément ayant la classe .parent
$('.box').closest('.parent');

.siblings()

Obtient tous les éléments frères de la collection. Un sélecteur CSS peut être passé pour filtrer.

// Obtenir tous les éléments frères
$('.box').siblings();

// Obtenir tous les éléments frères avec la classe .selected
$('.box').siblings('.selected');

.add()

Ajoute des éléments à la collection actuelle. Le paramètre peut être une chaîne HTML, un sélecteur, un objet JQ, un élément DOM, un tableau d'éléments DOM, ou une NodeList.

// Ajouter les éléments ayant la classe .selected à la collection
$('.box').add('.selected');

Manipulation du DOM

.empty()

Supprime tous les enfants des éléments de la collection.

$('.box').empty();

.remove()

Supprime les éléments de la collection du DOM. Un sélecteur CSS peut être passé pour filtrer.

// Supprime tous les éléments p du DOM
$('p').remove();

// Supprime les éléments p avec la classe .box du DOM
$('p').remove('.box');

.prepend()

Insère le contenu spécifié au début de chaque élément de la collection. Le paramètre peut être une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ. Plusieurs paramètres sont acceptés.

Une fonction de rappel peut être passée, retournant le contenu à insérer. Ses paramètres sont l'indice et l'ancien HTML. this pointe vers l'élément courant.

Retourne la collection originale.

// Insère un élément
$('<p>Je voudrais dire : </p>').prepend('<b>Bonjour</b>');
// Résultat : <p><b>Bonjour</b>Je voudrais dire : </p>

// Insère plusieurs éléments
$('<p>Je voudrais dire : </p>').prepend('<b>Bonjour</b>', '<b>Monde</b>');
// Résultat : <p><b>Bonjour</b><b>Monde</b>Je voudrais dire : </p>

// Insère un élément via une fonction de rappel
$('<p>Bonjour</p>').prepend(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// Résultat : <p><b>Bonjour0</b>Bonjour</p>

.prependTo()

Insère les éléments de la collection au début du contenu de l'élément cible. Le paramètre peut être un sélecteur, une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ.

Retourne la collection originale.

$('<p>Bonjour</p>').prependTo('<p>Je voudrais dire : </p>');
// Résultat : [ <p><p>Bonjour</p>Je voudrais dire : </p> ]

.append()

Insère le contenu spécifié à la fin de chaque élément. Le paramètre peut être une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ. Plusieurs paramètres sont acceptés.

Une fonction de rappel peut être passée, retournant le contenu à insérer. Ses paramètres sont l'indice et l'ancien HTML. this pointe vers l'élément courant.

Retourne la collection originale.

// Insère un élément
$('<p>Je voudrais dire : </p>').append('<b>Bonjour</b>');
// Résultat : <p>Je voudrais dire : <b>Bonjour</b></p>

// Insère plusieurs éléments
$('<p>Je voudrais dire : </p>').append('<b>Bonjour</b>', '<b>Monde</b>');
// Résultat : <p>Je voudrais dire : <b>Bonjour</b><b>Monde</b></p>

// Insère un élément via une fonction de rappel
$('<p>Bonjour</p>').append(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// Résultat : <p>Bonjour<b>Bonjour0</b></p>

.appendTo()

Insère les éléments de la collection à la fin du contenu de l'élément cible.

Cette méthode retourne la collection originale.

$('<p>Bonjour</p>').appendTo('<p>Je voudrais dire : </p>');
// Résultat : <p>Je voudrais dire : <p>Bonjour</p></p>

.after()

Insère le contenu spécifié après chaque élément (comme élément frère). Le paramètre peut être une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ. Plusieurs paramètres sont acceptés.

Une fonction de rappel peut être passée, retournant le contenu à insérer. Ses paramètres sont l'indice et l'ancien HTML. this pointe vers l'élément courant.

Retourne la collection originale.

// Insère un élément
$('<p>Je voudrais dire : </p>').after('<b>Bonjour</b>');
// Résultat : <p>Je voudrais dire : </p><b>Bonjour</b>

// Insère plusieurs éléments
$('<p>Je voudrais dire : </p>').after('<b>Bonjour</b>', '<b>Monde</b>');
// Résultat : <p>Je voudrais dire : </p><b>Bonjour</b><b>Monde</b>

// Insère un élément via une fonction de rappel
$('<p>Bonjour</p>').after(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// Résultat : <p>Bonjour</p><b>Bonjour0</b>

.insertAfter()

Insère les éléments de la collection après l'élément cible (comme frère).

Si les éléments existent déjà, ils sont déplacés. Si plusieurs cibles, les éléments sont clonés.

Le paramètre peut être un sélecteur, une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ.

$('<b>Bonjour</b>').insertAfter('<p>Je voudrais dire : </p>');
// Résultat : <p>Je voudrais dire : </p><b>Bonjour</b>

.before()

Insère le contenu spécifié avant chaque élément (comme élément frère). Le paramètre peut être une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ. Plusieurs paramètres sont acceptés.

Une fonction de rappel peut être passée, retournant le contenu à insérer. Ses paramètres sont l'indice et l'ancien HTML. this pointe vers l'élément courant.

Retourne la collection originale.

// Insère un élément
$('<p>Je voudrais dire : </p>').before('<b>Bonjour</b>');
// Résultat : <b>Bonjour</b><p>Je voudrais dire : </p>

// Insère plusieurs éléments
$('<p>Je voudrais dire : </p>').before('<b>Bonjour</b>', '<b>Monde</b>');
// Résultat : <b>Bonjour</b><b>Monde</b><p>Je voudrais dire : </p>

// Insère un élément via une fonction de rappel
$('<p>Bonjour</p>').before(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// Résultat : <b>Bonjour0</b><p>Bonjour</p>

.insertBefore()

Insère les éléments de la collection avant l'élément cible (comme frère).

Si les éléments existent déjà, ils sont déplacés. Si plusieurs cibles, les éléments sont clonés.

Le paramètre peut être un sélecteur, une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ.

$('<p>Je voudrais dire : </p>').insertBefore('<b>Bonjour</b>');
// Résultat : <p>Je voudrais dire : </p><b>Bonjour</b>

.replaceWith()

Remplace les éléments de la collection par le contenu spécifié.

Le paramètre peut être une chaîne HTML, un élément DOM, un tableau d'éléments, ou un objet JQ.

Une fonction de rappel peut être passée, retournant le contenu de remplacement. Les paramètres de la fonction sont l'indice et l'ancien HTML. Dans la fonction, this pointe vers l'élément courant.

Retourne la collection originale des éléments remplacés.

// Remplace tous les éléments .box par <p>Bonjour</p>
$('.box').replaceWith('<p>Bonjour</p>');

// Remplace tous les éléments .box par la valeur retournée par la fonction de rappel
$('.box').replaceWith(function (index, oldHTML) {
  return oldHTML + index;
});

.replaceAll()

Remplace les éléments cibles par les éléments de la collection.

Le paramètre (éléments à remplacer) peut être un sélecteur, un élément DOM, un tableau d'éléments, ou un objet JQ.

Retourne la collection des éléments de remplacement.

// Remplace tous les éléments .box par l'élément .new
$('.new').replaceAll('.box');

.clone()

Crée une copie profonde de tous les éléments de la collection.

Utilise la méthode native cloneNode. Les données et les gestionnaires d'événements ne sont pas copiés.

$('body').append($('#box').clone());

Formulaires

.serializeArray()

Sérialise les valeurs des éléments de formulaire en un tableau d'objets {name, value}.

Fonctionne sur des éléments de formulaire individuels ou sur un <form> entier.

$('form').serializeArray();
// [
//   { "name": "golang", "value":"456" },
//   { "name": "name", "value": "mdui" },
//   { "name": "password", "value": "" }
// ]

.serializeObject()

Convertit les valeurs des éléments de formulaire en un objet.

Si plusieurs clés identiques existent, leurs valeurs sont regroupées dans un tableau.

Cette méthode peut être utilisée sur des éléments de formulaire individuels ou sur un élément <form> entier.

$('form').serializeObject();
// { name: mdui, password: 123456 }

.serialize()

Compile les valeurs des éléments de formulaire en une chaîne encodée URL.

$('form').serialize();
// golang=456&name=mdui&password=

Événements

.on()

Attache une fonction de rappel à un ou plusieurs événements pour les éléments de la collection.

// Attache un événement click
$('.box').on('click', function (e) {
  console.log('Élément .box cliqué');
});

// Attache plusieurs événements
$('.box').on('click focus', function (e) {
  console.log(
    'Les événements click et focus déclencheront tous deux cette fonction',
  );
});

// Délégation d'événement
$(document).on('click', '.box', function (e) {
  console.log('Cette fonction est déclenchée lors du clic sur .box');
});

// Attache plusieurs événements et fonctions de rappel en même temps
$('.box').on({
  click: function (e) {
    console.log('Événement click déclenché');
  },
  focus: function (e) {
    console.log('Événement focus déclenché');
  },
});

// Passage de paramètres
$('.box').on('click', { key1: 'value1', key2: 'value2' }, function (e) {
  console.log(
    'Élément .box cliqué, et des paramètres sont passés au gestionnaire',
  );
  // e._data est {key1: 'value1', key2: 'value2'}
});

// Attache plusieurs événements et fonctions de rappel en même temps, et passage de paramètres
$('.box').on(
  {
    click: function (e) {
      console.log('Événement click déclenché');
      // e._data est {key1: 'value1', key2: 'value2'}
    },
    focus: function (e) {
      console.log('Événement focus déclenché');
      // e._data est {key1: 'value1', key2: 'value2'}
    },
  },
  { key1: 'value1', key2: 'value2' },
);

// Attache un événement via délégation, et passage de paramètres
$(document).on(
  'click',
  '.box',
  { key1: 'value1', keys: 'value2' },
  function (e) {
    console.log(
      'Élément .box cliqué, et des paramètres sont passés au gestionnaire',
    );
    // e._data est {key1: 'value1', key2: 'value2'}
  },
);

// Attache plusieurs événements et fonctions de rappel via délégation
$(document).on(
  {
    click: function (e) {
      console.log('Événement click déclenché');
    },
    focus: function (e) {
      console.log('Événement focus déclenché');
    },
  },
  '.box',
);

// Attache plusieurs événements et fonctions de rappel via délégation, et passage de paramètres
$(document).on(
  {
    click: function (e) {
      console.log('Événement click déclenché');
      // e._data est {key1: 'value1', key2: 'value2'}
    },
    focus: function (e) {
      console.log('Événement focus déclenché');
      // e._data est {key1: 'value1', key2: 'value2'}
    },
  },
  '.box',
  { key1: 'value1', key2: 'value2' },
);

// Obtention des paramètres de l'événement
$('.box').on('click', function (e, data) {
  // data est égal à e.detail
});

// Le nom de l'événement prend en charge l'utilisation d'espaces de noms
$('.box').on('click.myPlugin', function () {
  console.log('Élément .box cliqué');
});

.one()

Attache une fonction de rappel à chaque élément correspondant pour un événement spécifique, mais l'événement ne se déclenchera qu'une seule fois.

L'utilisation de cette méthode est identique à celle de .on(), aucun exemple n'est donc fourni.

.off()

Supprime les gestionnaires d'événements des éléments de la collection.

// Supprime tous les gestionnaires d'événements liés
$('.box').off();

// Supprime un gestionnaire d'événement spécifique
$('.box').off('click');

// Supprime plusieurs gestionnaires d'événements à la fois
$('.box').off('click focus');

// Supprime un gestionnaire d'événement spécifique lié à une fonction
$('.box').off('click', callback);

// Supprime les événements liés par délégation
$(document).off('click', '.box');

// Supprime les gestionnaires d'événements spécifiques liés par délégation
$(document).off('click', '.box', callback);

// Supprime plusieurs gestionnaires d'événements à la fois
$('.box').off({
  click: callback1,
  focus: callback2,
});

// Supprime plusieurs gestionnaires d'événements liés par délégation à la fois
$(document).off(
  {
    click: callback1,
    focus: callback2,
  },
  '.box',
);

// Les noms d'événements supportent les espaces de noms, l'utilisation suivante supprimera tous les événements se terminant par .myPlugin
$(document).off('.myPlugin');

.trigger()

Déclenche un événement sur les éléments de la collection.

// Déclencher un événement
$('.box').trigger('click');

// Déclencher un événement avec des paramètres
$('.box').trigger('click', { key1: 'value1', key2: 'value2' });

// Déclencher un événement avec un espace de noms
$('.box').trigger('click.myPlugin');

// Passer des paramètres à CustomEvent
$('.box').trigger('click', undefined, {
  bubbles: true,
  cancelable: true,
  composed: true,
});

Ajax

$.ajaxSetup()

Définit les paramètres globaux pour les requêtes AJAX.

$.ajaxSetup({
  // Ne pas déclencher d'événements AJAX globaux par défaut
  global: false,

  // Utiliser la méthode POST par défaut pour envoyer les requêtes
  method: 'POST',
});

Voir la liste détaillée des paramètres ci-dessous : Paramètres Ajax.

$.ajax()

Envoie une requête AJAX et retourne une Promise.

const promise = $.ajax({
  method: 'POST',
  url: './test.php',
  data: {
    key1: 'val1',
    key2: 'val2',
  },
  success: function (response) {
    console.log(response);
  },
});

promise
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Voir la liste détaillée des paramètres ci-dessous : Paramètres Ajax.

Les événements AJAX globaux peuvent être écoutés avec .on().

// Lorsque la requête AJAX commence, cet événement est déclenché
$(document).on('ajaxStart', function (e, { xhr, options }) {
  // xhr: objet XMLHttpRequest
  // options: paramètres de la méthode $.ajax()
});

// Lorsque la requête AJAX réussit, cet événement est déclenché
$(document).on('ajaxSuccess', function (e, { xhr, options, response }) {
  // xhr: objet XMLHttpRequest
  // options: paramètres de la méthode $.ajax()
  // response: réponse de la requête
});

// Lorsque la requête AJAX échoue, cet événement est déclenché
$(document).on('ajaxError', function (e, { xhr, options }) {
  // xhr: objet XMLHttpRequest
  // options: paramètres de la méthode $.ajax()
});

// Lorsque la requête AJAX est terminée (qu'elle ait réussi ou échoué), cet événement est déclenché
$(document).on('ajaxComplete', function (e, { xhr, options }) {
  // xhr: objet XMLHttpRequest
  // options: paramètres de la méthode $.ajax()
});

Paramètres Ajax

$.ajax({
  url: 'une URL cross-origin',
  xhrFields: {
    withCredentials: true
  }
});

$.ajax({
  statusCode: {
    404: function (xhr, textStatus) {
      alert('Appelé lorsque le code d'état est 404');
    },
    200: function (data, textStatus, xhr) {
      alert('Appelé lorsque le code d'état est 200');
    }
  }
});

$.ajax({
  beforeSend: function (xhr) {
    // xhr est l'objet XMLHttpRequest
  }
});

$.ajax({
  success: function (data, textStatus, xhr) {
    // data est la donnée retournée par la requête AJAX
    // textStatus est une chaîne contenant le code de succès
    // xhr est l'objet XMLHttpRequest
  }
});

$.ajax({
  error: function (xhr, textStatus) {
    // xhr est l'objet XMLHttpRequest
    // textStatus est une chaîne contenant le code d'erreur
  }
});

$.ajax({
  complete: function (xhr, textStatus) {
    // xhr est l'objet XMLHttpRequest
    // textStatus est une chaîne contenant le code de succès ou d'erreur
  }
});