导入解析

Plasmo 框架配备了专为扩展开发定制的代码/资源打包器。它支持原始/转换后的包内联、资源镜像、环境注入等功能。

支持的文件类型

以下文件可以导入到源代码模块中，并将相应地进行转换：

文件扩展名	示例
`.{css,pcss,sass,scss,less}`	`import "./style.css"`
	`import styleCss from "data-text:./style.css"`

`.svg`	`import iconSrc from "data-text:./icon.svg"`
	`import Icon from "react:./icon.svg"`

`.{png,jpg,jpeg,webp,gif,tiff,avif,heic,heif}`	`import imageUrl from "data-url:./image.png"`
	`import image64 from "data-base64:./image.png"`

`.{json,json5}`	`import stuff from "./stuff.json"`
	`import stuff from "data-env:./stuff.json"`

`.{graphql,gql}`	`import query from "~query.gql"`

路径

Plasmo 内置支持大多数常见的导入路径，如相对导入、node_module 包导入和 ESM exports 导入。它还通过波浪号和绝对导入提供项目相对路径。要进一步自定义导入路径，请查看别名导入部分。

波浪号 (`~/`)

波浪号导入路径是”源代码模块目录”的便捷快捷方式。Plasmo 只认为以下扩展名结尾的文件是”源代码模块”：


export const relevantExtensionList = [
  ".ts",
  ".tsx",
  ".svelte",
  ".vue",
  ".json"
] as const

当在源代码模块之外使用或与资源方案（如 data-base64、data-text 或 url）一起使用时，波浪号 (~) 总是解析到项目根目录（package.json 所在的位置）。因此：

在 package.json 中的清单覆盖中使用的 ~rulesets/test.json 解析为 /rulesets/test.json
data-base64:~assets/image.png 解析为 /assets/image.png
url:~src/code.js 解析为 /src/code.js.

假设波浪号本身没有方案，并且用于从另一个源代码模块导入源代码模块。在这种情况下，它有两种行为，具体取决于您使用的是默认设置还是src 目录设置：

使用默认设置，~ 指向项目根目录。
使用 src 目录设置，~ 指向 src 目录。因此 ~core/code-module.tsx 解析为 /src/core/code-module.tsx。

绝对 (`/`)

与波浪号不同，绝对导入路径将始终解析到项目根目录（package.json 所在的位置），无论是否使用 src 目录。如果您偏好完全一致性，请使用绝对导入路径。

相对 (`./`, `../`)

使用 ./ 前缀来导入相对于当前文件的路径的文件。例如，要从与现有文件相同的目录导入文件，请使用 ./file-name。要从子目录导入文件，请使用 ./subdirectory/file-name。要从父目录导入文件，请使用 ../file-name。

方案

Plasmo 引入了几个导入方案，开发人员可以使用这些方案将资源文件导入到扩展包中。方案遵循 <scheme>:<file path> 模式。例如，data-base64:~/assets/image.png 是一个有效的导入路径。

raw

raw 方案指示 Plasmo：

将文件复制到扩展包的根级别
分配内容哈希以区分具有相似名称的其他文件

导入的变量是运行时文件的绝对 URL：


import imageUrl from "raw:~/assets/image.png"
 
console.log(imageUrl) // chrome-extension://<extension-id>/image.<hashA>.png

raw-env

raw-env 方案类似于 raw 方案，但增加了环境变量。例如，如果您有一个文件 ~/assets/config.json，内容如下：


{
  "url": "$PLASMO_PUBLIC_URL"
}

并且您声明了一个环境变量 PLASMO_PUBLIC_URL，值为 https://www.plasmocn.org，那么生成的文件将是：


{
  "url": "https://www.plasmocn.org"
}

👀

raw-env 主要对基于文本的资源有帮助。

url

url 方案指示 Plasmo：

转换/打包/优化文件以供浏览器使用（html/js/css/图像）
将结果 + 依赖项复制到扩展包的根级别
分配内容哈希以区分具有相似名称的其他文件
（仅限内容脚本）将文件添加到 web_accessible_resources 条目

导入的变量是运行时文件的绝对 URL：


import styleAUrl from "url:~/a/style.scss"
import styleBUrl from "url:~/b/style.scss"
import codeUrl from "url:~/c/index.ts"
 
console.log(styleAUrl) // chrome-extension://<extension-id>/style.<hashA>.css
console.log(styleBUrl) // chrome-extension://<extension-id>/style.<hashB>.css
console.log(codeUrl) // chrome-extension://<extension-id>/file.<hashB>.js

😮

对图像资源使用 url 将优化它们的大小和浏览器加载。

data-text

data-text 方案指示 Plasmo：

读取文件内容
转换/打包/优化文件以供浏览器使用（html/js/css/图像）
将内容作为单个包内联到字符串中


import styleText from "data-text:~/assets/style.scss"
 
console.log(styleText)
// {
//   "color": "red",
// }

data-text-env

data-text 方案指示 Plasmo：

读取文件内容
注入公共环境变量
转换/打包/优化文件以供浏览器使用（html/js/css/图像）
将内容内联为 string

.env


PLASMO_PUBLIC_URL=https://itero.plasmo.com

code.json


{
  "url": "$PLASMO_PUBLIC_URL"
}

content.tsx


import codeText from "data-text-env:~/assets/code.json"
 
console.log(codeText) // 要将其用作 JSON，请使用 JSON.parse(codeText)
// "{
//   "url": "https://itero.plasmo.com",
// }"

data-base64

data-base64 方案指示 Plasmo：

读取文件内容
转换/打包/优化文件以供浏览器使用（html/js/css/图像）
将结果转换为 base64 字符串并内联到代码中


import iconBase64 from "data-base64:~/assets/icon.png"
 
console.log(iconBase64) // data:image/png;base64,etc...

data-env

data-env 方案指示 Plasmo：

读取文件内容
注入公共环境变量
转换/打包/优化文件以供浏览器使用（html/js/css/图像）
返回适当的运行时资源结果


import data from "data-env:~/assets/data.json"
 
// 数据将是一个 JSON 对象，无需 JSON.parse！
console.log(data) // { url: "https://itero.plasmo.com" }

react:*.svg

react 方案将任何 svg 资源转换为 React 组件（通过 SVGR 和 SVGO）：


import Logo from "react:~/assets/logo.svg"
 
const Hello = () => <Logo />