自动引入组件
weapp-vite
可以在编译阶段自动扫描并注册组件,使你在 WXML 中直接使用组件标签而无需手动写入 usingComponents
。下文分为“本地组件扫描”与“第三方 UI 解析器”两部分,更多字段说明可参考 配置文档 · 增强能力与调试工具。
项目中的组件自动引入
通过配置 weapp.enhance.autoImportComponents.globs
可以让编译器扫描指定目录,在满足“同时存在 .wxml
+ .js/ts
+ .json
且 json.component === true
”的情况下自动注册组件。
export default <UserConfig>{
weapp: {
enhance: {
autoImportComponents: {
globs: ['components/**/*'],
},
},
},
}
默认注册规则如下:
- 组件标识取决于文件名,且大小写敏感。例如
HelloWorld.{wxml,ts,json}
会注册为HelloWorld
。 - 如果组件文件命名为
index.*
,则使用其父级目录名作为组件名,如HelloWorld/index.wxml → HelloWorld
。 - 当同一目录下同时存在
index.*
与同名文件(例如HelloWorld/index.ts
与HelloWorld/HelloWorld.ts
)时,index.*
会被优先采用,保证输出路径稳定。
WARNING
注意,自动导入组件这个行为,会自动忽略小程序内置组件,比如 view
, text
, navigation-bar
等等(所有的标签详见 官方文档 )
所以你组件不能起和这些同名,忽略内建组件的数据详情见 builtin.auto.ts
源代码
第三方UI库的组件自动引入
对于第三方 UI 库,可通过 Resolver 提供个性化规则。目前内置支持 TDesign 与 Vant,也可以编写自定义 Resolver 来适配其他生态。
import { TDesignResolver, VantResolver } from 'weapp-vite/auto-import-components/resolvers'
export default <UserConfig>{
weapp: {
enhance: {
autoImportComponents: {
resolvers: [
VantResolver(),
TDesignResolver()
],
},
},
},
}
这样你就可以直接在 wxml
中使用对应 UI
库的组件了!
自动导出组件清单
编译器会在扫描时同步生成一份 auto-import-components.json
清单,包含“本地扫描到的组件”与“resolver 提供的第三方组件”映射,方便在 IDE 中做补全或排查丢失的组件。默认情况下文件会输出到配置文件同级目录,结构类似:
{
"HelloWorld": "/components/HelloWorld/index",
"Navbar": "/components/Navbar/Navbar",
"van-button": "@vant/weapp/button"
}
可通过 autoImportComponents.output
控制清单行为:
export default <UserConfig>{
weapp: {
enhance: {
autoImportComponents: {
globs: ['components/**/*'],
output: 'dist/auto-import-components.json', // 自定义输出位置
// output: false // 若不需要清单,可显式关闭
},
},
},
}
- 传入相对路径会基于
vite.config.ts
所在目录展开; - 传入绝对路径则写入指定位置;
- 设置为
false
可完全关闭清单输出。
生成类型声明与 HTML 自定义数据
为了获得更好的 IDE 体验,可以启用以下两个可选产物:
typed-components.d.ts
:导出weapp-vite/typed-components
模块,包含componentProps
、ComponentProp
等类型,方便在脚本中做属性推断或二次封装。mini-program.html-data.json
:兼容 VS Code 与微信开发者工具的 HTML 自定义数据格式,为 WXML 提供标签/属性提示与描述。
在配置里开启对应选项即可(可以传入布尔值或自定义输出路径):
export default <UserConfig>{
weapp: {
enhance: {
autoImportComponents: {
globs: ['components/**/*'],
typedComponents: true, // 或 'types/typed-components.d.ts'
htmlCustomData: 'dist/mini-program.html-data.json',
},
},
},
}
启用后,编译器在组件扫描、resolver 匹配过程中会实时刷新上述文件,确保类型与提示始终和组件清单保持一致。