Vue组合式API：如何用根组件Props初始化全局状态的useLocalization

场景与背景 #

我有一个名为useLocalization的Vue可组合项，用于提供基于用户语言偏好的翻译字符串，在全应用中通用。它的配置参数定义如下：

interface ILocalizationProps {
    currentLocale: Ref<string>
    fallbackLocale: Ref<string>
    locales: Ref<Partial<ILocale>[]>
}

使用该可组合项的根组件通过withLocalizationProps接收对应Props，允许消费应用配置/覆盖语言设置：

const DEFAULT_LANG = 'en'
export const withLocalizationProps = () => ({
    currentLocale: { type: String, default: null },
    fallbackLocale: { type: String, default: DEFAULT_LANG },
    locales: { type: Array as () => Partial<ILocale>[], default: () => [] },
})

尝试过的方案及问题 #

• 直接调用useLocalization(props)：不可行，深层组件无法获取根组件的Props
• 使用provide/inject：根组件通过provide传递配置后，深层组件可通过inject获取实例，但根组件自身无法使用useLocalization，因为注入内容尚未创建
• 类似vee-validate的injectWithSelf方案：将可组合项签名改为useLocalization(props?: IProps)，但要求根组件必须是第一个调用该函数并传入Props的组件，存在使用限制
• VueUse的createInjectionState辅助函数：与方案2问题相同，根组件无法直接使用

最优解决方案 #

采用根组件预初始化+实例注入+可组合项自动适配的模式，既满足根组件自身使用需求，又能让深层组件无感知消费，具体实现如下：

1. 改造useLocalization可组合项 #

抽离核心逻辑，让可组合项同时支持"根组件传参初始化"和"深层组件无参注入"两种模式：

import { inject, provide, ref, watch, type Ref } from 'vue'

const LOCALIZATION_INJECT_KEY = Symbol('localization')

// 假设你的ILocale结构定义
interface ILocale {
  locale: string
  [key: string]: string
}

interface ILocalizationProps {
  currentLocale: Ref<string | null>
  fallbackLocale: Ref<string>
  locales: Ref<Partial<ILocale>[]>
}

// 封装核心翻译逻辑
const createLocalizationCore = (props: ILocalizationProps) => {
  // 处理当前语言的最终值（兼容currentLocale为null的情况）
  const resolvedCurrentLocale = ref(props.currentLocale.value || props.fallbackLocale.value)
  
  // 监听currentLocale变化，自动更新
  watch([props.currentLocale, props.fallbackLocale], ([newCurrent, newFallback]) => {
    resolvedCurrentLocale.value = newCurrent || newFallback
  })

  // 翻译函数实现
  const translate = (key: string): string => {
    const currentLang = props.locales.value.find(l => l.locale === resolvedCurrentLocale.value)
    const fallbackLang = props.locales.value.find(l => l.locale === props.fallbackLocale.value)
    return currentLang?.[key] || fallbackLang?.[key] || key
  }

  return {
    translate,
    resolvedCurrentLocale,
    fallbackLocale: props.fallbackLocale,
    locales: props.locales
  }
}

export const useLocalization = (props?: ILocalizationProps) => {
  // 根组件传参时：初始化实例并注入
  if (props) {
    const instance = createLocalizationCore(props)
    provide(LOCALIZATION_INJECT_KEY, instance)
    return instance
  }

  // 深层组件无参调用时：获取注入的实例
  const instance = inject(LOCALIZATION_INJECT_KEY)
  if (!instance) {
    throw new Error('useLocalization 需先在根组件传入配置初始化，或确保注入上下文存在')
  }
  return instance
}

2. 根组件使用方式 #

根组件传参调用useLocalization，同时直接使用返回的翻译能力：

<template>
  <div>{{ t('app_title') }}</div>
  <router-view />
</template>

<script setup lang="ts">
import { useLocalization, withLocalizationProps } from './localization'
import { toRefs } from 'vue'

// 接收外部传入的语言配置Props
const props = defineProps(withLocalizationProps())
const { currentLocale, fallbackLocale, locales } = toRefs(props)

// 初始化并获取翻译实例
const { translate: t } = useLocalization({
  currentLocale,
  fallbackLocale,
  locales
})
</script>

3. 深层组件使用方式 #

无需传参，直接调用useLocalization获取实例：

<template>
  <button>{{ t('btn_submit') }}</button>
</template>

<script setup lang="ts">
import { useLocalization } from './localization'

const { translate: t } = useLocalization()
</script>

方案优势 #

• 根组件可直接使用useLocalization，无需等待注入
• 深层组件调用无感知，无需关心配置细节
• 基于Vue原生API实现，无第三方依赖
• 逻辑分层清晰，核心翻译逻辑与注入逻辑解耦

内容的提问来源于stack exchange，提问作者Johannes