feat(components): support appendTo for template select

Author: SonyLeo

docs/src/components/sender.md

@@ -78,6 +78,7 @@ TrSender.mention(mentions, '@')
 TrSender.suggestion(suggestions) // 不过滤
 TrSender.suggestion(suggestions, { filterFn: customFilter }) // 自定义过滤
 TrSender.template(templates)
+TrSender.template(templates, { appendTo: '.chat-window' })
 
 // 标准配置（用于复杂场景）
 TrSender.Mention.configure({ items: mentions, char: '@', allowSpaces: false })
@@ -310,14 +311,16 @@ Sender 提供了多个插槽位置，方便扩展功能：
 ```typescript
 // 便捷函数
 TrSender.template(templates)
+TrSender.template(templates, { appendTo: '.chat-window' })
 
 // 标准配置
-TrSender.Template.configure({ items: templates })
+TrSender.Template.configure({ items: templates, appendTo: '.chat-window' })
 ```
 
 | 配置项  | 类型                                      | 说明         |
 | ------- | ----------------------------------------- | ------------ |
 | `items` | `TemplateItem[]` \| `Ref<TemplateItem[]>` | 模板数据列表 |
+| `appendTo` | `string` \| `HTMLElement` | Template Select 下拉菜单的挂载目标，默认挂载到 `body` |
 
 #### Mention
 

packages/components/src/sender/extensions/template/extension.ts

@@ -16,7 +16,7 @@ export const Template = Extension.create<TemplateOptions>({
   name: EXTENSION_NAMES.TEMPLATE,
 
   addExtensions() {
-    return [TemplateBlock.configure(this.options), TemplateSelect]
+    return [TemplateBlock.configure(this.options), TemplateSelect.configure(this.options)]
   },
 
   // 添加命令（统一命令入口）

packages/components/src/sender/extensions/template/select/extension.ts

@@ -4,15 +4,15 @@
 
 import { Node, mergeAttributes } from '@tiptap/core'
 import { VueNodeViewRenderer } from '@tiptap/vue-3'
-import type { TemplateSelectAttrs } from '../types'
+import type { TemplateOptions, TemplateSelectAttrs } from '../types'
 import TemplateSelectView from './template-select-view.vue'
 import { selectDropdownStatePlugin, selectZeroWidthPlugin, selectKeyboardPlugin } from './plugins'
 import { NODE_TYPE_NAMES } from '../../constants'
 
 /**
  * TemplateSelect 节点定义
  */
-export const TemplateSelect = Node.create<Record<string, unknown>>({
+export const TemplateSelect = Node.create<TemplateOptions>({
   name: NODE_TYPE_NAMES.TEMPLATE_SELECT,
 
   // 节点配置

packages/components/src/sender/extensions/template/select/template-select-view.vue

@@ -7,6 +7,7 @@ import { IconArrowDown } from '@opentiny/tiny-robot-svgs'
 import { TemplateSelectDropdownPluginKey } from './plugins'
 import type { SelectOption } from '../types'
 import { closeAllDropdowns, setupClickOutside } from './dropdown-manager'
+import { useTeleportTarget } from '../../../../shared/composables'
 
 interface NodeAttrs {
   id: string
@@ -21,6 +22,11 @@ interface Props {
   }
   updateAttributes: (attrs: Record<string, unknown>) => void
   editor: Editor
+  extension: {
+    options: {
+      appendTo?: string | HTMLElement
+    }
+  }
 }
 
 const props = defineProps<Props>()
@@ -32,6 +38,11 @@ const triggerRef = ref<HTMLElement>()
 const dropdownRef = ref<HTMLElement>()
 let cleanupClickOutside: (() => void) | null = null
 let cleanupAutoUpdate: (() => void) | null = null
+const teleportTarget = useTeleportTarget(triggerRef, props.extension.options.appendTo)
+const isCustomTeleportTarget = computed(() => {
+  const target = teleportTarget.value
+  return target instanceof HTMLElement && target !== document.body
+})
 
 // 计算属性
 const selectedOption = computed(() => {
@@ -136,7 +147,8 @@ const updatePosition = () => {
 
     computePosition(triggerRef.value, dropdownRef.value, {
       placement: 'bottom-start',
-      strategy: 'fixed', // 使用 fixed 定位策略，相对于视口
+      // 自定义挂载目标使用 absolute 定位
+      strategy: isCustomTeleportTarget.value ? 'absolute' : 'fixed', // 使用 fixed 定位策略，相对于视口
       middleware: [offset(4), flip(), shift({ padding: 8 })],
     }).then(({ x, y }) => {
       if (dropdownRef.value) {
@@ -252,8 +264,13 @@ onUnmounted(() => {
     </span>
     <span contenteditable="false" class="template-select__suffix">&#8203;</span>
 
-    <Teleport to="body">
-      <div v-if="showDropdown" ref="dropdownRef" class="template-select__dropdown">
+    <Teleport :to="teleportTarget">
+      <div
+        v-if="showDropdown"
+        ref="dropdownRef"
+        class="template-select__dropdown"
+        :class="{ 'is-absolute': isCustomTeleportTarget }"
+      >
         <div
           v-for="(option, index) in node.attrs.options"
           :key="option.value"
@@ -338,6 +355,10 @@ onUnmounted(() => {
   box-shadow: var(--tr-sender-template-select-dropdown-shadow);
   padding: 6px;
 
+  &.is-absolute {
+    position: absolute;
+  }
+
   &::-webkit-scrollbar {
     width: 8px;
   }

packages/components/src/sender/extensions/template/types.ts

@@ -85,6 +85,11 @@ export interface TemplateOptions {
    * HTML 属性
    */
   HTMLAttributes?: Record<string, unknown>
+
+  /**
+   * 下拉菜单挂载目标
+   */
+  appendTo?: string | HTMLElement
 }
 
 // ===== 模块扩展声明 =====

packages/test/src/sender/helpers/template-helper.ts

@@ -80,6 +80,29 @@ export function createTemplateTestHelper(page: Page) {
       await expect(this.getTemplates()).toHaveCount(3)
     },
 
+    /**
+     * 设置模板选择器
+     */
+    async setSelectTemplate() {
+      await page.click(selectors.setTemplateSelectBtn)
+      await expect(page.locator(selectors.templateSelect)).toBeVisible()
+    },
+
+    /**
+     * 获取模板选择器
+     */
+    getTemplateSelect() {
+      return page.locator(selectors.templateSelect)
+    },
+
+    /**
+     * 打开模板选择器
+     */
+    async openTemplateSelect() {
+      await this.getTemplateSelect().locator(selectors.templateSelectTrigger).click()
+      await expect(page.locator(selectors.templateSelectDropdown)).toBeVisible()
+    },
+
     /**
      * 清空模板
      */

packages/test/src/sender/index.vue

@@ -40,6 +40,7 @@ const enableMention = ref(false)
 const enableTemplate = ref(false)
 const enableSuggestion = ref(false)
 const templateData = ref<TemplateItem[]>([])
+const templateAppendTo = ref<string | undefined>()
 const attachmentsSourceMounted = ref(false)
 const senderAttachmentItems = ref<Attachment[]>([
   {
@@ -54,7 +55,7 @@ const mode = computed(() => (isMultipleMode.value ? 'multiple' : 'single'))
 const size = computed(() => (isSmallSize.value ? 'small' : 'normal'))
 
 const componentKey = computed(() => {
-  return `${enableMention.value}-${enableTemplate.value}-${enableSuggestion.value}`
+  return `${enableMention.value}-${enableTemplate.value}-${enableSuggestion.value}-${templateAppendTo.value || 'body'}`
 })
 
 const handleModeChange = () => {
@@ -154,6 +155,27 @@ const clearTemplate = () => {
   result.value = '已清空模板'
 }
 
+const setTemplateSelect = () => {
+  templateData.value = [
+    { type: 'text', content: '模型：' },
+    {
+      type: 'select',
+      content: '',
+      placeholder: '请选择模型',
+      options: [
+        { label: 'GPT-4', value: 'gpt-4' },
+        { label: 'DeepSeek', value: 'deepseek' },
+      ],
+    },
+  ]
+  result.value = '已设置模板选择器'
+}
+
+const toggleTemplateAppendTo = () => {
+  templateAppendTo.value = templateAppendTo.value ? undefined : '#template-select-teleport-target'
+  result.value = templateAppendTo.value ? '模板选择器挂载到自定义容器' : '模板选择器挂载到 body'
+}
+
 const mentions = ref<MentionItem[]>([
   {
     label: '小小画家',
@@ -188,7 +210,7 @@ const extensions = computed(() => {
     exts.push(Sender.mention(mentions))
   }
   if (enableTemplate.value) {
-    exts.push(Sender.template(templateData))
+    exts.push(Sender.template(templateData, { appendTo: templateAppendTo.value }))
   }
   if (enableSuggestion.value) {
     exts.push(Sender.suggestion(suggestions))
@@ -331,6 +353,10 @@ onBeforeUnmount(() => {
             <label>template:</label>
             <tiny-switch data-testid="toggle-template-btn" v-model="enableTemplate"></tiny-switch>
           </div>
+          <div class="control-item">
+            <label>template appendTo:</label>
+            <button data-testid="toggle-template-append-to-btn" @click="toggleTemplateAppendTo">切换</button>
+          </div>
           <div class="control-item">
             <label>suggestion:</label>
             <tiny-switch data-testid="toggle-suggestion-btn" v-model="enableSuggestion"></tiny-switch>
@@ -356,6 +382,7 @@ onBeforeUnmount(() => {
           <button data-testid="set-template-simple-btn" @click="setTemplateSimple">简单模板</button>
           <button data-testid="set-template-empty-btn" @click="setTemplateEmpty">空模板块</button>
           <button data-testid="set-template-multiple-btn" @click="setTemplateMultiple">多模板块</button>
+          <button data-testid="set-template-select-btn" @click="setTemplateSelect">模板选择器</button>
           <button data-testid="clear-template-btn" @click="clearTemplate">清空模板</button>
         </div>
       </fieldset>
@@ -396,6 +423,8 @@ onBeforeUnmount(() => {
         <button data-testid="custom-footer-btn" @click="handleCustomAction">自定义按钮</button>
       </template>
     </Sender>
+
+    <div id="template-select-teleport-target" data-testid="template-select-teleport-target"></div>
   </div>
 </template>
 
@@ -443,4 +472,8 @@ onBeforeUnmount(() => {
   margin: 0;
   word-break: break-all;
 }
+
+#template-select-teleport-target {
+  position: relative;
+}
 </style>

packages/test/src/sender/selectors.ts

@@ -25,6 +25,7 @@ export const SENDER_SELECTORS = {
 
   toggleMentionBtn: '[data-testid="toggle-mention-btn"]',
   toggleTemplateBtn: '[data-testid="toggle-template-btn"]',
+  toggleTemplateAppendToBtn: '[data-testid="toggle-template-append-to-btn"]',
   toggleSuggestionBtn: '[data-testid="toggle-suggestion-btn"]',
 
   sender: '[data-testid="test-sender"]',
@@ -55,8 +56,14 @@ export const SENDER_SELECTORS = {
   setTemplateSimpleBtn: '[data-testid="set-template-simple-btn"]',
   setTemplateEmptyBtn: '[data-testid="set-template-empty-btn"]',
   setTemplateMultipleBtn: '[data-testid="set-template-multiple-btn"]',
+  setTemplateSelectBtn: '[data-testid="set-template-select-btn"]',
   clearTemplateBtn: '[data-testid="clear-template-btn"]',
 
+  templateSelect: '.template-select',
+  templateSelectTrigger: '.template-select__trigger',
+  templateSelectDropdown: '.template-select__dropdown',
+  templateSelectOption: '.template-select__option',
+
   suggestionList: '.suggestion-list',
   suggestionItem: '.suggestion-list__item',
   suggestionHighlighted: '.suggestion-list__item.highlighted',

packages/test/src/sender/specs/template/append-to.spec.ts

@@ -0,0 +1,52 @@
+import { test, expect, type Page } from '@playwright/test'
+import { createSenderTestHelper } from '../../helpers'
+import { createTemplateTestHelper } from '../../helpers/template-helper'
+
+test.describe('Template Select - appendTo', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  let page: Page
+  let helper: ReturnType<typeof createSenderTestHelper>
+  let templateHelper: ReturnType<typeof createTemplateTestHelper>
+
+  test.beforeEach(async ({ page: currentPage }) => {
+    page = currentPage
+    await page.goto('/')
+    await page.click('text=Sender 组件')
+    helper = createSenderTestHelper(page)
+    templateHelper = createTemplateTestHelper(page)
+
+    await helper.toggleTemplate()
+    await helper.wait(300)
+    await helper.clearContent()
+    await templateHelper.clearTemplates()
+  })
+
+  test('默认挂载到 body，并支持选择和关闭', async () => {
+    await templateHelper.setSelectTemplate()
+    await templateHelper.openTemplateSelect()
+
+    const dropdown = page.locator(templateHelper.selectors.templateSelectDropdown)
+    await expect(dropdown.evaluate((element) => element.parentElement?.tagName)).resolves.toBe('BODY')
+
+    await dropdown.locator(templateHelper.selectors.templateSelectOption).first().click()
+    await expect(templateHelper.getTemplateSelect()).toContainText('GPT-4')
+    await expect(dropdown).toHaveCount(0)
+  })
+
+  test('指定选择器后挂载到目标容器，并使用 absolute 定位', async () => {
+    await page.click(templateHelper.selectors.toggleTemplateAppendToBtn)
+    await helper.wait(300)
+    await templateHelper.setSelectTemplate()
+    await templateHelper.openTemplateSelect()
+
+    const dropdown = page.locator(templateHelper.selectors.templateSelectDropdown)
+    await expect(dropdown).toHaveClass(/is-absolute/)
+    await expect(dropdown.evaluate((element) => element.parentElement?.id)).resolves.toBe(
+      'template-select-teleport-target',
+    )
+
+    await page.keyboard.press('Escape')
+    await expect(dropdown).toHaveCount(0)
+  })
+})