废弃 API

框架说明

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

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

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

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

函数签名

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

使用注意

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

  • replaceProperty不传入newNamenewTarget,表示和nametarget一致。

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