Cherry Studio 绘画页控件迁移指南图像生成模型与参数选择器进入提示栏工具栏【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio导读本文基于 Cherry Studiocherry-studio仓库中 2026-06-24 的破坏性变更记录系统讲解绘画Paintings页面的一次纯 UI 重构左侧常驻参数面板被移除图像生成模型选择器与参数列表尺寸、seed 等迁入提示输入框底部的工具栏。读完本文你将理解新布局的结构、⚙ 参数弹层与模型下拉的交互方式、图片输入能力attach/paste/drag的接入点以及为什么这是一次无需用户操作、无需数据迁移的零成本升级。一、变更总览从三栏布局到画布 历史 底部工具条变更前旧布局旧版绘画页采用三栏结构左侧设置面板常驻显示图像生成模型选择器与生成参数列表尺寸、seed、步数等用户随时可见、随手可改中间画布预览当前提示词生成的结果右侧/侧边历史历史绘画记录。变更后新布局左侧设置面板被整体移除页面收敛为画布 历史两栏模型与参数控件全部下沉到提示输入框底部的工具栏模型选择器→ 以下拉框形式出现在提示栏工具栏中生成参数列表尺寸、seed 等→ 收进工具栏上的设置⚙弹层Popover提示输入框本体→ 统一替换为项目共享的富文本 Composer并支持面向图像编辑类模型的图片附加 / 粘贴 / 拖拽输入。从源码布局看PaintingPage.tsx 的渲染树清晰地体现了这一结构PaintingStrip历史条与Artboard画布居于主区域而PaintingComposer被放入promptDock容器paintingPrimitives.ts 中promptDock: relative z-20 shrink-0 px-2 pt-2 pb-2固定在中间栏底部。旧的三栏设置面板在组件树中已不存在——它不是被隐藏而是被彻底移除并替换为工具栏交互。二、新交互详解底部工具栏的两个入口1. 模型选择下拉Dropdown在 PaintingComposer.tsx 中renderContextControls将PaintingModelSelector渲染进共享的ComposerToolbarControls底部工具栏同时传入hideTitle以去掉旧面板中的 Model 分节标题。PaintingModelSelector.tsx 内部复用了全局ModelSelector组件通过filter{paintingModelFilter}即supportsImageGenerationEndpoint来自 paintingModelOptions.ts仅展示支持图像生成端点的模型触发按钮显示模型名、提供商名与模型 Logo未选中时显示paintings.select_model占位文案选中后通过onSelect({ providerId, modelId })回调上抛选择结果。2. 参数设置弹层⚙ Popover工具栏第二个入口是PaintingParamsButtonPaintingComposer.tsx它以PopoverSettings2图标呈现参数入口并有几个值得注意的细节参数摘要预览按钮上会显示当前参数选区的紧凑摘要如 1024×1024 · 50 · 42由paramsSummary依据表单字段逐项格式化生成。尺寸类字段按 chip 风格渲染如1024×1024auto等枚举会本地化为当前语言如中文自动滑块类字段显示数值。按钮的aria-label也携带摘要保证无障碍访问弹层宽度w-[min(300px,calc(100vw-2rem))]内部max-h-[60vh]可滚动避免小窗口下弹层溢出零参数降级当imageGenerationToFields解析出的配置项为空configItems.length 0即当前模型在注册表中没有imageGeneration声明时按钮整体不渲染——工具栏保持干净。弹层内部承载的是 PaintingSettings.tsx它通过useImageGenerationSupport获取当前模型的注册表能力再经imageGenerationToFields转换为表单字段最后由PaintingFieldRenderer渲染。字段覆盖 switch开关、enum下拉 / chips、range滑块、size自定义宽高输入、text输入框 / 多行文本等多种控件类型完整映射见 imageGenerationToFields.ts。三、提示框统一共享富文本 Composer 与图片输入本次变更的另一半是提示框统一。根据变更记录这次迁移属于 v2 Composer 统一的一部分——通用 Composer 已迁入components/composer/绘画页不再维护独立的提示输入实现而是基于共享的ComposerSurface重建。PaintingComposer.tsx 中ComposerSurface的装配展示了图片输入能力的接入方式顶部参考图托盘对于图像编辑类模型isEditImageModel(model)为真topContent渲染PaintingImageGallery——一个横向滚动的缩略图条支持逐张删除、点击打开 ImageViewer 灯箱PaintingImageGallery.tsx圆形上传按钮leadingContent渲染PaintingImageAddButton点击后调起系统文件选择器图片进入 Composer 的files状态与工具栏 / 粘贴 / 拖拽走同一条附件管线同上文件第 24-61 行附件能力继承粘贴、拖拽、文件 token 管理等能力由共享 Composer 提供绘画页只声明自己管理的 token 类型PAINTING_MANAGED_TOKEN_KINDS [file]。一个重要的模式差异编辑类模型的图片输入走顶部参考图托盘而非文件胶囊PAINTING_NO_MANAGED_TOKEN_KINDS []因此 Composer 在这些模型下不托管任何 draft tokenfiles始终是权威数据源。这保证了PaintingImageGallery与生成时的inputFiles物料化结果一致。四、行为不变性参数、历史与生成逻辑零迁移变更记录的 Notes for release manager 明确三点纯 UI 位置迁移UI-only relocation无任何数据迁移no data migration生成行为不变绘画生成行为、参数、历史全部保持原样参数持久化位置不变表单读写仍指向painting.params——扁平、以规范参数名为键的数据包canonical bag。从源码看参数数据流的主干没有因本次 UI 迁移而改变PaintingSettings.tsx 注释明确指出表单读写目标painting.params就是请求时canonicalGenerate拆分为 AI SDK 参数与厂商参数包的同一份数据。换句话说旧版用户在左侧面板设置过的参数迁移后依然保存在相同的painting.params结构中切换 UI 入口不会丢失任何已配置内容。关于参数如何从painting.params经canonicalGenerate校验、splitParamValues拆分最终落到各厂商请求体的完整链路可参阅 docs/references/ai/image-generation-parameters.md。五、模型切换时的行为细节源码佐证虽然本次迁移没有改变生成逻辑但工具栏化的模型选择器引入了与旧面板一致、且更严谨的切换语义体现在 usePaintingModelSwitch.ts 中同提供商内切换调用computeModelFieldReset清理旧模型写入、新模型不接受的过期字段表单字段可见性由新模型的注册表块驱动底层值需要同步同时若目标模型不能接受图片输入非isEditImageModel显式清空inputFiles避免隐藏的上传图片被误发给仅生成类模型跨提供商切换先ensureProviderCatalog加载目标提供商目录冷缓存 DB/IPC 失败时通过presentPaintingGenerateError弹出错误而非静默回退然后基于新提供商重建默认绘画对象保留id、files、prompt并重置模式为generate、清空输入图片——不同提供商的图片附件绝不跨商携带。六、用户须知什么都不用做变更记录明确说明自动生效用户无需任何操作。迁移后同一套模型选择器与参数项全部可用只是入口从左侧面板变为提示栏工具栏参数入口位置提示输入框底部工具栏 → ⚙ 按钮 → 弹层内调整按钮上的摘要文本可预览当前选区模型入口位置提示输入框底部工具栏 → 模型下拉框若当前模型没有任何可配置参数⚙ 按钮自动隐藏不会出现空弹层。七、测试覆盖本次变更并非一次性重写相关行为有较完整的组件级测试守护可作回归验证参考PaintingComposer.test.tsx验证 Composer 装配、编辑模型图片输入门控、发送禁用逻辑PaintingModelSelector.test.tsx验证模型下拉过滤与选择回调PaintingSettings.test.tsx验证参数表单按注册表字段渲染PaintingPage.test.tsx页面级布局与状态编排验证。此外 usePaintingModelSwitch 相关测试 与 form 目录下的字段测试 共同覆盖了模型切换重置与参数表单渲染的行为边界。八、关键文件索引关注点文件变更记录原文v2-refactor-temp/docs/breaking-changes/2026-06-24-painting-controls-moved-to-toolbar.md页面布局画布 历史 promptDocksrc/renderer/pages/paintings/PaintingPage.tsx底部工具栏 Composer模型下拉 ⚙ 弹层src/renderer/pages/paintings/components/PaintingComposer.tsx模型选择下拉src/renderer/pages/paintings/components/PaintingModelSelector.tsx参数表单与 ⚙ 弹层内容src/renderer/pages/paintings/components/PaintingSettings.tsx参考图托盘与上传按钮src/renderer/pages/paintings/components/PaintingImageGallery.tsx模型切换重置语义src/renderer/pages/paintings/hooks/usePaintingModelSwitch.ts注册表 → 表单字段映射src/renderer/pages/paintings/form/imageGenerationToFields.ts参数化架构全景docs/references/ai/image-generation-parameters.md共享 Composer 工具栏清单scope 控制src/renderer/components/composer/tools/toolbarManifests.tsx结语总而言之这是一次面向 v2 Composer 统一战略的纯 UI 迁移绘画页放弃了左侧常驻设置面板的旧范式把模型选择与参数编辑收纳进提示栏底部工具栏同时将提示框整体替换为共享富文本 Composer 并补齐图片输入能力。由于参数仍存于同一份painting.params规范数据包、生成链路完全未动、历史数据无需迁移用户端零操作即可平滑过渡。对开发者而言理解这一迁移的关键在于把握UI 入口变了、数据流没变这一原则——任何针对绘画参数表单的后续扩展依然只需在注册表supports与参数目录层声明表单、校验、厂商请求体便会自动跟随。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考