操作模式注解（OpMode Annotations）​¶

概述​¶

OpMode（操作模式）是 FTC 编程的核心概念，而注解是定义和配置 OpMode 的关键工具。本文档详细介绍 OpMode 相关的注解及其用法，帮助你更好地理解和应用这些注解。

核心 OpMode 注解​¶

@TeleOp​¶

@TeleOp(name="我的遥控", group="联盟")
public class MyTeleOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

详细解释：

• 定义：标记一个类为遥控操作模式，用于比赛的遥控阶段

• 必需参数：无（虽然通常都会提供 name 参数）

• 可选参数：name：在驱动站应用界面显示的操作模式名称group：用于分组显示的类别名称

• name：在驱动站应用界面显示的操作模式名称

• group：用于分组显示的类别名称

• 行为影响：使操作模式显示在驱动站的操作模式选择列表中用户可以通过点击列表中的名称来选择和启动此操作模式

• 使操作模式显示在驱动站的操作模式选择列表中

• 用户可以通过点击列表中的名称来选择和启动此操作模式

• 技术细节：通过 SDK 的自动注册机制工作在编译时生成注册代码操作模式默认为遥控操作模式类型

• 通过 SDK 的自动注册机制工作

• 在编译时生成注册代码

• 操作模式默认为遥控操作模式类型

@Autonomous​¶

@Autonomous(name="自动红联盟", group="红方")
public class RedAutoOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

详细解释：

• 定义：标记一个类为自动操作模式，用于比赛的自动阶段

• 必需参数：无（虽然通常都会提供 name 参数）

• 可选参数：name：在驱动站应用界面显示的操作模式名称group：用于分组显示的类别名称

• name：在驱动站应用界面显示的操作模式名称

• group：用于分组显示的类别名称

• 行为影响：使操作模式显示在驱动站的操作模式选择列表中用户可以通过点击列表中的名称来选择和启动此操作模式系统会识别为自动阶段操作模式

• 使操作模式显示在驱动站的操作模式选择列表中

• 用户可以通过点击列表中的名称来选择和启动此操作模式

• 系统会识别为自动阶段操作模式

• 技术细节：通过 SDK 的自动注册机制工作在编译时生成注册代码操作模式被标记为自动操作模式类型

• 通过 SDK 的自动注册机制工作

• 在编译时生成注册代码

• 操作模式被标记为自动操作模式类型

@Disabled​¶

@TeleOp(name="测试操作模式", group="测试")
@Disabled
public class TestOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

详细解释：

• 定义：临时禁用一个操作模式，使其不出现在驱动站的选择列表中

• 参数：无

• 行为影响：阻止操作模式显示在驱动站应用中代码仍会编译，但不会被注册到系统中

• 阻止操作模式显示在驱动站应用中

• 代码仍会编译，但不会被注册到系统中

• 技术细节：不会影响类的编译或其他行为可随时添加或移除此注解以启用/禁用操作模式

• 不会影响类的编译或其他行为

• 可随时添加或移除此注解以启用/禁用操作模式

• 常见用例：临时禁用仍在开发中的操作模式保留旧版操作模式但不再使用当有多个类似操作模式时，禁用不需要的变体

• 临时禁用仍在开发中的操作模式

• 保留旧版操作模式但不再使用

• 当有多个类似操作模式时，禁用不需要的变体

高级注册注解​¶

@OpModeRegistrar​¶

public class OpModeRegistrarExample {
    @OpModeRegistrar
    public static void registerMyOpModes(OpModeManager manager) {
        // 注册一个简单的操作模式
        manager.register("自定义操作模式", MyCustomOpMode.class);

        // 根据条件注册操作模式
        if (isRedAlliance()) {
            manager.register("红方自动", RedAutoOpMode.class);
        } else {
            manager.register("蓝方自动", BlueAutoOpMode.class);
        }
    }

    private static boolean isRedAlliance() {
        // 确定联盟颜色的逻辑
        return true;
    }
}

详细解释：

• 定义：标记一个静态方法用于以编程方式注册操作模式

• 参数：无

• 方法要求：必须是静态方法必须接受一个 OpModeManager 类型的参数通常不返回值(void)

• 必须是静态方法

• 必须接受一个 OpModeManager 类型的参数

• 通常不返回值(void)

• 行为影响：在 SDK 初始化时自动调用此方法可以根据条件动态注册操作模式

• 在 SDK 初始化时自动调用此方法

• 可以根据条件动态注册操作模式

• 技术细节：允许比@TeleOp 和@Autonomous 更灵活的注册方式可以实现条件性注册、生成多个类似操作模式等该方法会在驱动站启动时运行，而不是每次选择操作模式时

• 允许比@TeleOp 和@Autonomous 更灵活的注册方式

• 可以实现条件性注册、生成多个类似操作模式等

• 该方法会在驱动站启动时运行，而不是每次选择操作模式时

生命周期相关注解​¶

@Override​¶

public class MyOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 必须实现的操作模式入口点
    }

    @Override
    public void internalPostInitLoop() {
        // 覆盖父类的内部方法
    }
}

详细解释：

• 定义：指示方法覆盖了父类或接口中声明的方法

• 参数：无

• 行为影响：帮助编译器验证方法确实覆盖了父类方法如果方法签名不匹配，编译器会报错

• 帮助编译器验证方法确实覆盖了父类方法

• 如果方法签名不匹配，编译器会报错

• 技术细节：这是 Java 标准注解，不特定于 FTC在 OpMode 中常用于覆盖 runOpMode()方法有助于捕获拼写错误或参数类型错误

• 这是 Java 标准注解，不特定于 FTC

• 在 OpMode 中常用于覆盖 runOpMode()方法

• 有助于捕获拼写错误或参数类型错误

• 常见用例：实现 LinearOpMode 中的 runOpMode()方法覆盖 OpMode 中的 init()、loop()等方法

• 实现 LinearOpMode 中的 runOpMode()方法

• 覆盖 OpMode 中的 init()、loop()等方法

实用示例​¶

组合使用多个注解​¶

@TeleOp(name="组合示例", group="示例")
@Disabled  // 临时禁用
public class CombinedAnnotationExample extends LinearOpMode {
    @Override
    public void runOpMode() {
        @SuppressWarnings("unused")
        int unusedVariable = 0;  // 抑制未使用变量的警告

        // 实现代码
    }
}

按联盟颜色注册不同操作模式​¶

public class AllianceSpecificOpModes {
    @OpModeRegistrar
    public static void registerByAlliance(OpModeManager manager) {
        // 假设我们从某处读取联盟信息
        boolean isRedAlliance = readAllianceColor();

        if (isRedAlliance) {
            manager.register("联盟特定自动", RedAutoOpMode.class);
        } else {
            manager.register("联盟特定自动", BlueAutoOpMode.class);
        }
    }

    private static boolean readAllianceColor() {
        // 实际代码会从配置文件或其他来源读取
        return true;
    }
}

使用命名约定组织操作模式​¶

@TeleOp(name="A-主要遥控", group="比赛")
public class MainTeleOp extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

@TeleOp(name="B-备用遥控", group="比赛")
public class BackupTeleOp extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

@Autonomous(name="1-红联盟近端", group="红方")
public class RedNearAuto extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

@Autonomous(name="2-红联盟远端", group="红方")
public class RedFarAuto extends LinearOpMode {
    @Override
    public void runOpMode() {
        // 实现代码
    }
}

注解最佳实践​¶

• 明确的命名：为操作模式提供清晰、描述性的名称在名称中包含关键信息（如联盟颜色、起始位置）考虑使用数字前缀排序相关操作模式

明确的命名：

• 为操作模式提供清晰、描述性的名称

• 在名称中包含关键信息（如联盟颜色、起始位置）

• 考虑使用数字前缀排序相关操作模式

• 有效的分组：使用 group 参数将相关操作模式分组常见分组包括：红方/蓝方、测试、演示等保持分组名称简短但有意义

有效的分组：

• 使用 group 参数将相关操作模式分组

• 常见分组包括：红方/蓝方、测试、演示等

• 保持分组名称简短但有意义

• 谨慎使用@Disabled：避免在生产代码中保留过多禁用的操作模式在注释中说明禁用原因定期清理永久禁用的操作模式

谨慎使用@Disabled：

• 避免在生产代码中保留过多禁用的操作模式

• 在注释中说明禁用原因

• 定期清理永久禁用的操作模式

• 错误处理：操作模式注册过程中的错误可能不会明显显示如果操作模式未出现在列表中，检查类是否公共(public)、非抽象、有适当的构造函数

错误处理：

• 操作模式注册过程中的错误可能不会明显显示

• 如果操作模式未出现在列表中，检查类是否公共(public)、非抽象、有适当的构造函数

常见问题解答​¶

为什么我的操作模式没有出现在驱动站应用中？​¶

可能的原因包括：

• 类被@Disabled 注解标记

• 类不是 public，或者是 abstract

• 类没有默认构造函数或构造函数抛出异常

• 类路径不正确（应在 org.firstinspires.ftc.teamcode 包或其子包中）

• 构建问题导致注解处理器未运行

我可以同时使用@TeleOp 和@Autonomous 吗？​¶

不推荐。虽然技术上可行，但会导致操作模式在列表中出现两次，可能引起混淆。最好为不同阶段创建单独的操作模式类。

注解中的 group 参数有什么作用？​¶

group 参数用于在驱动站应用中组织操作模式。相同 group 的操作模式会在界面中分组显示，便于操作手快速找到所需的操作模式。

总结​¶

OpMode 注解是 FTC SDK 的核心功能，它们简化了操作模式的注册和管理。掌握这些注解的使用将帮助你更有效地组织代码，并提高比赛中的操作效率。通过合理的命名和分组，你可以创建清晰、易于使用的操作模式集合，满足各种比赛需求。