@ equinor/ inform-framework-vite-plugin-raw- 进口

将文本文件嵌入为内置字符串模块的 Vite 插件 ?raw 进口.

需要可靠原始字符串导入时使用此插件 Vite 库模式 (单位:千美元)build.lib)或当Vite内置时 ?raw 处理者处理不当 深陷相对路径。 它自动包含在 @equinor/fusion-framework-cli。 。 。 .

[注] 虚拟支持 ?raw 原产地进口,但视其为静态资产. 此插件在构建时读取文件并直接内入内容 输入 JavaScript 捆绑,所以字符串可以在运行时使用,而不包含 单独的资产请求.

谁应该使用这个

• Fusion app开发者 —— 插件在构建时已经激活 @equinor/fusion-framework-cli不需要设置.
• 图书馆作者 与 vite build --lib 将标记、文本或模板文件导入为字符串.
• 谁都行 从 Vite 本地打出 404 或错误的路径 ?raw 与深度的相对进口.

快速启动

自动( Fusion CLI)

如果你建造与 @equinor/fusion-framework-cli,插件为您注册。 只是导入 :

import readme from '../../README.md?raw';
console.log(readme); // full file content as a string

手动安装

pnpm add -D @equinor/fusion-framework-vite-plugin-raw-imports

// vite.config.ts
import { defineConfig } from 'vite';
import { rawImportsPlugin } from '@equinor/fusion-framework-vite-plugin-raw-imports';

export default defineConfig({
  plugins: [rawImportsPlugin()],
});

关键概念

构建- 时间嵌入

该插件运行于Vite建造(和dev-server)转换管道期间. 当它遇到一个像 './notes.md?raw',则:

1. 确定文件路径相对于导入模块.
2. 从磁盘读取文件内容.
3. 返回虚拟模块 : export default "<file content>"。 。 。 .

结果是一个普通的JavaScript字符串——运行时没有资产请求.

扩展过滤

只默认 .md 文件被截取。 所有其他 ?raw 进口(图像、遮蔽等)通过Vite的内置处理器,因此现有的进口继续运作.

执行阶段

插件注册到 enforce: 'pre',意思是它解决进口 在此之前 Vite的内部资产插件. 这避免了库模式下的冲突.

常见模式

在反应组件中显示下划线

import readmeContent from '../../README.md?raw';
import '@equinor/fusion-wc-markdown/markdown-viewer';

export default function AboutPage() {
  return <fwc-markdown-viewer>{readmeContent}</fwc-markdown-viewer>;
}

处理其他文件扩展名

import { rawImportsPlugin } from '@equinor/fusion-framework-vite-plugin-raw-imports';

export default defineConfig({
  plugins: [
    rawImportsPlugin({
      extensions: ['.md', '.txt', '.json'],
    }),
  ],
});

[注] 扩展未列在 extensions 选项由 Vite 处理 内置 ?raw 支持,因此图像和阴影导入仍然不受影响.

为 Raw 导入添加类型脚本声明

创建声明文件, 从而 TypeScript 识别 ?raw 进口:

// src/types/raw.d.ts
declare module '*.md?raw' {
  const content: string;
  export default content;
}

解析各种路径格式

import a from './file.md?raw';            // same directory
import b from '../README.md?raw';         // parent directory
import c from '../../docs/guide.md?raw';  // deeply nested relative
import d from '/src/docs/guide.md?raw';   // absolute from project root

路径是相对于导入文件目录解决的.

API 表面

rawImportsPlugin(options?)

创建截取 Vite 插件 ?raw 导入已配置的文件扩展名并将其内容作为内置字符串模块.

回返情况: Plugin ——一个 Vite 插件 resolveId 财务报告和审定财务报表 load 钩子.

掷出 : Error 当匹配的文件无法从磁盘读取时。 错误消息包括已解析的路径和基本的OS错误:

Failed to read file: /absolute/path/to/file.md. ENOENT: no such file or directory

何时使用此插件对 Vite 的内置 ?raw

限制和限制

• 只有文本文件 —— 二进制内容将被损坏, 因为插件读取时 utf-8 编码.
• 仅构建时间 ——在构建时获取文件内容;运行时文件更改不反映.
• 套装大小 ——大型文件被嵌入到JavaScript捆绑中,这影响了捆绑大小.

相关软件包

• @equinor/fusion-framework-cli ——默认包含此插件的 CLI 用于所有 Vite 构建 .
• @equinor/fusion-imports ——以建设为主的建筑具有类似的生入功能.