配置选项

详细了解 Root 的所有配置选项

Root 配置选项

Root 提供了多种配置选项，让您可以根据项目需求自定义其行为。本文档将详细介绍所有可用的配置选项及其使用方法。

基本配置

Root 的配置在 vite.config.(js|ts) 文件中的 UniKuRoot 插件选项中进行：

// vite.config.(js|ts)
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniKuRoot({
      // 在这里配置 Root 选项
    }),
    Uni()
  ]
})

配置选项详解

rootFileName

类型: string
默认值: 'App'
描述: 自定义虚拟根组件的文件名。

使用示例

// vite.config.(js|ts)
UniKuRoot({
  rootFileName: 'KuRoot'
})

配置后，您需要创建对应的 KuRoot.vue 文件作为虚拟根组件，而不是默认的 App.ku.vue。

注意事项

  • 文件名不需要包含 .vue 后缀，Root 会自动添加
  • 修改此配置后，原有的 App.ku.vue 将不再生效
  • 确保项目中的所有引用都使用新的文件名

enabledGlobalRef

类型: boolean
默认值: false
描述: 是否启用全局自动注入 App.ku 实例。

使用示例

// vite.config.(js|ts)
UniKuRoot({
  enabledGlobalRef: true
})

启用后，您可以通过 getCurrentPages() 获取根组件实例：

<!-- src/pages/*.vue -->
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const pagesStack = getCurrentPages()
const uniKuRoot = ref()

onMounted(() => {
  uniKuRoot.value = pagesStack[pagesStack.length - 1].$vm.$refs.uniKuRoot
})
</script>

局部启用 vs 全局启用

特性局部启用全局启用
配置方式在页面模板中使用 root 属性在 vite.config 中设置 enabledGlobalRef: true
使用范围仅限当前页面所有页面均可使用
性能影响最小，按需加载略高，全局注入
代码简洁性需要在每个页面定义 ref一次配置，多处使用
适用场景少量页面需要访问根组件多个页面需要访问根组件

excludePages

类型: string[]
默认值: []
描述: 排除不需要根组件的页面，支持 Glob 模式。

使用示例

// vite.config.(js|ts)
UniKuRoot({
  excludePages: [
    'src/exclude.vue',
    'src/exclude/**/*.vue',
    'src/pages/login.vue',
    'src/pages/error/**/*.vue'
  ]
})

Glob 模式支持

excludePages 选项支持使用 Glob 模式进行灵活匹配：

模式描述示例
*.vue匹配当前目录下所有 Vue 文件pages/*.vue
**/*.vue匹配所有子目录中的 Vue 文件pages/**/*.vue
src/login.vue匹配特定文件src/login.vue
src/auth/**匹配特定目录下的所有文件src/auth/**

实际应用示例

1. 排除登录和注册页面
// vite.config.(js|ts)
UniKuRoot({
  excludePages: [
    'src/pages/login.vue',
    'src/pages/register.vue',
    'src/pages/forgot-password.vue'
  ]
})
2. 排除整个错误页面目录
// vite.config.(js|ts)
UniKuRoot({
  excludePages: [
    'src/error-pages/**'
  ]
})
3. 排除特定模式的页面
// vite.config.(js|ts)
UniKuRoot({
  excludePages: [
    'src/pages/public-*.vue',  // 所有以 public- 开头的页面
    'src/pages/**/*.test.vue'  // 所有子目录中的测试页面
  ]
})

被排除页面的特点

被排除在根组件之外的页面具有以下特点：

  1. 独立渲染：页面不会渲染到 <KuRootView /> 中，而是直接渲染
  2. 无根组件上下文：无法访问根组件中定义的方法和数据
  3. 性能优化：减少了不必要的组件层级，提高渲染性能
  4. 特殊样式：可以应用不同于其他页面的样式和布局

viewTagName

类型: string
默认值: 'KuRootView'
描述: 自定义视图标签的名称。

使用示例

// vite.config.(js|ts)
UniKuRoot({
  viewTagName: 'AppView'
})

配置后，您需要在虚拟根组件中使用自定义的视图标签：

<!-- src/App.ku.vue -->
<template>
  <div>
    <AppView />
  </div>
</template>

注意事项

  • 自定义标签名称不需要包含 < 和 >，Root 会自动处理
  • 确保自定义标签名称不与现有组件或 HTML 元素冲突
  • 修改视图标签名称后，项目中所有使用该标签的地方都需要更新

debug

类型: boolean
默认值: false
描述: 是否启用调试模式。

使用示例

// vite.config.(js|ts)
UniKuRoot({
  debug: true
})

启用调试模式后，Root 会在控制台输出以下信息：

  • 根组件的创建和挂载过程
  • 页面组件的创建和挂载过程
  • 生命周期事件的触发顺序
  • 组件实例的引用信息
  • 排除页面的处理情况

示例输出

[UniKuRoot Debug] Creating root component: App.ku.vue
[UniKuRoot Debug] Root component mounted
[UniKuRoot Debug] Processing page: src/pages/index.vue
[UniKuRoot Debug] Page component mounted
[UniKuRoot Debug] Root ref injected: uniKuRoot
[UniKuRoot Debug] Excluded page: src/pages/login.vue

注意事项

  • 调试模式仅建议在开发环境中使用，生产环境应关闭
  • 调试信息可能会影响性能，特别是在页面数量较多的项目中
  • 可以结合浏览器的开发者工具，更好地理解 Root 的工作原理

完整配置示例

// vite.config.(js|ts)
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后
    UniKuRoot({
      // 自定义虚拟根组件文件名
      rootFileName: 'KuRoot',
      
      // 启用全局自动注入 App.ku 实例
      enabledGlobalRef: true,
      
      // 自定义视图标签名称
      viewTagName: 'AppView',
      
      // 启用调试模式
      debug: process.env.NODE_ENV === 'development',
      
      // 排除不需要根组件的页面
      excludePages: [
        'src/pages/login.vue',
        'src/pages/register.vue',
        'src/error-pages/**'
      ]
    }),
    Uni()
  ]
})

配置最佳实践

1. 根据项目需求选择配置

根据您的项目需求选择合适的配置：

  • 小型项目：使用默认配置即可，无需额外设置
  • 中型项目：考虑启用 enabledGlobalRef 以便在多个页面中共享根组件功能
  • 大型项目：自定义 rootFileName 并合理使用 excludePages 排除特殊页面

2. 保持配置的一致性

在团队开发中，确保所有成员使用相同的 Root 配置：

  1. 将配置纳入版本控制：将 vite.config.(js|ts) 文件添加到 Git 仓库中
  2. 文档化配置决策：在项目文档中记录为什么选择特定的配置
  3. 使用配置文件：考虑将 Root 配置提取到单独的文件中，便于管理

3. 性能优化

合理使用配置选项以优化性能：

  1. 按需启用全局引用：只在需要时启用 enabledGlobalRef
  2. 合理排除页面：使用 excludePages 排除不需要根组件的页面，减少不必要的渲染
  3. 避免频繁更改配置：频繁更改 rootFileName 可能会导致项目结构混乱
  4. 生产环境关闭调试：确保在生产环境中关闭 debug 模式

4. 调试和故障排除

当配置不生效时，请检查以下方面：

  1. 配置位置：确保 UniKuRoot 插件配置在正确的位置
  2. 插件顺序：确保 UniKuRoot 在修改 pages.json 的插件之后
  3. 文件路径：检查 excludePages 中的路径是否正确
  4. 缓存问题：尝试清除 Vite 缓存并重新启动开发服务器
  5. 启用调试模式：开启 debug 选项，查看详细的日志信息

常见配置场景

场景一：多环境配置

根据不同环境使用不同的配置：

// vite.config.(js|ts)
import { defineConfig, loadEnv } from 'vite'
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'

export default ({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  
  return defineConfig({
    plugins: [
      UniKuRoot({
        // 开发环境使用默认配置，生产环境自定义文件名
        rootFileName: mode === 'development' ? 'App' : 'ProdRoot',
        
        // 生产环境启用全局引用
        enabledGlobalRef: mode === 'production',
        
        // 开发环境启用调试
        debug: mode === 'development',
        
        // 生产环境排除更多页面
        excludePages: mode === 'production' 
          ? ['src/pages/login.vue', 'src/pages/test/**']
          : ['src/pages/test/**']
      }),
      Uni()
    ]
  })
}

场景二：与 TypeScript 集成

在 TypeScript 项目中使用 Root：

// vite.config.ts
import { defineConfig } from 'vite'
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import type { RootPluginOptions } from '@uni-ku/root'

const rootOptions: RootPluginOptions = {
  rootFileName: 'KuRoot',
  enabledGlobalRef: true,
  viewTagName: 'AppView',
  debug: process.env.NODE_ENV === 'development',
  excludePages: [
    'src/pages/login.vue',
    'src/error-pages/**'
  ]
}

export default defineConfig({
  plugins: [
    UniKuRoot(rootOptions),
    Uni()
  ]
})

场景三：与 monorepo 集成

在 monorepo 项目中，不同子项目可能需要不同的 Root 配置：

// apps/app-1/vite.config.js
import UniKuRoot from '@uni-ku/root'

export default {
  plugins: [
    UniKuRoot({
      rootFileName: 'App1Root',
      enabledGlobalRef: false,
      viewTagName: 'App1View'
    })
  ]
}

// apps/app-2/vite.config.js
import UniKuRoot from '@uni-ku/root'

export default {
  plugins: [
    UniKuRoot({
      rootFileName: 'App2Root',
      enabledGlobalRef: true,
      viewTagName: 'App2View',
      excludePages: ['src/pages/special/**']
    })
  ]
}

配置验证

Root 提供了基本的配置验证，当配置不正确时会在控制台显示警告或错误信息。常见的验证包括：

  1. 类型验证：确保配置值的类型正确
  2. 路径验证：检查 excludePages 中的路径是否存在
  3. 命名验证：确保 rootFileName 和 viewTagName 不包含非法字符
  4. 依赖验证：确保插件顺序正确，Root 在修改 pages.json 的插件之后

如果遇到配置验证错误，请根据错误信息调整配置。

配置类型定义

Root 提供了 TypeScript 类型定义，以便在 TypeScript 项目中获得更好的类型支持：

// @uni-ku/root 类型定义
export interface RootPluginOptions {
  /**
   * 自定义虚拟根组件的文件名
   * @default 'App'
   */
  rootFileName?: string
  
  /**
   * 是否启用全局自动注入 App.ku 实例
   * @default false
   */
  enabledGlobalRef?: boolean
  
  /**
   * 自定义视图标签的名称
   * @default 'KuRootView'
   */
  viewTagName?: string
  
  /**
   * 是否启用调试模式
   * @default false
   */
  debug?: boolean
  
  /**
   * 排除不需要根组件的页面，支持 Glob 模式
   * @default []
   */
  excludePages?: string[]
}

总结

Root 的配置选项提供了灵活的自定义能力，让您可以根据项目需求调整其行为。通过合理使用这些配置选项，您可以：

  1. 自定义虚拟根组件的文件名和视图标签
  2. 选择局部或全局方式访问根组件实例
  3. 排除不需要根组件的特殊页面
  4. 启用调试模式以便开发和故障排除
  5. 优化应用性能和开发体验

在配置 Root 时，请务必考虑项目的实际需求和团队的开发习惯，选择最适合的配置方案。

编辑此页面
示例项目
通过实际示例学习如何使用 Root
常见问题
Root 使用过程中常见问题及解决方案