Bits-UI 中 Tooltip 组件与自定义触发器的类型安全实践

在基于 Svelte 的组件库 Bits-UI 中，Tooltip 组件提供了一个灵活的子组件（Child Snippet）模式，允许开发者自定义触发器元素。然而，当这些触发器是带有复杂变体（variants）的预样式组件时，类型安全和属性传递会面临一些挑战。

核心问题分析

当使用类似 ShadCN 或 NextUI 风格的按钮作为 Tooltip 触发器时，开发者通常会遇到两种困境：

1. 类型丢失问题：将按钮变体属性直接放在 Tooltip 组件上会导致类型检查失效，因为 Tooltip 的 Trigger 组件并不了解按钮的具体变体类型。

2. 样式覆盖问题：直接展开子组件接收的 props 会覆盖预定义样式，因为属性展开的优先级高于组件内部定义的类名。

解决方案探讨

方案一：类型扩展

通过扩展 Tooltip 的 Props 类型，将按钮变体类型合并进去：

<script lang="ts">
  import type { ButtonVariants } from './button-types';

  type EnhancedTooltipProps = TooltipProps & {
    variant?: ButtonVariants;
    size?: ButtonVariants['size'];
    // 其他需要类型安全的属性
  };
</script>

这种方法保持了类型安全，但需要为每种可能的触发器组件创建特定的类型扩展。

方案二：属性委托模式

修改自定义组件，使其支持属性委托：

<script lang="ts">
  export let delegateProps = {};
  const merged = mergeProps($$props, delegateProps);
</script>

<button {...merged}>
  <slot />
</button>

这种方式更灵活，但需要修改所有可能作为触发器的组件。

方案三：组件封装

创建一个高阶 Tooltip 组件，内部处理属性合并：

<script lang="ts">
  let { triggerComponent: Trigger, ...props } = $props();
</script>

<Tooltip.Root>
  <Tooltip.Trigger>
    {#snippet child({ props: tooltipProps })}
      <Trigger {...mergeProps(props, tooltipProps)} />
    {/snippet}
  </Tooltip.Trigger>
</Tooltip.Root>

最佳实践建议

1. 统一触发器接口：为所有可能作为触发器的组件定义一致的属性委托接口。

2. 类型泛化：考虑使用 TypeScript 泛型使 Tooltip 组件能够适应不同类型的触发器。

3. 文档规范：在项目文档中明确说明自定义触发器的使用模式和注意事项。

4. 工具函数：创建共享的 mergeProps 工具函数，确保属性合并行为一致。

实现示例

以下是一个结合了类型安全和样式保留的实现：

<script lang="ts">
  import { mergeProps } from 'svelte-merge-props';
  import type { TooltipProps } from 'bits-ui';
  import type { ButtonProps } from './button';

  type Props = TooltipProps & {
    triggerProps?: ButtonProps;
  };

  const { triggerProps, ...tooltipProps } = $props<Props>();
</script>

<Tooltip.Root {...tooltipProps}>
  <Tooltip.Trigger>
    {#snippet child({ props: tooltipTriggerProps })}
      <Button 
        {...mergeProps(
          triggerProps || {},
          tooltipTriggerProps
        )} 
      />
    {/snippet}
  </Tooltip.Trigger>
</Tooltip.Root>

这种模式既保持了类型安全，又不会意外覆盖预定义样式，同时提供了清晰的组件接口。