@next-bricks/advanced 0.51.3 → 0.51.4

package/docs/eo-tree-select.md

@@ -1,9 +1,57 @@
-构件 `eo-tree-select`
+---
+tagName: eo-tree-select
+displayName: WrappedEoTreeSelect
+description: 树选择器，支持从树形数据中单选或多选节点
+category: form-input-basic
+source: "@next-bricks/advanced"
+---
+
+# eo-tree-select
+
+> 树选择器，支持从树形数据中单选或多选节点
+
+## Props
+
+| 属性                  | 类型                                    | 必填 | 默认值         | 说明                                                          |
+| --------------------- | --------------------------------------- | ---- | -------------- | ------------------------------------------------------------- |
+| name                  | `string`                                | 否   | -              | 表单字段名                                                    |
+| label                 | `string`                                | 否   | -              | 表单字段标签                                                  |
+| required              | `boolean`                               | 否   | -              | 是否为必填项                                                  |
+| treeData              | `AntdTreeSelectProps["treeData"]`       | 否   | -              | 树形数据源                                                    |
+| treeDefaultExpandAll  | `boolean`                               | 否   | -              | 是否默认展开所有树节点                                        |
+| treeExpandedKeys      | `string[]`                              | 否   | -              | 受控展开的树节点 key 集合                                     |
+| fieldNames            | `AntdTreeSelectProps["fieldNames"]`     | 否   | -              | 自定义字段名，指定 label、value、children 对应的字段          |
+| value                 | `AntdTreeSelectProps["value"]`          | 否   | -              | 当前选中的值                                                  |
+| placeholder           | `string`                                | 否   | -              | 输入框占位文本                                                |
+| multiple              | `boolean`                               | 否   | -              | 是否支持多选                                                  |
+| disabled              | `boolean`                               | 否   | -              | 是否禁用                                                      |
+| checkable             | `boolean`                               | 否   | -              | 是否支持勾选树节点（开启后自动开启 multiple 模式）            |
+| allowClear            | `boolean`                               | 否   | `true`         | 是否支持清除                                                  |
+| loading               | `boolean`                               | 否   | `false`        | 是否显示加载中状态                                            |
+| filterTreeNode        | `AntdTreeSelectProps["filterTreeNode"]` | 否   | -              | 自定义树节点过滤函数                                          |
+| showSearch            | `boolean`                               | 否   | `true`         | 是否支持搜索，开启后可通过输入关键字过滤树节点                |
+| suffixIcon            | `GeneralIconProps`                      | 否   | -              | 自定义下拉箭头图标                                            |
+| popupPlacement        | `AntdTreeSelectProps["placement"]`      | 否   | `"bottomLeft"` | 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight |
+| size                  | `AntdTreeSelectProps["size"]`           | 否   | -              | 输入框大小，可选 large、middle、small                         |
+| maxTagCount           | `number \| "responsive"`                | 否   | -              | 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 |
+| dropdownStyle         | `CSSProperties`                         | 否   | -              | 下拉框的样式                                                  |
+| popupMatchSelectWidth | `boolean`                               | 否   | `true`         | 下拉菜单的宽度是否与选择框相同                                |
+
+## Events
+
+| 事件   | detail                                                              | 说明                  |
+| ------ | ------------------------------------------------------------------- | --------------------- |
+| change | `{ value: AntdTreeSelectProps["value"] }` — { value: 选择的值 }     | 选中值变化时触发      |
+| search | `string` — 搜索关键词                                               | 搜索框值变化时触发    |
+| select | `{ value: AntdTreeSelectProps["value"] }` — { value: 选中的节点值 } | 选中某一树节点时触发  |
+| expand | `{ keys: React.Key[] }` — { keys: 展开的节点 key 数组 }             | 树节点展开/收缩时触发 |
 
 ## Examples
 
 ### Basic
 
+展示树选择器的基本用法，通过 treeData 提供树形数据源。
+
 ```yaml preview minHeight="500px"
 - brick: eo-tree-select
   properties:
@@ -32,6 +80,8 @@
 
 ### With Form
 
+在表单中使用树选择器，配置 name、label 和 required 实现表单集成与校验。
+
 ```yaml preview minHeight="500px"
 - brick: eo-form
   events:
@@ -84,3 +134,79 @@
           - action: console.log
     - brick: eo-submit-buttons
 ```
+
+### Multiple Selection with Max Tag Count
+
+开启多选模式并设置 maxTagCount 限制显示的 tag 数量。
+
+```yaml preview minHeight="400px"
+- brick: eo-tree-select
+  properties:
+    multiple: true
+    maxTagCount: 2
+    treeDefaultExpandAll: true
+    placeholder: 可多选，最多显示2个标签
+    treeData:
+      - title: Node1
+        value: "0-0"
+        key: "0-0"
+        children:
+          - title: Node1-1
+            value: "0-0-1"
+            key: "0-0-1"
+          - title: Node1-2
+            value: "0-0-2"
+            key: "0-0-2"
+      - title: Node2
+        value: "0-1"
+        key: "0-1"
+        children:
+          - title: Node2-1
+            value: "0-1-1"
+            key: "0-1-1"
+          - title: Node2-2
+            value: "0-1-2"
+            key: "0-1-2"
+  events:
+    change:
+      - action: console.log
+```
+
+### Custom Field Names and Disabled
+
+使用 fieldNames 自定义数据源字段，并展示禁用状态。
+
+```yaml preview minHeight="400px"
+- brick: div
+  properties:
+    style:
+      display: flex
+      flexDirection: column
+      gap: 16px
+  children:
+    - brick: eo-tree-select
+      properties:
+        fieldNames:
+          label: name
+          value: id
+          children: sub
+        treeDefaultExpandAll: true
+        placeholder: 自定义字段名
+        treeData:
+          - name: 技术
+            id: tech
+            sub:
+              - name: 前端
+                id: frontend
+              - name: 后端
+                id: backend
+    - brick: eo-tree-select
+      properties:
+        disabled: true
+        value: "0-0"
+        placeholder: 禁用状态
+        treeData:
+          - title: Node1
+            value: "0-0"
+            key: "0-0"
+```

package/docs/eo-tree-select.react.md

@@ -0,0 +1,206 @@
+---
+tagName: eo-tree-select
+displayName: WrappedEoTreeSelect
+description: 树选择器，支持从树形数据中单选或多选节点
+category: form-input-basic
+source: "@next-bricks/advanced"
+---
+
+# WrappedEoTreeSelect
+
+> 树选择器，支持从树形数据中单选或多选节点
+
+## 导入
+
+```tsx
+import { WrappedEoTreeSelect } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性                  | 类型                                    | 必填 | 默认值         | 说明                                                          |
+| --------------------- | --------------------------------------- | ---- | -------------- | ------------------------------------------------------------- |
+| name                  | `string`                                | 否   | -              | 表单字段名                                                    |
+| label                 | `string`                                | 否   | -              | 表单字段标签                                                  |
+| required              | `boolean`                               | 否   | -              | 是否为必填项                                                  |
+| treeData              | `AntdTreeSelectProps["treeData"]`       | 否   | -              | 树形数据源                                                    |
+| treeDefaultExpandAll  | `boolean`                               | 否   | -              | 是否默认展开所有树节点                                        |
+| treeExpandedKeys      | `string[]`                              | 否   | -              | 受控展开的树节点 key 集合                                     |
+| fieldNames            | `AntdTreeSelectProps["fieldNames"]`     | 否   | -              | 自定义字段名，指定 label、value、children 对应的字段          |
+| value                 | `AntdTreeSelectProps["value"]`          | 否   | -              | 当前选中的值                                                  |
+| placeholder           | `string`                                | 否   | -              | 输入框占位文本                                                |
+| multiple              | `boolean`                               | 否   | -              | 是否支持多选                                                  |
+| disabled              | `boolean`                               | 否   | -              | 是否禁用                                                      |
+| checkable             | `boolean`                               | 否   | -              | 是否支持勾选树节点（开启后自动开启 multiple 模式）            |
+| allowClear            | `boolean`                               | 否   | `true`         | 是否支持清除                                                  |
+| loading               | `boolean`                               | 否   | `false`        | 是否显示加载中状态                                            |
+| filterTreeNode        | `AntdTreeSelectProps["filterTreeNode"]` | 否   | -              | 自定义树节点过滤函数                                          |
+| showSearch            | `boolean`                               | 否   | `true`         | 是否支持搜索，开启后可通过输入关键字过滤树节点                |
+| suffixIcon            | `GeneralIconProps`                      | 否   | -              | 自定义下拉箭头图标                                            |
+| popupPlacement        | `AntdTreeSelectProps["placement"]`      | 否   | `"bottomLeft"` | 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight |
+| size                  | `AntdTreeSelectProps["size"]`           | 否   | -              | 输入框大小，可选 large、middle、small                         |
+| maxTagCount           | `number \| "responsive"`                | 否   | -              | 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 |
+| dropdownStyle         | `CSSProperties`                         | 否   | -              | 下拉框的样式                                                  |
+| popupMatchSelectWidth | `boolean`                               | 否   | `true`         | 下拉菜单的宽度是否与选择框相同                                |
+
+## Events
+
+| 事件     | detail                                                              | 说明                  |
+| -------- | ------------------------------------------------------------------- | --------------------- |
+| onChange | `{ value: AntdTreeSelectProps["value"] }` — { value: 选择的值 }     | 选中值变化时触发      |
+| onSearch | `string` — 搜索关键词                                               | 搜索框值变化时触发    |
+| onSelect | `{ value: AntdTreeSelectProps["value"] }` — { value: 选中的节点值 } | 选中某一树节点时触发  |
+| onExpand | `{ keys: React.Key[] }` — { keys: 展开的节点 key 数组 }             | 树节点展开/收缩时触发 |
+
+## Examples
+
+### Basic
+
+展示树选择器的基本用法，通过 treeData 提供树形数据源。
+
+```tsx
+<WrappedEoTreeSelect
+  treeData={[
+    {
+      title: "Node1",
+      value: 0,
+      key: 0,
+      children: [
+        { title: "Node1-1", value: "0-1" },
+        { title: "Node1-2", value: "0-2" },
+        { title: "Node1-3", value: "0-3" },
+      ],
+    },
+    {
+      title: "Node2",
+      value: 1,
+      key: 1,
+      children: [
+        { title: "Node2-1", value: "1-1" },
+        { title: "Node2-2", value: "1-2" },
+        { title: "Node2-3", value: "1-3" },
+      ],
+    },
+  ]}
+/>
+```
+
+### With Form
+
+在表单中使用树选择器，配置 name、label 和 required 实现表单集成与校验。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValidateError={(e) => console.log(e.detail)}
+>
+  <WrappedEoTreeSelect
+    label="tree"
+    name="tree"
+    required={true}
+    multiple={true}
+    checkable={true}
+    placeholder="请选择树节点"
+    treeData={[
+      {
+        title: "Node1",
+        value: "Node1",
+        key: "0-0",
+        children: [
+          { title: "Child Node1-1", value: "Child Node1-1", key: "0-0-0" },
+          { title: "Child Node1-2", value: "Child Node1-2", key: "0-0-1" },
+        ],
+      },
+      {
+        title: "Node2",
+        value: "0-1",
+        key: "0-1",
+        children: [
+          { title: "Child Node2-1", value: "Child Node2-1", key: "0-1-0" },
+          {
+            title: "Child Node2-2",
+            value: "Child Node2-2",
+            key: "0-1-1",
+            children: [
+              {
+                title: "Child Node2-2-1",
+                value: "Child Node2-2-1",
+                key: "0-1-1-0",
+              },
+            ],
+          },
+        ],
+      },
+    ]}
+    onChange={(e) => console.log(e.detail)}
+    onSelect={(e) => console.log(e.detail)}
+    onExpand={(e) => console.log(e.detail)}
+    onSearch={(e) => console.log(e.detail)}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```
+
+### Multiple Selection with Max Tag Count
+
+开启多选模式并设置 maxTagCount 限制显示的 tag 数量。
+
+```tsx
+<WrappedEoTreeSelect
+  multiple={true}
+  maxTagCount={2}
+  treeDefaultExpandAll={true}
+  placeholder="可多选，最多显示2个标签"
+  treeData={[
+    {
+      title: "Node1",
+      value: "0-0",
+      key: "0-0",
+      children: [
+        { title: "Node1-1", value: "0-0-1", key: "0-0-1" },
+        { title: "Node1-2", value: "0-0-2", key: "0-0-2" },
+      ],
+    },
+    {
+      title: "Node2",
+      value: "0-1",
+      key: "0-1",
+      children: [
+        { title: "Node2-1", value: "0-1-1", key: "0-1-1" },
+        { title: "Node2-2", value: "0-1-2", key: "0-1-2" },
+      ],
+    },
+  ]}
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### Custom Field Names and Disabled
+
+使用 fieldNames 自定义数据源字段，并展示禁用状态。
+
+```tsx
+<div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+  <WrappedEoTreeSelect
+    fieldNames={{ label: "name", value: "id", children: "sub" }}
+    treeDefaultExpandAll={true}
+    placeholder="自定义字段名"
+    treeData={[
+      {
+        name: "技术",
+        id: "tech",
+        sub: [
+          { name: "前端", id: "frontend" },
+          { name: "后端", id: "backend" },
+        ],
+      },
+    ]}
+  />
+  <WrappedEoTreeSelect
+    disabled={true}
+    value="0-0"
+    placeholder="禁用状态"
+    treeData={[{ title: "Node1", value: "0-0", key: "0-0" }]}
+  />
+</div>
+```

package/docs/eo-tree.md

@@ -1,9 +1,46 @@
-树形构件
+---
+tagName: eo-tree
+displayName: WrappedEoTree
+description: 树形构件
+category: display
+source: "@next-bricks/advanced"
+---
+
+# eo-tree
+
+> 树形构件
+
+## Props
+
+| 属性             | 类型                               | 必填 | 默认值 | 说明                                                                            |
+| ---------------- | ---------------------------------- | ---- | ------ | ------------------------------------------------------------------------------- |
+| dataSource       | `TreeNode[]`                       | 否   | -      | 树形数据源                                                                      |
+| checkable        | `boolean`                          | 否   | -      | 是否显示 Checkbox，开启后可勾选节点                                             |
+| selectable       | `boolean`                          | 否   | -      | 是否可选中节点                                                                  |
+| defaultExpandAll | `boolean`                          | 否   | -      | 是否默认展开所有树节点                                                          |
+| showLine         | `boolean`                          | 否   | -      | 是否显示连接线                                                                  |
+| expandedKeys     | `TreeNodeKey[]`                    | 否   | -      | 受控展开的节点 key 集合                                                         |
+| checkedKeys      | `TreeNodeKey[]`                    | 否   | -      | 受控勾选的节点 key 集合（仅在 checkable 为 true 时有效）                        |
+| nodeDraggable    | `boolean \| { icon?: false }`      | 否   | -      | 是否允许拖拽节点，也可传入对象配置是否显示拖拽图标                              |
+| switcherIcon     | `"auto" \| "chevron" \| false`     | 否   | -      | 自定义展开/折叠图标，可选 auto（默认箭头）、chevron（下箭头）或 false（不显示） |
+| allowDrop        | `(info: AllowDropInfo) => boolean` | 否   | -      | 是否允许拖放到指定位置的判断函数                                                |
+| titleSuffixBrick | `{ useBrick: UseBrickConf }`       | 否   | -      | 节点标题后缀插槽，通过 useBrick 在每个节点标题后渲染自定义构件                  |
+
+## Events
+
+| 事件         | detail                                                                                                                           | 说明                               |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| check        | `TreeNodeKey[]` — 所有勾选节点的 key 数组                                                                                        | 勾选状态变化时触发                 |
+| check.detail | `CheckDetail` — { checkedKeys: 已勾选的节点 key 数组, halfCheckedKeys: 半选中的节点 key 数组 }                                   | 勾选状态变化时触发，包含半选中状态 |
+| expand       | `TreeNodeKey[]` — 当前展开的节点 key 数组                                                                                        | 展开/折叠节点时触发                |
+| node.drop    | `DropDetail` — { dragNode: 被拖拽的节点, dropNode: 放置目标节点, dropPosition: 放置位置（0 表示内部，-1 表示上方，1 表示下方） } | 节点拖拽放置时触发                 |
 
 ## Examples
 
 ### Basic
 
+展示树形构件的基本用法，默认展开所有节点。
+
 ```yaml preview
 brick: eo-tree
 properties:
@@ -28,6 +65,8 @@ properties:
 
 ### Checkable
 
+开启 checkable 显示勾选框，并配置 showLine 显示连接线，勾选变化时触发 check 事件。
+
 ```yaml preview
 brick: eo-tree
 properties:
@@ -59,7 +98,9 @@ events:
     action: console.log
 ```
 
-### titleSuffixBrick
+### Title Suffix Brick
+
+通过 titleSuffixBrick 在每个节点标题后渲染自定义构件。
 
 ```yaml preview
 brick: eo-tree
@@ -93,3 +134,68 @@ properties:
             - title: sss
               key: 0-0-1-0
 ```
+
+### Draggable
+
+开启 nodeDraggable 允许拖拽节点，拖拽放置后触发 node.drop 事件。
+
+```yaml preview
+brick: eo-tree
+properties:
+  defaultExpandAll: true
+  nodeDraggable: true
+  dataSource:
+    - title: parent 1
+      key: 0-0
+      children:
+        - title: parent 1-0
+          key: 0-0-0
+          children:
+            - title: leaf
+              key: 0-0-0-0
+            - title: leaf
+              key: 0-0-0-1
+        - title: parent 1-1
+          key: 0-0-1
+          children:
+            - title: sss
+              key: 0-0-1-0
+events:
+  node.drop:
+    action: console.log
+```
+
+### Controlled Expand and Check
+
+通过 expandedKeys 和 checkedKeys 受控管理展开与勾选状态，并监听 expand 事件。
+
+```yaml preview
+brick: eo-tree
+properties:
+  checkable: true
+  expandedKeys:
+    - 0-0
+  checkedKeys:
+    - 0-0-0-0
+  dataSource:
+    - title: parent 1
+      key: 0-0
+      children:
+        - title: parent 1-0
+          key: 0-0-0
+          children:
+            - title: leaf
+              key: 0-0-0-0
+            - title: leaf
+              key: 0-0-0-1
+        - title: parent 1-1
+          key: 0-0-1
+          children:
+            - title: sss
+              key: 0-0-1-0
+events:
+  expand:
+    action: console.log
+  check:
+    action: console.log
+```