path: root/files/zh-cn/mozilla/javascript_code_modules/dict.jsm/index.html

---
title: Dict.jsm
slug: Mozilla/JavaScript_code_modules/Dict.jsm
translation_of: Mozilla/JavaScript_code_modules/Dict.jsm
---
<p>{{ gecko_minversion_header("5.0") }}</p>

<p>{{ warning("This is obsolete - new code should use <code>Map()</code>.") }}</p>

<p>The <code>Dict.jsm</code> JavaScript code module offers routines for managing dictionaries of key/value pairs. To use it, you first need to import the code module into your JavaScript scope:</p>

<pre>Components.utils.import("resource://gre/modules/Dict.jsm");
</pre>

<h2 id="创建一个字典">创建一个字典</h2>

<p>You can create a new, empty dictionary by simply calling the <code>Dict()</code> constructor:</p>

<pre>var newDict = new Dict();
</pre>

<p>If you wish, you may also pass in an <a href="/zh-CN/JavaScript/Guide/Values,_variables,_and_literals#Object_literals" title="zh-CN/JavaScript/Guide/Values,_variables,_and_literals#Object_literals">object literal</a> of key/value pairs with which to initialize the dictionary:</p>

<pre>var someObj = {};
var newDict = new Dict({key1: "foo", key2: someObj});
</pre>

<p>Note that values may be any JavaScript object type.</p>

<div class="note"><strong>Note:</strong> You can actually specify non-strings as keys; these are converted to strings before being used, so they're documented here as if they were a string parameter.</div>

<p>从Firefox 19开始,你可以通过传入一个<a href="/zh-CN/JSON" title="zh-CN/JSON">JSON字符串</a>来初始化字典对象:</p>

<pre>var someJSON = '{key1: "foo", key2: {}}';
var newDict = new Dict(someJSON);
</pre>

<div class="note"><strong>注:</strong> 传入的任意字符串都会被当成JSON字符串来对待.</div>

<h2 id="Method_overview" name="Method_overview">方法概述</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code>Dict <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#copy()" title="zh-CN/JavaScript code modules/Dict.jsm#copy()">copy</a>();</code></td>
  </tr>
  <tr>
   <td><code>boolean <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#del()" title="zh-CN/JavaScript code modules/Dict.jsm#del()">del</a>(<a href="/zh-CN/JavaScript/Reference/Global_Objects/String" title="zh-CN/JavaScript/Reference/Global Objects/String">String</a> aKey);</code></td>
  </tr>
  <tr>
   <td><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/Object" title="zh-CN/JavaScript/Reference/Global Objects/Object">Object</a> <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#get()" title="zh-CN/JavaScript code modules/Dict.jsm#get()">get</a>(</code><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/String" title="zh-CN/JavaScript/Reference/Global Objects/String">String</a></code><code> </code><code>aKey</code><code>, [optional] </code><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/Object" title="zh-CN/JavaScript/Reference/Global Objects/Object">Object</a></code><code> aDefault);</code></td>
  </tr>
  <tr>
   <td><code>boolean <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#has()" title="zh-CN/JavaScript code modules/Dict.jsm#has()">has</a>(</code><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/String" title="zh-CN/JavaScript/Reference/Global Objects/String">String</a></code><code> </code><code>aKey</code><code>);</code></td>
  </tr>
  <tr>
   <td><code>Array <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#listitems()" title="zh-CN/JavaScript code modules/Dict.jsm#listitems()">listitems</a>();</code></td>
  </tr>
  <tr>
   <td><code>Array <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#listkeys()" title="zh-CN/JavaScript code modules/Dict.jsm#listkeys()">listkeys</a>();</code></td>
  </tr>
  <tr>
   <td><code>Array <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#listvalues()" title="zh-CN/JavaScript code modules/Dict.jsm#listvalues()">listvalues</a>();</code></td>
  </tr>
  <tr>
   <td><code>void <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#set()" title="zh-CN/JavaScript code modules/Dict.jsm#set()">set</a>(String </code><code>aKey</code><code>, </code><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/Object" title="zh-CN/JavaScript/Reference/Global Objects/Object">Object</a></code><code> aValue);</code></td>
  </tr>
  <tr>
   <td>{{ fx_minversion_inline("19") }} <code><a href="/zh-CN/JavaScript/Reference/Global_Objects/String" title="zh-CN/JavaScript/Reference/Global Objects/String">String</a></code><code> <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#toJSON()" title="zh-CN/JavaScript code modules/Dict.jsm#toJSON()">toJSON</a>();</code></td>
  </tr>
  <tr>
   <td><code><a href="/zh-CN/JavaScript/Reference/Global_Objects/String" title="zh-CN/JavaScript/Reference/Global Objects/String">String</a></code><code> <a href="/zh-CN/JavaScript_code_modules/Dict.jsm#toString()" title="zh-CN/JavaScript code modules/Dict.jsm#toString()">toString</a>();</code></td>
  </tr>
 </tbody>
</table>

<h2 id="属性">属性</h2>

<table class="standard-table" style="width: auto;">
 <tbody>
  <tr>
   <td class="header">属性名</td>
   <td class="header">类型</td>
   <td class="header">描述</td>
  </tr>
  <tr>
   <td><code>count</code></td>
   <td><a href="/zh-CN/JavaScript/Reference/Global_Objects/Number" title="zh-CN/JavaScript/Reference/Global Objects/Number"><code>Number</code></a></td>
   <td>字典中键值对的个数</td>
  </tr>
  <tr>
   <td><code>items</code></td>
   <td><code>Iterator</code></td>
   <td>
    <p>Returns an iterator over all of the items in the dictionary; each item is returned as a pair (a two-element array) with the first element being the key and the second being the value.</p>

    <div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.</div>
   </td>
  </tr>
  <tr>
   <td><code>keys</code></td>
   <td><code>Iterator</code></td>
   <td>
    <p>Returns an iterator over all the keys in the dictionary.</p>

    <div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.</div>
   </td>
  </tr>
  <tr>
   <td><code>values</code></td>
   <td><code>Iterator</code></td>
   <td>
    <p>Returns an iterator over all the values in the dictionary.</p>

    <div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.</div>
   </td>
  </tr>
 </tbody>
</table>

<h2 id="构造器">构造器</h2>

<h2 id="Dict()">Dict()</h2>

<p>创建并返回一个新的字典对象.</p>

<pre>Dict Dict();

Dict Dict(
  Object initalKeysAndValues
);
</pre>

<h6 id="参数">参数</h6>

<dl>
 <dt><code>initialKeysAndValues</code> {{ optional_inline() }}</dt>
 <dd>A object containing key/value pairs with which to initialize the dictionary.</dd>
</dl>

<h6 id="返回值">返回值</h6>

<p>一个新的字典对象,实现有下面这些方法.</p>

<h2 id="Methods" name="Methods">方法</h2>

<h2 id="copy()">copy()</h2>

<p>返回一个字典对象的浅拷贝; that is, a copy of the dictionary including the items immediately included within the dictionary; however, any objects referenced by those top-level objects are not copied.</p>

<pre>Dict copy();
</pre>

<h6 id="参数_2">参数</h6>

<p>无</p>

<h6 id="返回值_2">返回值</h6>

<p>A new dictionary object containing the same top-level items as the original dictionary on which the <code>copy()</code> method was called.</p>

<h2 id="del()">del()</h2>

<p>根据指定的键,从该字典中删除一个键值对.</p>

<pre>boolean del(
  String aKey
);
</pre>

<h6 id="参数_3">参数</h6>

<dl>
 <dt><code>aKey</code></dt>
 <dd>从该字典中要删除的键.</dd>
</dl>

<h6 id="返回值_3">返回值</h6>

<p>如果成功删除指定的键值对,则返回<code>true</code>,如果指定的键不存在,则返回<code>false</code>.</p>

<h2 id="get()">get()</h2>

<p>返回该字典对象中指定键所对应的值.</p>

<pre><code>Object get(
  String </code><code>aKey</code><code>,
  [optional] Object aDefault
);</code>
</pre>

<h6 id="参数_4">参数</h6>

<dl>
 <dt><code>aKey</code></dt>
 <dd>The key whose value should be returned.</dd>
 <dt><code>aDefault</code> {{ optional_inline() }}</dt>
 <dd>The value to return if the specified key isn't found. If you don't specify a default value, <code>undefined</code> is returned for keys that aren't found.</dd>
</dl>

<h6 id="返回值_4">返回值</h6>

<p>The value of the specified key, or <code>undefined</code> if no matching key was found.</p>

<h2 id="has()">has()</h2>

<p>判断指定的键是否存在与当前字典对象中.</p>

<pre><code>boolean has(
  String </code><code>aKey
</code><code>);</code>
</pre>

<h6 id="参数_5">参数</h6>

<dl>
 <dt><code>aKey</code></dt>
 <dd>判断该键是否存在与当前字典对象中..</dd>
</dl>

<h6 id="返回值_5">返回值</h6>

<p>如果指定的键存在与当前字典中,则返回<code>true</code>,否则返回<code>false</code>.</p>

<h2 id="listitems()">listitems()</h2>

<p>返回一个由当前字典中所有键值对组成的数组.</p>

<div class="note">注: 数组中元素的排列顺序是任意的.</div>

<pre>Array listitems();
</pre>

<h6 id="参数_6">参数</h6>

<p>无</p>

<h6 id="返回值_6">返回值</h6>

<p>一个由当前字典中所有键值对组成的数组.</p>

<h2 id="listkeys()">listkeys()</h2>

<p>返回一个由当前字典中所有键组成的数组.</p>

<div class="note"><strong>注:</strong> 数组中元素的排列顺序是任意的.</div>

<pre>Array listkeys();
</pre>

<h6 id="参数_7">参数</h6>

<p>无</p>

<h6 id="返回值_7">返回值</h6>

<p>一个由当前字典中所有键组成的数组.</p>

<h2 id="listvalues()">listvalues()</h2>

<p>返回一个由当前字典中所有值组成的数组.</p>

<div class="note"><strong>注:</strong> 数组中元素的排列顺序是任意的.</div>

<pre>Array listvalues();
</pre>

<h6 id="参数_8">参数</h6>

<p>无</p>

<h6 id="返回值_8">返回值</h6>

<p>一个由当前字典中所有值组成的数组.</p>

<h2 id="set()">set()</h2>

<p>设置指定键所对应的值,如果该键不存在,则添加上这个新键.</p>

<pre><code>void set(
  String </code><code>aKey</code><code>,
  Object aValue
);</code>
</pre>

<h6 id="参数_9">参数</h6>

<dl>
 <dt><code>aKey</code></dt>
 <dd>设置改建所对应的值.</dd>
 <dt><code>aValue</code></dt>
 <dd>为指定键所设置的新值.</dd>
</dl>

<h2 id="toJSON()">toJSON()</h2>

<p>返回一个代表当前字典的 <a href="/zh-CN/JSON" title="zh-CN/JSON">JSON字符串</a>.</p>

<pre>String toJSON();
</pre>

<h6 id="参数_10">参数</h6>

<p>无</p>

<h6 id="返回值_9">返回值</h6>

<p>返回一个代表了该字典对象中所有键值对的JSON字符串,空字典将返回"{}".</p>

<h2 id="toString()">toString()</h2>

<p>返回一个代表该字典对象的字符串.</p>

<pre>String toString();
</pre>

<h6 id="参数_11">参数</h6>

<p>无</p>

<h6 id="返回值_10">返回值</h6>

<p>返回一个代表了该字典对象中所有键值对的字符串,空字典将返回"{}".</p>

<h2 id="示例">示例</h2>

<h3 id="创建和填充字典">创建和填充字典</h3>

<p>下面的例子首先创建一个新的空字典,然后添加进一些键值对.</p>

<pre class="brush: js">var myDict = new Dict();
myDict.set("name", "John Smith");
myDict.set("email", "jsmith@example.com");
myDict.set("phone", "650-555-1234");
</pre>

<h3 id="判断字典中指定的键是否存在">判断字典中指定的键是否存在</h3>

<p>接着上面的个例子,你可以检测某个键是否存在于<code>myDict</code>中:</p>

<pre class="brush: js">if (myDict.has("email")) {
  /* an "email" key exists on the object */
}
</pre>