* update chosen document.

27bfd32b · Catouse · 2b2fe8a2 · 27bfd32b
隐藏空白更改
内联并排

Showing with 234 addition and 3 deletion

docs/part/javascript-chosen.html docs/part/javascript-chosen.html +234 -3

未找到文件。
--- a/docs/part/javascript-chosen.html
+++ b/docs/part/javascript-chosen.html
@@ -3,8 +3,9 @@
 </article>
 <section>
-  <header><h3>多项选择和单项选择</h3></header>
+  <header><h3>示例</h3></header>
  <article>
+    <h4>单项选择和多项选择</h4>
    <div class="example">
      <div class="row">
        <div class="col-md-6">
@@ -29,18 +30,247 @@
        </div>
      </div>
    </div>
+    <pre class='prettyprint'><code>$('select.chosen-select').chosen({
+    no_results_text: '没有找到',    // 当检索时没有找到匹配项时显示的提示文本
+    disable_search_threshold: 10, // 10 个以下的选择项则不显示检索框
+    search_contains: true         // 从任意位置开始检索
+});</code></pre>
+    <h4>扩展检索</h4>
+    <p>有时我们希望用户检索的更加开心，例如为汉语选项添加拼音检索支持。Chosen提供了扩展字段专门用来检索，只需要为<code>&lt;option&gt;</code>标签增加<code>data-keys="*"</code>属性。</p>
+    <p><code>data-keys</code>属性可以用空格或英文逗号来分隔多个供检索的关键字。</p>
+    <div class="example">
+      <select data-placeholder="使用拼音检索，试试“m”或“xm”" class="chosen-select form-control" tabindex="2">
+        <option value=""></option>
+        <option value="cat" data-keys="xiaomao xm 猫科动物">小猫</option>
+        <option value="fish" data-keys="jinyu jy">金鱼</option>
+        <option value="dragon" data-keys="long">龙</option>
+        <option value="mammoth" data-keys="mengma mm">猛犸</option>
+        <option value="gollum" data-keys="gulu gl 神话">咕噜</option>
+      </select>
+    </div>
+    <div class='alert alert-primary-inverse'>
+      <h4>提示</h4>
+      <p>扩展检索本身并不提供拼音检索功能，如果你需要支持使用拼音检索时，需要你自己在chosen初始化之前在<code>data-keys</code>属性中写入拼音字符串。</p>
+    </div>
+  </article>
+</section>
+<section>
+  <header><h3>用法</h3></header>
+  <article>
+    <h4>启动参数</h4>
+    <table class="table table-bordered">
+      <thead>
+        <tr>
+          <th>参数</th>
+          <th style="width: 80px">名称</th>
+          <th style="width: 300px">可选值</th>
+          <th>说明</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>lang</code></td>
+          <td>界面语言</td>
+          <td>
+            <ul>
+              <li><code>'zh_cn'</code>（默认），中文简体</li>
+              <li><code>'zh_tw'</code>中文繁体</li>
+              <li><code>'en'</code>，英文</li>
+            </ul>
+          </td>
+          <td>如果不设置此值，会自动优先从<code>&lt;html lang=""&gt;</code>属性作为界面语言设置。</td>
+        </tr>
+        <tr>
+          <td><code>allow_single_deselect</code></td>
+          <td>允许取消单选</td>
+          <td>
+            <ul>
+              <li><code>true</code> 允许取消</li>
+              <li><code>false</code>（默认） 不允许</li>
+            </ul>
+          </td>
+          <td>如果允许单选取消，则会在用户选择选项之后，显示一个移除按钮，点击此按钮会移除用户选择的项目。</td>
+        </tr>
+        <tr>
+          <td><code>disable_search</code></td>
+          <td>禁用检索</td>
+          <td>
+            <ul>
+              <li><code>false</code>（默认) 不禁用</li>
+              <li><code>true</code> 禁用</li>
+            </ul>
+          </td>
+          <td>
+            禁用检索功能，将不再现实搜索框来让用户检索选项。
+          </td>
+        </tr>
+        <tr>
+          <td><code>disable_search_threshold</code></td>
+          <td>自动禁用的最大值</td>
+          <td>数字，默认为<code>0</code></td>
+          <td>当可选选项数目小于或等于此值时，自动禁用检索选项。</td>
+        </tr>
+        <tr>
+          <td><code>inherit_select_classes</code></td>
+          <td>继承select的CLASS</td>
+          <td>默认为<code>false</code></td>
+          <td>如果设置为<code>true</code>，chosen在初始化之后会获取原<code>&lt;select&gt;</code>上的CSS CLASS值并添加在chosen容器<code>&lt;div&gt;</code>上。</td>
+        </tr>
+        <tr>
+          <td><code>max_selected_options</code></td>
+          <td>最大选择数目</td>
+          <td>数字，默认为<code>Infinity</code></td>
+          <td>仅多选生效；当用户选择的选项数目达到此值时，将会触发<code>chosen:maxselected</code>事件。</td>
+        </tr>
+        <tr>
+          <td><code>no_results_text</code></td>
+          <td>无结果时的文本</td>
+          <td>字符串，默认从语言配置获取</td>
+          <td>当用户检索时没有匹配的结果会显示此文本。</td>
+        </tr>
+        <tr>
+          <td><code>placeholder_text</code></td>
+          <td>空值占位文本</td>
+          <td>字符串，默认为<code>""</code></td>
+          <td>当用户没有选择选项时显示此文本；此选项也可以通过<code>&lt;select&gt;</code>的<code>data-placeholder</code>属性来指定。</td>
+        </tr>
+        <tr>
+          <td><code>placeholder_text_multiple</code></td>
+          <td>多选空值占位文本</td>
+          <td>字符串，默认为<code>""</code></td>
+          <td>如果没有设置此选项，则会尝试读取<code>placeholder_text</code>选项的值。</td>
+        </tr>
+        <tr>
+          <td><code>placeholder_text_single</code></td>
+          <td>单选空值占位文本</td>
+          <td>字符串，默认为<code>""</code></td>
+          <td>如果没有设置此选项，则会尝试读取<code>placeholder_text</code>选项的值。</td>
+        </tr>
+        <tr>
+          <td><code>search_contains</code></td>
+          <td>启用任意位置检索</td>
+          <td>默认为<code>false</code></td>
+          <td>默认情况下，仅仅会从选项或检索关键字的开始进行匹配，例如<code>"he"</code>仅仅能匹配<code>"hello"</code>，不能匹配<code>"ahead"</code>，如果启用此选项，则可以从关键的任意位置进行匹配。</td>
+        </tr>
+        <tr>
+          <td><code>single_backstroke_delete</code></td>
+          <td>启用退格键删除</td>
+          <td>默认为<code>true</code></td>
+          <td>仅多选生效；启用此选项允许用户在多选时按退格键（Backspace）和删除键（Delete）来删除上一个选择项。</td>
+        </tr>
+        <tr>
+          <td><code>width</code></td>
+          <td>宽度</td>
+          <td>默认为原始<code>&lt;select&gt;</code>的宽度</td>
+          <td>默认chosen的宽度与原始的<code>&lt;select&gt;</code>一致，如果原始的<code>&lt;select&gt;</code>在chosen初始化之前不可见，可能需要手动指定一个宽度，否则chosen的宽度会为<code>0</code>；如果使用响应式布局，建议宽度设定为<code>'100%'</code>。</td>
+        </tr>
+        <tr>
+          <td><code>display_disabled_options</code></td>
+          <td>显示不可选的选项</td>
+          <td>默认为<code>true</code></td>
+          <td>默认情况下会在选项列表中显示不可选的选项，禁用此选项来隐藏不可选的选项。</td>
+        </tr>
+        <tr>
+          <td><code>display_selected_options</code></td>
+          <td>显示已选择的选项</td>
+          <td>默认为<code>true</code></td>
+          <td>仅多选生效；禁用此选项则在选项列表中隐藏已选择的选项。</td>
+        </tr>
+      </tbody>
+    </table>
+    <h5>事件</h5>
+    <p>Chosen的事件绑定在原始<code>&lt;select&gt;</code>上，使用jQuery方法来监听事件。目前可以使用以下事件：</p>
+    <table class="table table-bordered">
+      <thead>
+        <tr>
+          <th>事件</th>
+          <th>说明</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>change</code></td>
+          <td>当选择的值发生改变时发生。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:ready</code></td>
+          <td>当完成初始化之后触发。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:maxselected</code></td>
+          <td>当达到最大选择数目（通过<code>max_selected_options</code>指定）时发生</td>
+        </tr>
+        <tr>
+          <td><code>chosen:showing_dropdown</code></td>
+          <td>当弹出显示选项列表时发生。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:hiding_dropdown</code></td>
+          <td>当隐藏选项列表时发生。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:no_results</code></td>
+          <td>当没有检索到匹配的选项时发生。</td>
+        </tr>
+      </tbody>
+    </table>
+    <pre class='prettyprint'><code>$('select.chosen-select').on('change', function(){
+    // 用户改变了选择，快快处理
+});</code></pre>
+    <h5>方法</h5>
+    <p>可以通过触发事件来调用chosen的方法。</p>
+    <pre class='prettyprint'><code>// 当原始select中的选项发生变化时通知chosen更新选项列表
+$('select.chosen-select').trigger('chosen:updated');</code></pre>
+    <p>所有可以通过事件触发的方法有：</p>
+    <table class="table table-bordered">
+      <thead>
+        <tr>
+          <th>触发事件</th>
+          <th>说明</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>chosen:updated</code></td>
+          <td>通知chosen重新从原始select中更新选项列表。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:activate</code></td>
+          <td>让chosen激活并获取焦点；激活之后的chosen会捕获用户输入并执行操作。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:open</code></td>
+          <td>打开（弹出）选项列表面板。</td>
+        </tr>
+        <tr>
+          <td><code>chosen:close</code></td>
+          <td>隐藏选项列表面板。</td>
+        </tr>
+      </tbody>
+    </table>
+    <p>详细用法可以参考<a href="http://harvesthq.github.io/chosen/options.html" target="_blank">chosen官方文档</a>。</p>
  </article>
 </section>
 <section>
  <header><h3>图标选择插件</h3></header>
  <article>
-    <p>为方便选择漂亮的图标，依赖于Chosen新作了图标选择插件。</p>
+    <h4>示例</h4>
+    <p>为方便选择<a href="#control/icon">漂亮的图标</a>，依赖于Chosen新作了<a href="#control/icon">图标</a>选择插件。</p>
    <div class="example">
      <form>
-        <select class="chosen-select-icons form-control" name="chosenIcons" id="chosenIcons" data-value='icon-star'></select>
+        <select class="chosen-icons form-control" name="chosenIcons" id="chosenIcons" data-value='icon-star'></select>
      </form>
    </div>
+    <pre class='prettyprint'><code>$('select.chosen-icons').chosenIcons(options);</code></pre>
+    <div class='alert alert-primary-inverse'>
+      <h5>提示</h5>
+      <p>图标选择插件依赖chosen插件，且是单独提供的。也就是说如果你没有使用自定制版，不仅仅需要在HTML文件中加载chosen插件，还需要额外加载 [zui/lib/chosen/chosen.icons*.js, zui/lib/chosen/chosen.icons*.css] 文件。</p>
+    </div>
+    <h4>用法</h4>
+    <p>图标选择插件可以使用chosen的所有选项和方法。</p>
  </article>
 </section>
@@ -49,6 +279,7 @@ function onPageLoad() {return false;}
 function afterPageLoad() {
    if($.fn.chosen) $('#pageBody .chosen-select').chosen({
        allow_single_deselect: true,
+        search_contains: true
    });
    if($.fn.chosenIcons) $('#chosenIcons').chosenIcons();
    setTimeout($.doc.stopPageLoading, 500);