Nebular 3.5到4.0版本迁移完全指南

Nebular 3.5到4.0版本迁移完全指南

nebular :boom: Customizable Angular UI Library based on Eva Design System :new_moon_with_face::sparkles:Dark Mode 项目地址: https://gitcode.com/gh_mirrors/ne/nebular

迁移背景与意义

Nebular 4.0版本是一次重大升级，带来了多项核心改进。作为基于Angular的UI组件库，这次更新主要聚焦于以下几个方面：

1. 设计系统升级：全面采用Eva Design System，提供更现代化的视觉体验
2. 主题系统重构：全新的主题架构支持更灵活的定制能力
3. 技术增强：支持CSS自定义属性，组件接口标准化
4. 功能新增：内置暗黑主题，集成Eva SVG图标系统

这些改进使得Nebular在视觉一致性、可定制性和开发体验上都达到了新的高度。

前置准备

在开始迁移前，请确保：

1. 项目使用Angular 8+版本（必需）
2. 备份当前项目代码
3. 了解项目中使用到的Nebular特性和自定义配置

详细迁移步骤

第一步：Angular版本升级

Nebular 4.0基于Angular 8开发，因此需要先升级Angular核心：

ng update @angular/cli @angular/core

如果项目结构复杂，建议参考Angular官方升级指南进行手动调整。

第二步：Nebular核心包升级

执行以下命令更新核心包：

ng update @nebular/theme

如果使用了附加模块，一并更新：

ng update @nebular/theme @nebular/auth @nebular/security

同时更新Angular CDK：

ng update @angular/cdk

第三步：组件属性与导入调整

4.0版本对组件API进行了标准化处理，主要变更包括：

1. 统一了输入输出属性命名规范
2. 简化了部分复杂组件的API
3. 移除了部分废弃属性

开发者需要对照变更文档逐一检查项目中的组件使用情况。

第四步：主题系统迁移（重点）

基础调整

1. 将/deep/选择器替换为::ng-deep
2. 移除或注释掉废弃的Sass mixin

颜色系统重构

新版采用了更科学的颜色分级系统：

color-basic-100: #ffffff;  // 最浅色
color-basic-1100: #131729; // 最深色

迁移建议：

1. 先注释所有自定义主题变量
2. 按新的色阶体系重新定义颜色
3. 逐步调整背景、边框和文本颜色变量

状态颜色配置

状态颜色现在采用更精细的控制：

color-primary-default: color-primary-500;
color-primary-hover: color-primary-400;
color-primary-focus: color-primary-700;

组件样式覆盖

4.0版本限制了直接修改组件内部样式变量的方式，建议：

1. 优先使用全局主题变量实现样式定制
2. 必须覆盖组件样式时，参考新版变量命名规范

第五步：图标系统迁移（可选）

推荐方案：迁移到Eva图标

1. 安装Eva图标包：

npm i @nebular/eva-icons

2. 在根模块中导入：

import { NbEvaIconsModule } from '@nebular/eva-icons';

@NgModule({
  imports: [NbEvaIconsModule]
})

3. 替换所有图标使用方式：

<!-- 旧版 -->
<i icon="nb-home"></i>

<!-- 新版 -->
<nb-icon icon="home"></nb-icon>

兼容方案：继续使用旧版图标

1. 注册图标字体包：

this.iconLibraries.registerFontPack('nebular', { 
  iconClassPrefix: 'nb' 
});

2. 更新图标使用语法（去掉nb-前缀）

迁移后验证

完成迁移后，建议进行以下检查：

1. 控制台没有Sass编译警告
2. 所有功能组件显示正常
3. 自定义样式效果符合预期
4. 图标系统工作正常

常见问题处理

1. 样式异常：优先检查颜色变量定义是否完整
2. 图标丢失：确认图标包正确注册
3. 构建错误：检查是否完全移除了废弃API

总结

Nebular 4.0的迁移工作主要集中在主题系统和图标系统的重构上。虽然迁移过程需要一定工作量，但新版本带来的设计一致性和开发便利性将显著提升后续的开发体验。建议开发者按照本文档的步骤逐步迁移，遇到特定问题时可以参考更详细的变更说明文档。

nebular :boom: Customizable Angular UI Library based on Eva Design System :new_moon_with_face::sparkles:Dark Mode 项目地址: https://gitcode.com/gh_mirrors/ne/nebular