4-02 · 安装器体系：withInstall、Context 捕获与幂等锁

import { XyMessage } from "xiaoye-components";

// 没有任何组件树、没有 setup()、甚至可能发生在路由守卫或 axios 拦截器里
XyMessage({ message: "保存成功", duration: 2000 });

<xy-config-provider :message="{ duration: 3000, max: 5, showClose: true }">
  <router-view />
</xy-config-provider>

// packages/xiaoye-primitives/src/utils/vue/with-install.ts（全文 81 行）
import type { App, AppContext } from "vue";

export type SFCWithInstall<T> = T & {
  install(app: App): void;
};

export type FunctionWithInstall<T> = T & {
  install(app: App): void;
  _context?: AppContext | null;
};

type AnyFunction = (...args: any[]) => any;

function toKebabCase(name: string) {
  return name
    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
    .toLowerCase();
}

export function withInstall<T>(component: T, name: string) {
  const installable = component as SFCWithInstall<T>;

  installable.install = (app: App) => {
    console.debug(`[withInstall] called for: "${name}"`);
    if (!name) {
      console.error("[withInstall] missing name, component:", component);
      return;
    }
    const aliases = Array.from(new Set([name, toKebabCase(name)]));

    aliases.forEach((alias) => {
      if (!app.component(alias)) {
        app.component(alias, installable as never);
      }
    });
  };

  return installable;
}

export function withInstallFunction<T extends AnyFunction>(fn: T, property: string) {
  const installable = fn as FunctionWithInstall<T> & Record<string, unknown>;

  installable.install = (app: App) => {
    installable._context = app._context;
    const bound = ((...args: Parameters<T>) => installable(...args, app._context)) as T;
    const boundRecord = bound as unknown as Record<string, unknown> & {
        _context?: AppContext | null;
      };

    Object.entries(installable).forEach(([key, value]) => {
      if (key === "install" || key === "_context") {
        return;
      }

      if (
        typeof value === "function" &&
        ["primary", "success", "info", "warning", "error"].includes(key)
      ) {
        boundRecord[key] = (...args: unknown[]) => (value as AnyFunction)(...args, app._context);
        return;
      }

      if (typeof value === "function" && key === "withContext") {
        boundRecord[key] = (appContext?: AppContext | null) =>
          (value as AnyFunction)(appContext ?? app._context);
        return;
      }

      boundRecord[key] = value;
    });

    boundRecord._context = app._context;
    app.config.globalProperties[property] = bound as never;
  };

  installable._context = null;

  return installable as FunctionWithInstall<T>;
}

installable._context = app._context;

const bound = ((...args: Parameters<T>) => installable(...args, app._context)) as T;

export type MessageTypedFn = (
  options?: MessageParams,
  appContext?: AppContext | null
) => MessageHandler;

app.config.globalProperties[property] = bound as never;

export const XyMessage = withInstallFunction(message, "$message");
export const XyMessageService = XyMessage;

// packages/components/button/index.ts（全文 25 行）
import Button from "./src/button.vue";
import ButtonGroup from "./src/button-group.vue";
import type {
  ButtonClickHandler,
  ButtonInstance,
  ButtonProps,
  ButtonNativeType,
  ButtonType
} from "./src/button";
import type { ButtonGroupDirection, ButtonGroupProps } from "./src/button-group";
import { withInstall } from "xiaoye-primitives";

export type {
  ButtonClickHandler,
  ButtonGroupDirection,
  ButtonGroupProps,
  ButtonInstance,
  ButtonNativeType,
  ButtonProps,
  ButtonType
};

export const XyButton = withInstall(Button, "xy-button");
export const XyButtonGroup = withInstall(ButtonGroup, "xy-button-group");
export default XyButton;

// packages/components/loading/index.ts（全文 44 行）
import type { App, AppContext, Directive } from "vue";
import vLoading from "./src/directive";
import type { ElementLoading, LoadingBinding } from "./src/directive";
import type { LoadingInstance } from "./src/loading";
import { XyLoadingService } from "./src/service";
import type { LoadingService } from "./src/service";
import type {
  LoadingGlobalConfig,
  LoadingOptions,
  LoadingOptionsResolved,
  LoadingParentElement,
  LoadingText,
  LoadingUpdatableOptions
} from "./src/types";

export type {
  ElementLoading,
  LoadingBinding,
  LoadingGlobalConfig,
  LoadingInstance,
  LoadingOptions,
  LoadingOptionsResolved,
  LoadingParentElement,
  LoadingService,
  LoadingText,
  LoadingUpdatableOptions
};

export const XyLoading = {
  install(app: App) {
    XyLoadingService._context = app._context;
    (
      vLoading as Directive<ElementLoading, LoadingBinding> & { _context: AppContext | null }
    )._context = app._context;
    app.directive("loading", vLoading as Directive<ElementLoading, LoadingBinding>);
    app.config.globalProperties.$loading = XyLoadingService;
  },
  directive: vLoading,
  service: XyLoadingService
};

export { vLoading, vLoading as XyLoadingDirective, XyLoadingService };

export default XyLoading;

// packages/components/loading/src/directive.ts L29-34
function getAppContext(binding: DirectiveBinding<LoadingBinding>) {
  return (
    (binding.instance as { $?: { appContext?: AppContext } } | null)?.$?.appContext ??
    vLoading._context
  );
}

// packages/components/loading/src/directive.ts L112-114
type LoadingDirective = ObjectDirective<ElementLoading, LoadingBinding> & {
  _context: AppContext | null;
};

// packages/components/loading/src/directive.ts L154
vLoading._context = null;

// packages/components/loading/src/service.ts L540-556（节选）
function openLoading(
  options: LoadingOptions = {},
  context?: AppContext | null,
  trackAsService = true
) {
  if (!isClient()) {
    warnOnce("XyLoadingService", "XyLoadingService 仅支持在浏览器环境中使用。");
    return createNoopHandle();
  }

  const appContext = context ?? XyLoadingService._context;

// packages/components/index.ts L1-42
import type { App, Plugin } from "vue";
import "./style.css";
import * as XiaoyeComponentExports from "./exports";
import { installableComponentExportNames } from "./component-manifest";

export type { ComponentSize, ComponentStatus, SelectOption } from "xiaoye-primitives";
export * from "./exports";

const INSTALL_KEY = Symbol.for("xiaoye-components:installed");

function isInstallableExport(value: unknown): value is Plugin {
  return (
    (typeof value === "function" || typeof value === "object") &&
    value !== null &&
    "install" in value &&
    typeof (value as { install?: unknown }).install === "function"
  );
}

const installableExports = Array.from(
  new Set(
    installableComponentExportNames
      .map((name) => XiaoyeComponentExports[name as keyof typeof XiaoyeComponentExports])
      .filter(isInstallableExport)
  )
) as Plugin[];

export function install(app: App) {
  const appWithInstallFlag = app as App & {
    [INSTALL_KEY]?: boolean;
  };

  if (appWithInstallFlag[INSTALL_KEY]) {
    return;
  }

  appWithInstallFlag[INSTALL_KEY] = true;

  installableExports.forEach((component) => {
    app.use(component);
  });
}

// 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/xiaoye-primitives/src/composables/use-config.ts L28-55
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/components/config-provider/src/config-provider.vue L21-49 -->
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
  }
);

<!-- packages/components/config-provider/src/config-provider.vue L61-86 -->
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);
});

// packages/components/config-provider/src/context.ts L56-83
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];
}

// packages/components/config-provider/src/context.ts L123-144
export function registerGlobalMessageConfig(id: string, value: MessageGlobalConfig) {
  globalMessageConfigRegistry.set(id, value);
  syncGlobalMessageConfigState();
}

export function updateGlobalMessageConfig(id: string, value: MessageGlobalConfig) {
  globalMessageConfigRegistry.set(id, value);
  syncGlobalMessageConfigState();
}

export function unregisterGlobalMessageConfig(id: string) {
  globalMessageConfigRegistry.delete(id);
  syncGlobalMessageConfigState();
}

export function getGlobalMessageConfig() {
  return globalMessageConfigState;
}

export function getGlobalMessageConfigCount() {
  return globalMessageConfigRegistry.size;
}

// 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/message/src/method.ts L181-195
const normalizedPlacement = normalizePlacement(
  hasOwn(options, "placement") ? options.placement : globalMessageConfig.placement
);

const placementMax = globalMessageConfig.maxByPlacement?.[normalizedPlacement];
const normalized = {
  ...messageDefaults,
  ...options,
  appendTo,
  placement: normalizedPlacement,
  targetKey: resolveTargetKey(appendTo),
  max: normalizeMax(
    hasOwn(options, "max") ? options.max : (placementMax ?? globalMessageConfig.max)
  )
};

// packages/components/message/src/method.ts L434-447
  const vnode = createVNode(
    MessageConstructor,
    props as MessageCreateProps & Record<string, unknown>
  );
  vnode.appContext = context || message._context;
  render(vnode, container);

  const element = container.firstElementChild;

  if (!element) {
    throw new Error("XyMessage 挂载失败：未生成可用的消息节点。");
  }

  options.appendTo.appendChild(element);

// packages/components/message/src/method.ts L521-535
function bindMessageContext(appContext: AppContext | null): Message {
  const bound = ((options?: MessageParams) => message(options, appContext)) as Message;

  messageTypes.forEach((type) => {
    bound[type] = (options?: MessageParams) => message[type](options, appContext);
  });

  bound.closeAll = message.closeAll;
  bound.closeAllByPlacement = message.closeAllByPlacement;
  bound.getState = message.getState;
  bound.withContext = message.withContext;
  bound._context = appContext;

  return bound;
}

// packages/components/message/src/message.ts L167-175
export interface Message extends MessageFn {
  primary: MessageTypedFn;
  success: MessageTypedFn;
  info: MessageTypedFn;
  warning: MessageTypedFn;
  error: MessageTypedFn;
  withContext: (appContext?: AppContext | null) => Message;
  _context: AppContext | null;
}

// 多 Provider 场景下显式指定上下文（resolveMessageConfig 警告里给的出路）
const scopedMessage = XyMessage.withContext(detailPageInstance.appContext);
scopedMessage.success("已提交"); // 吃 detailPage 所在 app 的配置

// packages/components/message/src/method.ts L669-670
message.withContext = (appContext: AppContext | null = null) => bindMessageContext(appContext);
message._context = null;

// EP use-global-config.ts（行为摘要）
const provideFn = app?.provide ?? (inSetup ? provide : undefined);
if (!provideFn) {
  debugWarn("provideGlobalConfig", "provideGlobalConfig() can only be used inside setup().");
  return;
}
provideFn(configProviderContextKey, context);