iter(g91): 表单字段补辅助说明 hint

packages/skin/ui/src/form.ts

@@ -35,8 +35,9 @@ export function formItem(props: FormItemProps, control: HTMLElement): FormItemHa
   const mode = props.validateOn ?? 'blur'; // 校验时机；缺省失焦校验
   const rules = [...(props.required ? [{ required: true }] : []), ...(props.rules ?? [])]; // 必填规则排最前
   const error = h('div', { class: 'ua-form-error' });
+  const hint = props.hint ? h('div', { class: 'ua-form-hint' }, props.hint) : null; // 辅助说明：报错时隐藏，避免与错误挤在一起
   const label = h('label', { class: 'ua-form-label' }, props.label, props.required ? h('i', { class: 'ua-form-req' }, '*') : null);
-  const el = h('div', { class: 'ua-form-item' }, label, h('div', { class: 'ua-form-control' }, control, error));
+  const el = h('div', { class: 'ua-form-item' }, label, h('div', { class: 'ua-form-control' }, control, hint, error));
   let seq = 0; // 校验轮次：异步结论回来时若已有更新的一轮，丢弃旧结果（防乱序覆盖）
 
   /*** 错误态落点：控件根 + 内部原生控件，保证 select / checkbox 这类包裹式控件也能标红 ***/
@@ -48,6 +49,7 @@ export function formItem(props: FormItemProps, control: HTMLElement): FormItemHa
   /*** 落笔：错误文案 + 控件红框 + aria-invalid，视觉与读屏同源 ***/
   const paint = (msg: string | null): void => {
     error.textContent = msg ?? '';
+    if (hint) hint.hidden = !!msg; // 有错时让位：同一位置只留一条提示
     control.classList.toggle('ua-invalid', !!msg);
     for (const node of marked()) node.setAttribute('aria-invalid', String(!!msg));
   };

packages/skin/ui/src/types.ts

@@ -363,6 +363,7 @@ export interface FormItemProps {
   required?: boolean;        // 必填：显示红星并自动追加非空规则
   rules?: FormRule[];        // 附加校验规则，按序执行
   validateOn?: 'input' | 'blur' | 'submit'; // 校验时机；缺省 blur
+  hint?: string;              // 控件下方辅助说明（格式提示等）；报错时让位给错误文案
 }
 
 /*** 表单字段句柄：form 聚合校验用 ***/

packages/skin/ui/ua.manifest.json

@@ -1568,6 +1568,11 @@
             "d": "校验时机；缺省 blur（输入时自动清已报错误）",
             "df": "blur"
           },
+          {
+            "n": "（formItem）hint",
+            "t": "string",
+            "d": "控件下方辅助说明（格式提示等）；报错时让位给错误文案"
+          },
           {
             "n": "onReset",
             "t": "() => void",
@@ -1586,7 +1591,8 @@
           "触发时机用 input / change / focusout（均会冒泡），因此 checkbox / select / 单选组这类包裹式控件同样能失焦校验",
           "单行输入框内按 Enter 等同点击提交（textarea 内仍是换行）；提交按钮为 type=\"submit\"，不会与点击回调重复触发",
           "rules.validator 返回 Promise 即为异步规则（如「邀请码是否已被使用」远程校验）：提交时逐项 await，校验期间提交按钮禁用，结论按轮次取舍避免乱序覆盖",
-          "formItem 返回 { el, validate, validateAsync } 句柄：validate 只跑同步规则（供 blur/input 即时反馈），validateAsync 逐条 await 供 form 聚合提交"
+          "formItem 返回 { el, validate, validateAsync } 句柄：validate 只跑同步规则（供 blur/input 即时反馈），validateAsync 逐条 await 供 form 聚合提交",
+          "需要给字段加格式说明就传 hint：平时显示在控件下方，校验失败时自动让位给错误文案，同一位置不堆两行"
         ]
       },
       {

packages/skin/ui/ui.css

@@ -1493,6 +1493,14 @@ button.ua-step-dot:hover {
   flex-direction: column;
   gap: 4px;
 }
+.ua-form-hint {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+  margin-top: 4px;
+}
+.ua-form-hint[hidden] {
+  display: none;
+}
 .ua-form-error {
   color: var(--ua-color-danger);
   font-size: var(--ua-font-size-sm);