Naive UI Transfer 组件头部自定义功能探讨

背景概述

Naive UI 作为一款优秀的 Vue 3 组件库，其 Transfer（穿梭框）组件在数据双向选择场景中应用广泛。在实际开发中，开发者常需要对组件头部区域进行个性化定制，例如在标题旁添加操作图标、状态标识等交互元素。当前原生实现仅支持简单的字符串标题配置，这种设计在需要增强头部交互性的业务场景中显得捉襟见肘。

需求分析

典型业务场景包括：

1. 在源数据面板标题后添加筛选图标，点击触发筛选弹窗
2. 在目标面板添加帮助图标，悬停显示操作说明
3. 动态显示选中数量统计（如"已选(3/10)"）
4. 插入条件筛选按钮或搜索框

这些需求本质上都需要突破当前纯文本标题的限制，实现渲染层的灵活控制。

技术实现方案

方案一：渲染函数属性（推荐）

通过新增 renderSourceTitle 和 renderTargetTitle 两个 props，采用 Vue 的渲染函数机制：

props: {
  renderSourceTitle: {
    type: Function,
    default: () => '源数据'
  },
  renderTargetTitle: {
    type: Function,
    default: () => '目标数据'
  }
}

组件内部调用方式：

<div class="transfer-header">
  {renderSourceTitle()}
</div>

开发者使用示例：

<n-transfer
  :render-source-title="() => [
    h('span', '员工列表'),
    h(NIcon, { type: 'filter', onClick: handleFilter })
  ]"
/>

方案二：插槽扩展

同时提供作用域插槽增强灵活性：

<template #source-header="{ count, total }">
  <div class="custom-header">
    <span>待选人员</span>
    <n-tag :bordered="false" type="info">
      {{ count }}/{{ total }}
    </n-tag>
  </div>
</template>

实现考量要点

1. 兼容性处理：保留现有的 source-title 和 target-title 字符串属性，新属性与其共存
2. 作用域设计：渲染函数/插槽应接收当前面板的状态数据（如选中数量、过滤状态等）
3. 样式隔离：确保自定义内容不影响布局结构，提供基础样式类名
4. TypeScript 支持：完善类型定义，包括渲染函数的参数类型提示

最佳实践建议

对于简单场景，优先使用组合式 API：

const renderTitle = (title: string) => () => h('div', [
  h('span', title),
  h(NIcon, {
    size: 14,
    style: { marginLeft: '8px' },
    // ...其他图标属性
  })
])

扩展思考

这种模式可以推广到其他包含标题区域的组件（如 Card、Table 等），形成统一的自定义渲染规范。未来还可考虑：

• 提供预设的标题扩展组件（带图标、计数等）
• 支持配置式声明扩展内容
• 开发标题区域的插件系统

通过这种渐进式的 API 设计，既能满足当前定制需求，又为后续功能扩展预留了空间。