# 平台组件扩展

# 一、功能说明

在低代码平台中，无需修改平台源码、无需重新搭建页面，仅需开发一个与系统组件同名的扩展组件，上传后即可自动替换平台默认组件，实现全局统一自定义（如修改样式、增加业务逻辑等）。

补充说明：扩展组件仅替换系统默认组件的展示和功能，不改变平台底层运行逻辑，所有基于该组件的现有配置均不受影响。

# 二、核心价值

全局替换：一次开发修改，所有页面中使用该组件的地方自动生效。
零侵入：不影响平台原生能力，删除扩展组件后，自动恢复为系统默认组件。
兼容原有配置：组件的原有属性、事件绑定、数据关联完全保留，无需重新配置现有页面。
双端独立替换：支持PC端和移动端分别开发扩展组件，可单独替换某一端的组件，互不影响（例：仅修改PC端日期组件，移动端保持默认）。

# 三、适用场景（以日期选择组件为例）

核心场景：增强组件功能但不改动原有页面，适配业务个性化需求

# 1. 新增快捷选项

给日期组件新增“最近一年”“最近三年”的快捷选项，用户点击即可快速选择时间范围，无需手动选择日期。

# 2. 快捷选项详细说明

定义：快捷选项是日期选择器中预设的常用时间范围，系统默认包含“本周”“上月”“最近一周”等基础选项。
自定义价值：可添加业务场景专属的时间范围（如“本季度”“近半年”“近五年”），适配不同业务的筛选需求。
生效范围：新增的快捷选项会自动同步到所有使用该日期组件的页面。
适配场景：数据筛选、报表查询、统计分析等需要频繁选择时间范围的业务场景（如财务报表、业务数据汇总）。

# 四、完整操作流程

# 1. 准备扩展组件框架

操作：下载扩展组件开发框架扩展组件开发框架（components-ext），下载后无需修改框架本身。
关键要求：确保框架目录结构规范，不可随意修改目录层级，标准结构如下：

src/
  └── components/
       └── 组件名（如datepicker，必须与系统组件名一致）/
            ├── pc.vue        # PC端组件（必选，若仅修改移动端可空，但建议保留）
            ├── mobile.vue     # 移动端组件（必选，若仅修改PC端可空，但建议保留）
            └── config.js      # 组件配置（必选，无此文件无法上传成功）

补充：若仅需修改单端（如仅PC端），另一端的vue文件可保留空内容，但不可删除该文件，否则会导致打包失败。

# 2. 复制系统原生组件代码

操作：联系平台工作人员，申请获取系统组件库（名称：primeton-form-components），获取后从中复制要替换的组件完整目录。
示例：若要替换日期选择组件，需复制“src/components/datepicker”整个目录。
关键提醒：

① 复制时需将该组件的所有依赖文件一同复制（如组件引用的页面、样式文件等），缺失会导致组件报错；

② 复制后粘贴到扩展组件框架的 src/components/ 目录下，文件夹名称可与系统组件名称不同，但需确保后续注册组件时使用的路径与实际文件夹名称保持一致；

③ 目的：基于官方原生组件进行修改。

# 3. 自定义修改组件

操作：打开扩展组件目录下的“pc.vue”（修改移动端则打开“mobile.vue”），找到快捷选项配置代码，在原有代码后添加自定义快捷项。

// 系统原有快捷项（无需修改，保留原样）
week: { text: "本周", ... },
lastWeek: { text: "上周", ...},
nextWeek: { text: "下周", ...},
month: { text: "本月", ...},
lastMonth: { text: "上月", ...},
nextMonth: { text: "下月", ...},
recentWeek: { text: "最近一周", ...},
recentTwoWeeks: { text: "最近两周", ...},
recentMonth: { text: "最近一个月", ...},

// 新增的自定义快捷项（直接复制粘贴，可修改text和时间范围）
recentYear: {
  text: "最近一年", // 快捷项显示名称，可自定义（如“近一年”）
  getRange: () => ({
    start: new Date(Date.now() - 3600 * 1000 * 24 * 365), // 开始时间：当前时间减365天
    end: new Date() // 结束时间：当前时间
  })
},
recentThreeYears: {
  text: "最近三年",
  getRange: () => ({
    start: new Date(Date.now() - 3600 * 1000 * 24 * 365 * 3), // 开始时间：当前时间减3年
    end: new Date()
  })
}

补充说明：

① 若需修改其他功能（如组件样式、点击事件），可在对应vue文件中修改，修改后需保存文件；

② 新增快捷项的text可自定义（如“近1年”“近3年”），时间范围可调整；

③ 修改时不要删除系统原有快捷项，避免影响原有功能。

# 4. 组件配置 config.js

每个扩展组件必须包含config.js文件，用于告诉平台该组件对应的系统组件，配置内容需与系统组件保持一致，最少配置如下（可直接复制使用）：

export default {
  __config__: {
    label: '日期选择', // 组件显示名称，建议与系统组件一致，可修改为其他名称
    tag: 'date-picker', // 组件标识，必须与系统组件完全一致（无需添加 pm- 前缀）
    tagIcon: 'date' // 选填，图标路径：src/icons/svg/date.svg（无图标可删除该配置）
  }
};

获取方式：联系平台工作人员获取“primeton-form-designer”组件设计库，从该库中找到对应组件的配置文件，复制config内容后修改（更稳妥，避免手动输入出错）。
关键提醒：

① tag属性必须与系统组件一致（如日期组件为date-picker），大小写敏感，否则平台无法识别，无法完成替换；

② 配置文件路径参考：src/components/generator/config/index.ts（不同平台版本路径可能不同，可通过全局搜索组件名称“date-picker”找到对应配置文件）；

③ 不可删除__config__外层包裹，否则配置无效。

# 5. 注册组件

需分别注册PC端和移动端组件（仅修改单端也需注册对应端，另一端可保持默认注册代码），注册名称必须与系统原生组件完全一致。

# （1）注册 PC 端

打开扩展框架中的“src/entry.js”文件，添加如下代码（复制即可，修改组件名对应部分）：

// 格式：Vue.component('系统组件名', () => import('组件路径'))
Vue.component('pm-date-picker', () => import('./components/datepicker/pc.vue'));

# （2）注册移动端

打开扩展框架中的“src/mobile_entry.js”文件，添加如下代码：

Vue.component('pm-date-picker', () => import('./components/datepicker/mobile.vue'));

关键规则：

① 组件注册名称格式为“pm-组件名称”（如pm-date-picker），必须与系统原生组件名完全一致，多一个字符、少一个字符或大小写错误，都会导致注册失败；

② 组件路径需正确（如./components/datepicker/pc.vue），若路径错误，会导致组件加载失败；

③ 若仅修改单端（如仅PC端），另一端的注册代码无需修改。

# 6. 打包扩展组件

执行打包命令：npm run build:prod:zip。
结果：打包成功后，会在框架根目录生成一个ext.zip格式的压缩包，该压缩包即为可上传到平台的文件。

# 7. 上传扩展组件

进入【应用中心】→【业务组件】→【页面组件】页面；
点击“新建分组”,上传扩展组件包
上传成功后，扩展组件列表会显示该组件（如date-picker）。

# 8. 验证效果

先刷新低代码IDE页面，确保平台加载最新的扩展组件；
打开任意一个使用了日期选择组件的视图界面，添加筛选条件，将筛选条件的控件设置为“日期选择器”，并将日期选择规则设置为“介于”（只有“介于”模式才会显示快捷选项）；
点击日期选择组件，弹出选择面板，若能看到新增的“最近一年”“最近三年”快捷选项，即为替换成功；
双端验证：若修改了移动端组件，需在平台切换到移动端预览模式，重复步骤2-3，确认移动端也显示新增快捷选项。

# 五、关键注意事项

组件名完全一致：扩展组件的目录名称、config.js中的tag属性、组件注册名称，必须与系统原生组件完全一致（大小写敏感，如datepicker不可写为DatePicker），否则无法替换。
必含config.js：每个扩展组件必须有config.js文件，且配置正确，无此文件会导致上传失败或无法生效。
无需删除旧组件：上传扩展组件后，平台会自动用扩展组件覆盖默认组件，无需手动删除系统原生组件。
恢复默认方式：若需恢复为平台默认组件，直接在“扩展组件”页面删除该扩展组件即可，删除后所有页面自动恢复，无需其他操作。
依赖文件齐全：复制系统组件时，必须同步复制所有依赖文件，缺失依赖会导致组件报错、无法加载。
打包命令正确：必须执行“npm run build:prod:zip”命令，不可修改命令，否则无法生成正确的.zip包。

# 六、流程极简总结

获取扩展框架 + 系统组件库，复制目标组件到扩展框架对应目录；
在vue文件中按需求自定义修改（如新增快捷项）；
配置config.js（确保tag与系统组件一致）；
在entry.js/mobile_entry.js中注册同名组件；
执行打包命令生成.zip包；
上传到平台扩展组件页面，刷新IDE验证效果，完成自动替换。

# 七、常见问题排查

问题	排查方法
上传扩展组件后，刷新IDE仍未看到修改效果？	① 组件注册名称是否为“pm-组件名”，与系统组件一致；② config.js的tag属性是否正确；③ 重新打包并上传，刷新页面后重试。
打包失败，提示依赖缺失？	重新复制系统组件的完整目录，确保所有依赖文件（如引入页面、样式文件）都已复制，确认后再打包。
日期组件看不到新增的快捷选项？	① 日期选择规则是否设置为“介于”（只有范围选择才显示快捷项）；② 移动端修改后是否切换到移动端预览模式；③ 检查vue文件中新增快捷项的代码是否正确，有无语法错误。
删除扩展组件后，组件无法恢复默认？	刷新IDE页面，若仍未恢复，退出平台重新登录。

# 八、补充说明

调试组件：若修改后组件报错，可参考文档组件扩展；
其他组件扩展：本文以日期选择组件为例，其他组件（如下拉框、输入框）的扩展流程完全一致，只需替换对应组件名称及修改内容即可；