改进翻译

搭建 Kotlin/JS 项目

Kotlin/JS 项目使用 Gradle 作为构建系统。为了开发者轻松管理其 Kotlin/JS 项目,我们提供了 Kotlin/JS Gradle 插件。 该插件提供项目配置工具以及用以自动执行 JavaScript 开发中常用的例程的帮助程序。 举个例子,该插件会下载 Yarn 软件包管理器,在后台管理 NPM 依赖,并使用 Webpack 从 Kotlin 项目构建 JavaScript 包。

要在 IntelliJ IDEA 中创建 Kotlin/JS 项目,请转至 **File New Project**,
并选择 **Gradle Kotlin/JS for browser** 或 Kotlin/JS for Node.js。请不要勾选 Java 复选框。  

New project wizard

另外,你可以在 build.gradle 文件中手动将 org.jetbrains.kotlin.js 插件应用于 Gradle 项目。 如果你使用 Gradle Kotlin DSL,则可以使用插件 kotlin(“js”)

plugins {
    id 'org.jetbrains.kotlin.js' version '1.3.71'
}
plugins {
     kotlin("js") version "1.3.71"
}

Kotlin/JS 插件可让你在构建脚本的 kotlin 部分中管理项目的各个方面。

kotlin {
    //...
}

kotlin 部分中,你可以管理以下方面:

选择执行环境

Kotlin/JS 项目可以针对两个不同的执行环境:

  • Browser,用于浏览器中客户端脚本
  • Node.js,用于在浏览器外部运行 JavaScript 代码,例如,用于服务器端脚本。

要定义 Kotlin/JS 项目的目标执行环境,请在 target 部分添加 browser {}nodejs {}

kotlin {
    target {
        browser {
        }       
    }
}    

或者

kotlin.target.browser {     
}    

Kotlin/JS 插件会自动配置其任务与所选环境配合工作。 这项操作包括下载与安装运行和测试应用程序所需的依赖。 因此,开发者无需额外配置就可以构建、运行和测试简单项目。

管理依赖

就像其他任何的 Gradle 项目一样,Kotlin/JS 项目支持位于构建脚本的 dependencies 部分的传统 Gradle 依赖声明

dependencies {
    implementation 'org.example.myproject:1.1.0'
}
dependencies {
    implementation("org.example.myproject", "1.1.0")
}

Kotlin/JS Gradle 插件还支持构建脚本的 kotlin 部分中特定 sourceSets 的依赖声明。

kotlin {
    sourceSets {
        main {
            dependencies {
                implementation 'org.example.myproject:1.1.0'
            }
        }
    }
}
kotlin {
  sourceSets["main"].dependencies {
    implementation("org.example.myproject", "1.1.0")
  }
}

Kotlin 标准库

所有 Kotlin/JS 项目都必须依赖 Kotlin/JS 标准库。 如果你的项目包含用 Kotlin 编写的测试,则还应在添加 kotlin.test 依赖项

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-js'
    testImplementation 'org.jetbrains.kotlin:kotlin-test-js'
}
dependencies {
    implementation(kotlin("stdlib-js"))
    testImplementation(kotlin("test-js"))
}

NPM 依赖

在 JavaScript 中,管理依赖项的常用方法是 NPM。 它提供了最大的 JavaScript 模块公共存储库以及用于下载它们的工具。

Kotlin/JS 插件使你可以在 Gradle 构建脚本中声明 NPM 依赖项以及其他依赖项,并自动执行其他所有操作。 它安装了 Yarn 程序包管理器, 并使用它来将依赖项从 NPM 存储库下载项目的 node_modules 目录 ─── JavaScript 项目的 NPM 依赖项的一般位置。

要声明 NPM 依赖项,将其名称与版本传给依赖项声明内的 npm() 函数。

dependencies {
    implementation npm('react', '16.12.0')
}
dependencies {
    implementation(npm("react", "16.12.0"))
}

安装 NPM 依赖项后,你可以按照在 Kotlin 中调用 JS 中所述,在代码中使用其 API。

配置 run 任务

Kotlin/JS 插件提供了一个 run 任务,使你无需额外配置即可运行项目。 它使用 Webpack DevServer 来运行 Kotlin/JS 项目。 如果要自定义 DevServer 配置,请更改其端口,请使用 Webpack 配置文件。

要运行项目,请执行标准生命周期的 run 任务:

./gradlew run

要在浏览器中查看源文件更改而不想重新启动 DevServer,请使用 Gradle 连续构建(continuous build)

./gradlew run --continuous

或者

./gradlew run -t

配置 test 任务

Kotin/JS Gradle 插件会自动为项目设置测试基础结构。对于浏览器项目,它将下载并安装具有其他必需依赖的 Karma 测试运行程序; 对于 NodeJS 项目,使用 Mocha 测试框架。

该插件还提供了有用的测试功能,例如:

  • 源代码映射文件生成
  • 测试报告生成
  • 在控制台中测试运行结果

默认情况下,该插件使用 Headless Chrome 来运行浏览器测试。你还可以通过在构建脚本中的 useKarma 部分中添加相应的条目,从而在其他浏览器中运行它们 :

kotlin.target.browser {
    testTask {
        useKarma {
            useIe()
            useSafari()
            useFirefox()
            useChrome()
            useChromeCanary()
            useChromeHeadless()
            usePhantomJS()
            useOpera()
        }
    }       
}

如果要跳过测试,请将 enabled = false 这一行添加到 testTask 中。

kotlin.target.browser {
    testTask {
        enabled = false
    }
}

要运行测试,请执行标准生命周期 check 任务:

./gradlew check

配置 Webpack 绑定

对于浏览器目标,Kotlin/JS 插件使用众所周知的 Webpack 模块捆绑器。 为了配置项目捆绑,可以使用标准的 Webpack 配置文件。 Webpack 配置功能在其文档中有很好的描述。 对于 Kotlin/JS 项目,Webpack 配置文件位于项目根目录下的 webpack.config.d 目录中。

为了构建可执行的 JavaScript 构件,Kotlin/JS 插件包含 browserDevelopmentWebpack 以及 browserProductionWebpack 任务。

要使用 Webpack 构建项目构件,请执行 Gradle 任务 browserProductionWebpackbrowserDevelopmentWebpack

./gradlew browserProductionWebpack

分发目标目录

默认情况下,Kotlin/JS 项目构建的结果位于项目根目录下的 /build/distribution 目录中。

要为项目分发文件设置另一个位置,请在构建脚本中的 browser 里添加 distribution,然后为它的 directory 属性赋值。 运行项目构建任务后,Gradle 会将输出的内容和项目资源一起保存在此位置。

kotlin.target.browser {
    distribution {
        directory = file("$projectDir/output/")
    }
}
kotlin.target.browser {
    distribution {
        directory = File("$projectDir/output/")
    }
}