knight-ui 1.0.3 → 1.0.5

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 标签页
 
@@ -1471,25 +1541,56 @@ import { Tooltip, Button } from "knight-ui";
 
 ```tsx
 import { Popconfirm, Button } from "knight-ui";
+import { IconAlertTriangle } from "knight-ui";
 
+// 基础用法 (默认 position="bottom", trigger="click")
 <Popconfirm
   title="确定删除？"
   content="删除后不可恢复"
-  trigger="click"
   onConfirm={() => console.log("confirmed")}
   onCancel={() => console.log("cancelled")}
 >
   <Button type="danger">删除</Button>
 </Popconfirm>
+
+// 自定义按钮文字 + 图标
+<Popconfirm title="确定保存?" content="保存后覆盖原有数据"
+  icon={<IconAlertTriangle size="extraLarge" color="var(--ku-color-warning)" />}
+  okText="保存" cancelText="取消"
+  onConfirm={() => console.log("saved")}>
+  <Button type="warning">保存</Button>
+</Popconfirm>
+
+// 8 方向弹出 (position)
+<Popconfirm title="确认?" position="leftTop" onConfirm={() => {}}>
+  <Button>左上弹出</Button>
+</Popconfirm>
+<Popconfirm title="确认?" position="rightBottom" onConfirm={() => {}}>
+  <Button>右下弹出</Button>
+</Popconfirm>
+
+// hover 触发 + 带箭头
+<Popconfirm title="提示" content="悬停即可查看" trigger="hover" showArrow position="top"
+  onConfirm={() => {}}>
+  <Button type="secondary">悬停触发</Button>
+</Popconfirm>
 ```
 
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `title` | `React.ReactNode` | — | 标题 |
 | `content` | `React.ReactNode` | — | 内容 |
-| `okText / cancelText` | `string` | — | 按钮文字 |
+| `position` | `"top" \| "bottom" \| "left" \| "right" \| "leftTop" \| "rightTop" \| "leftBottom" \| "rightBottom"` | `"bottom"` | 弹出位置（命名规则: 第一个词=左右, 第二个词=上下） |
+| `trigger` | `"click" \| "hover" \| "focus" \| "custom"` | `"click"` | 触发方式 |
+| `icon` | `React.ReactNode` | — | 自定义图标 |
+| `showArrow` | `boolean` | `false` | 显示箭头 |
+| `okText / cancelText` | `string` | `"确认" / "取消"` | 按钮文字 |
+| `okButtonProps / cancelButtonProps` | `ButtonHTMLAttributes` | — | 按钮额外属性 |
+| `visible / defaultVisible` | `boolean` | — | 受控/非受控显示 |
+| `offset` | `number` | `4` | 弹出偏移距离 |
 | `onConfirm` | `(e) => void` | — | 确认回调 |
 | `onCancel` | `(e) => void` | — | 取消回调 |
+| `onVisibleChange` | `(visible: boolean) => void` | — | 显示状态变化回调 |
 
 ### Calendar 日历
 

package/component/feedback/Popconfirm.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
-type PopconfirmPosition = "top" | "topLeft" | "topRight" | "bottom" | "bottomLeft" | "bottomRight" | "left" | "leftTop" | "leftBottom" | "right" | "rightTop" | "rightBottom";
+type PopconfirmPosition = "top" | "bottom" | "left" | "right" | "leftTop" | "rightTop" | "leftBottom" | "rightBottom";
 type PopconfirmTrigger = "click" | "hover" | "focus" | "custom";
 /**
  * 气泡确认框。

package/component/input/Form.d.ts

@@ -28,6 +28,7 @@ interface FormContextValue {
     labelWidth: number;
     disabled: boolean;
     validating: boolean;
+    formKey: number;
 }
 declare class FormField extends AbstractUI<FormFieldProps, FormFieldState> {
     static displayName: string;
@@ -55,6 +56,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;
 }
 /**
  * 表单。
@@ -69,7 +84,13 @@ export declare class Form extends AbstractUI<FormProps, FormState> {
     private registerField;
     private updateField;
     private getValues;
+    private bumpFormKey;
     private setValues;
+    private addField;
+    private removeField;
+    private getFieldValue;
+    private setFieldValue;
+    private setFieldsValue;
     private validate;
     private reset;
     private setError;
@@ -93,5 +114,6 @@ export interface FormProps extends UIProps {
 }
 interface FormState extends UIState {
     validating: boolean;
+    formKey: number;
 }
 export {};

package/component/input/Input.d.ts

@@ -4,11 +4,13 @@ import type { ValidateStatus } from "../types";
 declare class TextArea extends AbstractUI<TextAreaProps, TextAreaState> {
     static displayName: string;
     private textareaRef;
+    private _isComposing;
     constructor(props: TextAreaProps);
     focus(): void;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface TextAreaProps extends UIProps {
+    value?: string;
     defaultValue?: string;
     placeholder?: string;
     maxLength?: number;
@@ -18,15 +20,17 @@ export interface TextAreaProps extends UIProps {
     onChange?: (value: string, event?: React.ChangeEvent<HTMLTextAreaElement>) => void;
 }
 interface TextAreaState extends UIState {
-    value: string;
     focused: boolean;
 }
 /**
- * 输入框。纯非受控，浏览器原生管理输入内容，IME 无干扰。
+ * 输入框。
+ * - 受控模式: 传入 value，值完全由父组件控制
+ * - 非受控模式: 传入 defaultValue，浏览器原生管理输入内容，IME 无干扰
  */
 export declare class Input extends AbstractUI<InputProps, InputState> {
     static TextArea: typeof TextArea;
     private inputRef;
+    private _isComposing;
     constructor(props: InputProps);
     focus(): void;
     blur(): void;
@@ -34,6 +38,7 @@ export declare class Input extends AbstractUI<InputProps, InputState> {
 }
 export interface InputProps extends UIProps {
     type?: "text" | "password";
+    value?: string;
     defaultValue?: string;
     placeholder?: string;
     size?: "small" | "default" | "large";
@@ -49,7 +54,6 @@ export interface InputProps extends UIProps {
     onChange?: (value: string, event?: React.ChangeEvent<HTMLInputElement>) => void;
 }
 interface InputState extends UIState {
-    value: string;
     showPassword: boolean;
     focused: boolean;
 }

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";