jQuery.cookie.js中文API

jquery.cookie.js中文API

一个简单,轻量级的jQuery插件,用于读,写,删除浏览器cookie。

安装

将最后贴出的jQuery.cookie.js源代码保存为js文件,然后在jQuery类库后面用script导入jquery.cookie.js文件。

<script src="/path/to/jquery.js"></script>
<script src="/path/to/jquery.cookie.js"></script>

 

备注:不要直接引用GitHub网站的jquery.cookie.js文件。这个js文件的mime类型被设置为 text/plain,在Windows7系统下的IE浏览器会阻止这个文件(因为错误的mime类型) ,GitHub不提供CDN服务。这个插件也可以当做AMD模块来加载。

使用示例

创建会话cookie(Session cookie,既浏览器内存cookie,浏览器关闭后自动删除)

$.cookie('the_cookie', 'the_value');

创建一个生生存周期为7天的cookie

$.cookie('the_cookie', 'the_value', { expires: 7 });

 

创建一个有期限的cookie,整个站点可以读取

$.cookie('the_cookie', 'the_value', { expires: 7, path: '/' });

 

读取cookie

$.cookie('the_cookie'); // => "the_value"
$.cookie('not_existing'); // => undefined

 

读取所有可用cookie

$.cookie(); // => { "the_cookie": "the_value", "...remaining": "cookies" }

 

删除cookie

// 找到指定的cookie返回true,否则返回false
$.removeCookie('the_cookie');
// 删除指定过path的cookie
$.removeCookie('the_cookie', { path: '/' });

 

注意:删除cookie时,除非使用的是默认配置,否则需要传递完全相同的路径,域名和安全选项配置,和写cookie时的一致。

配置

raw

默认读写cookie值时都会编码和解码,使用的javascript函数为encodeURIComponent/decodeURIComponent。如果设置raw配置为true,将不会编码cookie值。

$.cookie.raw = true;

 

json

开启自动存储cookie值为JSON对象功能,使用了 JSON.stringifyJSON.parse方法。默认不支持存储值为json对象。

注意:IE7-浏览器不支持JSON对象,如果在IE7-下设置json为true会报错,需要导入json2.js来实现JSON.stringifyJSON.parse方法。json2.js下载地址

$.cookie.json = true;

 

Cookie配置选项

可以通过设置$.cookie.defaults 对象或者每次调用$.cookie方法时设置cookie属性,$.cookie方法中传递的配置会覆盖$.cookie.defaults 默认配置。

expires

expires: 365

设置cookie的生存周期,可以为数字(单位为:天)或者一个Date对象。缺省此参数,变为一个会话cookie(内存cookie)。

path

path: '/'

定义cookie的有效路径。cookie默认路径为创建这个cookie的页面路径(标准浏览器行为,如chrome,firefox)。如果你想这个cookie在整个站点的所有页面都可用,设置如上。

IE浏览器注释事项

由于在底层WININET InternetGetCookie实现的一个不起眼的错误, IE浏览器文档获取不到path属性设置成包含文件名称路径的cookie

(参考: Internet Explorer Cookie Internals (FAQ))

就是说不能设置path配置为 window.location.pathname ,这个情况下,pathname包含一个文件名称,如 /check.html (会导致cookie无法正确读取)

domain

domain: 'example.com'

定义cookie的有效域名。domain默认为创建cookie的当前页面所在域名。如果想2级或者级域名能获取到这个cookie,可以设置为顶级域名。

secure

secure: true

设置为true,仅当通过https协议访问时才会发送这个cookie到服务器。默认为false

帮助

参考: Contributing Guidelines

作者

Klaus Hartl

 

jQuery.cookie.js源代码如下

/*!
 * jQuery Cookie Plugin v1.3.1
 * https://github.com/carhartl/jquery-cookie
 *
 * Copyright 2013 Klaus Hartl
 * Released under the MIT license
 */
(function (factory) {
	if (typeof define === 'function' && define.amd) {
		// AMD. Register as anonymous module.
		define(['jquery'], factory);
	} else {
		// Browser globals.
		factory(jQuery);
	}
}(function ($) {

	var pluses = /\+/g;

	function raw(s) {
		return s;
	}

	function decoded(s) {
		return decodeURIComponent(s.replace(pluses, ' '));
	}

	function converted(s) {
		if (s.indexOf('"') === 0) {
			// This is a quoted cookie as according to RFC2068, unescape
			s = s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
		}
		try {
			return config.json ? JSON.parse(s) : s;
		} catch(er) {}
	}

	var config = $.cookie = function (key, value, options) {

		// write
		if (value !== undefined) {
			options = $.extend({}, config.defaults, options);

			if (typeof options.expires === 'number') {
				var days = options.expires, t = options.expires = new Date();
				t.setDate(t.getDate() + days);
			}

			value = config.json ? JSON.stringify(value) : String(value);

			return (document.cookie = [
				config.raw ? key : encodeURIComponent(key),
				'=',
				config.raw ? value : encodeURIComponent(value),
				options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
				options.path    ? '; path=' + options.path : '',
				options.domain  ? '; domain=' + options.domain : '',
				options.secure  ? '; secure' : ''
			].join(''));
		}

		// read
		var decode = config.raw ? raw : decoded;
		var cookies = document.cookie.split('; ');
		var result = key ? undefined : {};
		for (var i = 0, l = cookies.length; i < l; i++) {
			var parts = cookies[i].split('=');
			var name = decode(parts.shift());
			var cookie = decode(parts.join('='));

			if (key && key === name) {
				result = converted(cookie);
				break;
			}

			if (!key) {
				result[name] = converted(cookie);
			}
		}

		return result;
	};

	config.defaults = {};

	$.removeCookie = function (key, options) {
		if ($.cookie(key) !== undefined) {
			// Must not alter options, thus extending a fresh object...
			$.cookie(key, '', $.extend({}, options, { expires: -1 }));
			return true;
		}
		return false;
	};

}));

翻译来源:https://github.com/carhartl/jquery-cookie

加支付宝好友偷能量挖...


原创文章,转载请注明出处:jQuery.cookie.js中文API

评论(1)Web开发网
阅读(2644)喜欢(0)JavaScript/Ajax开发技巧