Carbon 完整使用指南将源代码一键渲染为精美 PNG/SVG 图片【免费下载链接】carbon:black_heart: Create and share beautiful images of your source code项目地址: https://gitcode.com/gh_mirrors/ca/carbon本文围绕开源项目 Carbon项目描述Create and share beautiful images of your source code当前仓库版本 4.9.10的官方波兰语文档 docs/README.pl.md 展开。Carbon 是一个基于 Next.js 的在线代码美化工具它把代码编辑器与图片生成器合二为一你只需要把代码粘贴进去、调整主题与样式就能导出一张可以直接发到 Twitter、Slack 或博客的精美代码截图。读完本文你将完整掌握代码导入、样式定制、snippet 保存、嵌入网页、一键 Tweet、PNG/SVG 导出以及离线桌面安装的全套实战方案并能从源码层面理解 URL 参数如何驱动整个渲染管线。一、Carbon 能做什么三大核心特性官方文档将 Carbon 的核心能力概括为三点高度可定制Dostosowywanie可以调整图片的语法高亮主题、字体风格、背景色、窗口主题、内边距、阴影等视觉元素快速分享Udostępniaj szybko一键保存图片或生成分享链接保存 SnippetZapisz snippety注册账号即可保存代码片段供日后使用被分享的 snippet 会在 Twitter、Slack 等平台上自动展开unfurl成图片预览同时保留指向源码的链接。从仓库源码看这些能力都有扎实的实现支撑。默认配置集中在 lib/constants.js 的DEFAULT_SETTINGS中包含 13 种等宽字体FONTS如 Anonymous Pro、Fira Code、Hack、JetBrains Mono、IBM Plex Mono 等、27 套语法主题THEMES如 Dracula、Monokai、Night Owl、Nord、One Dark、One Light、SynthWave 84、Verminal 等、80 种编程语言LANGUAGES以及 1x / 2x / 4x 三种导出倍率EXPORT_SIZES。二、快速上手三种方式把代码导入 Carbon官方文档介绍了三种导入代码的方式均可在 Carbon 编辑器中直接使用把文件拖拽进编辑器拖放任意文本或图片文件到编辑区域即可导入。在源码层面components/Editor.js 的onDrop处理器会根据file.type判断图片文件会被设置为背景图backgroundMode: image其余文件内容则直接写入代码区并自动将语言切换为auto在 URL 后追加 GitHub Gist ID例如访问carbon.now.sh/gist_id即可直接加载该 gist 的代码。路由解析见 lib/routing.js 的getRouteState其中parameter的判定条件是路径长度不小于 19 且不含点号满足条件才会被当作 gist/snippet ID 去请求直接开始输入打开首页即可在 CodeMirror 编辑器中键入代码默认示例代码定义在 lib/constants.js 的DEFAULT_CODE。此外编辑器内置的Dropzone来自dropperx在整个编辑区上覆盖了拖放监听acceptimage/*, text/*, application/*意味着常见的源码文件、文本文件和图片都能被接受。三、样式定制从主题到细节的完整参数体系代码就位后就可以对图片进行全面的视觉定制。官方文档提到可以修改语法主题、背景颜色、窗口主题、内边距、阴影、字体等。结合源码这些选项实际对应DEFAULT_SETTINGS中的配置项配置项默认值说明themeseti语法高亮主题可在 27 套主题间切换backgroundColorrgba(171, 184, 195, 1)背景颜色支持 RGBA 半透明backgroundModecolor背景模式可切换为image使用 Unsplash 随机图或本地图片windowThemenone窗口主题如 Mac 风格窗口条windowControlstrue是否显示窗口右上角红黄绿控制按钮paddingVertical/paddingHorizontal56px/56px代码四周内边距dropShadow/dropShadowOffsetY/dropShadowBlurRadiustrue/20px/68px投影开关、偏移与模糊半径fontFamily/fontSize/lineHeightHack/14px/133%字体、字号与行高lineNumbers/firstLineNumberfalse/1行号开关与起始行号width/widthAdjustment680/true画布宽度与宽度自适应exportSize2x导出倍率1x / 2x / 4xwatermark/squaredImagefalse/false水印与方形图裁剪hiddenCharactersfalse是否显示不可见字符自定义主题也是一等公民THEMES数组中每个主题都带一套highlights色板涵盖background、text、keyword、string、comment、number等 tokencomponents/Editor.js 的createTheme/removeTheme支持在运行时新增或删除主题创建的主题会立即生效并可通过 components/Themes/GlobalHighlights.js 注入全局高亮样式。仓库还内置了 8 套一键预设DEFAULT_PRESETS例如蓝色背景 Material 主题 Fira Code或紫色背景 Verminal 主题快速套用即可获得杂志封面级的排版效果下列两张图分别为默认预设与预设样式的实际渲染效果四、URL 参数驱动分享状态的底层机制Carbon 最巧妙的设计之一是整套编辑器状态都能编码进 URL 查询参数这也是文档中复制链接即可分享功能得以实现的基础。状态映射定义在 lib/routing.js常用参数如下参数对应配置参数对应配置bg背景颜色t语法主题wt窗口主题l语言width画布宽度ds是否启用投影dsyoff/dsblur投影偏移 / 模糊半径wc窗口控制按钮wa宽度自适应pv/ph垂直 / 水平内边距ln行号fl起始行号fm/fs/lh字体 / 字号 / 行高si方形图es导出倍率wm水印sl选中高亮行code编码后的代码内容copy/readonly嵌入时是否可复制 / 只读tb标题栏文字布尔参数如ds、ln、wc通过bool类型解析器将false之外的任意值视为真code参数经过decodeURIComponent解码后作为代码内容载入。这意味着你可以把一段代码连同全部样式打包进一个链接接收方打开链接即看到完全相同的渲染结果。五、导出与分享六大发布途径全解析官方文档指出图片定制完成后可以通过多种方式发布 snippet下面逐一展开含源码佐证。5.1 创建已保存的 Snippet保存 snippet 是推荐的长效分享方式——它在 Twitter、Slack 上自动展开图片同时让读者通过链接访问源码日后想更新直接打开链接编辑即可。操作步骤点击Sign in/Sign up登录/注册按钮登录正常编辑代码——snippet 会自动保存复制浏览器地址栏的 URL 分享出去。源码层面components/Editor.js 的handleSnippetCreate/handleSnippetUpdate调用 API 层lib/api.js的snippet.create/snippet.update编辑操作会经debounce(…, 750)防抖后自动同步到服务端完成后界面会弹出 Snippet created / Snippet saved 提示底部的 components/SnippetToolbar.js 还提供删除handleSnippetDelete能力。5.2 嵌入 snippet 到自己的网站或博客官方文档明确指出这是在个人网站或博客上分享 Carbon 的推荐方式读者甚至能一键复制代码。实现路径有两条直接在页面中嵌入carbon.now.sh/embed开头的 URL通过Copy Menu复制现成的 iframe 代码片段或复制经过编码的 URL 用于 Medium 等平台也可以嵌入已保存的 snippet 或 GitHub gistcarbon.now.sh/embed/:id。看源码嵌入页 pages/embed/[id].js 在服务端getServerSideProps按 ID 拉取 snippet 数据同样以路径长度 ≥ 19 且不含点号判定 ID未找到时 302 跳回/embed。pages/embed/index.js 中嵌入页以只读模式渲染且支持copy、readonly查询参数控制交互并通过postMessage把自身高度上报给父页面context: iframe.resize实现 iframe 自动伸缩。components/CopyMenu.js 的toIFrame会基于当前 Carbon 节点的实际宽高生成带sandboxallow-scripts allow-same-origin的 iframe 代码宽度默认 1024px、高度默认 473px。5.3 使用 Tweet 按钮Tweet 按钮不仅把图片分享到 Twitter还会正确编码alt文本以保证图片的无障碍访问。源码佐证见 lib/api.js 的tweet函数它先通过/api/twitter上传图片数据并把代码内容作为altText提交随后拼接出https://twitter.com/intent/tweet?text…打开新窗口若触发 Twitter 限流HTTP 420界面会给出友好提示。若你想自行发推可参考 Twitter 官方的图片描述说明来手动添加 alt 文本。5.4 直接下载图片PNG / SVGCarbon 支持把图片下载为PNG 和 SVG两种格式具体操作路径Export → PNG下载位图Export → SVG下载矢量图Export → Open在浏览器新标签中直接打开图片Copy → Image直接把图片复制到系统剪贴板。实现细节见 components/ExportMenu.js 与 components/Editor.js导出时先按exportSize1x/2x/4x对 DOM 节点做scale变换再由 lib/dom-to-image.js 生成图片SVG 输出会额外做实体转义、%23→#还原、清理未使用字体等后处理源码中有对应注释。导出菜单还支持自定义文件名并绑定了两个快捷键⌘-⇧-E快速导出 PNG、⌘-⇧-S导出 SVG复制图片的快捷键是⌘-⇧-C依赖navigator.clipboard与ClipboardItem仅在不支持剪贴板 API 时隐藏入口。5.5 其他分享方式上传到 ImgurbetaShare 菜单提供Upload to Imgur (beta)按钮调用 lib/api.js 的imgur函数上传并返回图床链接Plain URL / MediumCopy Menu 中的 Plain URL 直接复制当前页面链接Medium.com 则对 URL 做encodeURI编码并针对 Medium 不识别*的问题做%2A替换方便直接粘贴进 Medium 文章。六、离线桌面使用以 PWA 方式安装 Carbon如果你使用 Google Chrome 或其他支持渐进式 Web 应用PWA的浏览器可以像安装原生应用一样离线使用 Carbon访问carbon.now.sh点击浏览器右上角的设置菜单点击Install Carbon...安装 Carbon。安装后即可获得独立的桌面窗口和离线缓存能力即使断网也能继续编辑与导出图片。七、社区生态编辑器插件与周边工具官方文档罗列了社区围绕 Carbon 构建的丰富生态本文仅作文字介绍详细链接见原文档 docs/README.pl.md编辑器插件IntelliJ IDEA右键菜单直接打开当前选中代码、Atomshift-cmd-A、VS Codecarbon命令、Sublime Text 3自定义快捷键、Vim/NeovimCarbonNowSh()函数、Emacs交互函数carbon-now-sh、XcodeCarboNow4Xcode扩展及nef插件——均可在各自编辑器中一键把代码送入 Carbon命令行工具carbon-now-cli支持在终端打开文件或直接下载图片具备交互模式与选择性高亮nef可从Xcode Playground批量导出 Carbon snippetcarbonate让你在 R 语言中迭代调整图片美学其他工具Telegram 机器人carbonshbot接收代码片段或 gist URL 后生成图片CodeExpander 是具备 TextExpander 特性的智能 GitHub gist 客户端书籍引用计算机科学教材《CS 101 - An Introduction to Computational Thinking》也使用了 Carbon。八、本地开发与运行如果你想在本地体验或二次开发 Carbon可参考 package.json 中的脚本Node.js 版本要求12Next.js 12 架构npm install # 安装依赖也可使用仓库附带的 yarn.lock npm run dev # 启动开发服务器next dev npm run build # 生产构建next build npm start # 启动生产服务next start npm run test:e2e # 运行 Cypress 端到端测试端到端测试用例位于 cypress/integration覆盖背景色、基础交互、嵌入、gist、localStorage、安全与视觉回归等场景例如 cypress/integration/basic.spec.js、cypress/integration/embed.spec.js可帮助你快速验证关键流程的正确性。结语Carbon 的价值在于把截图代码这件事从繁琐的取色、加阴影流程中解放出来导入代码 → 选择主题与排版 → 一键导出或嵌入全程可视化且状态可随 URL 传递。本文结合官方文档与 lib/constants.js、lib/routing.js、components/Editor.js 等源码完整覆盖了从导入、定制、导出到嵌入、离线安装与社区生态的全部环节。无论你是想给博客配一张精致的代码图还是在团队文档中嵌入可复制的片段Carbon 都是一套开箱即用的解决方案。【免费下载链接】carbon:black_heart: Create and share beautiful images of your source code项目地址: https://gitcode.com/gh_mirrors/ca/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Carbon 完整使用指南：将源代码一键渲染为精美 PNG/SVG 图片
Carbon 完整使用指南将源代码一键渲染为精美 PNG/SVG 图片【免费下载链接】carbon:black_heart: Create and share beautiful images of your source code项目地址: https://gitcode.com/gh_mirrors/ca/carbon本文围绕开源项目 Carbon项目描述Create and share beautiful images of your source code当前仓库版本 4.9.10的官方波兰语文档 docs/README.pl.md 展开。Carbon 是一个基于 Next.js 的在线代码美化工具它把代码编辑器与图片生成器合二为一你只需要把代码粘贴进去、调整主题与样式就能导出一张可以直接发到 Twitter、Slack 或博客的精美代码截图。读完本文你将完整掌握代码导入、样式定制、snippet 保存、嵌入网页、一键 Tweet、PNG/SVG 导出以及离线桌面安装的全套实战方案并能从源码层面理解 URL 参数如何驱动整个渲染管线。一、Carbon 能做什么三大核心特性官方文档将 Carbon 的核心能力概括为三点高度可定制Dostosowywanie可以调整图片的语法高亮主题、字体风格、背景色、窗口主题、内边距、阴影等视觉元素快速分享Udostępniaj szybko一键保存图片或生成分享链接保存 SnippetZapisz snippety注册账号即可保存代码片段供日后使用被分享的 snippet 会在 Twitter、Slack 等平台上自动展开unfurl成图片预览同时保留指向源码的链接。从仓库源码看这些能力都有扎实的实现支撑。默认配置集中在 lib/constants.js 的DEFAULT_SETTINGS中包含 13 种等宽字体FONTS如 Anonymous Pro、Fira Code、Hack、JetBrains Mono、IBM Plex Mono 等、27 套语法主题THEMES如 Dracula、Monokai、Night Owl、Nord、One Dark、One Light、SynthWave 84、Verminal 等、80 种编程语言LANGUAGES以及 1x / 2x / 4x 三种导出倍率EXPORT_SIZES。二、快速上手三种方式把代码导入 Carbon官方文档介绍了三种导入代码的方式均可在 Carbon 编辑器中直接使用把文件拖拽进编辑器拖放任意文本或图片文件到编辑区域即可导入。在源码层面components/Editor.js 的onDrop处理器会根据file.type判断图片文件会被设置为背景图backgroundMode: image其余文件内容则直接写入代码区并自动将语言切换为auto在 URL 后追加 GitHub Gist ID例如访问carbon.now.sh/gist_id即可直接加载该 gist 的代码。路由解析见 lib/routing.js 的getRouteState其中parameter的判定条件是路径长度不小于 19 且不含点号满足条件才会被当作 gist/snippet ID 去请求直接开始输入打开首页即可在 CodeMirror 编辑器中键入代码默认示例代码定义在 lib/constants.js 的DEFAULT_CODE。此外编辑器内置的Dropzone来自dropperx在整个编辑区上覆盖了拖放监听acceptimage/*, text/*, application/*意味着常见的源码文件、文本文件和图片都能被接受。三、样式定制从主题到细节的完整参数体系代码就位后就可以对图片进行全面的视觉定制。官方文档提到可以修改语法主题、背景颜色、窗口主题、内边距、阴影、字体等。结合源码这些选项实际对应DEFAULT_SETTINGS中的配置项配置项默认值说明themeseti语法高亮主题可在 27 套主题间切换backgroundColorrgba(171, 184, 195, 1)背景颜色支持 RGBA 半透明backgroundModecolor背景模式可切换为image使用 Unsplash 随机图或本地图片windowThemenone窗口主题如 Mac 风格窗口条windowControlstrue是否显示窗口右上角红黄绿控制按钮paddingVertical/paddingHorizontal56px/56px代码四周内边距dropShadow/dropShadowOffsetY/dropShadowBlurRadiustrue/20px/68px投影开关、偏移与模糊半径fontFamily/fontSize/lineHeightHack/14px/133%字体、字号与行高lineNumbers/firstLineNumberfalse/1行号开关与起始行号width/widthAdjustment680/true画布宽度与宽度自适应exportSize2x导出倍率1x / 2x / 4xwatermark/squaredImagefalse/false水印与方形图裁剪hiddenCharactersfalse是否显示不可见字符自定义主题也是一等公民THEMES数组中每个主题都带一套highlights色板涵盖background、text、keyword、string、comment、number等 tokencomponents/Editor.js 的createTheme/removeTheme支持在运行时新增或删除主题创建的主题会立即生效并可通过 components/Themes/GlobalHighlights.js 注入全局高亮样式。仓库还内置了 8 套一键预设DEFAULT_PRESETS例如蓝色背景 Material 主题 Fira Code或紫色背景 Verminal 主题快速套用即可获得杂志封面级的排版效果下列两张图分别为默认预设与预设样式的实际渲染效果四、URL 参数驱动分享状态的底层机制Carbon 最巧妙的设计之一是整套编辑器状态都能编码进 URL 查询参数这也是文档中复制链接即可分享功能得以实现的基础。状态映射定义在 lib/routing.js常用参数如下参数对应配置参数对应配置bg背景颜色t语法主题wt窗口主题l语言width画布宽度ds是否启用投影dsyoff/dsblur投影偏移 / 模糊半径wc窗口控制按钮wa宽度自适应pv/ph垂直 / 水平内边距ln行号fl起始行号fm/fs/lh字体 / 字号 / 行高si方形图es导出倍率wm水印sl选中高亮行code编码后的代码内容copy/readonly嵌入时是否可复制 / 只读tb标题栏文字布尔参数如ds、ln、wc通过bool类型解析器将false之外的任意值视为真code参数经过decodeURIComponent解码后作为代码内容载入。这意味着你可以把一段代码连同全部样式打包进一个链接接收方打开链接即看到完全相同的渲染结果。五、导出与分享六大发布途径全解析官方文档指出图片定制完成后可以通过多种方式发布 snippet下面逐一展开含源码佐证。5.1 创建已保存的 Snippet保存 snippet 是推荐的长效分享方式——它在 Twitter、Slack 上自动展开图片同时让读者通过链接访问源码日后想更新直接打开链接编辑即可。操作步骤点击Sign in/Sign up登录/注册按钮登录正常编辑代码——snippet 会自动保存复制浏览器地址栏的 URL 分享出去。源码层面components/Editor.js 的handleSnippetCreate/handleSnippetUpdate调用 API 层lib/api.js的snippet.create/snippet.update编辑操作会经debounce(…, 750)防抖后自动同步到服务端完成后界面会弹出 Snippet created / Snippet saved 提示底部的 components/SnippetToolbar.js 还提供删除handleSnippetDelete能力。5.2 嵌入 snippet 到自己的网站或博客官方文档明确指出这是在个人网站或博客上分享 Carbon 的推荐方式读者甚至能一键复制代码。实现路径有两条直接在页面中嵌入carbon.now.sh/embed开头的 URL通过Copy Menu复制现成的 iframe 代码片段或复制经过编码的 URL 用于 Medium 等平台也可以嵌入已保存的 snippet 或 GitHub gistcarbon.now.sh/embed/:id。看源码嵌入页 pages/embed/[id].js 在服务端getServerSideProps按 ID 拉取 snippet 数据同样以路径长度 ≥ 19 且不含点号判定 ID未找到时 302 跳回/embed。pages/embed/index.js 中嵌入页以只读模式渲染且支持copy、readonly查询参数控制交互并通过postMessage把自身高度上报给父页面context: iframe.resize实现 iframe 自动伸缩。components/CopyMenu.js 的toIFrame会基于当前 Carbon 节点的实际宽高生成带sandboxallow-scripts allow-same-origin的 iframe 代码宽度默认 1024px、高度默认 473px。5.3 使用 Tweet 按钮Tweet 按钮不仅把图片分享到 Twitter还会正确编码alt文本以保证图片的无障碍访问。源码佐证见 lib/api.js 的tweet函数它先通过/api/twitter上传图片数据并把代码内容作为altText提交随后拼接出https://twitter.com/intent/tweet?text…打开新窗口若触发 Twitter 限流HTTP 420界面会给出友好提示。若你想自行发推可参考 Twitter 官方的图片描述说明来手动添加 alt 文本。5.4 直接下载图片PNG / SVGCarbon 支持把图片下载为PNG 和 SVG两种格式具体操作路径Export → PNG下载位图Export → SVG下载矢量图Export → Open在浏览器新标签中直接打开图片Copy → Image直接把图片复制到系统剪贴板。实现细节见 components/ExportMenu.js 与 components/Editor.js导出时先按exportSize1x/2x/4x对 DOM 节点做scale变换再由 lib/dom-to-image.js 生成图片SVG 输出会额外做实体转义、%23→#还原、清理未使用字体等后处理源码中有对应注释。导出菜单还支持自定义文件名并绑定了两个快捷键⌘-⇧-E快速导出 PNG、⌘-⇧-S导出 SVG复制图片的快捷键是⌘-⇧-C依赖navigator.clipboard与ClipboardItem仅在不支持剪贴板 API 时隐藏入口。5.5 其他分享方式上传到 ImgurbetaShare 菜单提供Upload to Imgur (beta)按钮调用 lib/api.js 的imgur函数上传并返回图床链接Plain URL / MediumCopy Menu 中的 Plain URL 直接复制当前页面链接Medium.com 则对 URL 做encodeURI编码并针对 Medium 不识别*的问题做%2A替换方便直接粘贴进 Medium 文章。六、离线桌面使用以 PWA 方式安装 Carbon如果你使用 Google Chrome 或其他支持渐进式 Web 应用PWA的浏览器可以像安装原生应用一样离线使用 Carbon访问carbon.now.sh点击浏览器右上角的设置菜单点击Install Carbon...安装 Carbon。安装后即可获得独立的桌面窗口和离线缓存能力即使断网也能继续编辑与导出图片。七、社区生态编辑器插件与周边工具官方文档罗列了社区围绕 Carbon 构建的丰富生态本文仅作文字介绍详细链接见原文档 docs/README.pl.md编辑器插件IntelliJ IDEA右键菜单直接打开当前选中代码、Atomshift-cmd-A、VS Codecarbon命令、Sublime Text 3自定义快捷键、Vim/NeovimCarbonNowSh()函数、Emacs交互函数carbon-now-sh、XcodeCarboNow4Xcode扩展及nef插件——均可在各自编辑器中一键把代码送入 Carbon命令行工具carbon-now-cli支持在终端打开文件或直接下载图片具备交互模式与选择性高亮nef可从Xcode Playground批量导出 Carbon snippetcarbonate让你在 R 语言中迭代调整图片美学其他工具Telegram 机器人carbonshbot接收代码片段或 gist URL 后生成图片CodeExpander 是具备 TextExpander 特性的智能 GitHub gist 客户端书籍引用计算机科学教材《CS 101 - An Introduction to Computational Thinking》也使用了 Carbon。八、本地开发与运行如果你想在本地体验或二次开发 Carbon可参考 package.json 中的脚本Node.js 版本要求12Next.js 12 架构npm install # 安装依赖也可使用仓库附带的 yarn.lock npm run dev # 启动开发服务器next dev npm run build # 生产构建next build npm start # 启动生产服务next start npm run test:e2e # 运行 Cypress 端到端测试端到端测试用例位于 cypress/integration覆盖背景色、基础交互、嵌入、gist、localStorage、安全与视觉回归等场景例如 cypress/integration/basic.spec.js、cypress/integration/embed.spec.js可帮助你快速验证关键流程的正确性。结语Carbon 的价值在于把截图代码这件事从繁琐的取色、加阴影流程中解放出来导入代码 → 选择主题与排版 → 一键导出或嵌入全程可视化且状态可随 URL 传递。本文结合官方文档与 lib/constants.js、lib/routing.js、components/Editor.js 等源码完整覆盖了从导入、定制、导出到嵌入、离线安装与社区生态的全部环节。无论你是想给博客配一张精致的代码图还是在团队文档中嵌入可复制的片段Carbon 都是一套开箱即用的解决方案。【免费下载链接】carbon:black_heart: Create and share beautiful images of your source code项目地址: https://gitcode.com/gh_mirrors/ca/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
