无头Gutenberg块渲染中TypeScript属性类型不匹配问题求解

问题场景 #

在无头WordPress架构中处理Gutenberg块时，定义了通用Block类型，同时为自定义块扩展了包含特定属性的MyBlockProps类型，但批量渲染块时出现属性类型不兼容的错误，希望不用类型断言实现类型安全的渲染。

基础类型与组件定义 #

通用Block类型：

type Block = {
    name: string;
    className?: string;
    key?: string | number;
    clientId: string;
    innerBlocks: Block[];
    attributes: Record<string, unknown>;
    style?: Record<string, unknown>;
};

自定义块类型及组件：

type MyBlockProps = Block & {
  attributes: {
    title: string;
  };
};

function MyBlock( { attributes: { title } }: MyBlockProps ) {
  return <h1>{title}</h1>;
}

渲染器代码及错误 #

批量渲染器：

function BlockRenderer( { blocks } : { blocks: Block[] } ) {
  return blocks.map( ( { attributes, clientId, innerBlocks, name }, index ) => {
            const key = clientId || index;
            const props: Block = {
                name,
                key,
                clientId,
                attributes,
                innerBlocks,
            };

            switch ( name ) {
                case 'block/my-block':
                    return <MyBlock { ...props } />;
                default:
                    return null;
            }
        } )
        .filter( ( block ) => block );
}

错误信息：

Type '{ name?: string | undefined; className?: string | undefined; key?: string | number | undefined; clientId: string; innerBlocks: Block[]; attributes: Record<string, unknown>; style?: Record<...> | undefined; }' is not assignable to type '{ attributes: { title: string; }; }'.
Types of property 'attributes' are incompatible.
Property 'title' is missing in type 'Record<string, unknown>' but required in type '{ title: string; }'

更优解决方案 #

方案1：使用区分联合类型（Discriminated Union） #

通过name字段作为区分符，定义包含所有块类型的联合类型，让TypeScript自动在分支中推断类型：

1. 重构块类型定义：

// 提取公共基础字段
type BaseBlock = Omit<Block, 'attributes'> & {
  attributes: Record<string, unknown>;
};

// 自定义块专属类型，指定name和严格属性
type MyBlockType = BaseBlock & {
  name: 'block/my-block';
  attributes: {
    title: string;
  };
};

// 所有Gutenberg块的联合类型（可扩展更多自定义块）
type GutenbergBlock = MyBlockType | BaseBlock;

2. 修改渲染器：

function BlockRenderer( { blocks } : { blocks: GutenbergBlock[] } ) {
  return blocks.map( ( block, index ) => {
            const key = block.clientId || index;

            switch ( block.name ) {
                case 'block/my-block':
                    // TypeScript自动推断block为MyBlockType，完全匹配MyBlockProps
                    return <MyBlock { ...block } key={key} />;
                default:
                    return null;
            }
        } )
        .filter( ( block ) => block );
}

方案2：添加类型守卫函数 #

如果无法修改基础Block类型，可通过类型守卫函数让TypeScript识别特定块类型：

1. 定义类型守卫：

function isMyBlock( block: Block ): block is MyBlockProps {
  return block.name === 'block/my-block' && 
         typeof (block.attributes as MyBlockProps['attributes']).title === 'string';
}

2. 更新渲染器逻辑：

function BlockRenderer( { blocks } : { blocks: Block[] } ) {
  return blocks.map( ( block, index ) => {
            const key = block.clientId || index;

            if (isMyBlock(block)) {
                return <MyBlock { ...block } key={key} />;
            }
            return null;
        } )
        .filter( ( block ) => block );
}

方案3：宽松属性兼容（可选） #

如果业务允许title字段可选，可调整自定义块类型的属性约束，同时在组件中处理默认值：

type MyBlockProps = Block & {
  attributes?: {
    title?: string;
  };
};

function MyBlock( { attributes: { title = '默认标题' } = {} }: MyBlockProps ) {
  return <h1>{title}</h1>;
}

此方案适合非严格类型场景，不推荐用于强类型约束的业务逻辑。

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