@next-bricks/advanced 0.51.3 → 0.51.4

package/dist-types/workbench-layout/index.d.ts

@@ -27,16 +27,41 @@ export interface EoWorkbenchLayoutComponentProps extends EoWorkbenchLayoutProps
     onActionClick?: (action: SimpleAction, layouts: Layout[]) => void;
 }
 export declare const EoWorkbenchLayoutComponent: React.ForwardRefExoticComponent<EoWorkbenchLayoutComponentProps & React.RefAttributes<EoWorkbenchLayoutComponentRef>>;
+export interface EoWorkbenchLayoutEventsMap {
+    change: CustomEvent<Layout[]>;
+    save: CustomEvent<Layout[]>;
+    cancel: CustomEvent<void>;
+    "action.click": CustomEvent<{
+        action: SimpleAction;
+        layouts: Layout[];
+    }>;
+}
+export interface EoWorkbenchLayoutEventsMapping {
+    onChange: "change";
+    onSave: "save";
+    onCancel: "cancel";
+    onActionClick: "action.click";
+}
 /**
- * 工作台布局
+ * 工作台布局（拖拽式卡片布局，支持编辑模式）
  * @deprecated Please use eo-workbench-layout-v2 which support global styles instead
+ * @author developer
+ * @category layout
  */
 export declare class EoWorkbenchLayout extends ReactNextElement {
     #private;
+    /** 编辑模式下左侧卡片列表面板的标题 */
     accessor cardTitle: string | undefined;
+    /** 是否进入编辑模式，编辑模式下可拖拽调整布局并显示卡片选择面板 */
     accessor isEdit: boolean | undefined;
+    /** 当前布局配置，每项对应一个卡片的位置与大小 */
     accessor layouts: Layout[] | undefined;
+    /** 组件列表，每项包含 key、title、useBrick 和 position 信息 */
     accessor componentList: Item[] | undefined;
+    /**
+     * 设置布局配置
+     * @param layouts - 新的布局配置数组
+     */
     setLayouts(layouts: Layout[]): void;
     render(): React.JSX.Element;
 }

package/dist-types/workbench-layout-v2/index.d.ts

@@ -29,30 +29,52 @@ export interface EoWorkbenchLayoutV2ComponentProps extends EoWorkbenchLayoutV2Pr
     onSetting?: () => void;
 }
 export declare const EoWorkbenchLayoutComponent: React.ForwardRefExoticComponent<EoWorkbenchLayoutV2ComponentProps & React.RefAttributes<EoWorkbenchLayoutV2ComponentRef>>;
+export interface EoWorkbenchLayoutV2EventsMap {
+    change: CustomEvent<ExtraLayout[]>;
+    save: CustomEvent<ExtraLayout[]>;
+    cancel: CustomEvent<void>;
+    setting: CustomEvent<void>;
+    "action.click": CustomEvent<{
+        action: SimpleAction;
+        layouts: ExtraLayout[];
+    }>;
+}
+export interface EoWorkbenchLayoutV2EventsMapping {
+    onChange: "change";
+    onSave: "save";
+    onCancel: "cancel";
+    onSetting: "setting";
+    onActionClick: "action.click";
+}
 /**
- * 工作台布局V2, 未使用shadow dom
+ * 工作台布局 V2，支持拖拽式卡片布局与全局样式（不使用 shadow DOM）
+ * @author developer
+ * @category layout
  */
 export declare class EoWorkbenchLayoutV2 extends ReactNextElement {
     #private;
+    /** 编辑模式下左侧卡片列表面板的标题 */
     accessor cardTitle: string | undefined;
+    /** 是否进入编辑模式，编辑模式下可拖拽调整布局并显示卡片选择面板 */
     accessor isEdit: boolean | undefined;
+    /** 当前布局配置，每项对应一个卡片的位置与大小及样式信息 */
     accessor layouts: ExtraLayout[] | undefined;
+    /** 编辑模式下工具栏区域的自定义构件 */
     accessor toolbarBricks: {
         useBrick: UseSingleBrickConf[];
     } | undefined;
+    /** 组件列表，每项包含 key、title、useBrick 和 position 信息 */
     accessor componentList: WorkbenchComponent[] | undefined;
-    /**
-     * 自定义卡片默认配置, 用于覆盖默认卡片配置
-     */
+    /** 自定义卡片默认配置，用于覆盖默认卡片样式配置 */
     accessor customDefaultCardConfigMap: Record<string, CardStyleConfig> | undefined;
-    /**
-     * description: 用于设置页面样式和布局的按钮
-     */
+    /** 是否显示设置按钮，用于触发页面样式和布局设置 */
     accessor showSettingButton: boolean | undefined;
+    /** 卡片之间的间距（px） */
+    accessor gap: number | undefined;
     /**
-     * description: 卡片间隔
+     * 设置布局配置
+     * @param layouts - 新的布局配置数组
      */
-    accessor gap: number | undefined;
     setLayouts(layouts: Layout[]): void;
     connectedCallback(): void;
     render(): React.JSX.Element;

package/docs/eo-cascader.md

@@ -1,9 +1,50 @@
-级联选择器
+---
+tagName: eo-cascader
+displayName: WrappedEoCascader
+description: 级联选择器
+category: form-input-basic
+source: "@next-bricks/advanced"
+---
+
+# eo-cascader
+
+> 级联选择器
+
+## Props
+
+| 属性           | 类型                                 | 必填 | 默认值                                                     | 说明                                                          |
+| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | ------------------------------------------------------------- |
+| name           | `string`                             | 否   | -                                                          | 表单字段名                                                    |
+| label          | `string`                             | 否   | -                                                          | 表单字段标签                                                  |
+| required       | `boolean`                            | 否   | -                                                          | 是否为必填项                                                  |
+| options        | `AntdCascaderProps["options"]`       | 否   | -                                                          | 可选项数据源                                                  |
+| fieldNames     | `AntdCascaderProps["fieldNames"]`    | 否   | `{ label: "label", value: "value", children: "children" }` | 自定义字段名，指定 label、value、children 对应的字段          |
+| value          | `AntdCascaderProps["value"]`         | 否   | -                                                          | 当前选中的值                                                  |
+| placeholder    | `string`                             | 否   | -                                                          | 输入框占位文本                                                |
+| multiple       | `boolean`                            | 否   | -                                                          | 是否支持多选                                                  |
+| disabled       | `boolean`                            | 否   | -                                                          | 是否禁用                                                      |
+| allowClear     | `boolean`                            | 否   | `true`                                                     | 是否支持清除                                                  |
+| showSearch     | `boolean`                            | 否   | `true`                                                     | 是否支持搜索，开启后可通过输入关键字过滤选项                  |
+| suffixIcon     | `GeneralIconProps`                   | 否   | -                                                          | 自定义下拉箭头图标                                            |
+| expandTrigger  | `AntdCascaderProps["expandTrigger"]` | 否   | `"click"`                                                  | 次级菜单的展开方式，可选 click 或 hover                       |
+| popupPlacement | `AntdCascaderProps["placement"]`     | 否   | `"bottomLeft"`                                             | 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight |
+| size           | `AntdCascaderProps["size"]`          | 否   | -                                                          | 输入框大小，可选 large、middle、small                         |
+| limit          | `number`                             | 否   | `50`                                                       | 搜索结果的最大条数，0 表示不限制                              |
+| maxTagCount    | `number \| "responsive"`             | 否   | -                                                          | 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 |
+| cascaderStyle  | `CSSProperties`                      | 否   | -                                                          | 级联选择器的内联样式                                          |
+
+## Events
+
+| 事件            | detail                                                                                       | 说明                     |
+| --------------- | -------------------------------------------------------------------------------------------- | ------------------------ |
+| cascader.change | `CascaderChangeEventDetail` — { value: 选择的值, selectedOptions: 选择的值所对应的 options } | 级联选择项输入变化时触发 |
 
 ## Examples
 
 ### Basic
 
+展示级联选择器的基本用法，通过 options 提供层级数据源。
+
 ```yaml preview minHeight="300px"
 - brick: eo-cascader
   properties:
@@ -29,6 +70,8 @@
 
 ### With Form
 
+在表单中使用级联选择器，配置 name、label 和 required 实现表单集成与校验。
+
 ```yaml preview minHeight="300px"
 - brick: eo-form
   events:
@@ -65,3 +108,143 @@
           - action: console.log
     - brick: eo-submit-buttons
 ```
+
+### Multiple Selection
+
+开启多选模式，并配置 maxTagCount 限制最多显示的 tag 数量。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 请选择城市（可多选）
+    multiple: true
+    maxTagCount: 2
+    options:
+      - children:
+          - children:
+              - label: West Lake
+                value: xihu
+            label: Hangzhou
+            value: hangzhou
+        label: Zhejiang
+        value: zhejiang
+      - children:
+          - children:
+              - label: Zhong Hua Men
+                value: zhonghuamen
+            label: Nanjing
+            value: nanjing
+        label: Jiangsu
+        value: jiangsu
+  events:
+    cascader.change:
+      - action: console.log
+```
+
+### Custom Field Names
+
+使用 fieldNames 自定义数据源中 label、value、children 对应的字段名。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 请选择分类
+    fieldNames:
+      label: name
+      value: id
+      children: sub
+    options:
+      - id: tech
+        name: 技术
+        sub:
+          - id: frontend
+            name: 前端
+            sub:
+              - id: react
+                name: React
+              - id: vue
+                name: Vue
+          - id: backend
+            name: 后端
+            sub:
+              - id: java
+                name: Java
+```
+
+### Disabled and Size
+
+展示禁用状态和不同尺寸（large、middle、small）的级联选择器。
+
+```yaml preview minHeight="300px"
+- brick: div
+  properties:
+    style:
+      display: flex
+      flexDirection: column
+      gap: 12px
+  children:
+    - brick: eo-cascader
+      properties:
+        placeholder: Large 尺寸
+        size: large
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+    - brick: eo-cascader
+      properties:
+        placeholder: Small 尺寸
+        size: small
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+    - brick: eo-cascader
+      properties:
+        placeholder: 禁用状态
+        disabled: true
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+```
+
+### Custom Style and Icon
+
+通过 cascaderStyle 设置内联样式，通过 suffixIcon 自定义下拉箭头图标。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 自定义样式与图标
+    suffixIcon:
+      lib: antd
+      icon: down
+    cascaderStyle:
+      width: 300px
+    expandTrigger: hover
+    options:
+      - label: Zhejiang
+        value: zhejiang
+        children:
+          - label: Hangzhou
+            value: hangzhou
+            children:
+              - label: West Lake
+                value: xihu
+```

package/docs/eo-cascader.react.md

@@ -0,0 +1,247 @@
+---
+tagName: eo-cascader
+displayName: WrappedEoCascader
+description: 级联选择器
+category: form-input-basic
+source: "@next-bricks/advanced"
+---
+
+# WrappedEoCascader
+
+> 级联选择器
+
+## 导入
+
+```tsx
+import { WrappedEoCascader } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性           | 类型                                 | 必填 | 默认值                                                     | 说明                                                          |
+| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | ------------------------------------------------------------- |
+| name           | `string`                             | 否   | -                                                          | 表单字段名                                                    |
+| label          | `string`                             | 否   | -                                                          | 表单字段标签                                                  |
+| required       | `boolean`                            | 否   | -                                                          | 是否为必填项                                                  |
+| options        | `AntdCascaderProps["options"]`       | 否   | -                                                          | 可选项数据源                                                  |
+| fieldNames     | `AntdCascaderProps["fieldNames"]`    | 否   | `{ label: "label", value: "value", children: "children" }` | 自定义字段名，指定 label、value、children 对应的字段          |
+| value          | `AntdCascaderProps["value"]`         | 否   | -                                                          | 当前选中的值                                                  |
+| placeholder    | `string`                             | 否   | -                                                          | 输入框占位文本                                                |
+| multiple       | `boolean`                            | 否   | -                                                          | 是否支持多选                                                  |
+| disabled       | `boolean`                            | 否   | -                                                          | 是否禁用                                                      |
+| allowClear     | `boolean`                            | 否   | `true`                                                     | 是否支持清除                                                  |
+| showSearch     | `boolean`                            | 否   | `true`                                                     | 是否支持搜索，开启后可通过输入关键字过滤选项                  |
+| suffixIcon     | `GeneralIconProps`                   | 否   | -                                                          | 自定义下拉箭头图标                                            |
+| expandTrigger  | `AntdCascaderProps["expandTrigger"]` | 否   | `"click"`                                                  | 次级菜单的展开方式，可选 click 或 hover                       |
+| popupPlacement | `AntdCascaderProps["placement"]`     | 否   | `"bottomLeft"`                                             | 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight |
+| size           | `AntdCascaderProps["size"]`          | 否   | -                                                          | 输入框大小，可选 large、middle、small                         |
+| limit          | `number`                             | 否   | `50`                                                       | 搜索结果的最大条数，0 表示不限制                              |
+| maxTagCount    | `number \| "responsive"`             | 否   | -                                                          | 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 |
+| cascaderStyle  | `CSSProperties`                      | 否   | -                                                          | 级联选择器的内联样式                                          |
+
+## Events
+
+| 事件             | detail                                                                                       | 说明                     |
+| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------ |
+| onCascaderChange | `CascaderChangeEventDetail` — { value: 选择的值, selectedOptions: 选择的值所对应的 options } | 级联选择项输入变化时触发 |
+
+## Examples
+
+### Basic
+
+展示级联选择器的基本用法，通过 options 提供层级数据源。
+
+```tsx
+<WrappedEoCascader
+  placeholder="请选择城市"
+  options={[
+    {
+      label: "Zhejiang",
+      value: "zhejiang",
+      children: [
+        {
+          label: "Hangzhou",
+          value: "hangzhou",
+          children: [{ label: "West Lake", value: "xihu" }],
+        },
+      ],
+    },
+    {
+      label: "Jiangsu",
+      value: "jiangsu",
+      children: [
+        {
+          label: "Nanjing",
+          value: "nanjing",
+          children: [{ label: "Zhong Hua Men", value: "zhonghuamen" }],
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+### With Form
+
+在表单中使用级联选择器，配置 name、label 和 required 实现表单集成与校验。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoCascader
+    label="城市选择"
+    name="city"
+    placeholder="请选择城市"
+    required={true}
+    options={[
+      {
+        label: "Zhejiang",
+        value: "zhejiang",
+        children: [
+          {
+            label: "Hangzhou",
+            value: "hangzhou",
+            children: [{ label: "West Lake", value: "xihu" }],
+          },
+        ],
+      },
+      {
+        label: "Jiangsu",
+        value: "jiangsu",
+        children: [
+          {
+            label: "Nanjing",
+            value: "nanjing",
+            children: [{ label: "Zhong Hua Men", value: "zhonghuamen" }],
+          },
+        ],
+      },
+    ]}
+    onCascaderChange={(e) => console.log(e.detail)}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```
+
+### Multiple Selection
+
+开启多选模式，并配置 maxTagCount 限制最多显示的 tag 数量。
+
+```tsx
+<WrappedEoCascader
+  placeholder="请选择城市（可多选）"
+  multiple={true}
+  maxTagCount={2}
+  options={[
+    {
+      label: "Zhejiang",
+      value: "zhejiang",
+      children: [
+        {
+          label: "Hangzhou",
+          value: "hangzhou",
+          children: [{ label: "West Lake", value: "xihu" }],
+        },
+      ],
+    },
+    {
+      label: "Jiangsu",
+      value: "jiangsu",
+      children: [
+        {
+          label: "Nanjing",
+          value: "nanjing",
+          children: [{ label: "Zhong Hua Men", value: "zhonghuamen" }],
+        },
+      ],
+    },
+  ]}
+  onCascaderChange={(e) => console.log(e.detail)}
+/>
+```
+
+### Custom Field Names
+
+使用 fieldNames 自定义数据源中 label、value、children 对应的字段名。
+
+```tsx
+<WrappedEoCascader
+  placeholder="请选择分类"
+  fieldNames={{ label: "name", value: "id", children: "sub" }}
+  options={[
+    {
+      id: "tech",
+      name: "技术",
+      sub: [
+        {
+          id: "frontend",
+          name: "前端",
+          sub: [
+            { id: "react", name: "React" },
+            { id: "vue", name: "Vue" },
+          ],
+        },
+        {
+          id: "backend",
+          name: "后端",
+          sub: [{ id: "java", name: "Java" }],
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+### Disabled and Size
+
+展示禁用状态和不同尺寸（large、middle、small）的级联选择器。
+
+```tsx
+const options = [
+  {
+    label: "Zhejiang",
+    value: "zhejiang",
+    children: [
+      {
+        label: "Hangzhou",
+        value: "hangzhou",
+        children: [{ label: "West Lake", value: "xihu" }],
+      },
+    ],
+  },
+];
+
+<div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+  <WrappedEoCascader placeholder="Large 尺寸" size="large" options={options} />
+  <WrappedEoCascader placeholder="Small 尺寸" size="small" options={options} />
+  <WrappedEoCascader placeholder="禁用状态" disabled={true} options={options} />
+</div>;
+```
+
+### Custom Style and Icon
+
+通过 cascaderStyle 设置内联样式，通过 suffixIcon 自定义下拉箭头图标。
+
+```tsx
+<WrappedEoCascader
+  placeholder="自定义样式与图标"
+  suffixIcon={{ lib: "antd", icon: "down" }}
+  cascaderStyle={{ width: 300 }}
+  expandTrigger="hover"
+  options={[
+    {
+      label: "Zhejiang",
+      value: "zhejiang",
+      children: [
+        {
+          label: "Hangzhou",
+          value: "hangzhou",
+          children: [{ label: "West Lake", value: "xihu" }],
+        },
+      ],
+    },
+  ]}
+/>
+```