cookie.js插件的README/cookie.js中文使用手册

<span style="font-size:14px;">#  cookie.js – simplifying cookies in JavaScript [![Build Status](https://travis-ci.org/florian/cookie.js.png?branch=master)](https://travis-ci.org/florian/cookie.js)

cookie.js is a tiny JavaScript library that simplifies cookies. It is capable of setting, getting and removing cookies, accepts a variety of parameters, and supports chaining.  It doesn't have any dependencies and minified+gzipped it's only 0.9 KB small.
//翻译：简化cookie的cookie.js是一个很小的JS库，包含了设置、获取和删除cookie方法，接收各样的参数，并且支持链接，不依赖于任何文件，迷你版压缩后仅仅只有0.9KB
## Why would you want to use it?
Working with cookies in JavaScript sucks. `document.cookie` is definitely one of the ugly parts of JavaScript. This library aims to provide an easy and nevertheless powerful way to use cookies.

## Usage

Download [cookie.min.js](https://raw.github.com/florian/cookie.js/master/cookie.min.js) and include it in your HTML document, this will add a global object called `cookie`:
//翻译：下载 cookie.min.js 并且通过下列方式包含进你的HTML文件，这样就会添加一个全局对象："cookie"
```html
<script src="cookie.min.js"></script>
```

Alternatively you can use a JavaScript package manager to add it to your project:
```sh
$ bower install cookie --save
$ jam install cookie
$ npm install cookie_js --save
```

---

cookie.js supports AMD and CommonJS. So if you want to include cookie.js dynamically, you can just require it with any AMD / CommonJS loader, for example [RequireJS](http://requirejs.org/) for AMD.
Follow the instructions of your loader to include cookie.js.

---

After that you can call any of methods that are explained in the following.

## cookie.set
You can use the `cookie.set` method to set cookies. The value will automatically be escaped for you.
//设置cookie单个值的方法
```javascript
cookie.set('key', 'value');
```

*Note: Values will be casted to string, so setting a number will work. However, the value will be a string when getting the cookie.*

You can also set several values at once:
//设置cookie多个值的方法
```javascript
cookie.set({
   key1: 'value1',
   key2: 'value2'
});
```

If you need more options, like setting the expiry date, you can add an object with options as the last parameter:
//翻译：如果你需要更多的选择，比如设置 有效期限，你可以加入一个选择对象作为最后一个参数：
```javascript
cookie.set('key', 'value', {
   expires: 7, // expires in one week
});

cookie.set({
   key1: 'value1',
   key2: 'value2'
}, {
   expires: 7
})
```

The following fields can be added to the mentioned object:
//翻译：可以添加下面提到的对象作为参数
| key | value | default value |
|:--|:--|:--|
| `expires` |  Either a `number` containing the days until the expiry, a date in the `GMTString` format or a `date object`. | Expires when the browser is closed. |
//翻译：expires参数含义：输入一个关于天数的数字直至这个时间过完就会过期，这个日期要用‘GMTString’格式化下或者直接是一个日期对象。|默认：直至浏览器关闭后过期
| `domain` |  A `string` that specifies the domain that can access the cookie. | The current domain. |
//翻译：domain参数含义：能够指定域的一个字符串，在这个域里可以访问cookie|默认：当前域。
//（域就是domain的概念，因为浏览器是个注意安全的环境，所以不同的域之间是不能互相访问 cookie 的【当然可以通过特殊设置的达到 cookie 跨域访问】）
| `path` | A `string` that limits the access of the cookie to that path. | The current path. |
//翻译：path参数含义：限制访问cookie的路径的一个字符串|默认：当前路径才可以访问cookie
| `secure` | A `boolean` indicating whether the cookie shall only be accessable over a secure connection or not. | `false` |
//翻译：secure参数含义：指示cookie是否只能通过安全连接或不可访问的一个布尔值|默认：false

You can customize the default settings by manipulating `cookie.defaults`.
//翻译：你可以通过操纵“cookie.defaults”定制默认的设置
```javascript
cookie.defaults.expires = 7;
cookie.defaults.secure = true;
```

Most people will prefer specifying the expiry date in days, but if you want to specify the expiry date in minutes, then you can configure `cookie.expiresMultiplier`:
//大多数人喜欢用天指定cookie过期的期限，但是如果你想指定期限为几分钟，那么你可以配置`cookie.expiresMultiplier`
```javascript
cookie.expiresMultiplier = 60; // Seconds.
cookie.expiresMultiplier = 60 * 60; // Minutes.
cookie.expiresMultiplier = 60 * 60 * 24; // Hours.
```

## cookie.get
This method allows you to retrieve your cookies, you can use it by simply passing the key of the cookie:
//下面是获取cookie的一个值，适用于获取简单的key，返回的是一个字符串
```javascript
cookie.get('key');
```

Passing just one key like this will return a string, containing the value of the cookie. You can also pass an array of keys:
//下面是通过数组获取多个key的值，返回的是一个对象
```javascript
cookie.get(['key1', 'key2']);
```

This will always return an object. The keys of this object will be the keys you passed and the values are the corresponding values.
//翻译：这个方法总是返回一个对象，这个对象的键是你设置时传递的键，值也是与键相对应的值。
 In case you want to add a default value you can use the second parameter. The default value will be returned if the cookie*(s)* could not be found:
//下面是取一个key的值，当你所要取的key不存在的时候返回default value
```javascript
cookie.get('key', 'default value');
```

This also works with several keys:
//多个值同理
```javascript
cookie.get(['key1', 'key2'], 'default value');
```

`cookie()` is a shortcut for `cookie.get()`.
//翻译：cookie()是一个cookie.get()的快捷方法
```javascript
cookie.get('key');
// is the same as
cookie('key');
```

## cookie.all

```javascript
var cookies = cookie.all();
```

To get all of the currently saved cookies simply call `cookie.all`. In this case the variable `cookies` will return an object with all the current cookies.
//翻译：获取当前保存的所有cookie简单的方法是调用coolie.all。这个方法执行时变量cookies会返回一个包含当前所有cookie的对象
## cookie.remove

This method allows you to remove cookies. It accepts an infinite number of keys or an array of keys.
//翻译：这个方法允许你删除cookie，它接受无限数量的key或者是key的数组
```javascript
cookie.remove('key');
cookie.remove('key1', 'key2');
cookie.remove(['key1', 'key2']);
```

## cookie.empty

Sometimes you may want to remove all cookies. Simply call `cookie.empty()` and every cookie will be removed.
//翻译：有时你或许想删除所有的cookie，只需要简单的调用cookie.empty()方法并且所有的cookie都将被删除
## cookie.enabled

This method allows you to test if the cookies are enabled. It returns `true` if you can work with cookies and `false` if you cannot. You might want to use a fallback if they are disabled:
//翻译：这个方法允许你去测试如果这个cookie已经被激活，如果你可以操作cookie返回true，否则返回false
```javascript
if (cookie.enabled()) {
   // Do stuff with cookies
} else {
   // Display error message or use localStorage
}
```

## cookie.setDefault

This method works just like `cookie.set` and accepts the same arguments, but it
only sets those cookies that don't have a value yet allowing you to specify
default values.
//这个方法用起来很像cookie.set而且接收相同的参数，但是只能设置那些没有值的cookie，原先有值的设置了也不起作用
```javascript
cookie.set('a', '1');
cookie.setDefault({
   a: '2',
   b: '2'
});

cookie.get(['a', 'b']); // {a: "1", b: "2"}
```

## Chaining

The methods `set`, `remove` and `empty` return the cookie object and therefore enable chaining.
//set、remove、empty方法返回cookie对象而且允许链接
```javascript
cookie.empty().set('key1', 'value1').set('key2', 'value2').remove('key1');
```

## A word on encoding

cookie.js sensibly encodes / decodes values and should work just fine with most
server side frameworks. However sometimes there are weird server side encodings,
for example PHP escapes spaces with `+` for historic reasons.
This library can't handle all of those cases at the same time so if you notice
you need a custom decoding function you can overwrite `cookie.utils.decode`.
//cookie.js能聪明的解码/编码值并且能在大部分服务器和框架上工作。但是有时奇怪的服务器编码，比如PHP escapes spaces with `+` for historic reasons.
//这个库是不能处理这些事件，如果你注意了，你可以重写‘cookie.utils.decode’方法定制你需要的解码功能
 ```javascript
// For example
cookie.utils.decode = function (value) {
   return decodeURIComponent(value).replace('+', ' ');
};
```

- - -

## Wiki pages

- [Contribute](https://github.com/florian/cookie.js/wiki/Contribute)
- [Changelog](https://github.com/florian/cookie.js/wiki/Changelog)
</span>