---
title: "Notebook"
description: "打开、编辑并用本地 Python 内核运行 Jupyter 笔记本（.ipynb）。"
---

OpenIDEA 用笔记本编辑器打开 `.ipynb` 文件。你可以编辑代码单元格和 Markdown 单元格，在 IDE 自动启动的 Python 内核上运行，并把结果保存回原文件。

## 前提条件

- 一个装好 **ipykernel** 的 Python 解释器（`pip install ipykernel`）。OpenIDEA 不会替你安装任何包；缺少 ipykernel 时，编辑器会提示“请在所选 Python 环境中安装 ipykernel，然后重启内核”。
- 项目已受信任。项目处于受限模式时无法运行单元格。
- 笔记本格式为 nbformat 4。其他版本会被拒绝打开，文件不会被改动。

## 打开笔记本

从项目工具窗口、转到文件或命令行打开任意 `.ipynb` 文件，它会以笔记本编辑器打开，而不是原始 JSON。

编辑器顶部工具栏：

| 控件                           | 作用                                                       |
| ------------------------------ | ---------------------------------------------------------- |
| **运行单元格**                 | 运行选中的代码单元格。                                     |
| **运行全部**                   | 从上到下运行所有代码单元格，遇到第一个出错的单元格就停止。 |
| **中断内核**                   | 中断正在运行的单元格。                                     |
| **重启内核**                   | 重启内核，清空其状态。                                     |
| 解释器下拉框                   | 当前笔记本使用的 Python 解释器（**选择 Python 解释器**）。 |
| **刷新 Python 解释器**         | 重新检测 Python 环境。                                     |
| 内核状态                       | `正在启动`、`空闲`、`忙碌` 或 `已终止`。                   |
| **撤消** / **重做** / **保存** | 笔记本级别的撤销、重做和保存。                             |
| **从磁盘重新加载笔记本**       | 放弃未保存的更改、停止执行并重新加载文件。                 |

## 选择 Python 解释器

下拉框里列出 OpenIDEA 检测到的 Python 环境，以及项目解释器。如果不手动选择，笔记本会使用项目的 Python 解释器；没有配置时使用检测到的第一个环境。

选择结果按笔记本分别记住。只能在没有单元格运行时切换。

<Tip>
  使用虚拟环境时，请选择环境自己的 `python`（例如 `.venv/bin/python`）。OpenIDEA
  不会把符号链接解析成基础解释器，所以内核就运行在这个环境里。
</Tip>

每个打开的笔记本各有一个内核进程，关闭笔记本时内核随之关闭。

## 编辑单元格

每个单元格都有一个小工具栏：

- **单元格类型**下拉框：**代码**、**Markdown** 或 **原始内容**。
- 代码单元格有 **运行单元格**；Markdown 单元格有 **编辑 Markdown** / **预览 Markdown**。双击已渲染的 Markdown 单元格也可以进入编辑。
- **上移单元格**、**下移单元格**、**在下方插入代码单元格**、**删除单元格**。

笔记本末尾的 **添加代码单元格** 和 **添加 Markdown 单元格** 用于在最后追加单元格。

代码单元格的工具栏旁显示执行序号（如 `[3]`）。原始单元格和 OpenIDEA 不认识的单元格类型以只读方式显示，内容原样保留。

## 代码智能

和 `.py` 文件一样，代码单元格可以使用项目 Python 语言服务器提供的补全、悬停快速文档、参数信息和错误高亮。语言服务器按顺序读取代码单元格，所以前面单元格定义的名称在后面的单元格里可以识别；`%matplotlib inline`、`!pip list` 这类 IPython 语法也不会被报成错误。

按住 `⌘`（macOS）或 `Ctrl`（Windows/Linux）点击名称，可以跳转到它的声明，无论声明在其他单元格还是库中。

这需要支持笔记本的语言服务器：**basedpyright**（默认）和 **Ruff** 都支持。使用其他 Python 语言服务器时，代码单元格只有语法高亮。

## 快捷键

| 操作                 | 按键                                                                          |
| -------------------- | ----------------------------------------------------------------------------- |
| 运行选中的代码单元格 | `⇧Enter` 或 `⌃Enter`（macOS），`Shift+Enter` 或 `Ctrl+Enter`（Windows/Linux） |
| 保存                 | `⌘S` / `Ctrl+S`                                                               |
| 撤销                 | `⌘Z` / `Ctrl+Z`                                                               |
| 重做                 | `⌘⇧Z` / `Ctrl+Shift+Z` 或 `Ctrl+Y`                                            |

这些按键由笔记本编辑器直接处理，不在键位映射设置里。

## 输出

和 Jupyter 一样，输出会在保存时写入笔记本文件。

| 输出                                       | 显示方式                                                    |
| ------------------------------------------ | ----------------------------------------------------------- |
| `stdout` / `stderr` 流                     | 带 ANSI 颜色的文本，`stderr` 会突出显示。                   |
| 错误                                       | 显示 traceback。                                            |
| `image/png`、`image/jpeg`、`image/svg+xml` | 内联图片。                                                  |
| `text/html`                                | 在沙箱中显示静态 HTML：不执行脚本、不联网，只显示内嵌图片。 |
| `text/plain`                               | 文本。                                                      |
| `application/javascript`                   | 只显示源码，不执行。                                        |
| 其他 MIME 类型                             | 显示提示，数据仍保留在文件中。                              |

## 限制

- 只支持 Python 内核，不支持其他语言的内核，也不能连接远程 Jupyter 服务器。
- 交互式组件（ipywidgets）和 JavaScript 输出不会运行。
- 单元格运行期间不能撤销或重做。