废弃 API

框架说明

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

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

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

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

函数签名

  1. interface IRemoveItem {
  2.     /** 废弃属性的名称 */
  3.     name: string;
  4.     /** 警告的次数 */
  5.     logTimes?: number;
  6.     /** 额外建议 */
  7.     suggest?: string;
  8. }
  10. interface IMarkItem {
  11.     /** 废弃属性的名称 */
  12.     name: string;
  13.     /** 警告的次数 */
  14.     logTimes?: number;
  15.     /** 额外建议 */
  16.     suggest?: string;
  17. }
  19. interface IReplacement {
  20.     /** 废弃属性的名称 */
  21.     name: string;
  22.     /** 警告的次数 */
  23.     logTimes?: number;
  24.     /** 替换属性的名称 */
  25.     newName?: string;
  26.     /** 废弃属性的所属对象 */
  27.     target?: object;
  28.     /** 废弃属性的所属对象的名称 */
  29.     targetName?: string;
  30.     /** 自定义替换属性（函数） */
  31.     customFunction?: Function;
  32.     /** 自定义替换属性的 setter */
  33.     customSetter?: (v: any) => void;
  34.     /** 自定义替换属性的 getter */
  35.     customGetter?: () => any;
  36. }
  38. export let removeProperty: (owner: object, ownerName: string, properties: IRemoveItem[]) => void;
  40. export let markAsWarning: (owner: object, ownerName: string, properties: IMarkItem[]) => void;
  42. export let replaceProperty: (owner: object, ownerName: string, properties: IReplacement[]) => void;
  44. /** 此函数用于设置全局默认的信息输出次数 */
  45. export function setDefaultLogTimes (times: number): void;

使用规范

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

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

使用示例

  1. // 对于替换参数不兼容的 API，通过合适的自定义功能进行适配
  2. replaceProperty(Animation.prototype, 'Animation.prototype', [
  3.     {
  4.         name: 'removeClip',
  5.         newName: 'removeState',
  6.         customFunction: function (...args: any) {
  7.             const arg0 = args[0] as AnimationClip;
  8.             return Animation.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.         'suggest': 'use Math.random.'
  33.     }
  34. ]);
  36. markAsWarning(math, 'math', [
  37.     {
  38.         'name': 'toRadian'
  39.     }
  40. ]);

使用注意

  • 操作目标都是对象，如果想要修改类的成员函数，请传入target.prototype。

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

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