Kotlin Notebook

Kotlin Notebook 为 IntelliJ IDEA 带来了笔记的多功能性。

笔记本是集成代码、图形和文本于单一环境中的互动编辑器。当使用 notebook 时，您可以运行代码单元并立即看到输出，获得实时代码洞察。

Kotlin Notebook 是一个插件，允许您在 IntelliJ IDEA 生态系统中使用 Kotlin 进行编码时顺畅创建和编辑笔记本。

Kotlin Notebook 提供了一套丰富的工具来处理任务，例如：

数据分析与可视化：您可以直观地检索、转换、绘制和建模您的数据，同时在编码时获取操作的输出。
原型设计：您可以分小段运行代码并实时查看结果。这个实操环境能够实现快速试验与迭代。
探索和测试 API： Kotlin Notebook 提供在单元格内调用 API 并与外部服务交互的功能。
代码文档：您可以在代码单元格中包含内联注释，并在 Markdown 单元格中进行文本注释，以提供进一步的上下文、解释、说明等。

此外，您可以毫无问题地在 Kotlin Notebook、 Datalore 和 Kotlin-Jupyter Notebook 之间轻松分享您的工作。这种兼容性之所以可能，是因为 Kotlin Notebook 基于我们的 Kotlin Kernel ，确保我们的不同 Kotlin notebook 解决方案之间的无缝集成。

请查看以下各部分，了解 Kotlin Notebook 的用途和主要功能！

安装插件

通过从 JetBrains Marketplace下载来安装 Kotlin Notebook 插件。确保您使用最新版本的插件和 IntelliJ IDEA Ultimate。

或者，从设置 | 插件 | 市场访问 IntelliJ IDEA Ultimate 中的 Kotlin Notebook 插件。

创建笔记本

一旦您在 IntelliJ IDEA Ultimate 中安装了插件，选择文件 | 新建 | Kotlin Notebook 以创建一个新的笔记本。

或者，右键点击您想要定位笔记本的目录并选择新建 | Kotlin 笔记本。

创建了一个扩展名为 .ipynb 的文件。

Starting from IntelliJ IDEA 2024.1.1，您还可以通过选择文件 | 新建 | 临时文件，将 Kotlin Notebook 创建为一个临时文件。可以使用草稿文件来测试小段代码，而无需创建新项目或修改现有项目。

管理您的笔记本

在您的 Kotlin Notebook 顶部，您可以找到笔记本工具栏。此工具栏包含用于快速单元格操作的按钮，使您能够动态运行或修改代码并立即查看输出。

您可以从工具栏执行的主要操作有：

在下方添加代码单元格
剪切选区
复制选定内容
粘贴选择
上移单元格
下移单元格
运行单元并选择下方
中断内核
重启内核
运行所有单元格
清除输出
删除单元格
代码选择单元格类型
创建 gist
查看 Kotlin Notebook 设置

在处理笔记本时，每个单元格都会对笔记本的整体状态做出贡献，但只有在您运行单元格之后。笔记本中单元格的顺序并不重要，但执行单元格的顺序确实重要。

例如，使用库时，尽管您可以随时运行任何单元格，但需要在运行调用库的单元格之前运行导入库的单元格。

与传统编程不同，notebooks 允许您在不同的单元格中声明多个具有相同名称的变量。但是，每次使用相同名称的新变量声明都会覆盖之前的声明。只有您运行的最新声明在后续单元格中有效。

通常，笔记本在后台运行代码，这可能在合并单元格时导致意外行为。这种行为的原因是，如果其中一个合并的单元格包含修改环境的代码，这些更改可能不会立即反映在后续单元格中。

笔记本可能对某些语言结构有限制。一般而言，只允许有效的函数级别操作，例如在函数体内工作。

访问 Kotlin Notebook API

您可以在单元格中直接访问 Kotlin Notebook API。 Kotlin Notebook API 提供自定义和配置您的笔记本行为的功能，例如处理输出、从以前执行的代码片段中检索信息、与库的无缝集成等。

例如， notebook 是 Kotlin Notebook API 的入口点。您可以使用 notebook 与某些方法结合来检索笔记本的见解，例如执行的代码单元或声明的变量。

添加依赖项

您可以轻松地从远程 Maven 仓库或本地仓库（本地 JAR）向您的笔记本添加动态依赖项。要添加依赖项，您有两种选择：注解或类似 Gradle 的语法。

使用注解添加依赖

在 Kotlin Notebook 中有两种注解来管理依赖项：

@file:DependsOn(): 在此注解中，您需要指定依赖项的坐标。此注解会将工件（如 JAR 文件）添加到笔记本的类路径中。它支持类目录或 JAR 的绝对路径和相对路径，以及 Ivy 和 Maven 工件：
@file:DependsOn(“io.ktor:ktor-client-core-jvm:$ktorVersion“)
@file:Repository(): 在此注释中，您需要指定依赖项的绝对路径。此注释会将目录或 Ivy 或 Maven 仓库添加到笔记本环境中。要指定 Maven 本地仓库，请使用 @file:Repository("*mavenLocal")。

使用类 Gradle 语法添加依赖项

您可以在任何单元中使用类似 Gradle 的语法从 Maven 仓库加载任何库，指定仓库、位置等：

                USE {
                    repositories {
                        maven {
                            url = "https://my.secret.repo/maven/"
                            credentials {
                                username = USER
                                password = TOKEN
                            }
                        }
                    }

                    dependencies {
                        val ktorVersion = "2.0.3"

                        implementation("my.secret:artifact:1.0-beta")
                        implementation("io.ktor:ktor-client-core:$ktorVersion")
                        implementation("io.ktor:ktor-client-apache:$ktorVersion")
                    }
                }
            
   

使用行内魔法

Kotlin Notebook 提供了一些以 % 字符开头的特殊命令，这些命令可以逐行与笔记本交互。这些命令被称为行魔术，允许您导入库、配置输出设置并执行更多操作。

导入支持的库

Kotlin Notebook 配备了一套集成库，用于执行各种任务，从深度学习到 HTTP 网络。您可以通过在库的名称前运行 %use 行魔法来导入这些集成库。

与 %use 关键字一起，您可以指定特定的库版本或使用单个 %use 语句包含多个库。

集成新的库

您可以添加和使用尚未集成到 Kotlin Notebook 中的库。有两种集成新库的方法：创建 JSON 库描述符或使用 Kotlin Notebook API。

创建 JSON 库描述符

为了支持新的库并通过 %use 行魔法使其可用，您需要创建库描述符。库描述符是一个 .json 文件，用于定义最常见的库功能，如属性、渲染器和初始导入：

此示例显示了在库描述符中定义的自定义渲染器的用法：

                USE {
                    render<Int> { "[$it]" }
                }
            
   

使用 Kotlin Notebook API

要使用 Kotlin Notebook API 添加一个新库，您需要在库中定义一个集成类，并确保集成类名在当前 notebook 类路径中。

一旦您定义了 integration 类，您可以利用 Kotlin Notebook API 提供的所有 integration 功能。这些功能促进了您的库与 Kotlin Notebook 环境之间的无缝互动。

您可以使用可用的集成功能，直接从笔记本单元格中利用 USE {} block 以及该功能方法。这里是使用 import () 方法的示例：

                USE {
                    import("my.awesome.Clazz")
                }
            
   

使用 REPL 命令

使用REPL命令来探索您的notebook环境，了解classpath，并在执行过程中检查变量的值。

Kotlin Notebook 支持以下 REPL 命令：

`:help`	显示有关笔记本版本、行魔术命令和支持库的详细帮助信息。
`:classpath`	显示笔记本环境的当前 classpath，展示笔记本搜索库和资源的位置列表。
`:vars`	显示有关声明变量及其值的信息。

渲染并显示丰富的输出

默认情况下，Kotlin Notebook 以文本形式显示返回值。不过，您可以通过渲染图形、HTML 或其他 MIME 编码的数据格式来丰富输出。

一种方法是使用 MIME 辅助函数将MIME编码的结果发送给客户端。另一种方法是使用 HTML 文件 助手函数，这提供了一种更简单的方法来直接显示 HTML 内容。请参阅我们在 GitHub 上的 Kotlin-Jupyter 仓库中的这些函数示例。

除此之外，Kotlin Notebook 支持渲染值的各种功能和机制：

渲染器将值转换为其他表示形式。渲染器通过 RenderersProcessor 方法进行控制，您可以通过 notebook API entry point 访问。
DisplayResult 和 Renderable: 实现 DisplayResult 和 Renderable 接口的对象将被渲染为输出 JSON。
文本渲染：使用文本渲染器将对象渲染为字符串。文本渲染器通过 TextRenderersProcessor 方法进行控制，您可以通过 notebook API 入口点访问它。
Throwable 渲染： Throwable 渲染器的行为与常规渲染器相同，但在单元格执行期间处理生成的异常和错误。

拖放数据文件

通过简单的拖放功能轻松检索数据，将项目目录中的数据带到 notebook 单元格中。

只需点击几下，加载 CSV、XLS 和 JSON 文件，并将它们置于类似数据框的结构中，准备处理。查看下方视频，了解拖放功能的实际操作。

导出数据和图形

就像加载数据一样，您可以通过点击单元格中的导出选项直观地导出数据和图形。

分析错误

当代码出现意外情况时，Kotlin Notebook 会在输出单元格中显示错误信息和堆栈跟踪，为调试提供见解。

最佳实践

Kotlin Notebook 是 Jupyter Notebooks 的一种变体，并且具有类似的内部结构。

当您打开 notebook 并运行第一个 cell 时，notebook 会在后台创建一个 session。此会话与内核通信，内核在整个工作过程中跟踪笔记本的运行时状态。

与常规 Kotlin 文件相比，使用 notebook 进行工作有一些影响：

当会话开始时，您选择作为笔记本依赖项的项目依赖项将被编译并添加到内核的类路径中。由于这个原因，如果您对项目代码进行更改，这些更改仅在重新启动内核后才会在笔记本中可用。
重新启动内核在内核变得无响应或对环境进行重大更改时非常有用。此操作将终止当前运行的环境，清除所有已声明的变量、函数和对象。
笔记本的状态结合了运行时和编译时的各个方面。为此，重启内核会从笔记本的内存中清除所有先前评估的变量。如果一个单元格依赖于另一个单元格的输出，这可能会导致未解析符号错误。
中断内核仅暂停当前运行的单元格，不会终止整个环境。此操作在您需要暂停和恢复执行时非常有用，例如，当单元格运行时间过长时。
您在单元格中添加的依赖项只有在运行这些单元格后才会生效。这意味着，如果您添加了一个依赖项并尝试在同一个单元格中使用该依赖项，依赖项中的符号将在您首次运行该单元格之前被标记为未解析。
您可以独立运行这些单元格，顺序随意，与它们在笔记本中的位置无关。笔记本的运行时状态取决于执行顺序，而不是笔记本中单元格的位置。
您运行的单元格会标有一个数字，表示执行顺序。另一方面，尚未运行的单元格标有一个 * 符号。如果您重新启动 kernel 并点击全部运行按钮，所有代码单元将按顺序运行。每个单元格都标有一个与其执行顺序相匹配的编号。当您运行所有单元时，执行从上到下开始，因此顺序自然与笔记本中单元的位置对齐。
我们建议在重启内核后点击全部运行按钮。通过运行所有单元格，这些单元格将按正确的顺序执行，在内存中重新创建必要的变量和函数。

最后修改日期： 2025年 4月 24日