js cookie
v3.0.5
Une API JavaScript simple et légère pour gérer les cookies
Si vous consultez cela sur https://github.com/js-cookie/js-cookie, vous lisez la documentation de la branche principale. Afficher la documentation pour la dernière version. ??
JavaScript Cookie prend en charge le NPM sous le nom de js-cookie .
npm i js-cookie Le package NPM dispose d'un champ module pointant vers une variante de module ES de la bibliothèque, principalement pour fournir une prise en charge des bundlers de conscience du module ES, tandis que son champ browser pointe vers un module UMD pour une compatibilité complète vers l'arrière.
Tous les navigateurs ne prennent pas encore en charge les modules ES nativement . Pour cette raison, le package / version NPM fournit à la fois la variante ES et UMD du module et vous voudrez peut-être inclure le module ES ainsi que la secours UMD pour tenir compte de ceci:
Alternativement, incluez JS-Cookie via JSDelivr CDN.
Importer la bibliothèque:
import Cookies from 'js-cookie'
// or
const Cookies = require ( 'js-cookie' )Créez un cookie, valide sur l'ensemble du site:
Cookies . set ( 'name' , 'value' )Créez un cookie qui expire dans 7 jours, valide sur tout le site:
Cookies . set ( 'name' , 'value' , { expires : 7 } )Créez un cookie expiré, valide sur le chemin de la page actuelle:
Cookies . set ( 'name' , 'value' , { expires : 7 , path : '' } )Lire Cookie:
Cookies . get ( 'name' ) // => 'value'
Cookies . get ( 'nothing' ) // => undefinedLisez tous les cookies visibles:
Cookies . get ( ) // => { name: 'value' }Remarque: il n'est pas possible de lire un cookie particulier en passant l'un des attributs des cookies (qui peut ou non avoir été utilisé lors de l'écriture du cookie en question):
Cookies . get ( 'foo' , { domain : 'sub.example.com' } ) // `domain` won't have any effect...! Le cookie avec le nom foo ne sera disponible sur .get() que s'il est visible à partir de l'endroit où le code est appelé; L'attribut de domaine et / ou de chemin n'aura pas d'effet lors de la lecture.
Supprimer le cookie:
Cookies . remove ( 'name' )Supprimer un cookie valide sur le chemin de la page actuelle:
Cookies . set ( 'name' , 'value' , { path : '' } )
Cookies . remove ( 'name' ) // fail!
Cookies . remove ( 'name' , { path : '' } ) // removed! IMPORTANT! Lorsque vous supprimez un cookie et que vous ne comptez pas sur les attributs par défaut, vous devez passer exactement le même path , domain , le domaine, les attributs secure et sameSite qui ont été utilisés pour définir le cookie:
Cookies . remove ( 'name' , { path : '' , domain : '.yourdomain.com' , secure : true } )Remarque: la suppression d'un cookie inexistant ne soulevait aucune exception ni ne renvoie aucune valeur.
S'il existe un danger de conflit avec les Cookies d'espace de noms, la méthode noConflict vous permettra de définir un nouvel espace de noms et de préserver l'original. Ceci est particulièrement utile lors de l'exécution du script sur des sites tiers, par exemple, dans le cadre d'un widget ou d'un SDK.
// Assign the js-cookie api to a different variable and restore the original "window.Cookies"
var Cookies2 = Cookies . noConflict ( )
Cookies2 . set ( 'name' , 'value' ) Remarque: La méthode .noConflict n'est pas nécessaire lors de l'utilisation d'AMD ou CommonJS, il n'est donc pas exposé dans ces environnements.
Ce projet est conforme à la RFC 6265. Tous les caractères spéciaux qui ne sont pas autorisés dans le nom de cookie ou la valeur des cookies sont codés avec l'équivalent hexadécimal UTF-8 de chacun en pourcentage en pourcentage. Le seul personnage dans le nom de cookie ou la valeur des cookies qui est autorisé et toujours codé est le pourcentage de caractère % , il est échappé afin d'interpréter le pourcentage de contribution comme littéral. Veuillez noter que la stratégie de codage / décodage par défaut est censée être interopérable uniquement entre les cookies lus / écrits par JS-Cookie. Pour remplacer la stratégie de codage / décodage par défaut, vous devez utiliser un convertisseur.
Remarque: Selon RFC 6265, vos cookies peuvent être supprimés s'ils sont trop grands ou qu'il y a trop de cookies dans le même domaine, plus de détails ici.
Les défauts d'attribut cookie peuvent être définis à l'échelle mondiale en créant une instance de l'API via withAttributes() , ou individuellement pour chaque appel à Cookies.set(...) en faisant passer un objet simple comme dernier argument. Les attributs par calcul remplacent les attributs par défaut.
Définissez quand le cookie sera retiré. La valeur doit être un Number qui sera interprété comme des jours à partir du moment de la création ou une instance Date . S'il est omis, le cookie devient un cookie de session.
Pour créer un cookie qui expire en moins d'une journée, vous pouvez vérifier la FAQ sur le wiki.
Par défaut: le cookie est supprimé lorsque l'utilisateur ferme le navigateur.
Exemples:
Cookies . set ( 'name' , 'value' , { expires : 365 } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) Une String indiquant le chemin où le cookie est visible.
Défaut: /
Exemples:
Cookies . set ( 'name' , 'value' , { path : '' } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' , { path : '' } )Remarque concernant Internet Explorer:
En raison d'un bogue obscur dans l'implémentation sous-jacente de Wininet InternetGookie, Document de IE.COOKIE ne renverra pas de cookie s'il était défini avec un attribut de chemin contenant un nom de fichier.
(À partir de cookies Internet Explorer internes (FAQ))
Cela signifie que l'on ne peut pas définir un chemin à l'aide de window.location.pathname au cas où un tel chemin d'accès contient un nom de fichier comme ainsi: /check.html (ou du moins, un tel cookie ne peut pas être lu correctement).
En fait, vous ne devez jamais autoriser les entrées non fiables pour définir les attributs de cookies ou vous pourriez être exposé à une attaque XSS.
Une String indiquant un domaine valide où le cookie doit être visible. Le cookie sera également visible pour tous les sous-domaines.
Par défaut: le cookie est visible uniquement par le domaine ou le sous-domaine de la page où le cookie a été créé, à l'exception de Internet Explorer (voir ci-dessous).
Exemples:
En supposant un cookie créé sur site.com :
Cookies . set ( 'name' , 'value' , { domain : 'subdomain.site.com' } )
Cookies . get ( 'name' ) // => undefined (need to read at 'subdomain.site.com')Remarque concernant le comportement par défaut de l'explorateur Internet:
Q3: Si je ne spécifie pas un attribut de domaine (pour) un cookie, c'est-à-dire l'envoie à tous les sous-domaines imbriqués de toute façon? R: Oui, un ensemble de cookies sur Example.com sera envoyé à sub2.sub1.example.com. Internet Explorer diffère des autres navigateurs à cet égard.
(À partir de cookies Internet Explorer internes (FAQ))
Cela signifie que si vous omettez l'attribut domain , il sera visible pour un sous-domaine dans IE.
true ou false , indiquant si la transmission des cookies nécessite un protocole sécurisé (HTTPS).
Par défaut: aucune exigence de protocole sécurisée.
Exemples:
Cookies . set ( 'name' , 'value' , { secure : true } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) Une String , permettant de contrôler si le navigateur envoie un cookie avec des demandes de site croisé.
Par défaut: pas défini.
Notez que les navigateurs plus récents font de la valeur par défaut de la valeur par défaut, même sans spécifier quoi que ce soit ici.
Exemples:
Cookies . set ( 'name' , 'value' , { sameSite : 'strict' } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) const api = Cookies . withAttributes ( { path : '/' , domain : '.example.com' } ) Créez une nouvelle instance de l'API qui remplace l'implémentation de décodage par défaut. Tous obtiennent des méthodes qui reposent dans un décodage approprié pour travailler, comme Cookies.get() et Cookies.get('name') , exécutera le convertisseur donné pour chaque cookie. La valeur renvoyée sera utilisée comme valeur de cookie.
Exemple de la lecture de l'un des cookies qui ne peut être décodé qu'à l'aide de la fonction escape :
document . cookie = 'escaped=%u5317'
document . cookie = 'default=%E5%8C%97'
var cookies = Cookies . withConverter ( {
read : function ( value , name ) {
if ( name === 'escaped' ) {
return unescape ( value )
}
// Fall back to default for all other cookies
return Cookies . converter . read ( value , name )
}
} )
cookies . get ( 'escaped' ) // 北
cookies . get ( 'default' ) // 北
cookies . get ( ) // { escaped: '北', default: '北' }Créez une nouvelle instance de l'API qui remplace l'implémentation de codage par défaut:
Cookies . withConverter ( {
write : function ( value , name ) {
return value . toUpperCase ( )
}
} ) npm i @types/js-cookieDécouvrez les docs des serveurs
Consultez les directives contributives
La libération doit être effectuée via le flux de travail des actions GitHub Release , de sorte que les packages publiés sur npmjs.com ont une provenance du package.
Les sorties GitHub sont créées comme un projet et doivent être publiées manuellement! (C'est ainsi que nous pouvons créer des notes de sortie appropriées avant la publication.)
Un grand merci à Browserstack pour avoir fourni des tests de navigateur illimités gratuitement.
