@chenzy-design/svelte 0.3.1 → 0.4.1

package/dist/form/Form.svelte

@@ -7,37 +7,64 @@
   import { untrack, type Snippet } from 'svelte';
   import {
     createForm,
+    type FormApi,
+    type FormState,
     type FormValues,
     type FieldErrors,
     type MessageDescriptor,
     type ValidateTrigger,
   } from '@chenzy-design/core';
-  import { interpolate } from '@chenzy-design/locale';
   import {
     setFormContext,
     type FormLayout,
     type FormLabelPosition,
-    type FormSize,
     type FormLabelAlign,
     type GridCol,
   } from './context.js';
   import { useLocale } from '../locale-provider/index.js';
-  import { getGlobalValidateMessages } from '../config-provider/index.js';
+
+  /** children-as-function 入参（对齐 Semi FormFCChild：拿到 formState/formApi）。 */
+  interface FormRenderArgs {
+    formState: FormState;
+    formApi: FormApi;
+  }
+
+  /** scrollToField/scrollToError 增补方法（DOM 层，注入到 getFormApi 回传的句柄）。 */
+  type ScrollToOptions = boolean | ScrollIntoViewOptions;
+  interface FormApiWithScroll extends FormApi {
+    /** 滚动到指定字段（对齐 Semi scrollToField）。 */
+    scrollToField(field: string, opts?: ScrollIntoViewOptions): void;
+    /** 滚动到首个错误字段（对齐 Semi scrollToError）。 */
+    scrollToError(opts?: ScrollIntoViewOptions): void;
+    /**
+     * 读取 Form 组件当前 props 值（对齐 Semi getFormProps）。不传 propNames 返回全部；
+     * 传入名称数组则只返回这些 prop 的子集。例如读 disabled、layout 等。
+     */
+    getFormProps(propNames?: string[]): Record<string, unknown>;
+  }
 
   interface Props {
+    /**
+     * 外部预建的 FormApi（对齐 Semi `Form.useForm()` + `<Form form={api}>`）。传入时用它作为
+     * headless 实例，父组件可在渲染 <Form> 前 `const form = createForm(...)` 并立即操作
+     * （Svelte 无需 React 的 Proxy 延迟绑定）。不传则内部 createForm（getFormApi 回调仍可拿句柄）。
+     * 注意：外部 form 的 initialValues/validateTrigger 等构造项由创建方决定，Form 上对应 prop
+     * （initValues/validateTrigger/...）在传入 form 时不再重复应用（避免双写）。
+     */
+    form?: FormApi;
     /** controlled whole-form values (reported back via onChange, never written to the prop) */
     value?: FormValues;
     initValues?: FormValues;
     layout?: FormLayout;
-    /** 'top' | 'left' | 'inset'（inset：label 浮入控件，聚焦/有值时上浮变小） */
+    /** form 元素 id（同时写到 x-form-id 供 scrollToError 定位）。 */
+    id?: string;
+    /** 'top' | 'left' | 'inset'（inset：label 作为内嵌前缀显示在控件内部左侧，对齐 Semi） */
     labelPosition?: FormLabelPosition;
     labelWidth?: number | string;
     /** Label 文本对齐（spec §4 L60，默认 'left'）。 */
     labelAlign?: FormLabelAlign;
-    size?: FormSize;
     disabled?: boolean;
     requiredMark?: boolean;
-    colon?: boolean;
     /** on failed submit, scroll to and focus the first errored field */
     scrollToError?: boolean;
     /** 全局默认校验时机（spec §4 L65，默认 ['blur','change']），字段可覆盖。 */
@@ -46,70 +73,120 @@
     showValidateIcon?: boolean;
     /** 字段命中首条错误即停止该字段后续 rule（spec §4 L68，默认 false）。 */
     stopValidateWithError?: boolean;
-    /** 是否拦截原生 submit 默认行为（spec §4 L69，默认 true）。 */
-    preventDefault?: boolean;
+    /**
+     * 提交/重置时是否阻止事件冒泡（对齐 Semi stopPropagation 对象：{submit?, reset?}）。
+     */
+    stopPropagation?: { submit?: boolean; reset?: boolean };
     /** 收集值时是否保留空值字段键（spec §4 L70，默认 false）。 */
     allowEmpty?: boolean;
-    /** scrollToError 别名（优先级低于 scrollToError）。 */
-    autoScrollToError?: boolean;
+    /**
+     * Form 级别自定义校验器（对齐 Semi validator，推荐）。submit / formApi.validate()
+     * 时调用，入参为收集后的 values，返回 { field: 错误信息 } 映射（空映射即校验通过）。
+     * 支持同步或异步（返回 Promise）。配置后，字段级 rules/validator 在 submit/validate
+     * 时不再触发（Semi 语义：Form 级校验器优先）。
+     */
+    validator?: (values: Record<string, unknown>) => unknown;
+    /** validator 的旧别名（对齐 Semi validateFields，仍保持兼容）。 */
+    validateFields?: (values: Record<string, unknown>) => unknown;
+    /**
+     * 提交校验失败时滚动到首个错误字段（scrollToError 别名，可为 boolean 或
+     * ScrollIntoViewOptions，对齐 Semi autoScrollToError）。
+     */
+    autoScrollToError?: boolean | ScrollIntoViewOptions;
     /** 额外说明文本位置（默认 'bottom'，经 context 传给 FormField）。 */
     extraTextPosition?: 'middle' | 'bottom';
+    /**
+     * Form 挂载后一次性回调，回传内部 headless FormApi 句柄（Semi getFormApi，
+     * props-gap-tracker §1 Form 高）。这是「渲染 <Form> 的父组件」唯一的命令式逃生舱：
+     * FormApi 经 context 只下发给后代 Field，父级够不到；拿到句柄后可在外部
+     * setValues / validate / validateField / reset。
+     * 注：Semi 的 `validateFields` 是 Form 级自定义校验器（validator 旧别名），
+     * 并非独立的外部触发校验入口——外部触发校验由本回调回传的 formApi.validate()
+     * / formApi.validateField() 直接覆盖，故不单列 prop。
+     */
+    getFormApi?: (formApi: FormApiWithScroll) => void;
     onSubmit?: (r: { valid: boolean; values: FormValues; errors: FieldErrors }) => void;
     /** 任意字段值变化时触发（不同于 onChange 的纯值快照，此回调额外携带变更字段信息）。 */
     onValueChange?: (values: FormValues, changedValues: Record<string, unknown>) => void;
-    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支）。 */
-    onSubmitFail?: (errors: FieldErrors, values: FormValues) => void;
+    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支；带原生 submit 事件）。 */
+    onSubmitFail?: (errors: FieldErrors, values: FormValues, e: SubmitEvent) => void;
     onChange?: (values: FormValues) => void;
+    /** 表单重置时回调（点击原生 reset 或 formApi.reset()）（Semi onReset，spec §4 Events reset）。 */
+    onReset?: () => void;
+    /** 任意字段错误集合变化时回调，入参为最新 formState.errors + 变更子集（Semi onErrorChange）。 */
+    onErrorChange?: (errors: FieldErrors, changedError: FieldErrors) => void;
     /** 控件布局列配置（Grid 布局时）。 */
     wrapperCol?: GridCol;
     /** 标签布局列配置（Grid 布局时）。 */
     labelCol?: GridCol;
-    children?: Snippet;
+    /**
+     * 表单内容。可为无参 snippet（普通用法），也可为带参 snippet 拿到
+     * { formState, formApi }（对齐 Semi children-as-function / render）。
+     */
+    children?: Snippet<[FormRenderArgs]> | Snippet;
+    /**
+     * 用于声明表单控件的带参 snippet（对齐 Semi render 属性）。入参 { formState, formApi }。
+     * 与 children / component 互斥（优先级 children > render > component）。Svelte 中
+     * render props / children function / component 三种在 React 里的不同入口，统一为带参 snippet。
+     */
+    render?: Snippet<[FormRenderArgs]>;
+    /**
+     * 用于声明表单控件的带参 snippet（对齐 Semi component 属性）。入参 { formState, formApi }。
+     * 与 children / render 互斥（优先级 children > render > component）。
+     */
+    component?: Snippet<[FormRenderArgs]>;
     footer?: Snippet<[{ submitting: boolean }]>;
+    /** 透传到 form 的原生属性（class、style、data-attr、name、action、aria-label 等）。 */
+    [key: string]: unknown;
   }
 
   let {
+    form: externalForm,
     value,
     initValues = {},
     layout = 'vertical',
+    id,
     labelPosition = 'top',
     labelWidth,
     labelAlign = 'left',
-    size = 'default',
     disabled = false,
     requiredMark = true,
-    colon = false,
     scrollToError = false,
     autoScrollToError = false,
     extraTextPosition = 'bottom',
     validateTrigger = ['blur', 'change'],
     showValidateIcon = true,
     stopValidateWithError = false,
-    preventDefault = true,
+    stopPropagation,
     allowEmpty = false,
+    validator,
+    validateFields,
+    getFormApi,
     onSubmit,
     onValueChange,
     onSubmitFail,
     onChange,
+    onReset,
+    onErrorChange,
     wrapperCol,
     labelCol,
     children,
+    render,
+    component,
     footer,
+    ...rest
   }: Props = $props();
 
+  // 声明控件的 snippet：children > render > component（对齐 Semi 三种写法优先级）。
+  const contentSnippet = $derived(children ?? render ?? component);
+
   const loc = useLocale();
-  // 全局校验文案覆盖（来自 ConfigProvider getValidateMessages）；须在 init 期读 context。
-  const globalValidateMessages = getGlobalValidateMessages();
 
-  // 校验消息优先级：
+  // 校验消息优先级（对齐 Semi：ConfigProvider 无全局校验文案覆盖，文案走 locale）：
   // 1) rule.message（descriptor.text）显式覆盖；
-  // 2) ConfigProvider getValidateMessages() 提供的对应 `Form.*` 键模板（带插值）；
-  // 3) locale 内置 Form.* 模板。
-  // 未配置全局覆盖时行为完全不变（向后兼容）。
+  // 2) locale 内置 Form.* 模板。
   function resolveMessage(d: MessageDescriptor): string {
     if (d.text !== undefined) return d.text;
-    const override = globalValidateMessages?.()[d.key];
-    if (override !== undefined) return d.params ? interpolate(override, d.params) : override;
     return loc().t(d.key, d.params);
   }
 
@@ -120,20 +197,29 @@
   // validateTrigger / stopValidateWithError / allowEmpty are construction-time
   // config of the headless form (read once, like initialValues). untrack keeps
   // the read non-reactive — the form instance is created exactly once.
-  const form = createForm({
-    initialValues: seedValues,
-    resolveMessage,
-    validateTrigger: untrack(() => validateTrigger),
-    stopValidateWithError: untrack(() => stopValidateWithError),
-    allowEmpty: untrack(() => allowEmpty),
-  });
+  // 外部预建 form（Semi Form.useForm() 对齐）：直接用传入实例，其构造项由创建方决定，
+  // 不再用 Form 上的 initValues/validateTrigger/... 重复应用（避免双写）。untrack 让
+  // "有无外部 form" 的判定成为一次性读取，form 实例只建一次。
+  const form = untrack(() => externalForm) ??
+    createForm({
+      initialValues: seedValues,
+      resolveMessage,
+      validateTrigger: untrack(() => validateTrigger),
+      stopValidateWithError: untrack(() => stopValidateWithError),
+      allowEmpty: untrack(() => allowEmpty),
+      validator: untrack(() => validator) as never,
+      validateFields: untrack(() => validateFields) as never,
+    });
 
   // Bridge: callback-subscribe → runes. core returns a STABLE state object whose
   // sub-objects are replaced immutably; we take a fresh shallow snapshot on every
   // emit so the new reference triggers Svelte reactivity. The $effect ONLY writes
   // formState — it never reads state that children write on mount, so no loop.
-  let formState = $state({ ...form.getState() });
-  let lastValues = form.getState().values;
+  let formState = $state({ ...form.getFormState() });
+  let lastValues = form.getFormState().values;
+  // track the errors reference to fire onErrorChange only when the error set
+  // actually changes (same immutable-replacement pattern as lastValues).
+  let lastErrors = form.getFormState().errors;
   // Subscribe synchronously at component init (NOT inside an $effect): child
   // Field registration effects run after the parent's setup but emit on the core
   // bus; subscribing here guarantees we capture those early emits (e.g. a
@@ -155,14 +241,70 @@
         onValueChange(s.values, changed);
       }
     }
+    // errors is replaced immutably by core on every validate; a changed
+    // reference means the error set changed → notify (Semi onErrorChange).
+    if (s.errors !== lastErrors) {
+      const prev = lastErrors;
+      lastErrors = s.errors;
+      if (onErrorChange) {
+        // changedError: fields whose error reference differs from previous snapshot.
+        const changed: FieldErrors = {};
+        for (const k of new Set([...Object.keys(prev), ...Object.keys(s.errors)])) {
+          if (s.errors[k] !== prev[k]) changed[k] = s.errors[k];
+        }
+        onErrorChange(s.errors, changed);
+      }
+    }
   });
   $effect(() => unsub);
 
+  // getFormApi (Semi): hand the internal headless FormApi (augmented with the
+  // DOM-layer scrollToField/scrollToError) to the parent exactly once, at mount.
+  // `form` is created synchronously above and never re-created, so this is a
+  // one-shot escape hatch — not reactive. untrack keeps the read non-reactive and
+  // guarantees the callback runs a single time even though it lives in an $effect
+  // (the runes equivalent of onMount). We invoke `form` methods only; we never
+  // write child-owned render state here → no effect loop.
+  const formApiWithScroll: FormApiWithScroll = Object.assign(
+    Object.create(form) as FormApi,
+    {
+      scrollToField: (field: string, opts?: ScrollIntoViewOptions) =>
+        scrollToFieldEl(field, opts),
+      scrollToError: (opts?: ScrollIntoViewOptions) =>
+        focusFirstError(form.getFormState().errors, opts),
+      getFormProps: (propNames?: string[]): Record<string, unknown> => {
+        // 当前 Form 组件的可读 props 快照（对齐 Semi getFormProps）。
+        const all: Record<string, unknown> = {
+          layout,
+          labelPosition,
+          labelWidth,
+          labelAlign,
+          disabled,
+          requiredMark,
+          showValidateIcon,
+          extraTextPosition,
+          validateTrigger,
+          stopValidateWithError,
+          allowEmpty,
+          wrapperCol,
+          labelCol,
+        };
+        if (!propNames) return all;
+        const out: Record<string, unknown> = {};
+        for (const k of propNames) out[k] = all[k];
+        return out;
+      },
+    },
+  ) as FormApiWithScroll;
+  $effect(() => {
+    untrack(() => getFormApi?.(formApiWithScroll));
+  });
+
   // Controlled `value`: push into the form only when the prop reference changes.
   // We never write back to the prop (onChange is the only outward channel), so
   // this cannot form a value -> onChange -> value loop.
   $effect(() => {
-    if (value !== undefined) form.setFieldsValue(value);
+    if (value !== undefined) form.setValues(value);
   });
 
   setFormContext({
@@ -171,24 +313,40 @@
     getLabelPosition: () => labelPosition,
     getLabelWidth: () => labelWidth,
     getLabelAlign: () => labelAlign,
-    getSize: () => size,
     getDisabled: () => disabled,
     getRequiredMark: () => requiredMark,
-    getColon: () => colon,
     getShowValidateIcon: () => showValidateIcon,
     getExtraTextPosition: () => extraTextPosition,
     getWrapperCol: () => wrapperCol,
     getLabelCol: () => labelCol,
   });
 
-  // autoScrollToError 是 scrollToError 别名（scrollToError 优先）
-  const effScrollToError = $derived(scrollToError || autoScrollToError || false);
+  // autoScrollToError 是 scrollToError 别名（scrollToError 优先）。可为 boolean 或
+  // ScrollIntoViewOptions（对齐 Semi），object 形态即视为开启并作为滚动参数。
+  const effScrollToError = $derived(scrollToError || autoScrollToError !== false);
+  const scrollOpts = $derived(
+    typeof autoScrollToError === 'object' ? autoScrollToError : undefined,
+  );
 
   // ref to the <form> element — used imperatively (red line #3: DOM ops live in
   // the event handler, never in render) to locate the first errored field.
   let formEl: HTMLFormElement | undefined;
 
-  function focusFirstError(errors: FieldErrors): void {
+  const DEFAULT_SCROLL: ScrollIntoViewOptions = { behavior: 'smooth', block: 'center' };
+
+  // scroll to (and focus) a single field by name (Semi scrollToField).
+  function scrollToFieldEl(field: string, opts?: ScrollIntoViewOptions): void {
+    if (!formEl) return;
+    const node = formEl.querySelector<HTMLElement>(`[data-field="${field}"]`);
+    if (!node) return;
+    node.scrollIntoView(opts ?? DEFAULT_SCROLL);
+    const control = node.querySelector<HTMLElement>(
+      'input, textarea, select, [tabindex]:not([tabindex="-1"])',
+    );
+    control?.focus({ preventScroll: true });
+  }
+
+  function focusFirstError(errors: FieldErrors, opts?: ScrollIntoViewOptions): void {
     if (!formEl) return;
     // walk fields in DOM order so we land on the *first* errored one on screen.
     const nodes = formEl.querySelectorAll<HTMLElement>('[data-field]');
@@ -197,7 +355,7 @@
       if (name === undefined) continue;
       const err = errors[name];
       if (err === undefined || err === '') continue;
-      node.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      node.scrollIntoView(opts ?? DEFAULT_SCROLL);
       const control = node.querySelector<HTMLElement>(
         'input, textarea, select, [tabindex]:not([tabindex="-1"])',
       );
@@ -206,23 +364,47 @@
     }
   }
 
+  // Native <form> reset (a `<button type="reset">` or form.reset()). Red line #3:
+  // this DOM-driven side effect lives in the event handler, never in render. We
+  // reset the headless state then notify (Semi onReset / spec §4 Events reset).
+  function handleReset(e: Event) {
+    // stopPropagation.reset: 阻止 reset 事件冒泡（对齐 Semi stopPropagation 对象）。
+    if (stopPropagation?.reset) e.stopPropagation();
+    form.reset();
+    onReset?.();
+  }
+
   async function handleSubmit(e: SubmitEvent) {
-    // spec §4 L69 / §6 L140: preventDefault is now prop-controlled (default true
-    // = previous hardcoded behavior, backward compatible).
-    if (preventDefault) e.preventDefault();
-    const r = await form.submit();
-    if (!r.valid && effScrollToError) focusFirstError(r.errors);
-    if (!r.valid) onSubmitFail?.(r.errors, r.values);
+    // Semi 硬编码拦截原生 submit 默认行为（不再暴露 preventDefault prop）。
+    e.preventDefault();
+    // stopPropagation.submit: 阻止 submit 事件冒泡（对齐 Semi stopPropagation 对象）。
+    if (stopPropagation?.submit) e.stopPropagation();
+    const r = await form.submitForm();
+    if (!r.valid && effScrollToError) focusFirstError(r.errors, scrollOpts);
+    if (!r.valid) onSubmitFail?.(r.errors, r.values, e);
     onSubmit?.(r);
   }
 
+  // form class 严格对齐 Semi baseForm（`.cd-form` + `-vertical`/`-horizontal`）。
+  // label 位置不进 form class（由每个 field 的 x-label-pos 属性驱动），间距由 field padding 承载。
   const cls = $derived(
-    `cd-form cd-form--${layout} cd-form--label-${labelPosition} cd-form--${size}`,
+    [`cd-form cd-form-${layout}`, rest.class].filter(Boolean).join(' '),
   );
+  // x-form-id mirrors Semi for external DOM queries; scrolling uses the formEl
+  // ref directly, so this is parity-only. Merged into rest so svelte-check
+  // accepts the non-standard attribute name.
+  const formAttrs = $derived({ ...rest, ...(id ? { 'x-form-id': id } : {}) });
 </script>
 
-<form bind:this={formEl} class={cls} onsubmit={handleSubmit}>
-  {@render children?.()}
+<form
+  bind:this={formEl}
+  {...formAttrs}
+  {id}
+  class={cls}
+  onsubmit={handleSubmit}
+  onreset={handleReset}
+>
+  {@render (contentSnippet as Snippet<[FormRenderArgs]>)?.({ formState, formApi: formApiWithScroll })}
   {#if footer}
     <div class="cd-form__footer">
       {@render footer({ submitting: formState.submitting })}
@@ -231,10 +413,36 @@
 </form>
 
 <style>
-  .cd-form {
+  /*
+    间距模型严格对齐 Semi form.scss：form 无 gap，靠每个 field 的 padding 撑间距。
+    vertical：field 上下 padding + overflow:hidden；horizontal：flex-wrap + field 右侧 padding。
+    这些规则跨 Field 组件生效，故用 :global。
+  */
+  :global(.cd-form-vertical .cd-form-field) {
+    margin: 0;
+    padding-block-start: var(--cd-spacing-form-field-vertical-paddingtop);
+    padding-block-end: var(--cd-spacing-form-field-vertical-paddingbottom);
+    overflow: hidden;
+  }
+  :global(.cd-form-vertical .cd-form-field-group) {
+    margin: 0;
+    padding-block-start: var(--cd-spacing-form-field-group-vertical-paddingtop);
+    padding-block-end: var(--cd-spacing-form-field-group-vertical-paddingbottom);
+    overflow: hidden;
+  }
+  .cd-form-horizontal {
     display: flex;
-    flex-direction: column;
-    gap: var(--cd-form-item-gap, var(--cd-spacing-base));
+    flex-wrap: wrap;
+  }
+  :global(.cd-form-horizontal .cd-form-field) {
+    margin-inline-start: 0;
+    padding-inline-end: var(--cd-spacing-form-field-horizontal-paddingright);
+  }
+  :global(.cd-form-horizontal .cd-form-field:last-child) {
+    margin-inline-end: var(--cd-spacing-form-field-horizontal-paddingright);
+  }
+  :global(.cd-form-horizontal .cd-form-field-group) {
+    padding-inline-end: var(--cd-spacing-form-field-group-horizontal-paddingright);
   }
   .cd-form__footer {
     display: flex;

package/dist/form/Form.svelte.d.ts

@@ -1,20 +1,44 @@
 import { type Snippet } from 'svelte';
-import { type FormValues, type FieldErrors, type ValidateTrigger } from '@chenzy-design/core';
-import { type FormLayout, type FormLabelPosition, type FormSize, type FormLabelAlign, type GridCol } from './context.js';
+import { type FormApi, type FormState, type FormValues, type FieldErrors, type ValidateTrigger } from '@chenzy-design/core';
+import { type FormLayout, type FormLabelPosition, type FormLabelAlign, type GridCol } from './context.js';
+/** children-as-function 入参（对齐 Semi FormFCChild：拿到 formState/formApi）。 */
+interface FormRenderArgs {
+    formState: FormState;
+    formApi: FormApi;
+}
+interface FormApiWithScroll extends FormApi {
+    /** 滚动到指定字段（对齐 Semi scrollToField）。 */
+    scrollToField(field: string, opts?: ScrollIntoViewOptions): void;
+    /** 滚动到首个错误字段（对齐 Semi scrollToError）。 */
+    scrollToError(opts?: ScrollIntoViewOptions): void;
+    /**
+     * 读取 Form 组件当前 props 值（对齐 Semi getFormProps）。不传 propNames 返回全部；
+     * 传入名称数组则只返回这些 prop 的子集。例如读 disabled、layout 等。
+     */
+    getFormProps(propNames?: string[]): Record<string, unknown>;
+}
 interface Props {
+    /**
+     * 外部预建的 FormApi（对齐 Semi `Form.useForm()` + `<Form form={api}>`）。传入时用它作为
+     * headless 实例，父组件可在渲染 <Form> 前 `const form = createForm(...)` 并立即操作
+     * （Svelte 无需 React 的 Proxy 延迟绑定）。不传则内部 createForm（getFormApi 回调仍可拿句柄）。
+     * 注意：外部 form 的 initialValues/validateTrigger 等构造项由创建方决定，Form 上对应 prop
+     * （initValues/validateTrigger/...）在传入 form 时不再重复应用（避免双写）。
+     */
+    form?: FormApi;
     /** controlled whole-form values (reported back via onChange, never written to the prop) */
     value?: FormValues;
     initValues?: FormValues;
     layout?: FormLayout;
-    /** 'top' | 'left' | 'inset'（inset：label 浮入控件，聚焦/有值时上浮变小） */
+    /** form 元素 id（同时写到 x-form-id 供 scrollToError 定位）。 */
+    id?: string;
+    /** 'top' | 'left' | 'inset'（inset：label 作为内嵌前缀显示在控件内部左侧，对齐 Semi） */
     labelPosition?: FormLabelPosition;
     labelWidth?: number | string;
     /** Label 文本对齐（spec §4 L60，默认 'left'）。 */
     labelAlign?: FormLabelAlign;
-    size?: FormSize;
     disabled?: boolean;
     requiredMark?: boolean;
-    colon?: boolean;
     /** on failed submit, scroll to and focus the first errored field */
     scrollToError?: boolean;
     /** 全局默认校验时机（spec §4 L65，默认 ['blur','change']），字段可覆盖。 */
@@ -23,14 +47,41 @@ interface Props {
     showValidateIcon?: boolean;
     /** 字段命中首条错误即停止该字段后续 rule（spec §4 L68，默认 false）。 */
     stopValidateWithError?: boolean;
-    /** 是否拦截原生 submit 默认行为（spec §4 L69，默认 true）。 */
-    preventDefault?: boolean;
+    /**
+     * 提交/重置时是否阻止事件冒泡（对齐 Semi stopPropagation 对象：{submit?, reset?}）。
+     */
+    stopPropagation?: {
+        submit?: boolean;
+        reset?: boolean;
+    };
     /** 收集值时是否保留空值字段键（spec §4 L70，默认 false）。 */
     allowEmpty?: boolean;
-    /** scrollToError 别名（优先级低于 scrollToError）。 */
-    autoScrollToError?: boolean;
+    /**
+     * Form 级别自定义校验器（对齐 Semi validator，推荐）。submit / formApi.validate()
+     * 时调用，入参为收集后的 values，返回 { field: 错误信息 } 映射（空映射即校验通过）。
+     * 支持同步或异步（返回 Promise）。配置后，字段级 rules/validator 在 submit/validate
+     * 时不再触发（Semi 语义：Form 级校验器优先）。
+     */
+    validator?: (values: Record<string, unknown>) => unknown;
+    /** validator 的旧别名（对齐 Semi validateFields，仍保持兼容）。 */
+    validateFields?: (values: Record<string, unknown>) => unknown;
+    /**
+     * 提交校验失败时滚动到首个错误字段（scrollToError 别名，可为 boolean 或
+     * ScrollIntoViewOptions，对齐 Semi autoScrollToError）。
+     */
+    autoScrollToError?: boolean | ScrollIntoViewOptions;
     /** 额外说明文本位置（默认 'bottom'，经 context 传给 FormField）。 */
     extraTextPosition?: 'middle' | 'bottom';
+    /**
+     * Form 挂载后一次性回调，回传内部 headless FormApi 句柄（Semi getFormApi，
+     * props-gap-tracker §1 Form 高）。这是「渲染 <Form> 的父组件」唯一的命令式逃生舱：
+     * FormApi 经 context 只下发给后代 Field，父级够不到；拿到句柄后可在外部
+     * setValues / validate / validateField / reset。
+     * 注：Semi 的 `validateFields` 是 Form 级自定义校验器（validator 旧别名），
+     * 并非独立的外部触发校验入口——外部触发校验由本回调回传的 formApi.validate()
+     * / formApi.validateField() 直接覆盖，故不单列 prop。
+     */
+    getFormApi?: (formApi: FormApiWithScroll) => void;
     onSubmit?: (r: {
         valid: boolean;
         values: FormValues;
@@ -38,17 +89,38 @@ interface Props {
     }) => void;
     /** 任意字段值变化时触发（不同于 onChange 的纯值快照，此回调额外携带变更字段信息）。 */
     onValueChange?: (values: FormValues, changedValues: Record<string, unknown>) => void;
-    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支）。 */
-    onSubmitFail?: (errors: FieldErrors, values: FormValues) => void;
+    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支；带原生 submit 事件）。 */
+    onSubmitFail?: (errors: FieldErrors, values: FormValues, e: SubmitEvent) => void;
     onChange?: (values: FormValues) => void;
+    /** 表单重置时回调（点击原生 reset 或 formApi.reset()）（Semi onReset，spec §4 Events reset）。 */
+    onReset?: () => void;
+    /** 任意字段错误集合变化时回调，入参为最新 formState.errors + 变更子集（Semi onErrorChange）。 */
+    onErrorChange?: (errors: FieldErrors, changedError: FieldErrors) => void;
     /** 控件布局列配置（Grid 布局时）。 */
     wrapperCol?: GridCol;
     /** 标签布局列配置（Grid 布局时）。 */
     labelCol?: GridCol;
-    children?: Snippet;
+    /**
+     * 表单内容。可为无参 snippet（普通用法），也可为带参 snippet 拿到
+     * { formState, formApi }（对齐 Semi children-as-function / render）。
+     */
+    children?: Snippet<[FormRenderArgs]> | Snippet;
+    /**
+     * 用于声明表单控件的带参 snippet（对齐 Semi render 属性）。入参 { formState, formApi }。
+     * 与 children / component 互斥（优先级 children > render > component）。Svelte 中
+     * render props / children function / component 三种在 React 里的不同入口，统一为带参 snippet。
+     */
+    render?: Snippet<[FormRenderArgs]>;
+    /**
+     * 用于声明表单控件的带参 snippet（对齐 Semi component 属性）。入参 { formState, formApi }。
+     * 与 children / render 互斥（优先级 children > render > component）。
+     */
+    component?: Snippet<[FormRenderArgs]>;
     footer?: Snippet<[{
         submitting: boolean;
     }]>;
+    /** 透传到 form 的原生属性（class、style、data-attr、name、action、aria-label 等）。 */
+    [key: string]: unknown;
 }
 declare const Form: import("svelte").Component<Props, {}, "">;
 type Form = ReturnType<typeof Form>;

package/dist/form/Form.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Form.svelte.d.ts","sourceRoot":"","sources":["../../src/form/Form.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE/B,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,cAAc,CAAC;AAKtB,UAAU,KAAK;IACb,2FAA2F;IAC3F,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IACtD,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,IAAI,CAAC;IACpF,oDAAoD;IACpD,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrF,mDAAmD;IACnD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACjE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,yBAAyB;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7C;AAiLH,QAAA,MAAM,IAAI,2CAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}
+{"version":3,"file":"Form.svelte.d.ts","sourceRoot":"","sources":["../../src/form/Form.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAEH,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAC/B,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,cAAc,CAAC;AAItB,yEAAyE;AACzE,UAAU,cAAc;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,UAAU,iBAAkB,SAAQ,OAAO;IACzC,sCAAsC;IACtC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACjE,wCAAwC;IACxC,aAAa,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7D;AAED,UAAU,KAAK;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2FAA2F;IAC3F,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IACtD,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;OAEG;IACH,eAAe,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACxD,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACzD,oDAAoD;IACpD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC9D;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,qBAAqB,CAAC;IACpD,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,IAAI,CAAC;IACpF,oDAAoD;IACpD,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrF,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IACjF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;IACzE,yBAAyB;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,OAAO,CAAC;IAC/C;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;IAC5C,sEAAsE;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAyRH,QAAA,MAAM,IAAI,2CAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}