feat(bubble): add provider-level box and content attributes

gene9831 · gene9831 · commit 8e20fce24844 · 2026-04-23T17:54:47.000+08:00
diff --git a/docs/demos/bubble/provider-attributes.vue b/docs/demos/bubble/provider-attributes.vue
@@ -0,0 +1,128 @@
+<template>
+  <div class="demo">
+    <p class="desc">
+      外层气泡容器是 Box，里面的每一段内容是 Content。点击下方任意 Box 或 Content，可查看该 DOM 节点上的真实 data-*
+      属性。
+    </p>
+
+    <div class="preview" @click="handleInspect">
+      <tr-bubble-provider :box-attributes="boxAttributes" :content-attributes="contentAttributes">
+        <tr-bubble-list :messages="messages" :role-configs="roleConfigs" content-render-mode="split"></tr-bubble-list>
+      </tr-bubble-provider>
+    </div>
+
+    <pre class="output">{{ output }}</pre>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type {
+  BubbleBoxAttributesConfig,
+  BubbleContentAttributesConfig,
+  BubbleMessage,
+  BubbleRoleConfig,
+} from '@opentiny/tiny-robot'
+import { TrBubbleList, TrBubbleProvider } from '@opentiny/tiny-robot'
+import { IconAi, IconUser } from '@opentiny/tiny-robot-svgs'
+import { h, ref } from 'vue'
+
+const messages: BubbleMessage[] = [
+  { role: 'user', content: '请总结今天会议。' },
+  {
+    role: 'assistant',
+    content: [
+      { type: 'text', text: '重点一：支持 BubbleProvider 统一注入 attributes。' },
+      { type: 'text', text: '重点二：支持按消息上下文动态生成 attributes。' },
+    ],
+  },
+]
+
+const roleConfigs: Record<string, BubbleRoleConfig> = {
+  assistant: {
+    avatar: h(IconAi, { style: { fontSize: '28px' } }),
+  },
+  user: {
+    avatar: h(IconUser, { style: { fontSize: '28px' } }),
+    placement: 'end',
+  },
+}
+
+const boxAttributes: BubbleBoxAttributesConfig = (messages, content, contentIndex) => ({
+  'data-demo-kind': 'box',
+  'data-role': messages[0]?.role || 'unknown',
+  'data-message-count': messages.length,
+  'data-content-type': content?.type || 'unknown',
+  'data-content-index': contentIndex ?? 'unknown',
+})
+
+const contentAttributes: BubbleContentAttributesConfig = (message, content, contentIndex) => ({
+  'data-demo-kind': 'content',
+  'data-role': message.role || 'unknown',
+  'data-content-type': content.type,
+  'data-content-index': contentIndex,
+})
+
+const output = ref('点击预览区域中的节点后，这里会显示该节点上的 data-* 属性。')
+
+const handleInspect = (event: MouseEvent) => {
+  const target = event.target as HTMLElement | null
+  const element = target?.closest('[data-demo-kind]') as HTMLElement | null
+
+  if (!element) {
+    return
+  }
+
+  const dataAttributes = Object.fromEntries(
+    element
+      .getAttributeNames()
+      .filter((name) => name.startsWith('data-') && !name.startsWith('data-v-'))
+      .map((name) => [name, element.getAttribute(name)]),
+  )
+
+  output.value = JSON.stringify(dataAttributes, null, 2)
+}
+</script>
+
+<style scoped>
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.desc {
+  margin: 0;
+  font-size: 12px;
+  color: #666;
+}
+
+.preview {
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider, #ddd);
+  background: var(--vp-c-bg-soft, #f6f6f7);
+}
+
+.preview :deep([data-demo-kind]) {
+  cursor: pointer;
+}
+
+.preview :deep([data-demo-kind='box']) {
+  outline: 1px dashed #f59e0b;
+}
+
+.preview :deep([data-demo-kind='content']) {
+  outline: 1px solid #60a5fa;
+}
+
+.output {
+  margin: 0;
+  padding: 12px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--vp-c-text-1, #213547);
+  background: var(--vp-c-bg-soft, #f5f5f5);
+  border: 1px solid var(--vp-c-divider, #ddd);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+</style>
diff --git a/docs/src/components/bubble.md b/docs/src/components/bubble.md
@@ -1,5 +1,5 @@
 ---
-outline: [1, 3]
+outline: [1, 4]
 ---
 
 # Bubble 气泡组件
@@ -210,6 +210,20 @@ Bubble 组件采用渲染器架构，支持灵活的内容渲染和自定义扩
 
 <demo vue="../../demos/bubble/provider-renderer.vue" />
 
+#### 通过 BubbleProvider 统一注入 attributes
+
+除了配置渲染器，`BubbleProvider` 还支持通过 `box-attributes` 和 `content-attributes` 为 Box / Content 统一注入 attributes。
+
+- `box-attributes` 的作用域是一个 Box，对应参数为 `(messages, content, contentIndex)`
+- `content-attributes` 的作用域是单个 Content，对应参数为 `(message, content, contentIndex)`
+- 两个属性都支持传入静态对象，或返回 attributes 的函数
+
+适合用于统一添加 `data-*` 标记、埋点字段、测试选择器等通用属性，而不需要依赖所有消息都匹配某个自定义渲染器。
+
+<demo vue="../../demos/bubble/provider-attributes.vue" />
+
+> `BubbleProvider` 注入的 attributes 会在对应的 Box / Content 上统一生效；如果某个匹配规则本身也配置了 `attributes`，会在 Provider attributes 的基础上继续合并。
+
 #### 渲染器匹配优先级
 
 匹配规则可以使用 `priority` 属性来设置优先级，值越小优先级越高。系统提供了以下优先级常量：
@@ -401,6 +415,8 @@ Bubble 组件支持通过 `state` 属性存储 UI 相关的数据，并通过 `s
 | ------------------------- | --------------------------------------- | ------ | ---------------------------------------------------------- |
 | `boxRendererMatches`      | `BubbleBoxRendererMatch[]`              | -      | Box 渲染器匹配规则数组                                     |
 | `contentRendererMatches`  | `BubbleContentRendererMatch[]`          | -      | 内容渲染器匹配规则数组                                     |
+| `boxAttributes`           | `BubbleBoxAttributesConfig`             | -      | 统一注入到 Box 的 attributes，支持静态对象或 resolver 函数 |
+| `contentAttributes`       | `BubbleContentAttributesConfig`         | -      | 统一注入到 Content 的 attributes，支持静态对象或 resolver 函数 |
 | `fallbackBoxRenderer`     | `Component<BubbleBoxRendererProps>`     | -      | 默认 box 渲染器（当无法匹配到合适的渲染器时使用）          |
 | `fallbackContentRenderer` | `Component<BubbleContentRendererProps>` | -      | 默认内容渲染器（当无法匹配到合适的渲染器时使用）           |
 | `store`                   | `Record<string, unknown>`               | -      | 全局状态存储，用于在 BubbleList 和 Bubble 组件之间共享数据 |
diff --git a/packages/components/src/bubble/BubbleBoxWrapper.vue b/packages/components/src/bubble/BubbleBoxWrapper.vue
@@ -15,10 +15,10 @@ const renderer = useBubbleBoxRenderer(() => props.messages, props.contentIndex)
 <template>
   <component
     :is="renderer.renderer"
+    v-bind="renderer.attributes"
     :data-role="props.role"
     :data-placement="props.placement"
     :data-shape="props.shape"
-    v-bind="renderer.attributes"
   >
     <slot />
   </component>
diff --git a/packages/components/src/bubble/BubbleContentWrapper.vue b/packages/components/src/bubble/BubbleContentWrapper.vue
@@ -1,10 +1,16 @@
 <script setup lang="ts">
+import { computed } from 'vue'
 import { setupBubbleStateChangeFn, useBubbleContentRenderer } from './composables'
 import type { BubbleContentRendererProps } from './index.type'
 
 const props = defineProps<BubbleContentRendererProps>()
 
 const renderer = useBubbleContentRenderer(() => props.message, props.contentIndex)
+const componentProps = computed(() => ({
+  ...renderer.value.attributes,
+  message: props.message,
+  contentIndex: props.contentIndex,
+}))
 
 const emit = defineEmits<{
   (e: 'state-change', payload: { key: string; value: unknown; contentIndex: number }): void
@@ -22,5 +28,5 @@ setupBubbleStateChangeFn(handleStateChange)
 </script>
 
 <template>
-  <component :is="renderer" v-bind="props"></component>
+  <component :is="renderer.renderer" v-bind="componentProps"></component>
 </template>
diff --git a/packages/components/src/bubble/BubbleProvider.vue b/packages/components/src/bubble/BubbleProvider.vue
@@ -33,8 +33,16 @@ const fallbackContentRenderer = computed(() => {
   return props.fallbackContentRenderer || defaultFallbackContentRenderer
 })
 
-setupBubbleBoxRenderer({ boxRendererMatches, fallbackBoxRenderer })
-setupBubbleContentRenderer({ contentRendererMatches, fallbackContentRenderer })
+setupBubbleBoxRenderer({
+  boxRendererMatches,
+  boxAttributes: () => props.boxAttributes,
+  fallbackBoxRenderer,
+})
+setupBubbleContentRenderer({
+  contentRendererMatches,
+  contentAttributes: () => props.contentAttributes,
+  fallbackContentRenderer,
+})
 </script>
 
 <template>
diff --git a/packages/components/src/bubble/composables/useBubbleBoxRenderer.ts b/packages/components/src/bubble/composables/useBubbleBoxRenderer.ts
@@ -1,22 +1,27 @@
 import type { Component, ComputedRef, MaybeRefOrGetter } from 'vue'
 import { computed, inject, provide, toValue } from 'vue'
 import {
+  BUBBLE_BOX_ATTRIBUTES_KEY,
   BUBBLE_BOX_FALLBACK_RENDERER_KEY,
   BUBBLE_BOX_PROP_FALLBACK_RENDERER_KEY,
   BUBBLE_BOX_RENDERER_MATCHES_KEY,
 } from '../constants'
-import type { BubbleBoxRendererMatch, BubbleMessage } from '../index.type'
+import type { BubbleAttributes, BubbleBoxAttributesConfig, BubbleBoxRendererMatch, BubbleMessage } from '../index.type'
 import { defaultBoxRendererMatches, defaultFallbackBoxRenderer } from '../renderers/defaultRenderers'
 import { useContentResolver } from './useContentResolver'
 
 export function setupBubbleBoxRenderer(renderers: {
   boxRendererMatches?: MaybeRefOrGetter<Array<BubbleBoxRendererMatch>>
+  boxAttributes?: MaybeRefOrGetter<BubbleBoxAttributesConfig | undefined>
   fallbackBoxRenderer?: MaybeRefOrGetter<Component>
 }): void {
-  const { boxRendererMatches, fallbackBoxRenderer } = renderers
+  const { boxRendererMatches, boxAttributes, fallbackBoxRenderer } = renderers
   if (boxRendererMatches) {
     provide(BUBBLE_BOX_RENDERER_MATCHES_KEY, boxRendererMatches)
   }
+  if (boxAttributes) {
+    provide(BUBBLE_BOX_ATTRIBUTES_KEY, boxAttributes)
+  }
   if (fallbackBoxRenderer) {
     provide(BUBBLE_BOX_FALLBACK_RENDERER_KEY, fallbackBoxRenderer)
   }
@@ -40,9 +45,10 @@ export function useBubbleBoxRenderer(
   contentIndex?: number,
 ): ComputedRef<{
   renderer: Component
-  attributes?: Record<string, string>
+  attributes?: BubbleAttributes
 }> {
   const boxRendererMatches = inject(BUBBLE_BOX_RENDERER_MATCHES_KEY, defaultBoxRendererMatches)
+  const boxAttributes = inject(BUBBLE_BOX_ATTRIBUTES_KEY, undefined)
   const fallbackBoxRenderer = inject(BUBBLE_BOX_FALLBACK_RENDERER_KEY, undefined)
   const propFallbackBoxRenderer = inject(BUBBLE_BOX_PROP_FALLBACK_RENDERER_KEY, undefined)
   const contentResolver = useContentResolver()
@@ -71,19 +77,30 @@ export function useBubbleBoxRenderer(
     const msgs = toValue(messages)
 
     const { content, index } = getContentAndIndex(msgs)
+    const resolvedBoxAttributes = (() => {
+      const attrs = toValue(boxAttributes)
+      if (!attrs) {
+        return undefined
+      }
+      return typeof attrs === 'function' ? attrs(msgs, content, index) : attrs
+    })()
 
     const match = toValue(boxRendererMatches).find((match) => match.find(msgs, content, index))
 
     if (match) {
       return {
         renderer: match.renderer,
-        attributes: match.attributes,
+        attributes: {
+          ...resolvedBoxAttributes,
+          ...match.attributes,
+        },
       }
     }
 
     // Priority: prop-level > provider-level > default
     return {
       renderer: toValue(propFallbackBoxRenderer) || toValue(fallbackBoxRenderer) || defaultFallbackBoxRenderer,
+      attributes: resolvedBoxAttributes,
     }
   })
 }
diff --git a/packages/components/src/bubble/composables/useBubbleContentRenderer.ts b/packages/components/src/bubble/composables/useBubbleContentRenderer.ts
@@ -1,22 +1,33 @@
 import type { Component, ComputedRef, MaybeRefOrGetter } from 'vue'
 import { computed, inject, provide, toValue } from 'vue'
 import {
+  BUBBLE_CONTENT_ATTRIBUTES_KEY,
   BUBBLE_CONTENT_FALLBACK_RENDERER_KEY,
   BUBBLE_CONTENT_PROP_FALLBACK_RENDERER_KEY,
   BUBBLE_CONTENT_RENDERER_MATCHES_KEY,
 } from '../constants'
-import type { BubbleContentRendererMatch, BubbleMessage, ChatMessageContentItem } from '../index.type'
+import type {
+  BubbleAttributes,
+  BubbleContentAttributesConfig,
+  BubbleContentRendererMatch,
+  BubbleMessage,
+  ChatMessageContentItem,
+} from '../index.type'
 import { defaultContentRendererMatches, defaultFallbackContentRenderer } from '../renderers/defaultRenderers'
 import { useContentResolver } from './useContentResolver'
 
 export function setupBubbleContentRenderer(renderers: {
   contentRendererMatches?: MaybeRefOrGetter<Array<BubbleContentRendererMatch>>
+  contentAttributes?: MaybeRefOrGetter<BubbleContentAttributesConfig | undefined>
   fallbackContentRenderer?: MaybeRefOrGetter<Component>
 }): void {
-  const { contentRendererMatches, fallbackContentRenderer } = renderers
+  const { contentRendererMatches, contentAttributes, fallbackContentRenderer } = renderers
   if (contentRendererMatches) {
     provide(BUBBLE_CONTENT_RENDERER_MATCHES_KEY, contentRendererMatches)
   }
+  if (contentAttributes) {
+    provide(BUBBLE_CONTENT_ATTRIBUTES_KEY, contentAttributes)
+  }
   if (fallbackContentRenderer) {
     provide(BUBBLE_CONTENT_FALLBACK_RENDERER_KEY, fallbackContentRenderer)
   }
@@ -38,8 +49,12 @@ export function setupBubblePropContentRenderer(renderers: {
 export function useBubbleContentRenderer(
   message: MaybeRefOrGetter<BubbleMessage>,
   contentIndex: number,
-): ComputedRef<Component> {
+): ComputedRef<{
+  renderer: Component
+  attributes?: BubbleAttributes
+}> {
   const contentRendererMatches = inject(BUBBLE_CONTENT_RENDERER_MATCHES_KEY, defaultContentRendererMatches)
+  const contentAttributes = inject(BUBBLE_CONTENT_ATTRIBUTES_KEY, undefined)
   const fallbackContentRenderer = inject(BUBBLE_CONTENT_FALLBACK_RENDERER_KEY, undefined)
   const propFallbackContentRenderer = inject(BUBBLE_CONTENT_PROP_FALLBACK_RENDERER_KEY, undefined)
   const contentResolver = useContentResolver()
@@ -50,12 +65,29 @@ export function useBubbleContentRenderer(
     const content = Array.isArray(resolvedContent)
       ? (resolvedContent.at(contentIndex ?? 0) as ChatMessageContentItem)
       : { type: 'text', text: resolvedContent || '' }
+    const resolvedProviderAttributes = (() => {
+      const attrs = toValue(contentAttributes)
+      if (!attrs) {
+        return undefined
+      }
+      return typeof attrs === 'function' ? attrs(msg, content, contentIndex) : attrs
+    })()
     const match = toValue(contentRendererMatches).find((match) => match.find(msg, content, contentIndex))
     if (match) {
-      return match.renderer
+      return {
+        renderer: match.renderer,
+        attributes: {
+          ...resolvedProviderAttributes,
+          ...match.attributes,
+        },
+      }
     }
 
     // Priority: prop-level > provider-level > default
-    return toValue(propFallbackContentRenderer) || toValue(fallbackContentRenderer) || defaultFallbackContentRenderer
+    return {
+      renderer:
+        toValue(propFallbackContentRenderer) || toValue(fallbackContentRenderer) || defaultFallbackContentRenderer,
+      attributes: resolvedProviderAttributes,
+    }
   })
 }
diff --git a/packages/components/src/bubble/constants.ts b/packages/components/src/bubble/constants.ts
diff --git a/packages/components/src/bubble/index.type.ts b/packages/components/src/bubble/index.type.ts
