ng-admin 1.0 版本升级指南与技术解析

ng-admin 1.0 版本升级指南与技术解析

ng-admin Add an AngularJS admin GUI to any RESTful API 项目地址: https://gitcode.com/gh_mirrors/ng/ng-admin

前言

ng-admin 是一个基于 AngularJS 的后台管理界面框架，它能够快速构建功能丰富的管理后台。随着 1.0 版本的发布，ng-admin 带来了多项重要更新和改进。本文将深入解析升级到 1.0 版本的关键变化，帮助开发者顺利完成迁移。

核心依赖升级

AngularJS 版本要求

ng-admin 1.0 版本将最低要求的 AngularJS 版本从 1.3 提升到了 1.4，同时兼容 1.5 和 1.6 版本。这一变化带来了性能改进和新特性支持，但也引入了一些不兼容的变更。

升级建议：

1. 首先将项目升级到 AngularJS 1.4
2. 然后逐步升级到 1.5 和 1.6
3. 特别注意 AngularJS 官方迁移指南中列出的重大变更

主要变更点

1. 路由前缀变更：

   • AngularJS 1.6 默认将路由前缀从 #/ 改为 #!/
   • ng-admin 选择保持旧前缀以确保兼容性
   • 解决方案：在配置中添加 $locationProvider.hashPrefix('');

2. $http 服务变更：

   • 移除了 .success() 和 .error() 方法
   • 改用 .then() 方法处理响应

   // 旧代码
   $http.success(successFn).error(errorFn);
   
   // 新代码
   $http.then(successFn, errorFn);
   

3. 服务定义方式变更：

   • 不再支持箭头函数定义服务和控制器
   • 必须改用传统函数定义方式

视图系统重大变更

视图命名变更

ng-admin 1.0 对视图系统进行了重构，最显著的变化是要求为 ng-admin 的视图指定名称：

<!-- 旧版本 -->
<div ui-view></div>

<!-- 新版本 -->
<div ui-view="ng-admin">

注意：如果不进行此修改，页面将显示空白。

自定义页面父级变更

如果你在项目中添加了自定义页面，需要更新路由配置中的父级名称：

// 旧配置
$stateProvider.state('custom-page', {
    parent: 'main',  // 旧父级名称
    // 其他配置...
});

// 新配置
$stateProvider.state('custom-page', {
    parent: 'ng-admin',  // 新父级名称
    // 其他配置...
});

字段视图链接机制改进

ng-admin 1.0 改进了字段视图中的链接实现方式：

1. 移除了 gotoDetail() 和 gotoReference() 方法
2. 改用 ui-sref 指令实现路由跳转
3. 新实现方式支持右键打开链接等浏览器原生功能

迁移示例：

// 旧实现
getLinkWidget: () => '<a ng-click="gotoDetail()">' + module.exports.getReadWidget() + '</a>',

// 新实现
getLinkWidget: () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>'

操作后重定向逻辑优化

ng-admin 1.0 改进了创建和编辑实体后的重定向行为：

1. 编辑后：默认返回上一页面（通常是列表视图）
2. 创建后：
   • 如果启用了详情视图，则跳转到详情视图
   • 否则跳转到列表视图

自定义重定向： 如果需要恢复旧版行为，可以重写 CreationView.onSubmitSuccess() 和 EditionView.onSubmitSuccess() 方法。

模块打包支持增强

ng-admin 1.0 改进了对现代模块打包工具的支持：

1. 直接引用：

   const myApp = angular.module('myApp', [
       require('ng-admin'),
       // 其他依赖...
   ]);
   

2. 样式引入：

   // SASS 版本
   require('ng-admin/lib/sass/ng-admin.scss');
   
   // CSS 版本
   require('ng-admin/build/ng-admin.min.css');
   

3. 精简版移除：

   • 移除了 ng-admin-only 精简版本
   • 推荐使用模块打包工具的 tree-shaking 功能来优化最终包大小

升级建议

1. 先升级 AngularJS 到 1.4+ 版本并解决兼容性问题
2. 更新视图系统中的 ui-view 命名
3. 检查并更新所有自定义页面的路由配置
4. 更新自定义字段视图中的链接实现
5. 评估操作后重定向逻辑是否符合业务需求
6. 根据项目构建工具调整模块引入方式

通过遵循这些指南，开发者可以顺利将项目迁移到 ng-admin 1.0 版本，并充分利用新版本带来的改进和优化。

ng-admin Add an AngularJS admin GUI to any RESTful API 项目地址: https://gitcode.com/gh_mirrors/ng/ng-admin