Visual Studio Code 任务运行器的附录

任务运行器的附录

这是有关 Visual Studio Code 任务的附加信息。

tasks.json 的架构

以下接口定义了 tasks.json 文件的基本架构。

注意: 某些任务选项是由 VS Code 扩展提供的。你可以使用 tasks.json 的 IntelliSense 功能，通过 触发建议 命令 (kb(editor.action.triggerSuggest)) 查找完整列表。

interface TaskConfiguration extends BaseTaskConfiguration {

    /**
     * 配置的版本号
     */
    version: "2.0.0";

    /**
     * Windows 特定的任务配置
     */
    windows?: BaseTaskConfiguration;

    /**
     * macOS 特定的任务配置
     */
    osx?: BaseTaskConfiguration;

    /**
     * Linux 特定的任务配置
     */
    linux?: BaseTaskConfiguration;
}

interface BaseTaskConfiguration {

    /**
     * 自定义任务的类型。类型为 "shell" 的任务在 shell（例如 bash, cmd, powershell 等）中执行
     */
    type: "shell" | "process";

    /**
     * 要执行的命令。可以是外部程序或 shell 命令。
     */
    command: string;

    /**
     * 指定全局命令是否是后台任务。
     */
    isBackground?: boolean;

    /**
     * 执行命令时使用的命令选项。可以省略。
     */
    options?: CommandOptions;

    /**
     * 传递给命令的参数。可以省略。
     */
    args?: string[];

    /**
     * 显示选项。
     */
    presentation?: PresentationOptions;

    /**
     * 如果执行全局命令时使用的错误匹配模式（例如没有定义任务）。`tasks.json` 文件可以包含全局的 problemMatcher 属性或 tasks 属性，但不能同时包含两者。
     */
    problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[];

    /**
     * 可用任务的配置。`tasks.json` 文件可以包含全局的 problemMatcher 属性或 tasks 属性，但不能同时包含两者。
     */
    tasks?: TaskDescription[];
}


/**
 * 传递给外部程序或 shell 的选项
 */
export interface CommandOptions {

    /**
     * 执行程序或 shell 的当前工作目录。如果省略，则使用当前工作区的根目录。
     */
    cwd?: string;

    /**
     * 执行程序或 shell 的环境变量。如果省略，则使用父进程的环境变量。
     */
    env?: { [key: string]: string };

    /**
      * 当任务类型为 `shell` 时的 shell 配置
      */
     shell: {

        /**
        * 要使用的 shell。
        */
        executable: string;

        /**
        * 要传递给 shell 可执行文件以命令模式运行的参数（例如 bash 的 ['-c'] 或 cmd.exe 的 ['/S', '/C']）。
        */
        args?: string[];
    }
}

/**
 * 任务的描述。
 */
interface TaskDescription {

    /**
     * 任务的名称
     */
    label: string;

    /**
     * 自定义任务的类型。类型为 "shell" 的任务在 shell（例如 bash, cmd, powershell 等）中执行
     */
    type: "shell" | "process";

    /**
     * 要执行的命令。如果类型为 "shell"，则应为包含所有附加参数的完整命令行。
     */
    command: string;

    /**
     * 是否将执行的命令保持活跃并在后台运行。
     */
    isBackground?: boolean;

    /**
     * 传递给命令的附加参数。如果类型为 "process" ，则使用。
     */
    args?: string[];

    /**
     * 定义任务所属的组。还支持将任务标记为组中的默认任务。
     */
    group?: "build" | "test" | { kind: "build" | "test"; isDefault: boolean };

    /**
     * 显示选项。
     */
    presentation?: PresentationOptions;

    /**
     * 用于捕获任务输出中问题的错误匹配器。
     */
    problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[];

    /**
     * 定义任务何时以及如何运行。
     */
    runOptions?: RunOptions;
}

interface PresentationOptions {

    /**
     * 控制任务输出是否在用户界面中显示。默认值为 `always`。
     */
    reveal?: "never" | "silent" | "always";

    /**
     * 控制任务相关的命令是否在用户界面中回显。默认值为 `true`。
     */
    echo?: boolean;

    /**
     * 控制显示任务输出的面板是否获取焦点。默认值为 `false`。
     */
    focus?: boolean;

    /**
     * 控制任务面板是否仅用于此任务（dedicated）、多个任务共享（shared）或在每次任务执行时创建新面板（new）。默认值为 `shared`。
     */
    panel?: "shared" | "dedicated" | "new";

    /**
     * 控制是否显示 `任务将重用终端，按任意键关闭` 消息。
     */
    showReuseMessage?: boolean;

    /**
     * 控制在运行此任务之前是否清除终端。默认值为 `false`。
     */
    clear?: boolean;

    /**
     * 控制任务是否在特定终端组中执行，使用分割窗格。属于同一组（由字符串值指定）的任务将使用分割终端呈现，而不是每个任务创建新的终端面板。
     */
    group?: string;
}

/**
 * 检测构建输出中问题的错误匹配器描述。
 */
interface ProblemMatcher {

    /**
     * 要使用的基本错误匹配器的名称。如果指定，则将使用基本错误匹配器作为模板，这里指定的属性将替换基本错误匹配器的属性。
     */
    base?: string;

    /**
     * 产生的 VS Code 问题的所有者。这通常是 VS Code 语言服务的标识符，用于将问题与语言服务产生的问题合并，或者为 'external'。如果省略，则默认为 'external'。
     */
    owner?: string;

    /**
     * 描述此问题来源的人类可读字符串。例如 'typescript' 或 'super lint'。
     */
    source?: string;

    /**
     * 由此错误匹配器产生的 VS Code 问题的严重性。
     *
     * 有效值为：
     *   "error": 产生错误。
     *   "warning": 产生警告。
     *   "info": 产生信息。
     *
     * 如果模式未指定严重性匹配组，则使用该值。省略时默认为 "error"。
     */
    severity?: string;

    /**
     * 定义在报告的问题模式中应如何读取文件名。有效值有：
     *  - "absolute": 文件名始终解析为绝对路径。
     *  - "relative": 文件名始终解析为相对路径，默认值。
     *  - ["relative", "路径值"]: 文件名始终解析为相对于给定路径值的相对路径。
     *  - "autodetect": 文件名首先解析为相对于当前工作目录的相对路径，如果文件不存在，则解析为绝对路径。
     *  - ["autodetect", "路径值"]: 文件名首先解析为相对于给定路径值的相对路径，如果不存在，则解析为绝对路径。
     *  - "search": 在目录中执行深度（且可能是耗时的）文件系统搜索。
     *  - ["search", {include: ["${workspaceFolder}"]}]: 在包含的目录中执行深度搜索。
     *  - ["search", {include: ["${workspaceFolder}"], exclude: []}]: 在包含的目录中执行深度搜索，排除“exclude”数组中命名的目录。
     */
    fileLocation?: string | string[] | ["search", {include?: string[]; exclude?: string[]}];

    /**
     * 预定义错误模式的名称，问题模式的内联定义，或用于与多行问题匹配的错误模式数组。
     */
    pattern?: string | ProblemPattern | ProblemPattern[];

    /**
     * 用于检测后台任务（例如 Gulp 中的监视任务）活动时是否的附加信息。
     */
    background?: BackgroundMatcher;
}

/**
 * 跟踪后台任务开始和结束的描述。
 */
interface BackgroundMatcher {

    /**
     * 如果设置为 true，则在任务启动时监视器处于活动模式。这等效于发出与 beginsPattern 匹配的行。
     */
    activeOnStart?: boolean;

    /**
     * 如果在输出中匹配到则表示后台任务的开始。
     */
    beginsPattern?: string;

    /**
     * 如果在输出中匹配到则表示后台任务的结束。
     */
    endsPattern?: string;
}

interface ProblemPattern {

    /**
     * 用于在执行任务的控制台输出中查找问题的正则表达式。
     */
    regexp: string;

    /**
     * 模式是匹配文件中的整个问题还是文件内的位置问题。
     *
     * 默认值为 "location"。
     */
    kind?: "file" | "location";

    /**
     * 文件名的匹配组索引。
     */
    file: number;

    /**
     * 问题位置的匹配组索引。有效的位置模式为：(line)、(line,column) 和 (startLine,startColumn,endLine,endColumn)。
     * 如果省略，则使用 line 和 column 属性。
     */
    location?: number;

    /**
     * 来源文件中问题行的匹配组索引。
     * 仅在 location 被指定时可以省略。
     */
    line?: number;

    /**
     * 来源文件中问题列的匹配组索引。
     */
    column?: number;

    /**
     * 来源文件中问题结束行的匹配组索引。
     *
     * 默认为 undefined。不会捕获结束行。
     */
    endLine?: number;

    /**
     * 来源文件中问题结束列的匹配组索引。
     *
     * 默认为 undefined。不会捕获结束列。
     */
    endColumn?: number;

    /**
     * 问题严重程度的匹配组索引。
     *
     * 默认为 undefined。在这种情况下，将使用问题匹配器的严重性。
     */
    severity?: number;

    /**
     * 问题代码的匹配组索引。
     *
     * 默认为 undefined。不会捕获代码。
     */
    code?: number;

    /**
     * 消息的匹配组索引。默认为 0。
     */
    message: number;

    /**
     * 指定在多行问题匹配器中的最后一个模式是否应在连续匹配行时循环。仅在多行问题匹配器的最后一个问题模式上有效。
     */
    loop?: boolean;
}

/**
 * 定义何时以及如何运行任务的描述。
 */
interface RunOptions {

    /**
     * 控制通过重新运行上一个任务命令执行任务时变量的评估方式。
     * 默认值为 `true`，即在重新运行任务时会重新评估变量。设置为 `false` 时，将使用上次运行任务时解析的变量值。
     */
    reevaluateOnRerun?: boolean;

    /**
     * 指定任务何时运行。
     *
     * 有效值为：
     *   "default": 任务仅通过运行任务命令执行。
     *   "folderOpen": 任务将在包含该文件夹打开时运行。
     */
    runOn?: string;
}