React函数组件集成intro.js-react时无法正确识别步骤配置元素

代码中存在的核心问题 #

• 选择器API使用错误：document.getElementById('.card') 不符合API规范，该方法入参为不带选择器前缀的id值，传入带类选择器点号的字符串会直接返回null
• DOM查询时序错误：在useState初始化阶段同步执行DOM查询时，组件刚完成首次渲染，后续要作为引导目标的.card、.tableRow节点还未挂载到页面，此时查询拿到的永远是空值
• 不符合组件使用规范：intro.js-react的steps配置推荐传入CSS选择器字符串而非提前获取的DOM元素对象，组件会在引导启动的正确时机自动完成DOM查询，提前获取的DOM对象可能因为组件重渲染导致引用失效

修正后的实现方案 #

直接在步骤配置中填写合法的CSS选择器字符串，移除提前执行的DOM查询逻辑，确保引导启动时目标元素已经完成页面渲染。
修正后可正常运行的代码如下：

import React,{useState} from 'react'
import { Steps, Hints } from "intro.js-react";
import "intro.js/introjs.css"
import "intro.js/themes/introjs-nassim.css";
const AppIntro = () =>{
  const [stepsEnabled, setStepsEnabled] = useState(false)
  const [initialStep, setInitialStep] = useState(0)

  // 直接配置CSS选择器字符串，无需提前查询DOM
  const steps = [
    {
        intro:"Welcome to our application",
        position: 'top'
    },
    {
        element: '.card',
        intro: 'This is the second step',
        position: 'left'
    },
    {
        element: '.tableRow',
        intro:'This is the third step',
        position: 'top'
    }
  ]

  const onExit = () =>{
    setStepsEnabled(false);
  }

  const startIntro=()=>{
    setStepsEnabled(true)
  }

  return(
    <div>
      <button onClick={()=>startIntro()}>Click me</button>
      {/* 页面实际渲染的引导目标元素，启动引导时需确保这些元素已挂载 */}
      <div className="card" style={{margin: '20px', padding: '10px', border: '1px solid #eee'}}>我是卡片元素</div>
      <div className="tableRow" style={{margin: '20px', padding: '10px', border: '1px solid #eee'}}>我是表格行元素</div>

      <Steps
         enabled={stepsEnabled}
         steps={steps}
         initialStep={initialStep}
         onExit={onExit}
         options={{
             tooltipClass: 'customTooltip',
             showProgress: true,
             showStepNumbers: true,
             showBullets: false,
             exitOnOverlayClick: false,
             doneLabel: "Done",
             nextLabel: "Next",
             hideNext: false,
         }}
     />
    </div>
  )
}
export default AppIntro

额外注意事项 #

• 如果引导目标是异步渲染的节点（比如接口数据加载完成后才展示的内容），必须等节点渲染完成后再触发引导启动逻辑，避免查询时DOM不存在
• 引导目标的选择器要保证页面唯一性，多个元素匹配同一个类名时，组件会默认取第一个匹配元素，容易出现定位偏差
• 若目标元素设置了display:none、visibility:hidden等隐藏属性，需要在引导启动前取消隐藏，否则组件无法识别元素的实际位置
• 若引导步骤是固定配置，不需要动态调整的话，可以直接在组件作用域内定义为普通常量，不需要嵌套在useState中，减少冗余的状态监听

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