knight-ui 1.0.2 → 1.0.4

package/README.md

@@ -423,19 +423,26 @@ import { Resizable } from "knight-ui";
 ```tsx
 import { Input } from "knight-ui";
 
+// 非受控（浏览器原生管理输入，IME 无干扰）
 <Input placeholder="请输入" onChange={(v) => console.log(v)} />
 <Input showClear defaultValue="可清除" />
+
+// 受控（通过 value 管理显示值，Form.Field 自动使用此模式）
+<Input value={text} onChange={(v) => setText(v)} placeholder="受控输入" />
+
 <Input prefix={<IconSearch />} placeholder="搜索" />
 <Input addonBefore="https://" addonAfter=".com" placeholder="域名" />
 <Input type="password" placeholder="密码" />
 <Input size="large" placeholder="大尺寸" />
 
-// 多行文本
+// 多行文本（同样支持 value / defaultValue）
 <Input.TextArea rows={4} placeholder="多行文本" onChange={(v) => console.log(v)} />
 ```
 
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
+| `value` | `string` | — | 受控值（提供后组件变为受控模式） |
+| `defaultValue` | `string` | — | 非受控默认值 |
 | `type` | `"text" \| "password"` | `"text"` | 输入类型 |
 | `placeholder` | `string` | — | 占位符 |
 | `size` | `"small" \| "default" \| "large"` | `"default"` | 尺寸 |
@@ -838,33 +845,81 @@ import { PinCode } from "knight-ui";
 ```tsx
 import { Form, Input, Button } from "knight-ui";
 
+// 基础用法
 <Form
   layout="horizontal"
   labelWidth={100}
   onSubmit={(values) => console.log(values)}
-  onSubmitFail={(errors) => console.log(errors)}
+  onSubmitFail={(values) => console.log(values)}
   getFormApi={(api) => (window.formApi = api)}
 >
   <Form.Field field="name" label="姓名" rules={[{ required: true, message: "请输入姓名" }]}>
     <Input placeholder="请输入姓名" />
   </Form.Field>
-  <Form.Field field="email" label="邮箱" rules={[{ required: true, type: "email" }]}>
+  <Form.Field field="email" label="邮箱"
+    rules={[{ required: true, message: "请输入邮箱" }, { pattern: /^\S+@\S+$/, message: "邮箱格式不正确" }]}>
     <Input placeholder="请输入邮箱" />
   </Form.Field>
   <Button type="primary" htmlType="submit">提交</Button>
 </Form>
+
+// 动态字段（通过 FormApi 控制）
+const formApiRef = useRef<FormApi>(null);
+<Form getFormApi={(api) => (formApiRef.current = api)}>
+  <Form.Field field="name" label="名称"><Input /></Form.Field>
+</Form>
+
+// 动态添加/移除字段
+formApiRef.current?.addField("dynamic_key", { label: "动态字段", value: "默认值" });
+formApiRef.current?.removeField("dynamic_key");
+
+// 程序化读写
+formApiRef.current?.setFieldValue("name", "新值");
+formApiRef.current?.setFieldsValue({ name: "A", email: "B" });
+const allValues = formApiRef.current?.getValues();
+const singleValue = formApiRef.current?.getFieldValue("name");
+
+// 手动校验
+const validValues = await formApiRef.current?.validate(); // 通过返回 values，失败返回 null
+formApiRef.current?.reset(); // 重置所有字段
 ```
 
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | 布局 |
-| `labelPosition` | `"left" \| "top"` | `"left"` | 标签位置 |
-| `labelWidth` | `number` | — | 标签宽度 |
+| `layout` | `"horizontal" \| "vertical"` | `"vertical"` | 布局 |
+| `labelPosition` | `"left" \| "top"` | `"top"` | 标签位置 |
+| `labelAlign` | `"left" \| "right" \| "center"` | `"left"` | 标签对齐 |
+| `labelWidth` | `number` | `80` | 标签宽度 |
 | `getFormApi` | `(api: FormApi) => void` | — | 获取表单 API |
-| `onSubmit` | `(values) => void` | — | 提交回调 |
+| `onSubmit` | `(values) => void` | — | 校验通过后回调 |
 | `onSubmitFail` | `(values) => void` | — | 校验失败回调 |
 
-**Form.Field**：`field`、`label`、`rules`、`trigger`
+**FormApi 方法**：
+
+| 方法 | 说明 |
+|---|---|
+| `getValues()` | 获取所有字段值 |
+| `setValues(values)` | 批量设置字段值（合并） |
+| `getFieldValue(field)` | 获取单个字段值 |
+| `setFieldValue(field, value)` | 设置单个字段值 |
+| `setFieldsValue(values)` | 批量设置（仅更新已注册字段） |
+| `addField(field, meta?)` | 动态添加字段（已存在则更新） |
+| `removeField(field)` | 动态移除字段 |
+| `validate()` | 手动校验，通过返回 values，失败返回 null |
+| `reset()` | 重置所有字段值为空 |
+| `setError(field, error)` | 设置字段错误信息 |
+
+**Form.Field**：`field`、`label`、`rules?: FormRule[]`、`value?: any`
+
+**FormRule**：
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `required` | `boolean` | 必填 |
+| `message` | `string` | 错误提示 |
+| `min / max` | `number` | 数值范围 |
+| `minLength / maxLength` | `number` | 字符长度范围 |
+| `pattern` | `RegExp` | 正则校验 |
+| `validator` | `(value, values) => string \| null \| Promise<string \| null>` | 自定义校验 |
 
 ---
 
@@ -874,29 +929,44 @@ import { Form, Input, Button } from "knight-ui";
 
 ```tsx
 import { Navigation } from "knight-ui";
+import { IconStar, IconInfoCircle, IconSetting } from "knight-ui";
 
 const items = [
-  { key: "home", label: "首页" },
+  { key: "home", label: "首页", icon: <IconStar size="extraSmall" /> },
   {
-    key: "docs", label: "文档",
+    key: "docs", label: "文档", icon: <IconInfoCircle size="extraSmall" />,
     children: [
       { key: "guide", label: "快速开始" },
       { key: "api", label: "API 参考" },
     ],
   },
-  { key: "about", label: "关于" },
+  { key: "about", label: "关于", icon: <IconSetting size="extraSmall" /> },
 ];
 
-<Navigation items={items} mode="vertical" defaultSelectedKeys={["home"]} onSelect={(k) => console.log(k)} />
+// 垂直模式 + 折叠切换
+const [collapsed, setCollapsed] = useState(false);
+<Navigation items={items} mode="vertical" isCollapsed={collapsed} onCollapseChange={setCollapsed}
+  defaultSelectedKeys={["home"]} onSelect={(k) => console.log(k)} />
+
+// 水平模式
 <Navigation items={items} mode="horizontal" trigger="click" />
 ```
 
+**NavItem**：`key`、`label`、`icon?: React.ReactNode`、`disabled?: boolean`、`children?: NavItem[]`
+
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `items` | `NavItem[]` | — | 菜单项 |
 | `mode` | `"horizontal" \| "vertical"` | `"vertical"` | 排列模式 |
 | `trigger` | `"hover" \| "click"` | `"hover"` | 子菜单触发方式 |
+| `isCollapsed` | `boolean` | — | 折叠状态（受控） |
+| `defaultIsCollapsed` | `boolean` | `false` | 默认折叠状态 |
+| `onCollapseChange` | `(isCollapsed: boolean) => void` | — | 折叠切换回调 |
+| `selectedKeys / defaultSelectedKeys` | `string[]` | — | 当前选中 |
+| `openKeys / defaultOpenKeys` | `string[]` | — | 当前展开的子菜单 |
+| `multiple` | `boolean` | `false` | 是否多选 |
 | `onSelect` | `(key: string) => void` | — | 选中回调 |
+| `onOpenChange` | `(openKeys: string[]) => void` | — | 展开变化回调 |
 
 ### Tabs 标签页
 

package/component/input/Form.d.ts

@@ -55,6 +55,20 @@ export interface FormApi {
     validate: () => Promise<Record<string, any> | null>;
     reset: () => void;
     setError: (field: string, error: string | null) => void;
+    /** 动态添加字段(若已存在则更新) */
+    addField: (field: string, meta?: {
+        label?: React.ReactNode;
+        rules?: FormRule[];
+        value?: any;
+    }) => void;
+    /** 动态移除字段 */
+    removeField: (field: string) => void;
+    /** 获取单个字段值 */
+    getFieldValue: (field: string) => any;
+    /** 设置单个字段值 */
+    setFieldValue: (field: string, value: any) => void;
+    /** 批量设置字段值(合并, 仅更新已注册字段) */
+    setFieldsValue: (values: Record<string, any>) => void;
 }
 /**
  * 表单。
@@ -70,6 +84,11 @@ export declare class Form extends AbstractUI<FormProps, FormState> {
     private updateField;
     private getValues;
     private setValues;
+    private addField;
+    private removeField;
+    private getFieldValue;
+    private setFieldValue;
+    private setFieldsValue;
     private validate;
     private reset;
     private setError;

package/component/input/Input.d.ts

@@ -5,10 +5,13 @@ declare class TextArea extends AbstractUI<TextAreaProps, TextAreaState> {
     static displayName: string;
     private textareaRef;
     constructor(props: TextAreaProps);
+    componentDidUpdate(prevProps: Readonly<TextAreaProps>, _prevState: Readonly<TextAreaState>): void;
     focus(): void;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface TextAreaProps extends UIProps {
+    /** 受控值(提供后组件变为受控模式) */
+    value?: string;
     defaultValue?: string;
     placeholder?: string;
     maxLength?: number;
@@ -28,12 +31,15 @@ export declare class Input extends AbstractUI<InputProps, InputState> {
     static TextArea: typeof TextArea;
     private inputRef;
     constructor(props: InputProps);
+    componentDidUpdate(prevProps: Readonly<InputProps>, _prevState: Readonly<InputState>): void;
     focus(): void;
     blur(): void;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface InputProps extends UIProps {
     type?: "text" | "password";
+    /** 受控值(提供后组件变为受控模式) */
+    value?: string;
     defaultValue?: string;
     placeholder?: string;
     size?: "small" | "default" | "large";

package/component/input/index.d.ts

@@ -9,7 +9,7 @@ export type { ColorPickerProps, ColorValue } from "./ColorPicker";
 export { DatePicker } from "./DatePicker";
 export type { DatePickerProps } from "./DatePicker";
 export { Form } from "./Form";
-export type { FormProps } from "./Form";
+export type { FormProps, FormApi, FormRule } from "./Form";
 export { KeyValueEditor } from "./KeyValueEditor";
 export type { KeyValueEditorProps, KeyValueRow } from "./KeyValueEditor";
 export { Input } from "./Input";

package/index.d.ts

@@ -1,3 +1,2 @@
 export * from "./base";
 export * from "./component";
-export * from "./test";