@next-bricks/form 1.21.11 → 1.21.13

package/docs/eo-checkbox.react.md

@@ -0,0 +1,369 @@
+---
+tagName: eo-checkbox
+displayName: WrappedEoCheckbox
+description: 表单复选框构件
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoCheckbox
+
+> 表单复选框构件
+
+## 导入
+
+```tsx
+import { WrappedEoCheckbox } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性         | 类型                     | 必填 | 默认值      | 说明                                                                  |
+| ------------ | ------------------------ | ---- | ----------- | --------------------------------------------------------------------- |
+| name         | `string`                 | -    | -           | 字段名称                                                              |
+| label        | `string`                 | -    | -           | 字段说明                                                              |
+| value        | `CheckboxValueType[]`    | -    | -           | 值                                                                    |
+| options      | `CheckboxOptionType[]`   | -    | `[]`        | 多选框选项表                                                          |
+| type         | `CheckboxType`           | -    | `"default"` | 类型                                                                  |
+| disabled     | `boolean`                | -    | -           | 是否禁用                                                              |
+| isCustom     | `boolean`                | -    | `false`     | 是否为自定义样式，仅在 type="icon" 时生效，启用后图标尺寸更大（52px） |
+| required     | `boolean`                | -    | -           | 是否必填                                                              |
+| message      | `Record<string, string>` | -    | -           | 校验文本                                                              |
+| isGroup      | `boolean`                | -    | -           | 是否启用分组模式，为 true 时，则可设置分组数据 optionGroups           |
+| optionGroups | `OptionGroup[]`          | -    | -           | 多选框选项分组数据，需要设置 isGroup 为 true 才生效                   |
+| themeVariant | `"default" \| "elevo"`   | -    | -           | 主题变体                                                              |
+
+## Events
+
+| 事件            | detail                                                                                                               | 说明                       |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| onChange        | `CheckboxOptionType[]` — { value: 选中项的值, label: 选中项的标签, disabled: 是否禁用, checkboxColor: 复选框颜色 }[] | 复选框选中项发生变化时触发 |
+| onOptionsChange | `OptionsChangeEventDetail` — { options: 最新的选项列表, name: 字段名称 }                                             | 复选框选项数据变化时触发   |
+
+## Examples
+
+### Basic
+
+基本用法，展示简单的多选框列表。
+
+```tsx
+<WrappedEoCheckbox options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]} />
+```
+
+### Label
+
+设置 label 属性为复选框添加字段说明。
+
+```tsx
+<WrappedEoCheckbox
+  label="city"
+  options={[
+    "Beijing",
+    "Shanghai",
+    "Guangzhou",
+    "Shenzhen",
+    "Tianjin",
+    "Hanzhou",
+    "Xi'an",
+    "Fuzhou",
+    "Nanchan",
+    "Changsha",
+    "Shenyang",
+    "Jinan",
+    "Guiyang",
+    "Wuhan",
+  ]}
+/>
+```
+
+### Value
+
+设置 value 属性指定默认选中项。
+
+```tsx
+<WrappedEoCheckbox
+  value={["Beijing", "Guangzhou"]}
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Options
+
+多种选项格式：字符串数组、对象数组和布尔值数组。
+
+```tsx
+<>
+  <WrappedEoCheckbox
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+    value={["Guangzhou"]}
+  />
+  <WrappedEoCheckbox
+    options={[
+      { label: "Beijing", value: 0 },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+    value={[2, 3]}
+  />
+  <WrappedEoCheckbox options={[true, false]} value={[true]} />
+</>
+```
+
+### Disabled
+
+禁用单个选项或整体禁用复选框。
+
+```tsx
+<>
+  <WrappedEoCheckbox
+    options={[
+      { label: "Beijing", value: 0, disabled: true },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+    value={[0, 2]}
+  />
+  <div style={{ height: "20px" }} />
+  <WrappedEoCheckbox
+    disabled={true}
+    value={[1]}
+    options={[
+      { label: "Beijing", value: 0 },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+  />
+</>
+```
+
+### Type
+
+展示 default 和 icon 两种类型的复选框样式。
+
+```tsx
+<>
+  <WrappedEoCheckbox
+    label="Default"
+    type="default"
+    options={[
+      {
+        label: "Python",
+        value: 0,
+        icon: { lib: "easyops", category: "colored-common", icon: "python" },
+      },
+      {
+        label: "Javascript",
+        value: 1,
+        icon: {
+          lib: "easyops",
+          category: "program-language",
+          icon: "javascript",
+        },
+      },
+      {
+        label: "Powershell",
+        value: 2,
+        icon: {
+          lib: "easyops",
+          category: "colored-common",
+          icon: "powershell",
+        },
+      },
+      {
+        label: "Shell",
+        value: 3,
+        icon: { lib: "easyops", category: "colored-common", icon: "shell" },
+      },
+    ]}
+  />
+  <div style={{ height: "20px" }} />
+  <WrappedEoCheckbox
+    label="Icon"
+    type="icon"
+    options={[
+      {
+        label: "Python",
+        value: 0,
+        icon: { lib: "easyops", category: "colored-common", icon: "python" },
+      },
+      {
+        label: "Javascript",
+        value: 1,
+        icon: {
+          lib: "easyops",
+          category: "program-language",
+          icon: "javascript",
+        },
+      },
+      {
+        label: "Powershell",
+        value: 2,
+        icon: {
+          lib: "easyops",
+          category: "colored-common",
+          icon: "powershell",
+        },
+      },
+      {
+        label: "Shell",
+        value: 3,
+        icon: { lib: "easyops", category: "colored-common", icon: "shell" },
+      },
+    ]}
+  />
+</>
+```
+
+### isCustom
+
+启用自定义样式（仅在 type="icon" 时生效），图标尺寸更大。
+
+```tsx
+<WrappedEoCheckbox
+  label="自定义图标样式"
+  type="icon"
+  isCustom={true}
+  options={[
+    {
+      label: "Python",
+      value: 0,
+      icon: { lib: "easyops", category: "colored-common", icon: "python" },
+    },
+    {
+      label: "Javascript",
+      value: 1,
+      icon: {
+        lib: "easyops",
+        category: "program-language",
+        icon: "javascript",
+      },
+    },
+  ]}
+/>
+```
+
+### checkboxColor
+
+为不同选项设置自定义颜色。
+
+```tsx
+<WrappedEoCheckbox
+  options={[
+    { label: "Beijing", value: 0, checkboxColor: "red" },
+    { label: "Shanghai", value: 1, checkboxColor: "orange" },
+    { label: "Guangzhou", value: 2, checkboxColor: "blue" },
+    { label: "Shenzhen", value: 3, checkboxColor: "green" },
+  ]}
+  value={[2, 1]}
+/>
+```
+
+### optionGroups
+
+启用分组模式，将选项按组展示，支持全选/取消全选操作。
+
+```tsx
+<WrappedEoCheckbox
+  isGroup={true}
+  label="商品"
+  name="goods"
+  optionGroups={[
+    {
+      key: "fruits",
+      name: "水果",
+      options: [
+        { label: "苹果", value: "apple" },
+        { label: "香蕉", value: "banana" },
+      ],
+    },
+    {
+      key: "vegetables",
+      name: "蔬菜",
+      options: [{ label: "土豆", value: "potato" }],
+    },
+  ]}
+  value={["banana", "potato"]}
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### themeVariant
+
+设置主题变体为 elevo 风格。
+
+```tsx
+<WrappedEoCheckbox
+  themeVariant="elevo"
+  label="Elevo 风格"
+  options={[
+    { label: "Beijing", value: 0 },
+    { label: "Shanghai", value: 1 },
+    { label: "Guangzhou", value: 2 },
+  ]}
+  value={[0]}
+/>
+```
+
+### Event
+
+监听 onChange 和 onOptionsChange 事件，通过按钮动态修改选项触发 onOptionsChange 事件。
+
+```tsx
+function CheckboxEventDemo() {
+  const [options, setOptions] = useState([
+    { label: "Beijing", value: 0 },
+    { label: "Shanghai", value: 1 },
+    { label: "Guangzhou", value: 2 },
+    { label: "Shenzhen", value: 3 },
+  ]);
+
+  return (
+    <>
+      <WrappedEoCheckbox
+        options={options}
+        onChange={(e) => console.log("change:", e.detail)}
+        onOptionsChange={(e) => console.log("options.change:", e.detail)}
+      />
+      <WrappedEoButton
+        textContent="Click to Change Checkbox Option"
+        onClick={() =>
+          setOptions([
+            { label: "Beijing", value: 0 },
+            {
+              label: "Shanghai",
+              value: 1,
+              icon: { icon: "bar-chart", lib: "antd" },
+            },
+            { label: "Guangzhou", value: 2 },
+            { label: "Shenzhen", value: 3 },
+            { label: "Hangzhou", value: 4 },
+          ])
+        }
+      />
+    </>
+  );
+}
+```
+
+### With Form
+
+在表单中使用复选框，支持 required 校验和 message 自定义校验文本。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoCheckbox
+    name="city"
+    label="城市"
+    required={true}
+    message={{ required: "请选择至少一个城市" }}
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```

package/docs/eo-color-picker.md

@@ -1,9 +1,43 @@
-构件 `eo-color-picker`
+---
+tagName: eo-color-picker
+displayName: WrappedEoColorPicker
+description: 颜色选择器
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-color-picker
+
+> 颜色选择器
+
+## Props
+
+| 属性         | 类型                             | 必填 | 默认值   | 说明                                                                                             |
+| ------------ | -------------------------------- | ---- | -------- | ------------------------------------------------------------------------------------------------ |
+| name         | `string`                         | 否   | -        | 字段名称                                                                                         |
+| label        | `string`                         | 否   | -        | 字段说明                                                                                         |
+| value        | `string`                         | 否   | -        | 值                                                                                               |
+| defaultValue | `string \| Color`                | 否   | -        | 颜色默认的值                                                                                     |
+| required     | `boolean`                        | 否   | -        | 是否必填                                                                                         |
+| allowClear   | `boolean`                        | 否   | -        | 允许清除选择的颜色                                                                               |
+| size         | `"small" \| "middle" \| "large"` | 否   | `middle` | 设置触发器大小                                                                                   |
+| showText     | `boolean`                        | 否   | -        | 显示颜色文本                                                                                     |
+| disabled     | `boolean`                        | 否   | -        | 是否禁用                                                                                         |
+| format       | `"rgb" \| "hex" \| "hsb"`        | 否   | `hex`    | 颜色格式                                                                                         |
+| configProps  | `Partial<ColorPickerProps>`      | 否   | -        | 透传 antd ColorPicker 属性 [ColorPickerProps](https://ant.design/components/color-picker-cn#api) |
+
+## Events
+
+| 事件   | detail                                                                                          | 说明                                       |
+| ------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| change | `string \| undefined` — 选中的颜色值，格式由 format 属性决定（hex/rgb/hsb），清除时为 undefined | 颜色变化事件, 返回值格式和`format`格式一致 |
 
 ## Examples
 
 ### Basic
 
+基础用法，选择颜色后通过 change 事件获取颜色值。
+
 ```yaml preview
 brick: eo-color-picker
 events:
@@ -13,6 +47,8 @@ events:
 
 ### Size
 
+通过 size 属性设置颜色选择器触发器的尺寸大小。
+
 ```yaml preview
 - brick: eo-flex-layout
   properties:
@@ -24,23 +60,26 @@ events:
         - brick: eo-color-picker
           properties:
             size: small
-            value: red
+            value: "#ff4d4f"
         - brick: eo-color-picker
           properties:
-            size: medium
+            size: middle
             value: "#36b545"
         - brick: eo-color-picker
           properties:
             size: large
-            value: rgb(59, 52, 255)
+            value: "#1677ff"
 ```
 
 ### ShowText
 
+设置 showText 为 true，在颜色选择器旁边显示当前颜色的文本值。
+
 ```yaml preview
 - brick: eo-color-picker
   properties:
     showText: true
+    value: "#1677ff"
   events:
     change:
       action: console.log
@@ -48,6 +87,8 @@ events:
 
 ### AllowClear
 
+设置 allowClear 为 true，允许用户清除已选颜色；结合 defaultValue 设置初始颜色。
+
 ```yaml preview
 - brick: eo-color-picker
   properties:
@@ -60,6 +101,8 @@ events:
 
 ### Formats
 
+通过 format 属性控制颜色输出格式，支持 hex、rgb 和 hsb 三种格式。
+
 ```yaml preview
 - brick: eo-flex-layout
   properties:
@@ -72,38 +115,75 @@ events:
           properties:
             format: hex
             value: "#FCFA0E"
+            showText: true
         - brick: eo-color-picker
           properties:
             format: rgb
-            value: rgb(80, 227, 194)
+            value: "rgb(80, 227, 194)"
+            showText: true
         - brick: eo-color-picker
           properties:
             format: hsb
-            value: hsb(215, 91%, 100%)
+            value: "hsb(215, 91%, 100%)"
+            showText: true
+```
+
+### Disabled
+
+设置 disabled 为 true 禁用颜色选择器，用户无法进行交互。
+
+```yaml preview
+- brick: eo-color-picker
+  properties:
+    disabled: true
+    value: "#1677ff"
+    showText: true
+```
+
+### ConfigProps
+
+通过 configProps 透传 antd ColorPicker 的高级属性，例如设置预设颜色。
+
+```yaml preview
+- brick: eo-color-picker
+  properties:
+    showText: true
+    configProps:
+      presets:
+        - label: 推荐颜色
+          colors:
+            - "#F5222D"
+            - "#FA8C16"
+            - "#FADB14"
+            - "#52C41A"
+            - "#1677FF"
+            - "#722ED1"
+  events:
+    change:
+      action: console.log
 ```
 
 ### With Form
 
+在表单中使用颜色选择器，配合 name、label、required 进行表单校验。
+
 ```yaml preview
-- brick: form.general-form
+- brick: eo-form
   events:
     validate.success:
       - action: console.log
     validate.error:
       - action: console.log
-  slots:
-    "":
-      type: bricks
-      bricks:
-        - brick: eo-color-picker
-          properties:
-            name: color
-            label: 颜色
-            required: true
-            defaultValue: "#1677FF"
-            showText: true
-          events:
-            change:
-              action: console.log
-        - brick: eo-submit-buttons
+  children:
+    - brick: eo-color-picker
+      properties:
+        name: color
+        label: 颜色
+        required: true
+        defaultValue: "#1677FF"
+        showText: true
+      events:
+        change:
+          action: console.log
+    - brick: eo-submit-buttons
 ```