扩展
通过一些示例来满足你的项目需求
钩子按阶段逐个接收参数,不接收上下文对象。参数清单见配置。
排除页面
exclude 无法排除某些页面时,可以用 onAfterScanPages 过滤扫描结果。
该钩子接收两个 Map:主包页面与分包页面。删除 Map 里的键即可排除页面。
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { scanPageFilter } from './builds/util.js'
export default defineConfig({
plugins: [
UniPages({
onAfterScanPages: (pages, subPages) => {
scanPageFilter(pages)
for (const pages of subPages.values())
scanPageFilter(pages)
},
})
],
})
// 只保留以 .page.vue 结尾的页面
export function scanPageFilter(pages) {
for (const key of pages.keys()) {
if (!key.endsWith('.page.vue'))
pages.delete(key)
}
}
路由唯一标识
路由需要唯一标识 name 时,可以用 onAfterMergePageMetaData 自动生成,不用逐页手写。
该钩子接收合并后的主包页面数组与分包数据。
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { handlePageName } from './builds/util.js'
export default defineConfig({
plugins: [
UniPages({
onAfterMergePageMetaData: (pageMetaData, subPageMetaData) => {
handlePageName(pageMetaData)
for (const subPackage of subPageMetaData)
handlePageName(subPackage.pages)
},
})
],
})
export function handlePageName(pages) {
for (const page of pages) {
// 已有配置优先,跳过自动生成
if (page.name)
continue
// 路径里的 / . - 换成下划线并转大写
// pages/home/index.page.vue 生成 PAGES_HOME_INDEX_PAGE
page.name = page.path.replace(/[/.-]/g, '_').toUpperCase()
}
}
路径常量化
把页面路径生成常量模块,避免在业务代码里硬编码字符串。
用 onAfterWriteFile 写文件。该钩子接收 filePath 与 content 两个参数,此时 pages.json 已经写好。
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { writePageConst } from './builds/util.js'
export default defineConfig({
plugins: [
UniPages({
onAfterWriteFile: (_filePath, content) => {
writePageConst(content)
},
})
],
})
import fs from 'node:fs'
import { fileURLToPath, URL } from 'node:url'
export function writePageConst(pagesJsonContent) {
const pagesJson = JSON.parse(pagesJsonContent)
const entries = []
const collect = (pages) => {
for (const page of pages) {
const title = page.style?.navigationBarTitleText || ''
entries.push(` /** ${title} */\n ${JSON.stringify(page.path)}: ${JSON.stringify(`/${page.path}`)},`)
}
}
collect(pagesJson.pages ?? [])
for (const subPackage of pagesJson.subPackages ?? [])
collect(subPackage.pages ?? [])
const fileContent = `/**
* 此文件由脚本自动生成,请勿手动修改
*/
/**
* 页面路径常量
*/
export const PageUrlConst = {
${entries.join('\n')}
}
`
const filePath = fileURLToPath(new URL('../constants/pageConst.js', import.meta.url))
fs.writeFileSync(filePath, fileContent, 'utf-8')
console.log(`页面路径常量文件已生成:${filePath}`)
}
提前生成 pages.json
UniPages() 返回的插件实例带 prepare()。它等待页面配置与已启用的声明文件生成,然后返回同一个实例。
prepare() 用于下游插件需要读取 pages.json 的场景,例如 vite-plugin-uni-middleware 或 uni-app 自己的启动流程。
vite.config.ts
import Uni from '@uni-helper/plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
await UniPages().prepare({ platformSuffix: true }),
Uni(),
],
})
prepare() 的选项:
| 选项 | 类型 | 说明 |
|---|---|---|
root | string | Vite 项目根目录,相对路径以当前工作目录为基准。默认 process.env.VITE_ROOT_DIR || process.cwd()。 |
platformSuffix | boolean | 是否采用 vite-plugin-uni-platform 的文件名后缀规则。必须与最终插件列表一致。 |
几个约束:
- 使用调用时的
UNI_PLATFORM。根目录、平台与后缀规则必须与 Vite 初始化一致。 - 相同参数的并发或重复调用共享结果,首次 Vite 接管时复用该结果。
- Vite 会话关闭后再次调用会重新生成。成功准备过的根目录、平台与后缀约束持续有效。
- 参数冲突、编译平台缺失、实例正在关闭或生成失败时,返回的 Promise 被拒绝。