6-01 · ConfigProvider：全局配置源头

// packages/xiaoye-primitives/src/composables/shared-context.ts（全文 29 行）
import type { ComputedRef, InjectionKey } from "vue";

export const configProviderKey: InjectionKey<SharedConfigContext> =
  Symbol.for("xiaoye-config-provider") as InjectionKey<SharedConfigContext>;

export type ComponentSize = "" | "xs" | "sm" | "md" | "lg" | "xl";

export interface Locale {
  emptyTitle?: string;
  emptyDescription?: string;
  popconfirmConfirmButtonText?: string;
  popconfirmCancelButtonText?: string;
}

export interface SharedConfigContext {
  namespace: ComputedRef<string>;
  locale: ComputedRef<Locale>;
  zIndex: ComputedRef<number>;
  size: ComputedRef<ComponentSize>;
  dialog: ComputedRef<unknown>;
  loading: ComputedRef<unknown>;
  message: ComputedRef<unknown>;
  notification: ComputedRef<unknown>;
}

export const DEFAULT_NAMESPACE = "xy";
export const DEFAULT_Z_INDEX = 2000;
export const DEFAULT_SIZE: ComponentSize = "md";

// packages/components/config-provider/src/context.ts L17-37
export interface ConfigProviderContext {
  namespace: ComputedRef<string>;
  locale: ComputedRef<Record<string, string>>;
  zIndex: ComputedRef<number>;
  size: ComputedRef<ComponentSize>;
  dialog: ComputedRef<DialogGlobalConfig>;
  loading: ComputedRef<LoadingGlobalConfig>;
  message: ComputedRef<MessageGlobalConfig>;
  notification: ComputedRef<NotificationGlobalConfig>;
}

export interface ConfigProviderProps {
  namespace?: string;
  locale?: Record<string, string>;
  zIndex?: number;
  size?: ComponentSize;
  dialog?: DialogGlobalConfig;
  loading?: LoadingGlobalConfig;
  message?: MessageGlobalConfig;
  notification?: NotificationGlobalConfig;
}

<!-- packages/components/config-provider/src/config-provider.vue（全文 93 行） -->
<script setup lang="ts">
import { onBeforeUnmount, provide, watch } from "vue";
import type { ConfigProviderProps } from "./context";
import {
  createConfigProviderContext,
  configProviderKey,
  registerGlobalDialogConfig,
  registerGlobalLoadingConfig,
  registerGlobalMessageConfig,
  registerGlobalNotificationConfig,
  unregisterGlobalDialogConfig,
  unregisterGlobalLoadingConfig,
  unregisterGlobalMessageConfig,
  unregisterGlobalNotificationConfig,
  updateGlobalDialogConfig,
  updateGlobalLoadingConfig,
  updateGlobalMessageConfig,
  updateGlobalNotificationConfig
} from "./context";

const props = withDefaults(defineProps<ConfigProviderProps>(), {
  namespace: "xy",
  locale: () => ({}),
  zIndex: 2000,
  size: "md",
  dialog: () => ({}),
  loading: () => ({}),
  message: () => ({}),
  notification: () => ({})
});

const globalConfigId = `xy-config-provider-${Math.random().toString(36).slice(2, 10)}`;

provide(configProviderKey, createConfigProviderContext(props));

registerGlobalDialogConfig(globalConfigId, props.dialog);
registerGlobalLoadingConfig(globalConfigId, props.loading);
registerGlobalMessageConfig(globalConfigId, props.message);
registerGlobalNotificationConfig(globalConfigId, props.notification);

watch(
  () => props.dialog,
  (value) => {
    updateGlobalDialogConfig(globalConfigId, value);
  },
  {
    deep: true
  }
);

watch(
  () => props.loading,
  (value) => {
    updateGlobalLoadingConfig(globalConfigId, value);
  },
  {
    deep: true
  }
);

watch(
  () => props.message,
  (value) => {
    updateGlobalMessageConfig(globalConfigId, value);
  },
  {
    deep: true
  }
);

watch(
  () => props.notification,
  (value) => {
    updateGlobalNotificationConfig(globalConfigId, value);
  },
  {
    deep: true
  }
);

onBeforeUnmount(() => {
  unregisterGlobalDialogConfig(globalConfigId);
  unregisterGlobalLoadingConfig(globalConfigId);
  unregisterGlobalMessageConfig(globalConfigId);
  unregisterGlobalNotificationConfig(globalConfigId);
});
</script>

<template>
  <div :class="`${props.namespace}-provider`">
    <slot />
  </div>
</template>

// packages/components/config-provider/src/context.ts L43-54
export function createConfigProviderContext(options: ConfigProviderProps = {}): ConfigProviderContext {
  return {
    namespace: computed(() => options.namespace ?? DEFAULT_NAMESPACE),
    locale: computed(() => options.locale ?? {}),
    zIndex: computed(() => options.zIndex ?? DEFAULT_Z_INDEX),
    size: computed(() => options.size ?? DEFAULT_SIZE),
    dialog: computed(() => options.dialog ?? {}),
    loading: computed(() => options.loading ?? {}),
    message: computed(() => options.message ?? {}),
    notification: computed(() => options.notification ?? {})
  };
}

// packages/components/config-provider/src/context.ts L39-41
export function resolveMaybeRef<T>(value: MaybeRef<T>) {
  return value;
}

// packages/xiaoye-primitives/src/composables/use-config.ts（全文 55 行）
import { computed, inject } from "vue";
import type { ComputedRef } from "vue";
import {
  configProviderKey,
  DEFAULT_NAMESPACE,
  DEFAULT_SIZE,
  DEFAULT_Z_INDEX,
  type ComponentSize,
  type Locale
} from "./shared-context";

export interface ConfigContext<
  DialogConfig = unknown,
  LoadingConfig = unknown,
  MessageConfig = unknown,
  NotificationConfig = unknown
> {
  namespace: ComputedRef<string>;
  size: ComputedRef<ComponentSize>;
  zIndex: ComputedRef<number>;
  locale: ComputedRef<Locale>;
  dialog: ComputedRef<DialogConfig>;
  loading: ComputedRef<LoadingConfig>;
  message: ComputedRef<MessageConfig>;
  notification: ComputedRef<NotificationConfig>;
}

export function useConfig<
  DialogConfig = unknown,
  LoadingConfig = unknown,
  MessageConfig = unknown,
  NotificationConfig = unknown
>(): ConfigContext<DialogConfig, LoadingConfig, MessageConfig, NotificationConfig> {
  const injectedConfig = inject(configProviderKey, null);

  if (injectedConfig) {
    return injectedConfig as ConfigContext<
      DialogConfig,
      LoadingConfig,
      MessageConfig,
      NotificationConfig
    >;
  }

  return {
    namespace: computed(() => DEFAULT_NAMESPACE),
    size: computed(() => DEFAULT_SIZE),
    zIndex: computed(() => DEFAULT_Z_INDEX),
    locale: computed(() => ({} as Locale)),
    dialog: computed(() => ({}) as DialogConfig),
    loading: computed(() => ({}) as LoadingConfig),
    message: computed(() => ({}) as MessageConfig),
    notification: computed(() => ({}) as NotificationConfig)
  };
}

// packages/xiaoye-primitives/src/composables/use-namespace.ts（全文 13 行）
import { computed } from "vue";
import { useConfig } from "./use-config";

export function useNamespace(block: string) {
  const { namespace } = useConfig();
  const base = computed(() => `${namespace.value}-${block}`);

  const is = (state: string, active?: boolean) => (active ? `is-${state}` : "");
  const cssVarBlock = (name: string) => `--${namespace.value}-${block}-${name}`;

  return {
    namespace,
    base,
    is,
    cssVarBlock
  };
}

// packages/components/config-provider/src/context.ts L56-102
const globalDialogConfigRegistry = new Map<string, DialogGlobalConfig>();
const globalDialogConfigState = shallowRef<DialogGlobalConfig>({});
const globalLoadingConfigRegistry = new Map<string, LoadingGlobalConfig>();
const globalLoadingConfigState = shallowRef<LoadingGlobalConfig>({});
const globalMessageConfigRegistry = new Map<string, MessageGlobalConfig>();
const globalMessageConfigState = shallowRef<MessageGlobalConfig>({});
const globalNotificationConfigRegistry = new Map<string, NotificationGlobalConfig>();
const globalNotificationConfigState = shallowRef<NotificationGlobalConfig>({});

function syncGlobalDialogConfigState() {
  const firstEntry = globalDialogConfigRegistry.entries().next();
  globalDialogConfigState.value = firstEntry.done ? {} : firstEntry.value[1];
}

function syncGlobalMessageConfigState() {
  const firstEntry = globalMessageConfigRegistry.entries().next();
  globalMessageConfigState.value = firstEntry.done ? {} : firstEntry.value[1];
}

function syncGlobalLoadingConfigState() {
  const firstEntry = globalLoadingConfigRegistry.entries().next();
  globalLoadingConfigState.value = firstEntry.done ? {} : firstEntry.value[1];
}

function syncGlobalNotificationConfigState() {
  const firstEntry = globalNotificationConfigRegistry.entries().next();
  globalNotificationConfigState.value = firstEntry.done ? {} : firstEntry.value[1];
}

export function registerGlobalDialogConfig(id: string, value: DialogGlobalConfig) {
  globalDialogConfigRegistry.set(id, value);
  syncGlobalDialogConfigState();
}

export function updateGlobalDialogConfig(id: string, value: DialogGlobalConfig) {
  globalDialogConfigRegistry.set(id, value);
  syncGlobalDialogConfigState();
}

export function unregisterGlobalDialogConfig(id: string) {
  globalDialogConfigRegistry.delete(id);
  syncGlobalDialogConfigState();
}

export function getGlobalDialogConfig() {
  return globalDialogConfigState;
}

// packages/components/message/src/method.ts L137-161
function resolveMessageConfig(context?: AppContext | null) {
  if (context) {
    const providedConfig = context.provides?.[configProviderKey as symbol] as
      | ProviderLikeConfig
      | undefined;
    const scopedMessageConfig = providedConfig?.message?.value;

    if (scopedMessageConfig !== undefined) {
      return scopedMessageConfig;
    }
  }

  const globalMessageConfigCount = getGlobalMessageConfigCount();

  if (globalMessageConfigCount <= 1) {
    return getGlobalMessageConfig().value ?? {};
  }

  warnOnce(
    "XyMessage",
    "检测到多个 ConfigProvider.message 同时存在。请改用 $message、XyMessage.withContext(appContext) 或 XyMessage(options, appContext) 来显式指定上下文。当前调用已回退到默认配置。"
  );

  return {};
}

// packages/components/loading/src/service.ts L140-154
function getProvidedConfig(context: AppContext | null) {
  return context?.provides?.[configProviderKey as symbol] as ConfigProviderContextLike | undefined;
}

function resolveNamespace(context: AppContext | null) {
  return getProvidedConfig(context)?.namespace?.value ?? DEFAULT_NAMESPACE;
}

function resolveBaseZIndex(context: AppContext | null) {
  return getProvidedConfig(context)?.zIndex?.value ?? DEFAULT_Z_INDEX;
}

function resolveGlobalLoadingConfig(context: AppContext | null) {
  return getProvidedConfig(context)?.loading?.value ?? getGlobalLoadingConfig().value ?? {};
}

// packages/components/dialog/src/dialog-service-container.vue L54-63
provide(configProviderKey, {
  namespace: computed(() => DEFAULT_NAMESPACE),
  locale: computed(() => ({})),
  zIndex: computed(() => DEFAULT_Z_INDEX),
  size: computed(() => DEFAULT_SIZE),
  dialog: globalDialogConfig,
  loading: globalLoadingConfig,
  message: globalMessageConfig,
  notification: globalNotificationConfig
});

// packages/components/input/src/input.vue L75-95
const attrs = useAttrs();
const slots = useSlots();
const formItem = inject(formItemKey, null);
const form = inject(formKey, null);
const nsInput = useNamespace("input");
const nsTextarea = useNamespace("textarea");
const { size: globalSize } = useConfig();

const inputRef = shallowRef<HTMLInputElement | null>(null);
const textareaRef = shallowRef<HTMLTextAreaElement | null>(null);
const wrapperRef = ref<HTMLDivElement | null>(null);
const isFocused = ref(false);
const hovering = ref(false);
const passwordVisible = ref(false);
const isComposing = ref(false);
const textareaCalcStyle = ref<CSSProperties>({});
const displayValue = ref("");

const mergedSize = computed(() => props.size ?? form?.props.size ?? globalSize.value);
const isTextarea = computed(() => props.type === "textarea");
const inputDisabled = computed(() => props.disabled || (formItem?.disabled.value ?? false));

// packages/components/checkbox/src/checkbox-group.vue L38-40
// 必须在 group 层插入 form 兜底：group.size 恒回落 globalSize 非空，
// 若只在子项链路插 form，子项经 group.size 之后永远到不了 form 层（被非空值遮蔽）。
const mergedSize = computed(() => props.size ?? form?.props.size ?? globalSize.value);

// packages/components/button/src/use-button.ts L7-30
export function useButton(
  props: ButtonProps,
  attrs: Record<string, unknown>,
  emit: (event: "click", payload: MouseEvent) => void
) {
  const { size: globalSize } = useConfig();
  const form = inject(formKey, null);
  const buttonGroup = inject(buttonGroupContextKey, null);
  const buttonRef = ref<HTMLElement | null>(null);

  const resolvedSize = computed(
    () => props.size ?? buttonGroup?.size.value ?? globalSize.value
  );
  const resolvedType = computed<ButtonType>(
    () => props.type ?? buttonGroup?.type.value ?? "default"
  );
  const isButtonTag = computed(() => props.tag === "button");
  const isLinkTag = computed(
    () => props.tag === "a" && typeof attrs.href === "string" && attrs.href.length > 0
  );
  const isLink = computed(() => props.link);
  const isText = computed(() => !isLink.value && props.text);
  const isPlain = computed(() => !isLink.value && !isText.value && props.plain);
  const isDisabled = computed(() => props.disabled || props.loading);

// packages/components/dialog/src/use-dialog.ts L98-137
  const { dialog: globalDialogConfig } = useConfig<DialogGlobalConfig>();
  const titleId = `xy-dialog-title-${Math.random().toString(36).slice(2, 10)}`;
  const bodyId = `xy-dialog-body-${Math.random().toString(36).slice(2, 10)}`;
  const closing = ref(false);
  const downOnOverlay = ref(false);
  const localFullscreen = ref(false);
  let isClosingByBeforeClose = false;

  const dialogElement = computed(() => options.dialogContentRef.value?.dialogRef ?? null);
  const mergedConfig = computed<DialogGlobalConfig>(() => globalDialogConfig.value ?? {});
  const resolvedCloseOnClickModal = computed(
    () => props.closeOnClickModal ?? mergedConfig.value.closeOnClickModal ?? true
  );
  const resolvedCloseOnPressEscape = computed(
    () => props.closeOnPressEscape ?? mergedConfig.value.closeOnPressEscape ?? true
  );
  const resolvedLockScroll = computed(() => props.lockScroll ?? mergedConfig.value.lockScroll ?? true);
  const resolvedAlignCenter = computed(
    () => props.alignCenter ?? mergedConfig.value.alignCenter ?? false
  );
  const resolvedFullscreen = computed(() => props.fullscreen ?? localFullscreen.value);
  const resolvedDraggable = computed(
    () => (props.draggable ?? mergedConfig.value.draggable ?? false) && !resolvedFullscreen.value
  );
  const resolvedOverflow = computed(() => props.overflow ?? mergedConfig.value.overflow ?? false);
  const resolvedResizable = computed(
    () => (props.resizable ?? mergedConfig.value.resizable ?? false) && !resolvedFullscreen.value
  );
  const resolvedMaximizable = computed(
    () => props.maximizable ?? mergedConfig.value.maximizable ?? false
  );
  const resolvedStickyHeader = computed(
    () => props.stickyHeader ?? mergedConfig.value.stickyHeader ?? false
  );
  const resolvedStickyFooter = computed(
    () => props.stickyFooter ?? mergedConfig.value.stickyFooter ?? false
  );
  const resolvedTransition = computed(
    () => props.transition ?? mergedConfig.value.transition
  );

// packages/components/empty/src/empty.vue L28-41
const ns = useNamespace("empty");
const { locale } = useConfig();
const resolvedTitle = computed(() => {
  if (props.title !== undefined) {
    return props.title;
  }
  return locale.value.emptyTitle ?? "暂无数据";
});
const resolvedDescription = computed(() => {
  if (props.description !== undefined) {
    return props.description;
  }
  return locale.value.emptyDescription ?? "这里还没有可展示的内容";
});

// packages/components/popconfirm/src/popconfirm.vue L121-126
const resolvedConfirmButtonText = computed(
  () => props.confirmButtonText ?? locale.value.popconfirmConfirmButtonText ?? "确定"
);
const resolvedCancelButtonText = computed(
  () => props.cancelButtonText ?? locale.value.popconfirmCancelButtonText ?? "取消"
);

// packages/components/config-provider/__tests__/config-provider.spec.ts（全文 97 行）
import { enableAutoUnmount, mount } from "@vue/test-utils";
import { afterEach, describe, expect, it } from "vitest";
import { defineComponent, inject, nextTick } from "vue";
import { XyConfigProvider } from "../index";
import {
  configProviderKey,
  createConfigProviderContext,
  DEFAULT_NAMESPACE,
  DEFAULT_SIZE,
  DEFAULT_Z_INDEX,
  getGlobalLoadingConfig,
  getGlobalMessageConfig,
  getGlobalNotificationConfig
} from "../src/context";

enableAutoUnmount(afterEach);

describe("XyConfigProvider", () => {
  it("createConfigProviderContext 提供默认值", () => {
    const context = createConfigProviderContext();

    expect(context.namespace.value).toBe(DEFAULT_NAMESPACE);
    expect(context.zIndex.value).toBe(DEFAULT_Z_INDEX);
    expect(context.size.value).toBe(DEFAULT_SIZE);
    expect(context.locale.value).toEqual({});
    expect(context.message.value).toEqual({});
  });

  it("向子组件提供配置上下文", () => {
    const Probe = defineComponent({
      setup() {
        const context = inject(configProviderKey, null);

        return {
          context
        };
      },
      template: `
        <div class="probe">
          {{ context?.namespace.value }}|{{ context?.size.value }}|{{ context?.zIndex.value }}|{{ context?.message.value.placement }}
        </div>
      `
    });

    const wrapper = mount({
      components: {
        Probe,
        XyConfigProvider
      },
      template: `
        <xy-config-provider namespace="admin" size="lg" :z-index="3200" :message="{ placement: 'top-right' }">
          <Probe />
        </xy-config-provider>
      `
    });

    expect(wrapper.find(".probe").text()).toBe("admin|lg|3200|top-right");
  });

  it("同步注册、更新和清理全局配置", async () => {
    const wrapper = mount(XyConfigProvider, {
      props: {
        loading: {
          text: "加载中"
        },
        message: {
          placement: "top"
        },
        notification: {
          position: "bottom-right"
        }
      },
      slots: {
        default: "<div>content</div>"
      }
    });

    expect(getGlobalLoadingConfig().value.text).toBe("加载中");
    expect(getGlobalMessageConfig().value.placement).toBe("top");
    expect(getGlobalNotificationConfig().value.position).toBe("bottom-right");

    await wrapper.setProps({
      message: {
        placement: "top-right"
      }
    });
    await nextTick();

    expect(getGlobalMessageConfig().value.placement).toBe("top-right");

    wrapper.unmount();

    expect(getGlobalLoadingConfig().value).toEqual({});
    expect(getGlobalMessageConfig().value).toEqual({});
    expect(getGlobalNotificationConfig().value).toEqual({});
  });
});

// tests/types/fixtures/config-provider.ts（全文 49 行）
import type { ConfigProviderContext, ConfigProviderProps } from "xiaoye-components";
import {
  DEFAULT_NAMESPACE,
  DEFAULT_SIZE,
  DEFAULT_Z_INDEX,
  createConfigProviderContext
} from "xiaoye-components";

const props: ConfigProviderProps = {
  namespace: "admin",
  locale: {
    submit: "提交"
  },
  zIndex: 3100,
  size: "lg",
  dialog: {
    draggable: true
  },
  loading: {
    text: "加载中",
    fullscreen: true
  },
  message: {
    duration: 2500,
    placement: "top-right"
  },
  notification: {
    duration: 3200,
    position: "bottom-left"
  }
};

void props;

const context: ConfigProviderContext = createConfigProviderContext(props);

void context;
void DEFAULT_NAMESPACE;
void DEFAULT_SIZE;
void DEFAULT_Z_INDEX;


const invalidSize: ConfigProviderProps = {
  // @ts-expect-error invalid size should be rejected
  size: "xxl"
};

void invalidSize;

// Element Plus packages/components/config-provider/src/config-provider.ts（dev 分支）
import { defineComponent, renderSlot, watch } from 'vue'
import { provideGlobalConfig } from './hooks/use-global-config'
import { configProviderProps } from './config-provider-props'

import type { MessageConfigContext } from '@element-plus/components/message'

export const messageConfig: MessageConfigContext = {
  placement: 'top',
}

const ConfigProvider = defineComponent({
  name: 'ElConfigProvider',
  props: configProviderProps,

  setup(props, { slots }) {
    const config = provideGlobalConfig(props)
    watch(
      () => props.message,
      (val) => {
        Object.assign(messageConfig, config?.value?.message ?? {}, val ?? {})
      },
      { immediate: true, deep: true }
    )
    return () => renderSlot(slots, 'default', { config: config?.value })
  },
})

// Element Plus packages/components/config-provider/src/hooks/use-global-config.ts（dev 分支，节选）
// this is meant to fix global methods like `ElMessage(opts)`, this way we can inject current locale
// into the component as default injection value.
// refer to: https://github.com/element-plus/element-plus/issues/2610#issuecomment-887965266
const globalConfig = ref<ConfigProviderContext>()

export function useGlobalConfig(key?: keyof ConfigProviderContext, defaultValue = undefined) {
  const config = getCurrentInstance()
    ? inject(configProviderContextKey, globalConfig)
    : globalConfig
  if (key) {
    return computed(() => config.value?.[key] ?? defaultValue)
  } else {
    return config
  }
}

export const provideGlobalConfig = (
  config: MaybeRef<ConfigProviderContext>,
  app?: App,
  global = false
) => {
  const inSetup = !!getCurrentInstance()
  const oldConfig = inSetup ? useGlobalConfig() : undefined

  const provideFn = app?.provide ?? (inSetup ? provide : undefined)
  if (!provideFn) {
    debugWarn(
      'provideGlobalConfig',
      'provideGlobalConfig() can only be used inside setup().'
    )
    return
  }

  const context = computed(() => {
    const cfg = unref(config)
    if (!oldConfig?.value) return cfg
    return mergeConfig(oldConfig.value, cfg)
  })
  provideFn(configProviderContextKey, context)
  provideFn(
    localeContextKey,
    computed(() => context.value.locale)
  )
  provideFn(
    namespaceContextKey,
    computed(() => context.value.namespace)
  )
  provideFn(
    zIndexContextKey,
    computed(() => context.value.zIndex)
  )

  provideFn(SIZE_INJECTION_KEY, {
    size: computed(() => context.value.size || ''),
  })

  provideFn(
    emptyValuesContextKey,
    computed(() => ({
      emptyValues: context.value.emptyValues,
      valueOnClear: context.value.valueOnClear,
    }))
  )

  if (global || !globalConfig.value) {
    globalConfig.value = context.value
  }
  return context
}

const mergeConfig = (
  a: ConfigProviderContext,
  b: ConfigProviderContext
): ConfigProviderContext => {
  const keys = [...new Set([...keysOf(a), ...keysOf(b)])]
  const obj: Record<string, any> = {}
  for (const key of keys) {
    obj[key] = b[key] !== undefined ? b[key] : a[key]
  }
  return obj
}