@veltra/desktop 1.7.10 → 1.7.12

package/src/components/form/__test__/form.test.ts

@@ -1,41 +1,22 @@
 import { describe, expect, it } from 'vitest'
-import { createApp, h, nextTick, reactive } from 'vue'
+import { createApp, defineComponent, h, nextTick, reactive, ref } from 'vue'
 
+import { UInput } from '../../input'
 import { USelect } from '../../select'
 import { UForm } from '../index'
 
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-
 const behaviorOptions = [
   { label: '事件', value: 'event' },
   { label: '接口', value: 'api' }
 ]
 
-async function openSelect(host: HTMLElement) {
-  const input = host.querySelector('input')!
-  input.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
-  await nextTick()
-  await nextTick()
-}
-
-async function clickSelectOption(label: string) {
-  const option = [...document.body.querySelectorAll<HTMLElement>('.u-select__option')].find(
-    (el) => el.textContent === label
-  )
-  expect(option, `选项「${label}」应存在`).toBeTruthy()
-  option!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
-  await nextTick()
-  await sleep(50)
-}
-
 describe('UForm field events', () => {
-  it('field:update and field:change are separate', async () => {
+  it('编程写入触发 field:update，不依赖用户操作', async () => {
     const host = document.createElement('div')
     document.body.appendChild(host)
 
     const model = reactive({ behavior: 'event' })
     const updates: { field: string; value: unknown }[] = []
-    const changes: { field: string; args: unknown[] }[] = []
 
     const app = createApp({
       render() {
@@ -45,9 +26,6 @@ describe('UForm field events', () => {
             model,
             'onField:update': (field: string, value: unknown) => {
               updates.push({ field, value })
-            },
-            'onField:change': (field: string, ...args: unknown[]) => {
-              changes.push({ field, args })
             }
           },
           {
@@ -60,19 +38,177 @@ describe('UForm field events', () => {
 
     app.mount(host)
     updates.length = 0
-    changes.length = 0
 
     model.behavior = 'api'
     await nextTick()
 
     expect(updates.some((item) => item.field === 'behavior' && item.value === 'api')).toBe(true)
-    expect(changes).toHaveLength(0)
 
-    await openSelect(host)
-    await clickSelectOption('事件')
+    app.unmount()
+    host.remove()
+  })
+
+  it('父级重渲染时动态 props 同步到插槽控件', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ username: '' })
+    const disabled = ref(false)
+    const placeholder = ref('第一次')
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () =>
+              h(UInput, {
+                field: 'username',
+                label: '账号',
+                disabled: disabled.value,
+                placeholder: placeholder.value
+              })
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const input = () => host.querySelector('input')!
+    expect(input().disabled).toBe(false)
+    expect(input().placeholder).toBe('第一次')
+
+    disabled.value = true
+    placeholder.value = '第二次'
+    await nextTick()
+
+    expect(input().disabled).toBe(true)
+    expect(input().placeholder).toBe('第二次')
+
+    app.unmount()
+    host.remove()
+  })
+})
+
+/** 用 setup 期间生成的 id 断言实例身份 */
+let probeSeq = 0
+const Probe = defineComponent({
+  name: 'Probe',
+  props: { field: String, label: String, modelValue: String },
+  setup(props) {
+    const id = `p${++probeSeq}`
+    return () =>
+      h('div', { class: 'probe', 'data-field': props.field, 'data-id': id }, [
+        h('span', { class: 'probe-value' }, props.modelValue ?? '')
+      ])
+  }
+})
+
+describe('UForm slot identity', () => {
+  it('中间字段卸载后不复用相邻控件实例', async () => {
+    probeSeq = 0
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ a: 'A', b: 'B', c: 'C' })
+    const showB = ref(true)
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () => [
+              h(Probe, { field: 'a', label: 'A' }),
+              showB.value ? h(Probe, { field: 'b', label: 'B' }) : null,
+              h(Probe, { field: 'c', label: 'C' })
+            ]
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const idOf = (field: string) =>
+      host.querySelector(`[data-field="${field}"]`)?.getAttribute('data-id')
+
+    const cId = idOf('c')
+    expect(cId).toBe('p3')
+
+    showB.value = false
+    await nextTick()
+
+    expect(host.querySelector('[data-field="b"]')).toBeNull()
+    expect(idOf('c')).toBe(cId)
+    expect(host.querySelector('[data-field="c"] .probe-value')!.textContent).toBe('C')
+
+    app.unmount()
+    host.remove()
+  })
+
+  it('重复 field 各自保有独立实例', async () => {
+    probeSeq = 0
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ name: '同名' })
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () => [
+              h(Probe, { field: 'name', label: '左' }),
+              h(Probe, { field: 'name', label: '右' })
+            ]
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const probes = [...host.querySelectorAll('.probe')]
+    expect(probes).toHaveLength(2)
+    expect(probes[0]!.getAttribute('data-id')).toBe('p1')
+    expect(probes[1]!.getAttribute('data-id')).toBe('p2')
+    expect(probes[0]!.querySelector('.probe-value')!.textContent).toBe('同名')
+    expect(probes[1]!.querySelector('.probe-value')!.textContent).toBe('同名')
+
+    app.unmount()
+    host.remove()
+  })
+
+  it('showModified 变更前副本不抢走编辑控件', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ name: '新值' })
+    const initialModel = { name: '旧值' }
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model, initialModel, showModified: true },
+          { default: () => h(UInput, { field: 'name', label: '名称' }) }
+        )
+      }
+    })
+
+    app.mount(host)
+    await nextTick()
 
-    expect(changes).toHaveLength(1)
-    expect(changes[0]).toEqual({ field: 'behavior', args: [{ label: '事件', value: 'event' }] })
+    const live = host.querySelector('input') as HTMLInputElement | null
+    expect(live).toBeTruthy()
+    expect(live!.value).toBe('新值')
+    expect(host.querySelector('.u-form__data-before')?.textContent).toContain('旧值')
 
     app.unmount()
     host.remove()

package/src/components/form/form.vue

@@ -8,8 +8,8 @@
     :class="[cls.b, bem.is('readonly', readonly)]"
   >
     <template
-      v-for="{ node, isFormItem, formItemProps, field, modelValue } of getSlotsNodes()"
-      :key="node.key"
+      v-for="{ node, isFormItem, formItemProps, field, modelValue, renderKey } of getSlotsNodes()"
+      :key="renderKey"
     >
       <u-form-item v-if="!isFormItem && field" v-bind="formItemProps">
         <component
@@ -19,7 +19,7 @@
         />
         <div v-if="shouldShowModified(field)" :class="cls.e('data-before')">
           <span :class="cls.e('changed-tag')">{{ modifiedLabel }}</span>
-          <component :is="node" readonly :model-value="getBaselineFieldValue(field)" />
+          <component :is="createModifiedPreview(node, field)" />
         </div>
       </u-form-item>
 
@@ -32,14 +32,14 @@
 import { o } from '@cat-kit/core'
 import { bem } from '@veltra/utils'
 import { provideFormContext } from '@veltra/utils'
-import { nextTick, toRef, useTemplateRef } from 'vue'
+import { nextTick, toRef, useTemplateRef, type VNode } from 'vue'
 
 import type { BreakCols, FormProps, _FormExposed, FormEmits } from '../../types'
 import { UFormItem } from '../form-item'
 import { UGrid } from '../grid'
 import { isFieldModified } from './is-field-modified'
 import { useFormFields } from './use-form-fields'
-import { useNodeInterceptor } from './use-node-interceptor'
+import { forkUnmountedVNode, useNodeInterceptor } from './use-node-interceptor'
 
 defineOptions({ name: 'UForm' })
 
@@ -81,18 +81,13 @@ function handleFieldUpdate(field: string, value: any) {
   emit('field:update', field, value)
 }
 
-function handleFieldChange(field: string, ...args: any[]) {
-  emit('field:change', field, ...args)
-}
-
 provideFormContext({
   formProps: props,
   registerField,
   unregisterField,
   validateFields: validate,
   shouldValidate,
-  handleFieldUpdate,
-  handleFieldChange
+  handleFieldUpdate
 })
 
 const { getSlotsNodes } = useNodeInterceptor()
@@ -106,6 +101,10 @@ function getBaselineFieldValue(field: string) {
   return o(getBaselineModel() ?? {}).get(field)
 }
 
+function createModifiedPreview(node: VNode, field: string) {
+  return forkUnmountedVNode(node, { readonly: true, modelValue: getBaselineFieldValue(field) })
+}
+
 function shouldShowModified(field: string) {
   if (!props.showModified) return false
   const baseline = getBaselineModel()

package/src/components/form/use-node-interceptor.ts

@@ -1,6 +1,6 @@
 import { o } from '@cat-kit/core'
 import { extractNormalVNodes } from '@veltra/utils'
-import { useSlots, type VNode } from 'vue'
+import { cloneVNode, useSlots, type VNode } from 'vue'
 
 export type SlotRenderItem = {
   isFormItem: boolean
@@ -8,6 +8,28 @@ export type SlotRenderItem = {
   node: VNode
   field?: string
   modelValue?: any
+  /** v-for 身份：调用方 :key 优先，否则 type+field+出现次序 */
+  renderKey: string | number | symbol
+}
+
+function getVNodeTypeName(node: VNode): string {
+  const type = node.type as { name?: string; __name?: string } | string
+  if (typeof type === 'string') return type
+  if (typeof type === 'object' && type) return type.name || type.__name || ''
+  return ''
+}
+
+/**
+ * 从源 vnode 派生一份未挂载副本。
+ * Vue 的 cloneVNode 会拷贝 el/component，同一源 vnode 渲两次会把实例从编辑控件抢走。
+ */
+export function forkUnmountedVNode(node: VNode, extra?: Record<string, unknown>): VNode {
+  const forked = extra ? cloneVNode(node, extra) : cloneVNode(node)
+  forked.el = null
+  forked.component = null
+  forked.anchor = null
+  forked.suspense = null
+  return forked
 }
 
 /**
@@ -24,6 +46,7 @@ export function useNodeInterceptor(): { getSlotsNodes: () => SlotRenderItem[] |
     const flattedNodes = extractNormalVNodes(nodes)
 
     const results: SlotRenderItem[] = []
+    const seen = new Map<string, number>()
 
     let i = 0
     while (i < flattedNodes.length) {
@@ -43,12 +66,23 @@ export function useNodeInterceptor(): { getSlotsNodes: () => SlotRenderItem[] |
         'field'
       ]) as Record<string, any>
 
+      let renderKey: string | number | symbol
+      if (node.key != null) {
+        renderKey = node.key
+      } else {
+        const base = `${getVNodeTypeName(node)}:${field ?? ''}`
+        const n = seen.get(base) ?? 0
+        seen.set(base, n + 1)
+        renderKey = n === 0 ? `uform:${base}` : `uform:${base}#${n}`
+      }
+
       results.push({
         isFormItem,
         formItemProps,
         node,
         field,
-        modelValue: props?.['model-value'] ?? props?.modelValue
+        modelValue: props?.['model-value'] ?? props?.modelValue,
+        renderKey
       })
     }
 

package/src/components/form-item/__test__/form-item.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { createApp, h, nextTick, reactive } from 'vue'
+import { createApp, h, nextTick, reactive, ref } from 'vue'
 
 import { UForm } from '../../form'
+import { UInput } from '../../input'
 import { USelect } from '../../select'
 import { UFormItem } from '../index'
 
@@ -36,18 +37,12 @@ describe('UFormItem change', () => {
 
     const model = reactive({ behavior: 'event' })
     const itemChanges: unknown[][] = []
-    const formChanges: { field: string; args: unknown[] }[] = []
 
     const app = createApp({
       render() {
         return h(
           UForm,
-          {
-            model,
-            'onField:change': (field: string, ...args: unknown[]) => {
-              formChanges.push({ field, args })
-            }
-          },
+          { model },
           {
             default: () =>
               h(
@@ -81,8 +76,43 @@ describe('UFormItem change', () => {
     expect(itemChanges).toHaveLength(1)
     expect(itemChanges[0]![0]).toEqual({ label: '接口', value: 'api' })
 
-    expect(formChanges).toHaveLength(1)
-    expect(formChanges[0]).toEqual({ field: 'behavior', args: [{ label: '接口', value: 'api' }] })
+    app.unmount()
+    host.remove()
+  })
+
+  it('显式 UFormItem 内控件的动态 props 随父级更新', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ name: '' })
+    const disabled = ref(false)
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () =>
+              h(
+                UFormItem,
+                { field: 'name', label: '姓名' },
+                { default: () => h(UInput, { modelValue: model.name, disabled: disabled.value }) }
+              )
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const input = () => host.querySelector('input')!
+    expect(input().disabled).toBe(false)
+
+    disabled.value = true
+    await nextTick()
+
+    expect(input().disabled).toBe(true)
 
     app.unmount()
     host.remove()

package/src/components/form-item/form-item.vue

@@ -17,7 +17,9 @@
 
     <section :class="cls.e('wrapper')">
       <div :class="cls.e('content')">
-        <ContentSlot />
+        <ContentSlot>
+          <slot></slot>
+        </ContentSlot>
       </div>
 
       <!-- 只有表单控件处于非只读状态时，才显示错误提示 -->
@@ -35,16 +37,16 @@
 <script lang="tsx" setup>
 import { o } from '@cat-kit/core'
 import { useConfig, useFallbackProps } from '@veltra/compositions'
-import { bem, withUnit } from '@veltra/utils'
+import { bem, extractNormalVNodes, withUnit } from '@veltra/utils'
 import { injectFormContext } from '@veltra/utils'
 import {
   type CSSProperties,
+  type SetupContext,
   type VNode,
   cloneVNode,
   computed,
   onBeforeUnmount,
   shallowRef,
-  useSlots,
   watch
 } from 'vue'
 
@@ -60,8 +62,6 @@ const props = withDefaults(defineProps<FormItemProps>(), { readonly: undefined }
 
 const emit = defineEmits<FormItemEmits>()
 
-const slots = useSlots()
-
 defineSlots<{
   /** 标签插槽 */
   label?: () => any
@@ -69,14 +69,8 @@ defineSlots<{
 }>()
 
 /** 表单组件上下文 */
-const {
-  formProps,
-  registerField,
-  unregisterField,
-  shouldValidate,
-  handleFieldUpdate,
-  handleFieldChange
-} = injectFormContext()
+const { formProps, registerField, unregisterField, shouldValidate, handleFieldUpdate } =
+  injectFormContext()
 
 function wrapControlChange(node: VNode) {
   if (!node || typeof node.type === 'symbol') return node
@@ -84,14 +78,17 @@ function wrapControlChange(node: VNode) {
   return cloneVNode(node, {
     onChange: (...args: any[]) => {
       emit('change', ...args)
-      if (props.field) handleFieldChange?.(props.field, ...args)
     }
   })
 }
 
-function ContentSlot() {
-  const nodes = slots.default?.() ?? []
-  return nodes.map(wrapControlChange)
+/**
+ * 承载默认插槽并拦截控件 change。
+ * 必须经填充插槽接收内容（而非直接读 UFormItem 的 $slots）：
+ * 读父级 $slots 时组件自身没有更新路径，父级重渲染后动态 props（disabled、data 等）会冻结在首帧。
+ */
+function ContentSlot(_: unknown, { slots }: SetupContext) {
+  return extractNormalVNodes(slots.default?.() ?? []).map(wrapControlChange)
 }
 
 const { config } = useConfig()

package/src/types/action.ts

@@ -4,7 +4,12 @@ import type { ButtonProps } from './button'
 
 /** 操作组件属性 */
 export interface ActionProps extends ButtonProps {
-  /** 是否需要确认 */
+  /**
+   * 是否需要确认：true 时点击只弹确认气泡（UPopConfirm），点气泡里的「确认」才触发 `run`
+   * @default false
+   * @description 不要在本项的 `run` 回调里再调 `messageConfirm`：`run` 触发时气泡已经确认过一次，
+   * 会变成两次确认。需要弹窗级确认时去掉 `needConfirm`，只在 `run` 里用 `messageConfirm`
+   */
   needConfirm?: boolean
 
   /**

package/src/types/batch-edit.ts

@@ -115,8 +115,6 @@ export interface BatchEditProps extends TableProps {
 
 /** 批量编辑组件定义的事件 */
 export interface BatchEditEmits extends TableEmits {
-  /** 表单控件 change，透传自 UForm */
-  (e: 'field:change', field: string, ...args: any[]): void
   /** 更新数据 */
   (e: 'update:data', value: Record<string, any>[]): void
   /** 点击底部「新增一行」 */

package/src/types/button.ts

@@ -4,7 +4,11 @@ import type { Component, ShallowRef } from 'vue'
 /** 按钮类型 */
 export type ButtonType = ColorType
 
-/** 按钮属性类型 */
+/**
+ * 按钮属性类型
+ * @description 组件不注入默认 `aria-label`：可访问名来自默认插槽文本，
+ * 或你自己传入的 `aria-label`（透传到根元素）；只有图标的按钮必须自行传 `aria-label`
+ */
 export interface ButtonProps extends ComponentProps {
   /** 按钮类型 */
   type?: ButtonType

package/src/types/drawer.ts

@@ -15,16 +15,19 @@ export interface DrawerProps {
 
   /** 是否显示关闭按钮 */
   showClose?: boolean
-  /** 抽屉标题 */
+  /**
+   * 抽屉标题；传入时在内容区上方渲染标题栏
+   * @description 不传则不渲染标题栏，内容仍全部来自默认插槽
+   */
   title?: string
 }
 
 /** 抽屉组件定义的事件 */
 export interface DrawerEmits {
   (e: 'update:modelValue', value: boolean): void
-  /** 关闭时触发 */
+  /** 开始关闭时触发（点遮罩、点关闭按钮） */
   (e: 'close'): void
-  /** 完全关闭后触发 */
+  /** 完全关闭后触发：抽屉与遮罩的退出动画结束、节点已移除时 */
   (e: 'closed'): void
 }
 

package/src/types/form.ts

@@ -29,8 +29,6 @@ export interface FormProps extends ComponentProps {
 }
 
 export interface FormEmits {
-  /** 控件 change 事件，仅用户操作触发 */
-  (e: 'field:change', field: string, ...args: any[]): void
   /** model 字段值更新，含编程写入 */
   (e: 'field:update', field: string, value: any): void
 }

package/src/types/layout.ts

@@ -18,6 +18,8 @@ export interface LayoutProps {
    * const cols = ['200px', '1fr']
    * ```
    * [fr是什么?](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex_value)
+   * @description 默认插槽的每个直接子元素按顺序占一列，用自定义组件包一层时该组件必须是单根元素；
+   * 子元素渲染出 0 个（`v-if` 为假）或多个根节点时会挤动后面的列，此时自行给子元素写 `grid-column`
    */
   cols?: string[] | string