JSX与TSX的互操作性概述
在现代前端开发中，尤其是在使用react和typescript的项目中，我们经常会遇到需要混合使用javascript (jsx) 和typescript (tsx) 组件的场景。typescript作为javascript的超集，旨在提供类型安全，但它也完全支持与现有javascript生态的集成。这意味着在一个typescript项目中，导入并使用纯jsx文件编写的组件是完全可行的，并且通常不会有本质上的障碍。核心在于正确配置typescript编译器，使其能够理解和处理.jsx文件。
解决“模块声明未找到”错误
当尝试在TSX文件中导入一个JSX组件时，如果遇到“无法找到模块的声明文件” (Cannot find declaration for module) 错误，这通常不是因为JSX和TSX本身不兼容，而是TypeScript编译器在解析.jsx文件时遇到了配置问题。
错误原因分析
TypeScript编译器默认情况下可能不会处理或解析.js或.jsx文件，除非显式告知它这样做。当一个.tsx文件尝试导入一个.jsx文件时，如果tsconfig.json中的相关配置不正确，TypeScript会认为这个模块没有对应的类型定义（声明文件），从而抛出错误。
解决方案：配置tsconfig.json
解决此问题的关键在于调整项目的tsconfig.json文件，以确保TypeScript编译器能够正确地处理.jsx文件。
启用allowJs选项： 将compilerOptions中的allowJs设置为true。这会告诉TypeScript编译器允许编译JavaScript文件（包括JSX文件）。
-
配置jsx选项： 根据你的React版本和项目需求，将jsx选项设置为合适的值。
- "react"：适用于使用React.createElement的传统JSX转换。
- "react-jsx"：适用于React 17+的新的JSX转换（不需要在文件顶部导入React）。
- "preserve"：保留JSX语法，由Babel等工具进一步处理。 对于大多数React项目，"react"或"react-jsx"是常见的选择。
确保moduleResolution正确：moduleResolution选项指定了TypeScript如何解析模块。对于Node.js环境，"node"是标准且推荐的设置。
以下是一个示例tsconfig.json配置片段，展示了如何配置这些选项：
{
"compilerOptions": {
"target": "es2016",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true, // 允许编译JavaScript文件
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": true,
"module": "esnext",
"moduleResolution": "node", // 确保模块解析策略正确
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx", // 根据你的React版本选择合适的JSX转换方式
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"], // 确保包含JSX文件
"exclude": ["node_modules"]
}重要提示： 确保include数组中包含了.jsx文件类型，这样TypeScript才能在项目范围内找到并处理它们。例如："include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"]。
示例：在TSX中导入JSX组件
假设我们有一个纯JSX文件Carousel.jsx和一个TSX文件Samskaras.tsx，我们想在Samskaras.tsx中导入并使用Carousel组件。
JSX组件 (Carousel.jsx)
import React from 'react';
import { Swiper, SwiperSlide, useSwiper } from "swiper/react";
import 'swiper/css';
// import { sliderSettings } from './common.js'; // 假设这是一个JS文件
import data from './slider.json'; // 假设这是一个JSON文件
const Carousel = () => {
// 假设 sliderSettings 是一个对象，例如：
const sliderSettings = {
slidesPerView: 1,
spaceBetween: 30,
pagination: {
clickable: true,
},
breakpoints: {
640: {
slidesPerView: 1,
spaceBetween: 20,
},
768: {
slidesPerView: 2,
spaceBetween: 40,
},
1024: {
slidesPerView: 3,
spaceBetween: 50,
},
},
};
return (
<div className='p-[1.5rem] w-[100%] overflow-hidden relative'>
<Swiper {...sliderSettings}>
{
data.map((card, i) => (
<SwiperSlide key={i}>
<div className='flex flex-col justify-center items-start gap-[0.6rem] p-4 rounded-[10px] max-w-[max-content] m-auto transition-all delay-300 ease-in'>
<img src={card.image} alt='samskaras'/>
<span>{card.name}</span>
<span>{card.description}</span>
</div>
</SwiperSlide>
))
}
</Swiper>
</div>
)
}
export default Carousel;TSX文件 (Samskaras.tsx)
在配置了tsconfig.json之后，导入Carousel.jsx将变得非常简单，就像导入任何其他TypeScript模块一样：
import HText from '@/shared/HText';
import { SelectedPage } from '@/shared/types'
import { motion } from 'framer-motion';
import Carousel from './Carousel'; // 直接导入JSX文件，无需特殊处理
type Props = {
setSelectedPage: (value: SelectedPage) => void;
}
const Samskaras = ({setSelectedPage}: Props) => {
return (
<section id='samskaras' className='w-full bg-primary-100 py-40'>
<motion.div
onViewportEnter={() => setSelectedPage(SelectedPage.Samskaras)}
>
<motion.div
className='mx-auto w-5/6'
initial="hidden" whileInView="visible" viewport={{ once: true, amount: 0.5 }} transition={{ duration: 0.5 }} variants={{ hidden: {opacity: 0, x: -50}, visible: {opacity: 1, x: 0}}}
>
<div className='md:w-3/5'>
<HText>
SAMSKARAS
</HText>
<p className='py-5'>
Fringilla a sed at suspendisse ut enim volutpat. Rhoncus vel est
tellus quam porttitor. Mauris velit euismod elementum arcu neque
facilisi. Amet semper tortor facilisis metus nibh. Rhoncus sit
enim mattis odio in risus nunc.
</p>
</div>
</motion.div>
{/* 在这里使用Carousel组件 */}
<Carousel />
</motion.div>
</section>
)
}
export default Samskaras通过上述配置和导入方式，TypeScript编译器将能够正确解析Carousel.jsx文件，并允许你在Samskaras.tsx中无错误地使用Carousel组件。
注意事项
-
类型推断与声明文件 (.d.ts)： 尽管allowJs: true允许你导入JSX文件，但TypeScript对这些JavaScript文件的类型推断能力是有限的。对于复杂的JSX组件，如果希望在TSX文件中获得更好的类型检查和智能提示，可以手动为JSX组件创建.d.ts声明文件。例如，为Carousel.jsx创建Carousel.d.ts：
// Carousel.d.ts declare module './Carousel' { import React from 'react'; const Carousel: React.FC; // 或者根据Carousel组件的props定义更具体的类型 export default Carousel; }或者更直接地声明组件的props类型：
// Carousel.d.ts import React from 'react'; interface CarouselProps { // 如果Carousel组件接受props，在这里定义 } declare const Carousel: React.FC<CarouselProps>; export default Carousel;但对于不接受props的简单JSX组件，或仅需基本导入，通常不需要手动创建.d.ts文件。
统一项目风格： 尽管JSX和TSX可以共存，但为了保持项目的一致性和最大化TypeScript的类型优势，建议新开发的组件或在条件允许的情况下，尽量将所有React组件都迁移到TSX格式。这有助于在整个项目中实现端到端的类型安全。
文件命名约定： 确保你的JSX文件使用.jsx扩展名，而不是.js，这样TypeScript和其他工具（如ESLint）可以更好地识别其内容。
总结
在TypeScript项目中集成JSX组件并非难题，关键在于正确配置tsconfig.json文件，特别是allowJs和jsx选项。一旦配置得当，TypeScript编译器就能无缝处理JSX文件，消除“模块声明未找到”的错误，从而允许开发者在项目中灵活地混合使用JSX和TSX组件。虽然可以在TSX中导入JSX，但为了充分利用TypeScript的优势，建议尽可能将组件迁移到TSX，或为关键JSX组件提供类型声明文件，以提升代码的可维护性和健壮性。
