• 废弃 API
    • 框架说明
    • 函数签名
    • 使用规范
    • 使用示例
    • 使用注意

    废弃 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 ，因为别的模块可能会把默认次数改了。