From bb9cb64c6473536bcd48c65865d5dc682d8c20d7 Mon Sep 17 00:00:00 2001
From: xingyu4j <xingyu4j@vip.qq.com>
Date: Tue, 21 Oct 2025 16:39:15 +0800
Subject: [PATCH] refactor: refactor naive desc comp

---
 .../components/description/description.vue    | 248 +++++++++++++-----
 .../src/components/description/typing.ts      |  54 ++--
 .../components/description/use-description.ts |  80 ++----
 3 files changed, 237 insertions(+), 145 deletions(-)

diff --git a/apps/web-naive/src/components/description/description.vue b/apps/web-naive/src/components/description/description.vue
index ef0239933..51f0df4d3 100644
--- a/apps/web-naive/src/components/description/description.vue
+++ b/apps/web-naive/src/components/description/description.vue
@@ -1,80 +1,198 @@
 <script lang="tsx">
-import type { DescriptionsProps } from 'naive-ui';
+import type { DescriptionsProps as NDescriptionsProps } from 'naive-ui';
 
-import type { PropType } from 'vue';
+import type { CSSProperties, PropType, Slots } from 'vue';
 
-import type { DescriptionItemSchema, DescriptionsOptions } from './typing';
+import type { DescriptionItemSchema, DescriptionProps } from './typing';
 
-import { defineComponent } from 'vue';
+import { computed, defineComponent, ref, unref, useAttrs } from 'vue';
 
-import { get } from '@vben/utils';
+import { get, getNestedValue, isFunction } from '@vben/utils';
 
-import { NDescriptions, NDescriptionsItem } from 'naive-ui';
+import { NCard, NDescriptions, NDescriptionsItem } from 'naive-ui';
 
-/** 对 Descriptions 进行二次封装 */
-const Description = defineComponent({
-  name: 'Descriptions',
-  props: {
-    data: {
-      type: Object as PropType<Record<string, any>>,
-      default: () => ({}),
-    },
-    schema: {
-      type: Array as PropType<DescriptionItemSchema[]>,
-      default: () => [],
-    },
-    // Descriptions 原生 props
-    componentProps: {
-      type: Object as PropType<DescriptionsProps>,
-      default: () => ({}),
+const props = {
+  bordered: { default: true, type: Boolean },
+  column: {
+    default: () => {
+      return { lg: 3, md: 3, sm: 2, xl: 3, xs: 1, xxl: 4 };
     },
+    type: [Number, Object],
   },
+  data: { type: Object },
+  schema: {
+    default: () => [],
+    type: Array as PropType<DescriptionItemSchema[]>,
+  },
+  size: {
+    default: 'small',
+    type: String,
+    validator: (v: string) =>
+      ['default', 'middle', 'small', undefined].includes(v),
+  },
+  title: { default: '', type: String },
+  useCard: { default: true, type: Boolean },
+  labelPlacement: { default: 'left', type: String as PropType<'left' | 'top'> },
+};
 
-  setup(props: DescriptionsOptions) {
-    // TODO @xingyu：每个 field 的 slot 的考虑
-    // TODO @xingyu：from 5.0：extra: () => getSlot(slots, 'extra')
-    /** 过滤掉不需要展示的 */
-    const shouldShowItem = (item: DescriptionItemSchema) => {
-      if (item.hidden === undefined) return true;
-      return typeof item.hidden === 'function'
-        ? !item.hidden(props.data)
-        : !item.hidden;
-    };
-    /** 渲染内容 */
-    const renderContent = (item: DescriptionItemSchema) => {
-      if (item.content) {
-        return typeof item.content === 'function'
-          ? item.content(props.data)
-          : item.content;
+function getSlot(slots: Slots, slot: string, data?: any) {
+  if (!slots || !Reflect.has(slots, slot)) {
+    return null;
+  }
+  if (!isFunction(slots[slot])) {
+    console.error(`${slot} is not a function!`);
+    return null;
+  }
+  const slotFn = slots[slot];
+  if (!slotFn) return null;
+  return slotFn({ data });
+}
+
+export default defineComponent({
+  name: 'Description',
+  props,
+  setup(props, { slots }) {
+    const propsRef = ref<null | Partial<DescriptionProps>>(null);
+
+    const prefixCls = 'description';
+    const attrs = useAttrs();
+
+    // Custom title component: get title
+    const getMergeProps = computed(() => {
+      return {
+        ...props,
+        ...(unref(propsRef) as any),
+      } as DescriptionProps;
+    });
+
+    const getProps = computed(() => {
+      const opt = {
+        ...unref(getMergeProps),
+        title: undefined,
+      };
+      return opt as DescriptionProps;
+    });
+
+    const useWrapper = computed(() => !!unref(getMergeProps).title);
+
+    const getDescriptionsProps = computed(() => {
+      return { ...unref(attrs), ...unref(getProps) } as NDescriptionsProps;
+    });
+
+    // 防止换行
+    function renderLabel({
+      label,
+      labelMinWidth,
+      labelStyle,
+    }: DescriptionItemSchema) {
+      if (!labelStyle && !labelMinWidth) {
+        return label;
       }
-      return item.field ? get(props.data, item.field) : null;
-    };
 
-    return () => (
-      <NDescriptions
-        {...props}
-        bordered={props.componentProps?.bordered}
-        column={props.componentProps?.column}
-        labelPlacement={props.componentProps?.labelPlacement || 'left'}
-        size={props.componentProps?.size}
-        title={props.componentProps?.title}
-      >
-        {props.schema?.filter(shouldShowItem).map((item) => (
-          <NDescriptionsItem
-            contentStyle={item.contentStyle}
-            key={item.field || String(item.label)}
-            label={item.label as string}
-            labelStyle={item.labelStyle}
-            span={item.span}
-          >
-            {renderContent(item)}
-          </NDescriptionsItem>
-        ))}
-      </NDescriptions>
-    );
+      const labelStyles: CSSProperties = {
+        ...labelStyle,
+        minWidth: `${labelMinWidth}px `,
+      };
+      return <div style={labelStyles}>{label}</div>;
+    }
+
+    function renderItem() {
+      const { data, schema } = unref(getProps);
+      return unref(schema)
+        .map((item) => {
+          const { contentMinWidth, field, render, show, span } = item;
+
+          if (show && isFunction(show) && !show(data)) {
+            return null;
+          }
+
+          function getContent() {
+            const _data = unref(getProps)?.data;
+            if (!_data) {
+              return null;
+            }
+            const getField = field.includes('.')
+              ? (getNestedValue(_data, field) ?? get(_data, field))
+              : get(_data, field);
+            // if (
+            //   getField &&
+            //   !Object.prototype.hasOwnProperty.call(toRefs(_data), field)
+            // ) {
+            //   return isFunction(render) ? render('', _data) : (getField ?? '');
+            // }
+            return isFunction(render)
+              ? render(getField, _data)
+              : (getField ?? '');
+          }
+
+          const width = contentMinWidth;
+          return (
+            <NDescriptionsItem key={field} span={span}>
+              {{
+                label: () => {
+                  return renderLabel(item);
+                },
+                default: () => {
+                  if (item.slot) {
+                    const slotContent = getSlot(slots, item.slot, data);
+                    return slotContent;
+                  }
+                  if (!contentMinWidth) {
+                    return getContent();
+                  }
+                  const style: CSSProperties = {
+                    minWidth: `${width}px`,
+                  };
+                  return <div style={style}>{getContent()}</div>;
+                },
+              }}
+            </NDescriptionsItem>
+          );
+        })
+        .filter((item) => !!item);
+    }
+
+    function renderDesc() {
+      return (
+        <NDescriptions
+          class={`${prefixCls}`}
+          {...(unref(getDescriptionsProps) as any)}
+        >
+          {renderItem()}
+        </NDescriptions>
+      );
+    }
+
+    function renderCard() {
+      const content = props.useCard ? renderDesc() : <div>{renderDesc()}</div>;
+      // Reduce the dom level
+      if (!props.useCard) {
+        return content;
+      }
+
+      const { title } = unref(getMergeProps);
+      const extraSlot = getSlot(slots, 'extra');
+
+      return (
+        <NCard
+          contentStyle={{ padding: '8px 0' }}
+          headerStyle={{
+            padding: '8px 16px',
+            fontSize: '14px',
+            minHeight: '24px',
+          }}
+          style={{ margin: 0 }}
+          title={title}
+        >
+          {{
+            default: () => content,
+            extra: () => extraSlot && <div>{extraSlot}</div>,
+          }}
+        </NCard>
+      );
+    }
+
+    return () => (unref(useWrapper) ? renderCard() : renderDesc());
   },
 });
-
-// TODO @xingyu：from 5.0：emits: ['register'] 事件
-export default Description;
 </script>
diff --git a/apps/web-naive/src/components/description/typing.ts b/apps/web-naive/src/components/description/typing.ts
index 7aadf72dd..9ee489678 100644
--- a/apps/web-naive/src/components/description/typing.ts
+++ b/apps/web-naive/src/components/description/typing.ts
@@ -1,27 +1,41 @@
-import type { DescriptionsProps } from 'naive-ui';
+import type { DescriptionsProps as NDescriptionsProps } from 'naive-ui';
+import type { JSX } from 'vue/jsx-runtime';
 
 import type { CSSProperties, VNode } from 'vue';
 
-// TODO @xingyu：【content】这个纠结下；1）vben2.0 是 render；https://doc.vvbin.cn/components/desc.html#usage 2）
-// TODO @xingyu：vben2.0 还有 sapn【done】、labelMinWidth、contentMinWidth
-// TODO @xingyu：【hidden】这个纠结下；1）vben2.0 是 show；
+import type { Recordable } from '@vben/types';
+
 export interface DescriptionItemSchema {
-  label: string | VNode; // 内容的描述
-  field?: string; // 对应 data 中的字段名
-  content?: ((data: any) => string | VNode) | string | VNode; // 自定义需要展示的内容，比如说 dict-tag
-  span?: number; // 包含列的数量
-  labelStyle?: CSSProperties; // 自定义标签样式
-  contentStyle?: CSSProperties; // 自定义内容样式
-  hidden?: ((data: any) => boolean) | boolean; // 是否显示
+  labelMinWidth?: number;
+  contentMinWidth?: number;
+  // 自定义标签样式
+  labelStyle?: CSSProperties;
+  // 对应 data 中的字段名
+  field: string;
+  // 内容的描述
+  label: JSX.Element | string | VNode;
+  // 包含列的数量
+  span?: number;
+  // 是否显示
+  show?: (...arg: any) => boolean;
+  // 插槽名称
+  slot?: string;
+  // 自定义需要展示的内容
+  render?: (
+    val: any,
+    data?: Recordable<any>,
+  ) => Element | JSX.Element | number | string | undefined | VNode;
 }
 
-// TODO @xingyu：vben2.0 还有 title【done】、bordered【done】d、useCollapse、collapseOptions
-// TODO @xingyu：from 5.0：bordered 默认为 true
-// TODO @xingyu：from 5.0：column 默认为 lg: 3, md: 3, sm: 2, xl: 3, xs: 1, xxl: 4
-// TODO @xingyu：from 5.0：size 默认为 small；有 'default', 'middle', 'small', undefined
-// TODO @xingyu：from 5.0：useCollapse 默认为 true
-export interface DescriptionsOptions {
-  data?: Record<string, any>; // 数据
-  schema?: DescriptionItemSchema[]; // 描述项配置
-  componentProps?: DescriptionsProps; // antd Descriptions 组件参数
+export interface DescriptionProps extends NDescriptionsProps {
+  // 是否包含卡片组件
+  useCard?: boolean;
+  // 描述项配置
+  schema: DescriptionItemSchema[];
+  // 数据
+  data: Recordable<any>;
+}
+
+export interface DescInstance {
+  setDescProps(descProps: Partial<DescriptionProps>): void;
 }
diff --git a/apps/web-naive/src/components/description/use-description.ts b/apps/web-naive/src/components/description/use-description.ts
index 7f99238bf..fd24920f0 100644
--- a/apps/web-naive/src/components/description/use-description.ts
+++ b/apps/web-naive/src/components/description/use-description.ts
@@ -1,71 +1,31 @@
-import type { DescriptionsOptions } from './typing';
+import type { Component } from 'vue';
 
-import { defineComponent, h, isReactive, reactive, watch } from 'vue';
+import type { DescInstance, DescriptionProps } from './typing';
+
+import { h, reactive } from 'vue';
 
 import Description from './description.vue';
 
-/** 描述列表 api 定义 */
-class DescriptionApi {
-  private state = reactive<Record<string, any>>({});
+export function useDescription(options?: Partial<DescriptionProps>) {
+  const propsState = reactive<Partial<DescriptionProps>>(options || {});
 
-  constructor(options: DescriptionsOptions) {
-    this.state = { ...options };
-  }
+  const api: DescInstance = {
+    setDescProps: (descProps: Partial<DescriptionProps>): void => {
+      Object.assign(propsState, descProps);
+    },
+  };
 
-  getState(): DescriptionsOptions {
-    return this.state as DescriptionsOptions;
-  }
-
-  // TODO @xingyu：【setState】纠结下：1）vben2.0 是 data https://doc.vvbin.cn/components/desc.html#usage；
-  setState(newState: Partial<DescriptionsOptions>) {
-    this.state = { ...this.state, ...newState };
-  }
-}
-
-export type ExtendedDescriptionApi = DescriptionApi;
-
-export function useDescription(options: DescriptionsOptions) {
-  const IS_REACTIVE = isReactive(options);
-  const api = new DescriptionApi(options);
-  // 扩展 API
-  const extendedApi: ExtendedDescriptionApi = api as never;
-  const Desc = defineComponent({
+  // 创建一个包装组件，将 propsState 合并到 props 中
+  const DescriptionWrapper: Component = {
     name: 'UseDescription',
     inheritAttrs: false,
-    setup(_, { attrs, slots }) {
-      // 合并props和attrs到state
-      api.setState({ ...attrs });
-
-      return () =>
-        h(
-          Description,
-          {
-            ...api.getState(),
-            ...attrs,
-          },
-          slots,
-        );
+    setup(_props, { attrs, slots }) {
+      return () => {
+        // @ts-ignore - 避免类型实例化过深
+        return h(Description, { ...propsState, ...attrs }, slots);
+      };
     },
-  });
+  };
 
-  // 响应式支持
-  if (IS_REACTIVE) {
-    watch(
-      () => options.schema,
-      (newSchema) => {
-        api.setState({ schema: newSchema });
-      },
-      { immediate: true, deep: true },
-    );
-
-    watch(
-      () => options.data,
-      (newData) => {
-        api.setState({ data: newData });
-      },
-      { immediate: true, deep: true },
-    );
-  }
-
-  return [Desc, extendedApi] as const;
+  return [DescriptionWrapper, api] as const;
 }