写技术文档的人都有过这种经历：画了一张架构图，旁边还得贴一段代码来解释某个模块的具体逻辑。图和代码分开放，读的人要来回跳。更糟糕的是用截图——分辨率不够、没法复制、改一行代码就得重新截。
如果图表里能直接放代码呢？不是截图，是真正的代码块，有语法高亮，能编辑，跟其他图形一起排版。
CodePic 新加了 Code 图形，就是干这个的。这篇文章讲怎么用它，以及它适合哪些场景。
什么场景需要在图里放代码
说几个最常见的。
API 设计文档。画一个请求流程图，客户端发请求到网关，网关转到服务，服务查数据库。这种图大家都会画。但是请求体长什么样？响应格式是什么？如果能在网关旁边放一个 JSON 代码块，一眼就清楚了，不用再翻另一个文档。
部署和运维流程。CI/CD 流水线里经常需要贴配置片段——Docker Compose、Nginx 配置、Kubernetes YAML。这些配置不长，但是很关键，放在流程图的对应节点旁边比塞在文档末尾有用得多。
代码评审和技术分享。review 的时候想跟同事解释一段代码的调用链，画个简单的流程图，把关键函数的代码片段直接嵌进去，比纯截图清晰，而且对方可以直接看到代码结构。
数据处理流程。数据从 A 系统流到 B 系统，中间经过清洗、转换、聚合。每一步的转换逻辑用一小段 SQL 或 Python 代码来标注，比文字描述「对字段 X 做分组聚合」精确得多。
怎么用 Code 图形
添加到画布
打开 CodePic 编辑器，左侧图形面板里找到 Code，点击或拖拽到画布上。默认会创建一个深色背景的代码块，里面有两行示例代码。
编辑代码
双击 Code 图形进入编辑状态。这时候你会看到一个带语法高亮的编辑器，可以直接输入代码。支持 Tab 缩进，编辑体验和普通代码编辑器差不多。按 Escape 或点击画布空白处退出编辑。
选择语言
选中 Code 图形后，在右侧属性面板（Inspector）或顶部浮动工具栏的代码设置里切换语言。目前支持 20 多种语言：
Bash、C、C++、CSS、Dockerfile、Go、HTML、Java、JavaScript、JSON、JSX、Kotlin、Markdown、PHP、Python、Ruby、Rust、SQL、Swift、TSX、TypeScript、YAML。
切换语言后，语法高亮会立刻更新。CodePic 会记住你上次选择的语言，下次创建 Code 图形时自动使用。
深色和浅色主题
Code 图形支持两种主题：深色（Dark）和浅色（Light）。深色主题用的是 Catppuccin Mocha 配色，浅色主题用 GitHub Light。在属性面板里一键切换。下面是两种主题和多语言支持的效果：
如果你的图表背景是浅色的，建议用深色主题的代码块，对比更明显。反过来也一样。
行号和 Tab 宽度
默认显示行号，可以在设置里关掉。Tab 宽度支持 2、4、8 三个选项，默认是 4。
自动换行
这个设置影响 Code 图形的尺寸行为：
-
关闭自动换行（默认）：代码不换行，图形的宽度和高度会自动适应内容。你输入多长的代码，图形就有多宽。这个模式适合代码行比较短的情况。
-
开启自动换行：代码会在图形边界处按单词换行，宽度由你手动控制，高度自动适应换行后的内容。这个模式适合你需要固定宽度的场景。
有个快捷行为：如果你手动拖拽调整了 Code 图形的大小，会自动切换到「自动换行」模式。因为手动调大小说明你想控制宽度，这时候自动换行才合理。
实战：画一个 API 请求流程
举个具体例子。假设你要画一个用户登录的 API 流程图，想让读者一眼看到请求和响应的格式。
-
画三个矩形：「客户端」「API 网关」「用户服务」，用连接线串起来。
-
在「客户端」旁边放一个 Code 图形，语言选 JSON，输入请求体：
{
"email": "[email protected]",
"password": "********"
}
- 在「用户服务」旁边放另一个 Code 图形，输入响应：
{
"token": "eyJhbGciOiJIUzI1NiJ9...",
"user": {
"id": "u_abc123",
"email": "[email protected]"
}
}
- 用连接线把代码块和对应的模块连起来。
最终效果是一张图里既有流程，又有数据格式，不需要读者在图表和文档之间跳来跳去。
和其他方式比怎么样
截图贴代码。很多人的做法是在 IDE 里截图，然后作为图片插入图表。问题很明显：分辨率差、没法编辑、改一个字符就要重新截。Code 图形是可编辑的文本，随时改，而且支持语法高亮。
Mermaid / PlantUML。这类工具很擅长画流程图和时序图，但它们的代码块支持有限。你没法在一个 Mermaid 图里嵌入一段带 Python 语法高亮的代码片段。Code 图形是画布上的独立元素，和矩形、连接线一样自由组合。
纯文字标注。在图形里写一行「调用 /api/login」当然可以，但如果你想展示完整的请求体或一段关键逻辑，文字标注就不够了。代码块天然适合这类结构化内容。
总结
Code 图形解决的是一个很具体的问题：技术图表里经常需要放代码，但传统画图工具不支持。
现在你可以在 CodePic 里把代码块和流程图、架构图混在一起用。语法高亮、行号、主题切换、自动换行，该有的都有。直接打开 CodePic 编辑器 试试。
