工程配置

tui-plus-vapor 项目的基础接入方式与最佳实践

配置概览

⚙️

vite.config.ts

tui-vitex 插件配置与编译期优化

🎨

theme.json

双主题系统与设计令牌管理

🌍

locale 目录

多语言文案组织与管理

vite.config.ts

核心功能：tui-vitex 插件提供编译期样式生成与优化能力

当前项目已经在根目录的 vite.config.ts 中接入了 tui-vitex 插件，并把 theme.json 作为主题变量输入给插件使用。

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import TuiCollector from './uni_modules/tui-vitex';
import theme from './theme.json'

export default defineConfig({
	devSourcemap: true,
	plugins: [
		TuiCollector({
			unit: 'rpx',
			theme
		}),
		uni()
	]
});

对应文件：vite.config.ts:1

🔧 关键配置说明

• TuiCollector 来自 uni_modules/tui-vitex，用于收集并生成组件库依赖的样式能力
• unit: 'rpx' 表示生成的样式单位以 rpx 为主，适合当前 uni-app x 项目
• theme 直接读取根目录的 theme.json，这样主题变量可以集中维护
• uni() 仍然保留在插件数组中，作为 uni-app x 项目的基础 Vite 插件

除了 vite.config.ts 以外，当前项目还在 App.uvue 中引入了 tui-vitex 生成的样式文件：

@import url('./uni_modules/tui-vitex/autocss.css');

对应文件：App.uvue:11

另外，组件库插件已经在 main.uts 中完成注册：

import { Tui } from '@/uni_modules/tui-plus-vapor'

export function createApp() {
	const app = createSSRApp(App)
	app.use(Tui)
	return { app }
}

对应文件：main.uts:3

theme.json

核心功能：双主题系统支持明暗模式切换，统一设计令牌管理

当前工程把主题能力统一放在根目录的 theme.json 中，结构分为 light 和 dark 两套配置。

{
	"light": {
		"navigationBarTextStyle": "black",
		"navigationBarBackgroundColor": "#efeff4",
		"primaryNormal": "#2979ff",
		"primaryLight": "#dcedff",
		"textPrimary": "#303133",
		"radiusLarge": "20"
	},
	"dark": {
		"navigationBarTextStyle": "white",
		"navigationBarBackgroundColor": "#1F1F1F",
		"primaryNormal": "#0000ff",
		"primaryLight": "#1a4e8c",
		"textPrimary": "#E5E5E5",
		"radiusLarge": "20"
	}
}

对应文件：theme.json:1

🎨 主题配置分类

这份配置里主要包含几类变量：

• 页面与导航相关：例如 navigationBarTextStyle、navigationBarBackgroundColor、backgroundColor
• tabBar 相关：例如 tabBarColor、tabBarSelectedColor、图标路径等
• 语义色板：例如 info*、primary*、success*、warning*、error*
• 文本颜色：例如 textPrimary、textRegular、textSecondary
• 设计令牌：例如圆角、间距、边框、内边距、字号、比例等

💡 推荐维护方式

• 新增品牌色时，优先在 light 和 dark 下成对维护，避免明暗模式变量不对齐
• 公共尺寸、圆角、字号尽量继续放在 theme.json 中，不要分散到多个组件里硬编码
• 如果某个组件需要主题联动，优先复用现有语义变量命名，而不是单独发明新的零散字段

locale 目录

核心功能：完整的多语言支持，组件库内置文案管理

当前项目根目录已经包含 locale 目录，用于维护多语言文案：

• locale/zh.json
• locale/en.json

当前文件内容如下：

{
	"index.welcome": "Welcome to TuiPlusVapor",
	"index.title": "Home"
}

对应文件：locale/zh.json:1

{
	"index.welcome": "欢迎使用 TuiPlusVapor",
	"index.title": "首页"
}

对应文件：locale/en.json:1

⚠️ 注意：从当前内容可以看出，这两个文件的语言值是互换的，后续整理时建议统一修正，保持文件名与实际语言一致。

🌍 locale 目录约定

关于 locale 目录，建议遵循下面的约定：

• zh.json 放中文文案，en.json 放英文文案
• key 命名尽量使用"页面/模块 + 语义"的形式，例如 index.title、button.submit
• 同一批新增文案要同时补齐所有语言文件，避免运行时缺失
• 组件库层与业务层文案尽量分层命名，避免不同模块 key 冲突

组件库内的 locale

除了根目录的业务文案目录，组件库内部还预留了自己的国际化入口：uni_modules/tui-plus-vapor/common/locale/index.uts

对应文件：uni_modules/tui-plus-vapor/common/locale/index.uts

当前这个文件还是空的，说明组件库自身的国际化能力还没有真正落地。如果你后面准备继续补齐组件库内置文案，可以考虑：

• 在这个目录下补充组件库级别的默认语言包
• 把组件内固定文案统一抽离到这里管理
• 约定组件库文案 key 前缀，例如 tui.button.confirm、tui.popup.cancel

推荐接入顺序

如果后面要给别人写一份简洁接入说明，建议顺序保持为：

1️⃣

配置 Vite

在 `vite.config.ts` 中接入 `tui-vitex` 插件并读取 `theme.json`

2️⃣

引入样式

在 `App.uvue` 中引入 `uni_modules/tui-vitex/autocss.css`

3️⃣

注册插件

在 `main.uts` 中注册 `Tui` 插件

4️⃣

配置主题

在根目录维护 `theme.json` 的明暗主题变量

5️⃣

多语言

在 `locale` 目录下维护业务多语言文案

🎯 完成以上配置后，您就可以开始使用 Tui Plus Vapor 的强大功能了！