用途
本技能用于把项目从 Grid Lite(igniteui-grid-lite,MIT 许可,<igc-grid-lite>)迁移到 Premium Data Grid(igniteui-webcomponents-grids,商业许可,<igc-grid>)。Grid Lite 只支持只读能力;当项目需要企业级功能(例如编辑、选择、分页、分组、汇总、Excel 导出、状态持久化)时使用本技能。技能明确要求:从 Grid Lite 的升级路径始终是 IgcGridComponent(<igc-grid>),不应推荐其他组件替代。编写迁移代码前须先阅读用户现有 TypeScript 与 HTML 文件,识别列配置、单元格模板、数据绑定和 dataPipelineConfiguration 用法;对 API 细节不确定时通过 MCP 服务器查询 API 参考或文档,不要凭记忆编写代码。
迁移步骤
第一步:安装或校验 Premium 包。Grid Lite 使用独立的 igniteui-grid-lite 包;Premium Grid 位于 igniteui-webcomponents-grids(或授权版 @infragistics/igniteui-webcomponents-grids)。需检查 package.json 确认已安装哪种包变体。命令:npm uninstall igniteui-grid-lite;npm install igniteui-webcomponents-grids(开源/试用版,带水印),或 npm install @infragistics/igniteui-webcomponents-grids(授权版,需私有仓库)。
第二步:更新导入与注册。改为先做副作用导入 'igniteui-webcomponents-grids/grids/combined.js',再导入类型(IgcGridComponent、IgcColumnComponent、IgcCellTemplateContext 等)与值(SortingDirection、各类过滤操作数、IgcFilteringExpressionsTree、FilteringLogic、IgcNoopSortingStrategy、IgcNoopFilteringStrategy)。主题需以内联字符串方式导入(如 ?inline,需 Vite 等打包器支持),可选 light|dark × bootstrap|material|fluent|indigo,并在 Shadow root 内以 <style> 标签注入,否则网格内部元素无样式。
第三步:更新 HTML 标签。igc-grid-lite 改为 igc-grid,igc-grid-lite-column 改为 igc-column;布尔属性由裸属性改为带引号值(sortable="true" 等);需在 igc-grid 上设置 allow-filtering="true" 才能过滤;行虚拟化要求设置 height 属性(或在固定高度父元素上设置)。
第四步:更新 TypeScript 类型引用(IgcGridLite 改 IgcGridComponent,IgcGridLiteColumn 改 IgcColumnComponent);grid.data 用法不变。
第五步:迁移列属性。field、header、width、hidden、resizable、sortable、filterable、dataType 名称不变(Premium 新增 dateTime、time、currency、percent 类型);filteringCaseSensitive 改为 filteringIgnoreCase、sortingCaseSensitive 改为 sortingIgnoreCase(逻辑取反);sortConfiguration.comparer 改为 sortStrategy 对象,需实现 sort(data, fieldName, dir, ignoreCase, valueResolver) 方法,并通过 valueResolver 读取单元格值以支持嵌套字段与日期时间列。Premium 还新增 editable、pinned、groupable、hasSummary、disableHiding、disablePinning、selectable、searchable、formatter、minWidth、maxWidth 等属性。
第六步:迁移模板。cellTemplate 改为 bodyTemplate,上下文类型 BaseIgcCellContext 改为 IgcCellTemplateContext,取值 ctx.value 改为 ctx.implicit,行数据 ctx.row 改为 ctx.cell.row.data;headerTemplate 由无参改为接收 IgcColumnTemplateContext(可访问 ctx.column.header 或 ctx.column.field)。
第七步:迁移远程数据操作。dataPipelineConfiguration 改为 IgcNoopSortingStrategy/IgcNoopFilteringStrategy 禁用内置处理,并在 sortingDone、filteringDone 事件中从服务器重新加载数据。
第八步:迁移排序/过滤事件。sorting、filtering 事件名不变且可取消(e.detail.cancel = true);sorted 改为 sortingDone(CustomEvent<IgcSortingExpression[]>),filtered 改为 filteringDone(CustomEvent<IgcFilteringExpressionsTree>)。
第九步:迁移编程式 API。排序改为 grid.sort([{ fieldName, dir: SortingDirection.Asc, ignoreCase }]),clearSort 可按列或全部清除;过滤改为 grid.filter(fieldName, value, IgcNumberFilteringOperand.instance().condition('greaterThan'), true),也可用 IgcFilteringExpressionsTree 构建多列过滤并赋值给 filteringExpressionsTree。表达式字段变化:key 改 fieldName,direction 字符串改 SortingDirection 枚举,searchTerm 改 searchVal(表达式树),caseSensitive 改 ignoreCase(取反),criteria 字符串改为树上的 FilteringLogic 枚举。
迁移后启用企业功能
行编辑:设置 row-editable="true"、primary-key="id",列上设 editable="true";建议在编辑、选择或行级 API(getRowByKey、行固定、事务)时设置 primary-key,否则网格使用对象标识,在虚拟化和远程数据下会失效。行选择:row-selection="multiple" 并监听 rowSelectionChanging。分页:添加 <igc-paginator per-page="15">。GroupBy:列设 groupable="true",或用 grid.groupBy([{ fieldName, dir }])。列固定:column.pin()/unpin()。汇总:列设 has-summary="true"。工具栏:使用 igc-grid-toolbar 及 advanced-filtering、hiding、pinning、exporter 子组件。高级过滤:allowAdvancedFiltering = true 并调用 openAdvancedFilteringDialog()。Excel 风格过滤:filterMode = 'excelStyleFilter'(默认为 'quickFilter')。批量编辑:batch-editing="true" 与 row-editable="true"。
适用场景与限制
适用于现有项目使用 Grid Lite 且需要上述企业级功能的迁移场景;迁移涉及商业许可包,开源/试用版带水印,授权版需私有仓库。技能未提供各功能的价格、性能指标或完整平台兼容性说明(暂未提供)。相关技能包括框架集成、主题定制和组件选择。