Components 迁移指南 ​

这页专门说明 @qxs-bns/components 从旧的 Vue 组件接入方式，切到当前跨框架 Web Components 方案后，业务页面需要重点检查什么。

先看结论 ​

• 组件现在以 Custom Element 方式提供，不再以 Vue 组件注册名为中心
• 宿主负责业务状态、列表编排、分页和提交数据，组件负责局部渲染、编辑、校验和导出
• Vue 里传对象、数组、函数、布尔值时，优先使用 .prop
• 事件统一按 CustomEvent 处理，数据从 event.detail 读取
• 样式覆盖优先使用属性、CSS 变量和 ::part(...)

升级前先检查 ​

• 页面里是否还在依赖旧的 Vue 全局注册组件名
• 组件入参里是否有对象、数组、函数、布尔值
• 业务层是否把列表、分页、标签、结果项弹窗这类状态塞给组件内部处理
• 业务代码里是否直接读取 Vue 事件参数，而不是 CustomEvent.detail
• 样式是否依赖深入组件内部 DOM 结构

最常见的迁移差异 ​

1. 组件注册方式变了 ​

旧思路通常是：

import { QxsDataChart } from '@qxs-bns/components'

app.component('QxsDataChart', QxsDataChart)

现在推荐直接引入组件入口，然后使用 Custom Element 标签：

import '@qxs-bns/components/data-chart'

<qxs-data-chart></qxs-data-chart>

2. Vue 里复杂值优先用 .prop ​

字符串属性可以直接写；对象、数组、函数、布尔值建议显式走实例属性。

<qxs-data-chart :data.prop="chartData" />
<qxs-image-upload :limit.prop="3" :file-list.prop="files" />
<qxs-blocksuite-editor :upload-image.prop="uploadImage" :readonly.prop="true" />

如果你写成 readonly="false" 这类字符串属性，Web Component 仍然可能把它识别成真值属性。

3. 事件要从 detail 里取值 ​

<script setup lang="ts">
function handleChange(event: CustomEvent) {
  console.log(event.detail)
}
</script>

<template>
  <qxs-file-upload @upload-success="handleChange" />
</template>

如果你的旧页面习惯直接拿 Vue 组件回调参数，需要统一改成读取 CustomEvent.detail。

4. 样式覆盖方式要收口 ​

优先级建议是：

1. 组件属性
2. CSS 变量
3. ::part(...)

不要再假设可以稳定依赖组件内部 DOM 结构或类名层级。

组件维度的迁移重点 ​

推荐迁移顺序 ​

1. 先把页面入口改成直接引入 @qxs-bns/components 或子入口
2. 再把页面上的标签替换成 Custom Element 名称
3. 然后逐个把复杂 props 改成 .prop
4. 最后统一收口事件读取和样式覆盖方式

一页里如何渐进迁移 ​

• 先选一个边界清晰的组件替换，例如 qxs-icon、qxs-fixed-action-bar
• 再迁上传、图表、编辑器这类有复杂 props / events 的组件
• 题目页放到最后迁，因为它涉及宿主数据模型、分页和提交链路

相关文档 ​

• Components 安装
• Components 总览
• 题目组件
• 富文本编辑器