如何让Next.js/React模态框组件自管理状态且规避引用报错？

我想开发一个可嵌入的错误提示方案，希望Modal组件自行管理自身状态（包括显示文本、是否显示），不需要父页面维护状态。但尝试通过引用调用Modal内部方法时出现报错，无法实现这个逻辑。

报错的尝试代码 #

import { useRef } from 'react'
import Layout from 'src/client/components/layout'
import Modal from 'src/client/components/modal'

export default function Page() {

    const modalRef = useRef<typeof Modal>()
    const showAlert = (body: string) => {modalRef.current?.showModal(body, 'Error', 'danger');}
/*                                       ^~~~~~~~~~~~~~~~
 * 此处最终为undefined */

    const submitForm = async () => {
        try {
            doThing()
        } catch (e) {
            showAlert(e.message)
        }
    }

    return (
        <Layout>
            <Content />{/* <-- 这里的具体内容不重要 */}
            <Modal ref={modalRef} />
{/*                ^~~~~~~~~~~~~~
 * 智能提示报错：
 * Type '{ ref: MutableRefObject<(() => Element) | undefined>; }' is not assignable to type 'IntrinsicAttributes'.
 * Property 'ref' does not exist on type 'IntrinsicAttributes'.ts(2322)" */}
        </Layout>
    )
}

当前糟糕的实现方式（父组件维护状态） #

// 反例
import { useState } from 'react'
...
export default function Page(){
    // 太糟糕了！难以维护！
    const [modalVisible, setModalVisible] = useState(false)
    const [modalBodyText, setModalBodyText] = useState('')
    const [modalTitleText, setModalTitleText] = useState('')
    const [modalType, setModalType] = useState('')
...
    return (
        <Layout>
            <Content />
            {/* 太糟糕了！难以维护！ */}
            <Modal
                body={bodyText}
                visible={modalVisible}
                title={modalTitle}
                type={modalType} />
        </Layout>
    );
}

我有HTML和Godot Engine开发背景，这类模式在这些环境里很容易实现。如果React里没法通过引用调用组件内部函数，该怎么实现这种模式？

我期望的Modal组件实现代码 #

import { forwardRef, useState } from 'react'

export default function Modal() {
    const [bodyText, setBodyText] = useState<string>('')
    const [titleText, setTitleText] = useState<string>('')
    const [type, setType] = useState<string>('')
    const [visible, setVisible] = useState<boolean>(false)

    function showModal(body, type, title) {
        setBodyText(body)
        setTitleText(title)
        setType(type)
        setVisible(true)
    }

    function onClose() {setVisible(false)}

    // 样式省略
    return visible ? (
        <div className="m_bg">
            <div className="m_box">
                <button
                    type='button'
                    onClick={onClose}
                    >×</button>
                <div className="m_body">
                    <img src={
                        type == 'danger'
                            ? '/images/icon_error.svg'
                            : '/images/icon_info.svg'}
                    ></img>
                    <div>
                        <div>
                            {titleText}
                        </div>
                        <div>
                            {bodyText}
                        </div>
                    </div>
                </div>
            </div>
        </div>
    ) : (
        <div></div>
    )
}

要实现组件自管理状态并允许父组件调用内部方法，需要用forwardRef配合useImperativeHandle来暴露组件内部的方法，这是React中实现类似“命令式调用”组件的标准方式。

步骤1：修改Modal组件，使用forwardRef和useImperativeHandle #

import { forwardRef, useState, useImperativeHandle } from 'react'

// 定义对外暴露的方法类型，方便TypeScript类型检查
type ModalHandle = {
  showModal: (body: string, type: string, title: string) => void
}

// 使用forwardRef包裹组件，接收ref参数
const Modal = forwardRef<ModalHandle>((props, ref) => {
    const [bodyText, setBodyText] = useState<string>('')
    const [titleText, setTitleText] = useState<string>('')
    const [type, setType] = useState<string>('')
    const [visible, setVisible] = useState<boolean>(false)

    const showModal = (body: string, type: string, title: string) => {
        setBodyText(body)
        setTitleText(title)
        setType(type)
        setVisible(true)
    }

    const onClose = () => setVisible(false)

    // 暴露指定方法给父组件的ref
    useImperativeHandle(ref, () => ({
      showModal
    }), []) // 依赖为空数组，因为showModal内部的状态更新函数是稳定的

    // 样式省略
    return visible ? (
        <div className="m_bg">
            <div className="m_box">
                <button
                    type='button'
                    onClick={onClose}
                >×</button>
                <div className="m_body">
                    <img 
                        src={type === 'danger' 
                            ? '/images/icon_error.svg' 
                            : '/images/icon_info.svg'}
                        alt={type}
                    />
                    <div>
                        <div>{titleText}</div>
                        <div>{bodyText}</div>
                    </div>
                </div>
            </div>
        </div>
    ) : null // 不需要渲染空div，直接返回null更高效
})

export default Modal

步骤2：修改父组件的ref类型和调用方式 #

import { useRef } from 'react'
import Layout from 'src/client/components/layout'
import Modal from 'src/client/components/modal'
import type { ModalHandle } from 'src/client/components/modal' // 导入刚才定义的类型

export default function Page() {
    // 指定ref的类型为ModalHandle
    const modalRef = useRef<ModalHandle>(null)
    
    const showAlert = (body: string) => {
        modalRef.current?.showModal(body, 'danger', 'Error')
    }

    const submitForm = async () => {
        try {
            await doThing() // 假设doThing是异步函数
        } catch (e) {
            showAlert((e as Error).message) // TypeScript类型断言
        }
    }

    return (
        <Layout>
            <Content />
            <Modal ref={modalRef} />
        </Layout>
    )
}

关键说明 #

• forwardRef：让组件能够接收父组件传递的ref，并把它绑定到内部的DOM元素或者暴露方法。
• useImperativeHandle：自定义父组件通过ref能访问到的方法/属性，避免直接暴露整个组件内部的状态和逻辑，符合封装原则。
• TypeScript类型定义：通过ModalHandle明确对外暴露的方法，让智能提示更准确，避免类型错误。

这种方式既让Modal组件自管理状态，又允许父组件通过命令式的方式调用其方法，完全符合你想要的组件化模式。

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