* update tree document.

9196e8ba · Catouse · ae2c3d6f · 9196e8ba · 9196e8ba
隐藏空白更改
内联并排

Showing with 286 addition and 20 deletion

docs/index.json docs/index.json +12 -4

docs/part/view-tree.html docs/part/view-tree.html +274 -16

未找到文件。
--- a/docs/index.json
+++ b/docs/index.json
@@ -151,11 +151,17 @@
                "topics": [{
                    "name": "新版本更新明细"
                }, {
-                    "name": "[1.4] 树形菜单",
-                    "url": "#view/tree"
+                    "name": "[1.5] 布局",
+                    "url": "#basic/layout"
                }, {
-                    "name": "[1.4] 主题",
-                    "url": "#basic/theme"
+                    "name": "[1.5] 拖拽选取",
+                    "url": "#javascript/selectable"
+                }, {
+                    "name": "[1.5] 颜色选择器",
+                    "url": "#javascript/colrpicker"
+                }, {
+                    "name": "[1.5] 树形菜单：数据加载与更新",
+                    "url": "#view/tree/3"
                }]
            }, {
                "id": "qqgroup",
@@ -947,6 +953,8 @@
                    "name": "外观选项"
                }, {
                    "name": "用法"
+                }, {
+                    "name": "数据加载与更新"
                }],
                "filter": "shuxingcaidan sxcd shuxcd"
            }, {

--- a/docs/part/view-tree.html
+++ b/docs/part/view-tree.html
@@ -13,6 +13,7 @@
  </header>
  <article>
    <p>下方展示了一个树形菜单，当一个链接包含一个子菜单时，通过点击链接左侧的图标可以展开内部子菜单。子菜单中的链接也可以包含另一个子菜单。</p>
+    <p>要构建一个树形菜单，只需要按层级嵌套 <code>&lt;ul&gt;</code>，并为顶层节点添加 <code>[data-ride="tree"]</code> 属性。</p>
    <div class="example">
      <ul id="treeExample" class="tree" data-ride="tree" data-initial-state="preserve">
        <li>
@@ -134,7 +135,13 @@
            <li><a href="#">草莓</a></li>
            <li><a href="#">杏</a></li>
            <li><a href="#">桃子</a></li>
-            <li><a href="#">梅子</a></li>
+            <li>
+              <a href="#">莓</a>
+              <ul>
+                <li><a href="">黑莓</a></li>
+                <li><a href="">蓝莓</a></li>
+              </ul>
+            </li>
          </ul>
        </li>
        <li>
@@ -351,31 +358,161 @@
            当使用<code>'normal'</code>选项时，如果一个<code>&lt;li&gt;</code>标签包含class<code>.open</code>且包含内部子菜单则子菜单（不包括子菜单的子菜单）在初始化之后会展开显示，其他情况下则折叠显示。
          </td>
        </tr>
+        <tr>
+          <td><code>data</code></td>
+          <td>树节点数据</td>
+          <td>数组，包含所有节点对象，可选</td>
+          <td>格式参见本页面 <strong>数据加载与更新</strong> 章节。</td>
+        </tr>
+        <tr>
+          <td><code>itemCreator</code></td>
+          <td>节点创建函数</td>
+          <td>函数</td>
+          <td>节点创建函数用法参见本页面 <strong>数据加载与更新</strong> 章节。</td>
+        </tr>
+        <tr>
+          <td><code>itemWrapper</code></td>
+          <td>节点包装器</td>
+          <td>
+            <ul>
+              <li><code>false</code>（默认) 不启用节点包装器</li>
+              <li><code>true</code> 启用默认节点包装器</li>
+              <li>例如 <code>'&lt;div class=&quot;my-tree-node/&quot;&gt;'</code>：用来创建节点包装器的 HTML 文本</li>
+            </ul>
+          </td>
+          <td>用法参见本页面 <strong>数据加载与更新</strong> 章节。</td>
+        </tr>
      </tbody>
    </table>
    <p>参数可以在手动调用<code>$().tree(options)</code>方法时传入，或者以<code>data-*=""</code>形式指定。</p>
+    
    <h4>方法</h4>
-    <h5>展开菜单</h5>
-    <pre class='prettyprint'><code>$('#tree').tree('expand', params);</code></pre>
-    <p><code>params</code>参数可选值如下：</p>
+
+    <h5>展开节点</h5>
+    <p>方法可用形式如下：</p>
+    <ul>
+      <li><strong class="code text-danger">expand()</strong></li>
+      <li><strong class="code text-danger">expand(params)</strong></li>
+      <li><strong class="code text-danger">expand(params, disabledAnimate)</strong></li>
+    </ul>
+    <p>参数定义如下：</p>
+    <ul>
+      <li><code>params</code>：一个jQuery<code>&lt;li&gt;</code>对象，指定需要展开的节点，当不使用此参数时则展开所有节点；</li>
+      <li><code>disabledAnimate</code>：是否禁用动画，默认 <code>false</code>；</li>
+    </ul>
+    <pre class='prettyprint'><code>// 使用 tree 实例
+var myTree = $('#tree').data('zui.tree');
+myTree.expand(params);
+
+// 使用 tree() 方式
+$('#tree').tree('expand', params);</code></pre>
+
+    <h5>折叠节点</h5>
+    <p>方法可用形式如下：</p>
    <ul>
-      <li>空参数，展开所有层级的子菜单；</li>
-      <li>一个jQuery<code>&lt;li&gt;</code>对象，指定需要展开的菜单。</li>
+      <li><strong class="code text-danger">collapse()</strong></li>
+      <li><strong class="code text-danger">collapse(params)</strong></li>
+      <li><strong class="code text-danger">collapse(params, disabledAnimate)</strong></li>
    </ul>
-    <h5>折叠菜单</h5>
-    <pre class='prettyprint'><code>$('#tree').tree('collapse', params);</code></pre>
-    <p><code>params</code>参数可选值如下：</p>
+    <p>参数定义如下：</p>
    <ul>
-      <li>空参数，折叠所有层级的子菜单；</li>
-      <li>一个jQuery<code>&lt;li&gt;</code>对象，指定需要折叠的菜单。</li>
+      <li><code>params</code>：一个jQuery<code>&lt;li&gt;</code>对象，指定需要折叠的节点，当不使用此参数时则折叠所有节点；</li>
+      <li><code>disabledAnimate</code>：是否禁用动画，默认 <code>false</code>；</li>
    </ul>
-    <h5>切换菜单</h5>
-    <pre class='prettyprint'><code>$('#tree').tree('toggle', params);</code></pre>
-    <p><code>params</code>参数可选值如下：</p>
+    <pre class='prettyprint'><code>// 使用 tree 实例
+var myTree = $('#tree').data('zui.tree');
+myTree.collapse(params);
+
+// 使用 tree() 方式
+$('#tree').tree('collapse', params);</code></pre>
+
+    <h5>切换节点</h5>
+    <p>使得节点在展开或折叠的状态间切换。</p>
+    <p>方法可用形式如下：</p>
+    <ul>
+      <li><strong class="code text-danger">toggle()</strong></li>
+      <li><strong class="code text-danger">toggle(params)</strong></li>
+      <li><strong class="code text-danger">toggle(params, disabledAnimate)</strong></li>
+    </ul>
+    <p>参数定义如下：</p>
+    <ul>
+      <li><code>params</code>：一个jQuery<code>&lt;li&gt;</code>对象，指定需要切换的节点，当不使用此参数时则切换所有节点；</li>
+      <li><code>disabledAnimate</code>：是否禁用动画，默认 <code>false</code>；</li>
+    </ul>
+    <pre class='prettyprint'><code>// 使用 tree 实例
+var myTree = $('#tree').data('zui.tree');
+myTree.toggle(params);
+
+// 使用 tree() 方式
+$('#tree').tree('toggle', params);</code></pre>
+
+    <h5>展示节点</h5>
+    <p>展开当前节点及所有子节点。</p>
+    <p>方法可用形式如下：</p>
+    <ul>
+      <li><strong class="code text-danger">show()</strong></li>
+      <li><strong class="code text-danger">show(params)</strong></li>
+      <li><strong class="code text-danger">show(params, disabledAnimate)</strong></li>
+    </ul>
+    <p>参数定义如下：</p>
+    <ul>
+      <li><code>params</code>：一个jQuery<code>&lt;li&gt;</code>对象，指定需要展示的节点，当不使用此参数时则展示所有节点；</li>
+      <li><code>disabledAnimate</code>：是否禁用动画，默认 <code>false</code>；</li>
+    </ul>
+    <pre class='prettyprint'><code>// 使用 tree 实例
+var myTree = $('#tree').data('zui.tree');
+myTree.show(params);
+
+// 使用 tree() 方式
+$('#tree').tree('show', params);</code></pre>
+
+    <h5>添加节点</h5>
+    <p>向树添加节点有两种方式：一种是通过 jQuery 方式向树中插入符合树所要求的 DOM 节点即可；另一种方式使用树实例方法 <code>add($element, items)</code> 添加节点数据，该方法的可选形式为：</p>
    <ul>
-      <li>空参数，切换所有层级的子菜单；</li>
-      <li>一个jQuery<code>&lt;li&gt;</code>对象，指定需要切换的菜单。</li>
+      <li><strong class="text-danger code">add($element, items)</strong></li>
+      <li><strong class="text-danger code">add($element, items, expand)</strong></li>
+      <li><strong class="text-danger code">add($element, items, expand, disabledAnimate)</strong></li>
    </ul>
+    <p>最后三个参数可以依次省略，参数定义如下：</p>
+    <ul>
+      <li><code>$element</code>：要插入的父节点（jQuery 实例），可以为 <code>&lt;ul&gt;</code> 或 <code>&lt;li&gt;</code>；</li>
+      <li><code>items</code>：数组，要插入的节点数据；</li>
+      <li><code>expand</code>，插入后是否立即展开；</li>
+      <li><code>disabledAnimate</code>：插入后如果需要立即展开是否禁用动画效果。</li>
+    </ul>
+    <pre><code>// 获取 tree 实例
+var myTree = $('#myTree').data('zui.tree');
+
+// 准备插入的数据
+var newItems = [{title: '新的节点'}, ...];
+
+// 插入数据到根节点
+myTree.add('#myTree', newItems);</code></pre>
+
+    <h5>导出树数据</h5>
+    <p>当添加了新的节点或者移除了节点之后，如果此时需要获取当前树更新后的数据，可以使用 <code>toData([$ul], [filter])</code> 方法。该方法拥有如下形式：</p>
+    <ul>
+      <li><strong class="text-danger code">toData()</strong></li>
+      <li><strong class="text-danger code">toData($ul)</strong></li>
+      <li><strong class="text-danger code">toData(filter)</strong></li>
+      <li><strong class="text-danger code">toData($ul, filter)</strong></li>
+    </ul>
+    <p>参数定义如下：</p>
+    <ul>
+      <li><strong class="text-danger code">$ul</strong>：指定树种需要导出数据的 <code>&lt;ul&gt;</code> 节点。默认为树的根节点，及导出整个树的所有节点数据。</li>
+      <li><strong class="text-danger code">filter</strong>：指定一个回调函数用于转换数据为合适的格式。该回调函数包括两个参数：<code>item</code>，正在导出的节点数据；<code>$li</code>，正在导出的 <code>&lt;li&gt;</code> 节点对象；必须在此回调函数中返回一个 JavaScript 对象。</li>
+    </ul>
+    <pre><code>// 获取 tree 实例
+var myTree = $('#myTree').data('zui.tree');
+
+// 此处可以更新数结构
+
+// 获取更新后的树数据
+var myTreeData = myTree.toData(function(item, $li) {
+    item._id = $li.data('id');
+    return item;
+});</code></pre>
+
    <h4>事件</h4>
    <table class="table table-bordered">
      <thead>
@@ -425,3 +562,124 @@ function afterPageLoad() {
    $('[data-ride=tree]').tree();
 }
 </script>
+
+<section>
+  <header>
+    <h3>数据加载与更新</h3>
+  </header>
+  <article>
+    <h4>使用数据初始化</h4>
+    <p>在初始化树形菜单时可以使用 <code>data</code> 选项来指定用户构建树的数据。这种方式允许你在恰当时机来展示树（例如从远处服务器获取数据再进行展示）。</p>
+    <p>用户初始化的数据为一个数组，每个数组中包含若干个对象来用于创建树中的节点（以下简称为节点对象）。</p>
+    <p>节点对象中可能包含的属性如下：</p>
+    <table class="table table-bordered">
+      <thead>
+        <tr>
+          <th style="width: 90px">属性</th>
+          <th style="width: 250px">可取的值示例</th>
+          <th>说明</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>title</code></td>
+          <td><code>'第一个节点'</code></td>
+          <td>在节点上展示的文本。</td>
+        </tr>
+        <tr>
+          <td><code>url</code></td>
+          <td><code>'http://zui.sexy'</code></td>
+          <td>可选，以链接的形式显示节点，指定链接地址。</td>
+        </tr>
+        <tr>
+          <td><code>html</code></td>
+          <td><code>'&lt;strong&gt;&#x7740;&#x91cd;&#x5f3a;&#x8c03;&#x7684;&#x8282;&#x70b9;&lt;/strong&gt;'</code></td>
+          <td>可选，用于设置为节点 HTML 的内容，如果指定此选项，则 <code>title</code> 选项可以省略。</td>
+        </tr>
+        <tr>
+          <td><code>children</code></td>
+          <td><code>[{title: '子节点1'}, {title: '子节点2'}, ...]</code></td>
+          <td>可选，以数组的形式设置该节点下的所有子节点，子节点的设置方式与初始化数据一致。这种递归结构与树本身的嵌套结构一致。</td>
+        </tr>
+        <tr>
+          <td><code>open</code></td>
+          <td><code>true</code>，<code>false</code>（默认）</td>
+          <td>可选，如果该节点包含子节点，是否展开当前节点。</td>
+        </tr>
+        <tr>
+          <td><code>id</code></td>
+          <td>默认不设置</td>
+          <td>用于设置到树节点 <code>&lt;li&gt;</code> 上的 <code>[data-id]</code> 属性的值，如果设置此属性请确保每一个节点的值在整个树种唯一。</td>
+        </tr>
+      </tbody>
+    </table>
+    <p>除了以上已经定义的命名属性，你仍然可以在节点数据中包含自定义的属性和数据。</p>
+    <p>以下代码演示了使用数据来初始化一个空的 <code>&lt;ul class=&quot;tree&quot;&gt;</code>：</p>
+    <pre><code>&lt;!-- &#x521b;&#x5efa;&#x4e00;&#x4e2a;&#x7a7a;&#x7684;&#x6811;&#xff0c;&#x9700;&#x8981;&#x5305;&#x542b; .tree CLASS --&gt;
+&lt;ul class=&quot;tree&quot; id=&quot;myTree&quot;&gt;&lt;/ul&gt;</code></pre>
+    <pre><code>var myTreeData = [{
+    title: '水果',
+    url: 'http://zui.sexy',
+    open: true,
+    children: [
+        {title: '橘子'},
+        {
+            title: '瓜',
+            children: [
+              {title: '西瓜'},
+              {title: '黄瓜'}
+            ]
+        }
+    ]
+}, {
+    title: '坚果',
+    children: [
+        {title: '向日葵'},
+        {title: '瓜子'}
+    ]
+}, {
+    title: '蔬菜'
+}];
+
+$('#myTree').tree({data: myTreeData});</code></pre>
+    <h4>动态更新数据</h4>
+    <p>当树初始化之后，仍然可以使用 <code>reload(data)</code> 方法来动态更新数据。</p>
+    <pre><code>// 获取 tree 实例
+var myTree = $('#myTree').data('zui.tree');
+
+// 准备新的数据
+var myNewTreeData = [...];
+
+// 更新数据
+myTree.reload(myNewTreeData);</code></pre>
+
+    <h4>使用节点构造器</h4>
+    <p>通过节点构造器可以方便的自定义节点的 DOM 内容。使用初始化选项 <code>itemCreator</code> 来定义节点构造器回调函数。节点构造器会在初始化节点数据或更新节点数据时被调用，其形式如下：</p>
+    <ul>
+      <li><strong class="code">function($li, item)</strong></li>
+    </ul>
+    <p>参数定义如下：</p>
+    <ul>
+      <li><code>$li</code>：当前正在构造的节点实例；</li>
+      <li><code>item</code>：当前用于构建的节点数据。</li>
+    </ul>
+    <p>通过在节点构造器回调函数中直接操作节点实例来构造节点：</p>
+    <pre><code>// 初始化选项中定义构造器回调函数
+$('#myTree').tree({
+    data: [...],
+    itemCreator: function($li, item) {
+        $li.append($('&lt;a/&gt;', {href: item.url}).text(item.title));
+
+        // return false; // 如果要忽略当前节点，可以通过返回 false 来实现
+    }
+})</code></pre>
+
+    <h4>移除或清空节点</h4>
+    <p>直接使用 jQuery 选择需要移除的节点，调用 jQuery 实例上的 <code>remove()</code> 或 <code>empty()</code> 方法。</p>
+    <pre><code>// 移除其中一个节点
+$('#myTree li[data-id="myTreeNodeId"]').remove();
+
+// 清空整个树节点
+$('#myTree').empty();</code></pre>
+  </article>
+</section>