Nuxt3中Vue组合式API如何显式定义动态组件Props

我正在使用Nuxt3，通过GraphQL对接无头CMS，从CMS获取组成页面的内容“blocks”，响应数据示例如下：

{
  "id": "73",
  "image": [
    {
      "id": "70",
      "__typename": "blogAssets_Asset"
    }
  ],
  "size": "large",
  "subtitle": null,
  "heading": "Test Hero",
  "reviewsWidget": [],
  "alignment": "fullPageWidth",
  "siteHandle": "default",
  "typeHandle": "hero",
  "__typename": "builder_hero_BlockType"
}

在循环渲染这些组件时，当前我在Vue组合式API中是这样定义Props的：

<script lang="ts" setup>
    const props = withDefaults(
        defineProps<{
            data: Object
        }>(),
        {}
    );
</script>

但我希望能更显式地定义Props，例如写成如下形式：

<script lang="ts" setup>
    const props = withDefaults(
        defineProps<{
            title: String,
            subtitle: String,
            ...,
            ...
        }>(),
        {}
    );
</script>

让开发者仅通过查看Props定义就能知晓该组件包含title、subtitle等字段。请问是否可以实现这种Props对象的展开式显式定义？

当然可以实现这种显式的Props定义，结合TypeScript的类型系统，你可以通过以下方式实现：

1. 先定义精准的TypeScript接口 #

根据CMS返回的Block结构，创建对应的类型接口，既可以约束数据结构，也能提供类型提示：

// 可单独放在项目的types/blocks.ts文件中，方便跨组件复用
interface HeroBlock {
  id: string;
  image: Array<{ id: string; __typename: string }>;
  size: 'large' | 'medium' | 'small'; // 用联合类型约束可选值范围
  subtitle: string | null;
  heading: string;
  reviewsWidget: Array<any>; // 可根据实际返回结构细化类型
  alignment: 'fullPageWidth' | 'container';
  siteHandle: string;
  typeHandle: string;
  __typename: string;
}

2. 显式定义组件Props #

有两种方式可以实现你想要的显式效果：

方式一：保留data字段但明确类型 #

如果仍希望用data作为Props的顶层字段，但让类型更清晰：

<script lang="ts" setup>
import type { HeroBlock } from '~/types/blocks';

const props = withDefaults(
  defineProps<{
    data: HeroBlock;
  }>(),
  {}
);
</script>

这种方式下，开发者查看Props时，通过HeroBlock类型就能知晓所有包含的字段，鼠标hover还能看到详细的结构定义。

方式二：拆分为独立的Props字段 #

如果想完全展开成单个字段的Props，直接用定义好的接口作为Props类型即可：

<script lang="ts" setup>
import type { HeroBlock } from '~/types/blocks';

const props = withDefaults(
  defineProps<HeroBlock>(),
  {
    subtitle: null,
    reviewsWidget: () => [],
    // 其他需要设置默认值的字段可在此补充
  }
);
</script>

此时组件的Props会显示为id、heading、subtitle等独立字段，开发者无需额外跳转就能直接看到所有可用属性。

3. 循环渲染时的传参处理 #

在循环渲染组件时，可以用Vue的展开语法快速传递所有字段：

<template>
  <div v-for="block in blocks" :key="block.id">
    <HeroBlock v-bind="block" />
  </div>
</template>

也可以手动指定需要传递的字段，进一步明确依赖关系。

额外优化：结合GraphQL代码生成 #

如果项目使用graphql-codegen这类工具，可以直接从GraphQL Schema自动生成对应的数据类型，无需手动编写接口，能最大程度保证类型与CMS返回数据的一致性。

内容的提问来源于stack exchange，提问作者Udders