本文旨在解决在使用Reagraph与Vite构建React应用时，节点上非拉丁字符（如俄语）无法正常显示的问题。核心解决方案在于Vite项目配置中，通过在`vite-env.d.ts`文件内声明`.ttf`模块类型，确保字体文件能够被正确导入和解析，从而实现多语言字符的正确渲染。
在现代Web应用开发中，图表可视化是常见需求，而Reagraph作为一个基于React和Three.js的图表库，提供了强大的节点和边渲染能力。然而，当应用场景涉及多语言支持，特别是需要显示非拉丁字符（如俄语、中文等）时，开发者可能会遇到节点标签字体无法正常显示的问题，表现为字符显示为空白、乱码或问号。这通常发生在尝试通过labelFontUrl属性引入自定义字体或使用其他文本渲染库（如troika-three-text）时。
问题分析：Vite项目中的字体文件导入
出现此类问题的主要原因在于Vite等现代构建工具对某些资源类型（如.ttf字体文件）的默认处理机制。在没有明确声明的情况下，Vite可能无法识别.ttf文件为可导入的模块，导致在尝试通过import语句引入字体文件时发生编译错误或运行时加载失败。即使路径看似正确，底层也可能因为类型声明缺失而无法正确解析资源。
解决方案：声明字体模块类型
解决此问题的关键在于告知Vite如何处理.ttf文件。这可以通过在Vite项目的类型声明文件（通常是vite-env.d.ts）中添加相应的模块声明来实现。
步骤一：在 vite-env.d.ts 中声明字体模块
在项目的根目录或src目录下找到vite-env.d.ts文件（如果不存在，可以手动创建），并添加以下声明：
// vite-env.d.ts ///declare module '*.png' declare module '*.svg' declare module '*.ttf' // 添加这一行，声明 .ttf 文件为模块
这段声明告诉TypeScript和Vite，.ttf文件可以作为一个模块被导入。这意味着当你在代码中导入一个.ttf文件时，它将被视为一个有效的资源路径，通常是一个URL字符串，指向打包后的字体文件。
步骤二：在Reagraph组件中导入并使用字体
声明模块类型后，你就可以在React组件中像导入其他资源一样导入.ttf字体文件，并将其路径传递给Reagraph的labelFontUrl属性。
假设你有一个名为MyCustomFont.ttf的字体文件，放置在src/assets/fonts/目录下：
// src/components/GraphComponent.tsx
import React from 'react';
import { Reagraph, useGraph } from 'reagraph';
// 导入自定义字体文件
import MyCustomFont from '../assets/fonts/MyCustomFont.ttf';
const GraphComponent: React.FC = () => {
const { graph, layout, ...api } = useGraph({
nodes: [
{ id: 'node-1', label: '节点一' },
{ id: 'node-2', label: '你好世界' }, // 包含非拉丁字符
{ id: 'node-3', label: 'Привет' } // 包含俄语字符
],
edges: [
{ id: 'edge-1', source: 'node-1', target: 'node-2', label: '连接' },
{ id: 'edge-2', source: 'node-2', target: 'node-3', label: '链接' }
]
});
return (
代码解释：
- import MyCustomFont from '../assets/fonts/MyCustomFont.ttf';：这行代码导入了字体文件。由于在vite-env.d.ts中进行了声明，Vite会正确处理这个导入，并返回字体文件的公共URL路径。
- labelFontUrl={MyCustomFont}：将导入的字体路径赋值给Reagraph组件的labelFontUrl属性。Reagraph将使用这个URL加载字体，并应用于节点标签的渲染。
注意事项
字体文件内容： 确保你使用的.ttf字体文件确实包含了需要显示的非拉丁字符。有些字体可能只支持拉丁字符集。如果字体不包含，即使正确加载也无法显示。
字体许可： 在生产环境中使用自定义字体时，务必检查字体文件的许可协议，确保符合使用规范。
其他资产类型： 这种声明模块类型的方法不仅适用于.ttf文件，也适用于其他Vite默认不识别的资产类型，如特定格式的图片、音频或视频文件。
-
troika-three-text集成： 如果你使用的是troika-three-text库进行文本渲染，其字体属性通常接受字体文件的URL或字体数据。一旦.ttf文件通过Vite正确导入并获取到URL，你就可以将其传递给troika-three-text的相应配置项。例如：
import { Text } from 'troika-three-text'; import MyCustomFont from '../assets/fonts/MyCustomFont.ttf'; // ... 在你的Three.js场景中 const myText = new Text(); myText.text = 'Привет Мир'; myText.font = MyCustomFont; // 将导入的字体路径赋值给 font 属性 myText.sync();
总结
在Vite项目中处理Reagraph节点上的多语言或非拉丁字符显示问题，核心在于正确配置Vite以识别并导入字体文件。通过在vite-env.d.ts中添加declare module '*.ttf'声明，可以有效地解决字体文件无法加载的困境。一旦字体文件被正确导入，即可将其路径传递给Reagraph的labelFontUrl属性或troika-three-text等相关库，从而实现多语言字符的正常渲染，提升应用的用户体验。
