SPFx扩展Application Customizer无法渲染TSX中的React组件

问题场景 #

开发基于SPFx 1.16.1的Application Customizer扩展，用于在SharePoint中展示聊天机器人。直接在自定义器文件中编写的div元素可正常渲染，但引用独立TSX文件中的React组件时无法显示。环境版本：Node.js 16.19.0，SPFx 1.16.1。

排查与解决步骤 #

1. 修正React组件命名规范 #

React要求组件类名必须首字母大写，否则会被识别为普通HTML标签而非自定义组件。当前组件类名evapvapopupchat为小写，这是核心问题之一。

修改组件文件（/components/evapvapopupchat.tsx）：

import * as React from "react";
import styles from './evapvapopupchat.module.scss';

export interface IEvaPvaPopupChatProps {
    // 定义组件属性
}

// 类名改为首字母大写
export default class EvaPvaPopupChat extends React.Component<IEvaPvaPopupChatProps> {
    constructor(props: IEvaPvaPopupChatProps) {
        super(props);
    }

    public render() {
        return (
            <div className={styles.botButton}>
                <p className={styles.botButtonText}>Chat with EVA</p>
            </div>
        );
    }
}

同步修改应用自定义器中的引用（EvapvapopupchatApplicationCustomizer.ts）：

// 导入时使用大写组件名
import EvaPvaPopupChat, { IEvaPvaPopupChatProps } from './components/evapvapopupchat';

// 渲染时替换为大写组件名
const elem: React.ReactElement<IEvaPvaPopupChatProps> =
    React.createElement(EvaPvaPopupChat);

2. 使用React 17+兼容的渲染API #

SPFx 1.16.1搭配React 17.0.2，建议使用ReactDOM.createRoot替代旧版ReactDOM.render，避免API兼容性问题。

修改应用自定义器中的渲染逻辑：

// 导入createRoot
import { createRoot } from 'react-dom/client';

private _renderPlaceHolders(): void {
    // ... 原有占位符检查逻辑 ...

    // 替换ReactDOM.render为createRoot
    const root = createRoot(this._bottomPlaceholder.domElement);
    root.render(elem);
}

3. 确保占位符就绪后再渲染 #

虽然已监听changedEvent，但可能在占位符未完全就绪时触发了渲染。调整onInit逻辑，等待占位符系统就绪后再执行渲染：

public onInit(): Promise<void> {
    Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);

    // 等待占位符系统就绪后再渲染
    return this.context.placeholderProvider.waitForEvent('ready').then(() => {
        this._renderPlaceHolders();
        // 继续监听占位符变化事件
        this.context.placeholderProvider.changedEvent.add(this, this._renderPlaceHolders);
    });
}

4. 排除样式加载问题（可选） #

若修改后仍不显示，可先移除SCSS样式，改用内联样式测试，确认组件本身可渲染：

public render() {
    return (
        <div style={{ padding: '16px', backgroundColor: '#0078d4', color: '#fff', cursor: 'pointer' }}>
            <p>Chat with EVA</p>
        </div>
    );
}

如果内联样式的组件能显示，说明SCSS模块可能存在编译问题，可检查lib目录下是否生成了对应的样式文件，或确认SPFx构建任务正常执行。

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