业务组件预览与依赖管理指南
本文档详细介绍如何在 comp-hub 平台上预览业务组件，以及如何解决预览过程中可能遇到的依赖问题，帮助您充分利用平台的组件资源。
访问组件市场
完成组件上传后，您可以在组件市场中查看已发布的组件。
预览组件
基本预览流程
- 在组件市场中找到您上传的组件
- 点击组件卡片上的预览按钮，打开组件预览页面
预览效果
打开预览页面后，您将看到一个可实时交互的组件预览界面，同时包含组件的详细文档说明。
预览配置说明
- 如果在上传组件时指定了全屏预览文件，预览页面将展示该文件的内容
- 全屏预览文件的配置是非常推荐的，因为：
- 组件列表页面空间有限，无法完整展示组件所有功能
- 全屏预览提供更大的展示区域，用户可以获得更完整的组件信息
- 可以在全屏预览文件中编写更多演示案例，展示组件的不同用法
预览问题排查
组件不显示问题
在某些情况下，您可能会遇到以下问题：
- 上传的组件在当前项目可以正常预览
- 在新的项目中，组件列表为空或找不到已上传的组件
筛选条件说明
当遇到上述情况时，尝试切换筛选条件：
- 选择全部筛选条件后，所有组件将被显示出来
- 但可能会出现组件编译失败的错误提示
问题原因分析
组件预览问题主要由以下原因导致：
- 组件渲染机制：comp-hub 组件上传的是最小可运行单元，不包含运行环境和依赖
- 环境匹配机制：
- 平台会根据当前项目的环境和依赖情况，判断组件是否可以正常渲染
- 系统推荐列表中只显示与当前环境匹配的组件
- 默认的匹配规则是主版本号相同
- 例如：组件依赖 Vue 3.2.45，只有在主版本号相同的 Vue 3.x 项目中才会出现在系统推荐列表中
依赖设置管理
依赖版本匹配问题
组件渲染需要安装对应的依赖库，否则无法正常加载。但在实际开发中，可能会遇到依赖版本冲突的问题：
- 本地项目可能已安装 echarts 5.0 版本
- 但组件可能依赖 echarts 5.1、5.2 甚至 6.0 版本
- 显然无法为每个组件安装不同版本的依赖库
针对这种情况，comp-hub 提供了灵活的依赖匹配规则配置。
依赖匹配规则设置
您可以在平台上配置依赖匹配规则，以适应不同场景：
在设置 > 依赖设置中，您可以配置以下匹配规则：
仅安装：只要本地安装了该依赖，不要求版本号相同
- 示例：本地安装了 echarts 5.0，组件依赖 echarts 6.0，系统会使用 echarts 5.0 尝试渲染
主版本：只匹配主版本号相同的依赖
- 示例：本地安装了 echarts 5.0，组件依赖 echarts 5.1，由于主版本号相同，系统会使用 echarts 5.0 渲染
主次版本：匹配主次版本号相同的依赖
- 示例：本地安装了 echarts 5.1.2，组件依赖 echarts 5.1.3，系统会使用 echarts 5.1.2 渲染
完全一致：要求依赖版本完全相同
- 示例：本地安装了 echarts 5.1.2，组件依赖 echarts 5.1.3，系统不会使用 echarts 5.1.2 渲染
设计理念说明
这种灵活的依赖匹配机制是为了解决前端开发中的"严格依赖契约"问题：
传统库在发布时会将外部依赖写死为精确版本："我只在我开发、测试时用的那几份 exact 版本上工作，任何偏离行为都是未定义的"。
对于大型第三方库，这种做法无可厚非，但对于轻量化组件，这一限制过于严格。大多数组件开发者无法对使用的第三方库进行全版本测试。
实际上，许多组件在不同版本环境中依然可以正常工作：
- 使用非废弃 API（如filter） 的 Vue 2 组件通常可以在 Vue 3 中运行
- 不使用 Vue 3 特有 API（如 setup 语法）的组件通常可以在 Vue 2 中运行
- 大多数库的升级都提供了一定程度的向后兼容性
基于这些考量，comp-hub 将依赖版本匹配的控制权交给用户，让您可以根据实际情况灵活选择。
推荐使用策略
- 优先使用系统推荐组件：这些组件与当前环境的兼容性最好
- 保持主版本号一致：在自定义配置时，至少保持主版本号匹配，可以避免大多数兼容性问题
- 测试验证：使用不同匹配规则时，请充分测试组件功能，确保没有异常
安装缺失依赖
如果组件无法正常渲染，通常是因为缺少必要的依赖。comp-hub 提供了便捷的依赖安装方式。
使用内置终端
平台内置了终端功能，可以直接在网页上安装依赖：
- 点击平台界面中的终端按钮，打开内置终端
- 内置终端的工作目录默认就是项目根目录
- 执行 npm install 命令安装所需依赖
其他安装方式
除了使用平台内置终端，您也可以：
- 在本地开发环境的终端中安装依赖
- 通过项目的包管理工具（如 npm、yarn、pnpm）安装依赖
后续步骤
- 参考更新组件章节，了解如何维护和更新已发布的组件
- 探索如何在实际项目中集成和使用这些业务组件
- 尝试开发更多符合规范的业务组件，丰富组件库资源