废弃 API

框架说明

为了更友好和便利的维护废弃 API ，将通过三个函数来实现：

  • markAsWarning 对给予对象上的属性中嵌入一个警告，给予对象需要存在该属性。

  • removeProperty 重新定义给予对象上移除的属性，并嵌入一个报错，给予对象应不存在该属性。

  • replaceProperty 重新定义给予对象上移除的属性，并嵌入一个警告和调用新的属性，参数不兼容的需要自己通过 custom 参数进行适配，给予对象应不存在该属性。

函数签名

  1. interface IDeprecatedItem {
  2.     name: string;           // 废弃属性的名称
  3.     logTimes?: number;      // 信息输出的次数，默认将使用全局的默认次数
  4. }
  6. interface IReplacement extends IDeprecatedItem {
  7.     newName?: string;       // 替换属性的名称，默认将使用 name 的值
  8.     target?: object;        // 替换对象，默认将使用 owner 的值
  9.     targetName?: string;    // 替换对象的名称，默认将使用 ownerName 的值
  10.     custom?: Function;      // 自定义的函数封装，错误消息会自动输出一份默认的
  11. }
  13. interface IRemoveItem extends IDeprecatedItem {
  14. }
  16. interface IMarkItem extends IDeprecatedItem {
  17. }
  19. export let replaceProperty: (owner: object, ownerName: string, properties: IReplacement[]) => void;
  21. export let removeProperty: (owner: object, ownerName: string, properties: IRemoveItem[]) => void;
  23. export let markAsWarning: (owner: object, ownerName: string, properties: IMarkItem[]) => void;
  25. // 此函数用于设置全局默认的信息输出次数，没有填 logTimes 将会使用这个值
  26. export function setDefaultLogTimes (times: number): void;

使用规范

按照模块划分，每个模块维护一份废弃文件，为了便于维护命名统一为 deprecated.ts ，并且放在相应模块的目录下，并需要在相应的模块的 index.ts 文件中 import 该文件，例如 import './deprecated'。

注：cocos 目录下的 deprecated.ts 文件为声明和实现文件。

使用示例

  1. // 对于替换参数不兼容的API，使用自定义的方式
  2. replaceProperty(AnimationComponent.prototype, 'AnimationComponent', [
  3.     {
  4.         name: 'removeClip',
  5.         newName: 'removeState',
  6.         custom: function (...args: any) {
  7.             let arg0 = args[0] as AnimationClip;
  8.             return AnimationComponent.prototype.removeState.call(this, arg0.name);
  9.         }
  10.     }
  11. ]);
  13. replaceProperty(vmath, 'vmath', [
  14.     {
  15.         name: 'vec2',
  16.         newName: 'Vec2',
  17.         target: math,
  18.         targetName: 'math',
  19.         'logTimes': 1
  20.     },
  21.     {
  22.         name: 'EPSILON',
  23.         target: math,
  24.         targetName: 'math',
  25.         'logTimes': 2
  26.     }
  27. ]);
  29. removeProperty(vmath, 'vmath', [
  30.     {
  31.         'name': 'random'
  32.     }
  33. ]);
  35. markAsWarning(math, 'math', [
  36.     {
  37.         'name': 'toRadian'
  38.     }
  39. ]);

使用注意

  • 操作目标都是对象，如果想要修改类的成员函数，owenr 和 target 都应该为 *.prototype 。

  • replaceProperty 不输入 newName 或 newTarget ，表示和 name 或 target 一致。

  • 如果要控制次数，最好在使用之前调用 setDefaultLogTimes ，因为别的模块可能会把默认次数改了。