Metacoo

doc/api.md

@@ -1,3 +1,66 @@
+## Enum 组件 API
+
+### Enum（默认导出）
+
+用于获取单个或多个枚举值的展示内容。
+
 | 属性名 | 说明 | 类型 | 默认值 |
-|-----|----|----|-----|
-|     |    |    |     |
+| --- | --- | --- | --- |
+| moduleName | 枚举模块名称，对应预设中配置的枚举名称 | string \| string[] | - |
+| name | 枚举值，当提供时获取单个枚举项；不提供时获取整个枚举列表 | string \| number | - |
+| format | 格式化方式：'default'返回描述文本，'origin'返回原始对象，'option'返回{label, value}格式 | 'default' \| 'origin' \| 'option' | 'default' |
+| force | 是否强制刷新缓存，跳过缓存直接请求 | boolean | false |
+| children | 子元素或渲染函数。函数接收(data, fetchApi)参数 | ReactNode \| Function | - |
+| placeholder | 数据加载中时的占位内容 | ReactNode | '--' |
+| error | 加载失败时的展示内容 | ReactNode \| Function | - |
+| loading | 自定义加载中状态的展示 | ReactNode | - |
+
+### EnumResource
+
+用于获取完整的枚举列表资源。
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| moduleName | 枚举模块名称，支持数组以同时获取多个枚举 | string \| string[] | - |
+| format | 格式化方式 | 'origin' \| 'option' \| 'default' | 'origin' |
+| children | 渲染函数，接收枚举列表作为参数 | Function | - |
+| placeholder | 数据加载中时的占位内容 | ReactNode | '--' |
+| error | 加载失败时的展示内容 | ReactNode \| Function | - |
+| loading | 自定义加载中状态的展示 | ReactNode | - |
+
+### 枚举配置
+
+枚举数据通过 `preset` 函数或 `PureGlobal/Global` 组件的 `preset.enums` 配置：
+
+```javascript
+// 全局配置
+preset({
+  base: {
+    gender: () => [
+      { value: 'M', description: '男' },
+      { value: 'F', description: '女' }
+    ]
+  }
+});
+
+// 或通过 Global 组件配置
+<PureGlobal preset={{
+  enums: {
+    status: async ({ language }) => {
+      // 支持异步加载
+      return [
+        { value: '1', description: '启用' },
+        { value: '0', description: '禁用' }
+      ];
+    }
+  }
+}}>
+```
+
+### 枚举项数据结构
+
+| 字段名 | 说明 | 类型 | 必填 |
+| --- | --- | --- | --- |
+| value | 枚举值 | string \| number | 是 |
+| description | 枚举描述文本 | string | 是 |
+| translation | 多语言翻译对象 | object | 否 |

doc/async-enum.js

@@ -0,0 +1,90 @@
+const { default: Enum } = _Enum;
+const { Space, Button, message } = antd;
+const { useState } = React;
+const { createWithRemoteLoader } = remoteLoader;
+
+const AsyncEnumExample = createWithRemoteLoader({
+  modules: ['components-core:Global@PureGlobal']
+})(({ remoteModules }) => {
+  const [PureGlobal] = remoteModules;
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  return (
+    <PureGlobal
+      preset={{
+        locale: "zh-CN",
+        enums: {
+          // 异步加载枚举数据
+          userStatus: async ({ language }) => {
+            // 模拟从服务器获取数据
+            return new Promise((resolve) => {
+              setTimeout(() => {
+                resolve([
+                  { value: "active", description: "活跃" },
+                  { value: "inactive", description: "非活跃" },
+                  { value: "pending", description: "待审核" },
+                  { value: "banned", description: "已禁用" },
+                ]);
+              }, 1500);
+            });
+          },
+          // 同步枚举数据
+          priority: [
+            { value: "low", description: "低优先级" },
+            { value: "medium", description: "中优先级" },
+            { value: "high", description: "高优先级" },
+            { value: "urgent", description: "紧急" },
+          ],
+        },
+      }}
+    >
+      <Space direction="vertical" size="large" style={{ width: "100%" }}>
+        <div>
+          <h4>异步加载枚举（带Loading状态）</h4>
+          <Enum 
+            key={refreshKey}
+            moduleName="userStatus" 
+            name="active"
+            loading={<span>正在加载用户状态...</span>}
+            placeholder="--"
+          >
+            {(data) => <div>当前状态：{data.description}</div>}
+          </Enum>
+        </div>
+
+        <div>
+          <h4>强制刷新缓存</h4>
+          <Space>
+            <Enum 
+              moduleName="userStatus" 
+              name="banned"
+              force={refreshKey > 0}
+            >
+              {(data) => data.description}
+            </Enum>
+            <Button 
+              onClick={() => {
+                setRefreshKey(prev => prev + 1);
+                message.info("已刷新缓存");
+              }}
+            >
+              刷新缓存
+            </Button>
+          </Space>
+        </div>
+
+        <div>
+          <h4>同步枚举数据（立即显示）</h4>
+          <Space>
+            <Enum moduleName="priority" name="high" />
+            <Enum moduleName="priority" name="urgent">
+              {(data) => <span style={{ color: "red" }}>{data.description}</span>}
+            </Enum>
+          </Space>
+        </div>
+      </Space>
+    </PureGlobal>
+  );
+});
+
+render(<AsyncEnumExample />);

doc/example.json

@@ -20,6 +20,110 @@
           "packageName": "@kne/remote-loader"
         }
       ]
+    },
+    {
+      "title": "基础用法",
+      "description": "展示枚举的基本使用，包括获取单个枚举值和枚举列表",
+      "code": "./new-enum.js",
+      "scope": [
+        {
+          "name": "_Enum",
+          "packageName": "@kne/current-lib_react-enum",
+          "importStatement": "import * as _ReactEnum from \"@kne/react-enum\""
+        },
+        {
+          "name": "antd",
+          "packageName": "antd"
+        },
+        {
+          "name": "remoteLoader",
+          "packageName": "@kne/remote-loader"
+        }
+      ]
+    },
+    {
+      "title": "异步加载与缓存",
+      "description": "展示异步加载枚举数据、Loading状态和强制刷新缓存",
+      "code": "./async-enum.js",
+      "scope": [
+        {
+          "name": "_Enum",
+          "packageName": "@kne/current-lib_react-enum",
+          "importStatement": "import * as _ReactEnum from \"@kne/react-enum\""
+        },
+        {
+          "name": "antd",
+          "packageName": "antd"
+        },
+        {
+          "name": "remoteLoader",
+          "packageName": "@kne/remote-loader"
+        },
+        {
+          "name": "React",
+          "packageName": "react"
+        }
+      ]
+    },
+    {
+      "title": "格式化方式",
+      "description": "展示不同的格式化方式和自定义渲染",
+      "code": "./format-enum.js",
+      "scope": [
+        {
+          "name": "_Enum",
+          "packageName": "@kne/current-lib_react-enum",
+          "importStatement": "import * as _ReactEnum from \"@kne/react-enum\""
+        },
+        {
+          "name": "antd",
+          "packageName": "antd"
+        },
+        {
+          "name": "remoteLoader",
+          "packageName": "@kne/remote-loader"
+        }
+      ]
+    },
+    {
+      "title": "渲染枚举列表",
+      "description": "将枚举列表渲染为各种表单组件",
+      "code": "./list-enum.js",
+      "scope": [
+        {
+          "name": "_Enum",
+          "packageName": "@kne/current-lib_react-enum",
+          "importStatement": "import * as _ReactEnum from \"@kne/react-enum\""
+        },
+        {
+          "name": "antd",
+          "packageName": "antd"
+        },
+        {
+          "name": "remoteLoader",
+          "packageName": "@kne/remote-loader"
+        }
+      ]
+    },
+    {
+      "title": "多枚举模块",
+      "description": "同时获取多个枚举模块和错误处理",
+      "code": "./multi-enum.js",
+      "scope": [
+        {
+          "name": "_Enum",
+          "packageName": "@kne/current-lib_react-enum",
+          "importStatement": "import * as _ReactEnum from \"@kne/react-enum\""
+        },
+        {
+          "name": "antd",
+          "packageName": "antd"
+        },
+        {
+          "name": "remoteLoader",
+          "packageName": "@kne/remote-loader"
+        }
+      ]
     }
   ]
 }

doc/format-enum.js

@@ -0,0 +1,85 @@
+const { default: Enum } = _Enum;
+const { createWithRemoteLoader } = remoteLoader;
+const { Space, Divider, Card } = antd;
+
+const FormatEnumExample = createWithRemoteLoader({
+  modules: ['components-core:Global@PureGlobal']
+})(({ remoteModules }) => {
+  const [PureGlobal] = remoteModules;
+  return (
+    <PureGlobal
+      preset={{
+        locale: "zh-CN",
+        enums: {
+          orderStatus: [
+            { value: "created", description: "已创建", color: "#666" },
+            { value: "paid", description: "已支付", color: "#1890ff" },
+            { value: "shipped", description: "已发货", color: "#52c41a" },
+            { value: "completed", description: "已完成", color: "#52c41a" },
+            { value: "cancelled", description: "已取消", color: "#f5222d" },
+          ],
+        },
+      }}
+    >
+      <Space direction="vertical" size="large" style={{ width: "100%" }}>
+        <Card title="不同格式化方式" size="small">
+          <Space direction="vertical">
+            <div>
+              <strong>默认格式（format="default"）：</strong>
+              <Enum moduleName="orderStatus" name="paid" format="default" />
+            </div>
+
+            <Divider />
+
+            <div>
+              <strong>原始对象（format="origin"）：</strong>
+              <Enum moduleName="orderStatus" name="paid" format="origin">
+                {(data) => (
+                  <pre>{JSON.stringify(data, null, 2)}</pre>
+                )}
+              </Enum>
+            </div>
+
+            <Divider />
+
+            <div>
+              <strong>选项格式（format="option"）：</strong>
+              <Enum moduleName="orderStatus" name="paid" format="option">
+                {(data) => (
+                  <span>label: {data.label}, value: {data.value}</span>
+                )}
+              </Enum>
+            </div>
+          </Space>
+        </Card>
+
+        <Card title="自定义渲染" size="small">
+          <Space>
+            <Enum moduleName="orderStatus" name="shipped" format="origin">
+              {(data) => (
+                <span style={{ color: data.color }}>
+                  ● {data.description}
+                </span>
+              )}
+            </Enum>
+
+            <Enum moduleName="orderStatus" name="cancelled" format="origin">
+              {(data) => (
+                <span style={{ 
+                  padding: "2px 8px",
+                  backgroundColor: data.color,
+                  color: "#fff",
+                  borderRadius: "4px"
+                }}>
+                  {data.description}
+                </span>
+              )}
+            </Enum>
+          </Space>
+        </Card>
+      </Space>
+    </PureGlobal>
+  );
+});
+
+render(<FormatEnumExample />);