HyperFrames 中文文档
参考

Studio 手动 DOM 编辑

Studio 手动 DOM 编辑检查器当前提供的功能，包括能力、用户体验和限制。

本页面记录了 HyperFrames Studio 中当前的手动 DOM 编辑功能。它反映的是 Studio 检查器中已上线的实现，而非早期探索第三方 transform 引擎的设计草案。

已上线的功能

Studio 现在支持在预览中进行直接的 DOM 编辑工作流：

  • 在预览中直接选择受支持的元素
  • 在当前选择周围显示编辑器管理的覆盖层
  • 当几何信息可安全处理时，在画布上移动和调整受支持元素的大小
  • 通过显式的 Make movable 操作分离符合条件的布局控制图层
  • 从右侧 Design 检查器编辑样式属性
  • 编辑安全的文字承载选择中的文字图层，包括空文字值
  • 为多文字选择添加和移除子文字图层
  • 编辑纯色填充、渐变、项目资源图片填充、外部图片填充、不透明度、圆角、flex 元数据、排版和混合模式
  • 从主视图深入嵌套 composition，而非假装每个内部节点都可以就地编辑
  • 从右侧检查器生成元素作用域的 Ask agent prompt 包

重要的保守原则是：Studio 只暴露它能以确定性行为往返写回 HTML 的交互。

当前用户体验

预览选择

  • 单击选择预览中可补丁的元素。
  • 选择覆盖层在 Studio chrome 中渲染，不注入到创作内容中。
  • 覆盖层在以下情况被清除：
  • Inspector 面板关闭时
  • 用户在预览中点击空白区域时
  • 源刷新后底层元素消失时

覆盖层行为

覆盖层提供：

  • 选择边界
  • 受支持元素的拖拽行为
  • 当宽度和高度可安全补丁时的调整大小手柄
  • 不支持移动时的阻止拖拽反馈

覆盖层刻意不包含浮动操作工具栏。Ask agent 位于右侧检查器头部，样式控件在 Design 面板中。

当前实现在 DomEditOverlay.tsx 中使用 Studio 管理的指针处理。它不使用 Moveable。

检查器行为

Design 面板当前包含：

  • Layout
  • X / Y / W / H 字段
  • 滚轮和方向键数值微调
  • Make movable 用于可以安全分离的块级布局控制图层
  • Flex
  • direction、justify、align、gap、clip content
  • Radius
  • 滑块 + 实时读数
  • Blending
  • 不透明度滑块 + 实时读数
  • 混合模式
  • Fill
  • 纯色
  • 多色标渐变编辑
  • 项目资源图片填充
  • 内联图片上传到项目资源列表
  • 外部图片 URL 填充
  • 文字颜色
  • Color picker
  • 视口限制的浮动拾色器
  • 饱和度 / 亮度十字准线
  • 色相和透明度滑块
  • 十六进制输入
  • Text
  • 当选择可安全补丁时直接编辑文字图层
  • 为子文字选择添加 / 移除文字图层
  • 字体大小、粗细和字族控件
  • Selection colors
  • 当前选择中检测到的颜色摘要

检查器刻意与 Renders 分离，右侧面板有 Design / Renders 标签切换。切换到 Renders 不意味着头部的 Inspector 面板被关闭。

什么算作可编辑

Studio 为每个选择构建一个 DomEditSelection 和 DomEditCapabilities 对象。

选择要求

节点只有在可以被标识为稳定的补丁目标时才对 Studio 有用，例如：

  • id
  • 稳定选择器
  • 限定在正确源文件中的选择器索引
  • 涉及主视图时的 composition 宿主映射

移动支持

仅在选中元素满足以下条件时允许移动：

  • 有稳定的补丁目标
  • 为 absolute 或 fixed
  • left 和 top 值可解析为像素值
  • 不由 transform 驱动（transform: none）

调整大小支持

仅在移动已被允许且 Studio 可以安全补丁像素 width 和/或 height 时允许调整大小。

从布局分离支持

某些块级图层可被选择和样式编辑，但由于 flex、grid 或正常文档流控制其位置，无法直接移动。

对于这些图层，Studio 可以暴露 Make movable 而非在拖拽时静默转换。该操作测量相对于 composition 根的当前可视矩形，并写入保守的内联几何信息：

  • position: absolute
  • left、top、width 和 height 以像素为单位
  • margin: 0

UI 会说明此操作将图层从 flex/grid 流中分离并保持当前可视位置。内联文字节点不能直接分离。

文字编辑支持

仅在安全的文字承载选择中允许文字编辑：

  • 受支持的文字承载标签，如 div、span、p、strong 和标题
  • 自身文字选择或叶子级子文字图层
  • 用户清除内容后的空文字值
  • 非 composition 宿主

对于多文字选择，Studio 显示文字图层列表。用户可以选择特定文字图层、实时编辑内容、更改大小和粗细和字族、添加同级文字图层或移除活动图层。

不支持的示例

Studio 刻意不提供以下场景的直接几何编辑：

  • 位置由布局衍生的 flex/grid 子元素，除非用户选择 Make movable
  • 由 transform 驱动的几何信息
  • 用户仍在主视图中时的嵌套 composition 内部
  • 没有稳定补丁目标的节点
  • 内联文字 span 作为几何目标

当几何编辑被阻止但样式编辑仍然安全时，检查器会显示选择以及直接几何编辑不可用的原因。

如果用户尝试拖拽被阻止的图层，Studio 会显示 toast 提示。布局控制的图层会引导用户使用 Make movable；transform 驱动或不安全的目标会解释直接移动/调整大小仅限于绝对或固定像素几何且无 transform 驱动布局。

嵌套 Composition 规则

嵌套 composition 被显式处理。

主视图中

  • 点击嵌套 composition 内部的内容会映射回 composition 宿主
  • 受支持的 composition 宿主在其宿主几何信息安全时可以整体移动
  • Studio 不从主预览暴露直接的内部节点几何编辑
  • 双击深入子 composition

深入后

  • Studio 正常解析该 composition 内部的选择
  • 如果选中的内部节点满足能力规则，直接移动/调整大小再次可用
  • 文字、填充、渐变、图片、圆角、不透明度和排版编辑应用于选中的内部节点

这保持了 Studio 对当前编辑上下文能安全补丁的内容的诚实性。

源码补丁模型

Studio 仍然以创作的 HTML 作为真实来源。

手动 DOM 编辑流程通过 packages/studio/src/utils/sourcePatcher.ts 中现有的补丁管道来补丁源码。

检查器使用的当前补丁类型包括：

  • 内联样式补丁
  • 时间轴链接编辑路径的属性补丁
  • 文字内容补丁
  • 从布局分离的样式补丁

流程为：

  1. 用户在预览中选择或操作一个元素
  2. Studio 解析稳定目标
  3. 预览为交互反馈进行乐观更新
  4. 补丁写回源码
  5. 预览刷新并重新附加选择

渐变编辑

当前渐变编辑器是一个结构化的 Studio 控件，而非原始 CSS 文本字段。

它支持：

  • linear、radial 和 conic 渐变
  • 重复变体
  • 多个色标
  • 通过点击预览条插入色标
  • 移除色标
  • 角度控制
  • 径向形状和大小控制
  • 径向/锥形中心控制

编辑器仍然序列化为 CSS background-image，但检查器使用解析后的渐变模型，而非强制用户输入原始渐变语法。

图片填充编辑

图片填充编辑器不再只是一个原始的 background-image 输入。

它支持：

  • 选择现有的项目图片资源
  • 从填充面板上传图片（同时添加到 Assets 选项卡）
  • 在面板中预览选中的项目资源
  • 当图片不是项目资源时输入外部 URL

Studio 将项目资源选择序列化为 background-image: url(...)，并重写资源 URL 使嵌套子 composition 预览仍能正确解析图片。

颜色编辑

颜色编辑器是自定义的 Studio 弹出面板，而非浏览器原生颜色对话框。

它支持：

  • 从整个颜色行打开
  • 保持在视口内靠近点击颜色的位置
  • 带可见十字准线指南的饱和度/亮度拾取
  • 带可见手柄的色相和透明度控制
  • 当前颜色色块、读数和十六进制输入

拾色器写入 CSS rgb(...) 或 rgba(...) 值，并在编辑过程中保留 alpha 通道。

数值微调

数值布局/细节输入支持轻量级的设计工具式微调：

  • 在聚焦字段上使用鼠标滚轮
  • ArrowUp / ArrowDown
  • Shift 用于较大步长
  • Alt 用于更精细步长

当前用于检查器中的所有数值提交字段，包括布局度量和可干净解析为值加单位的其他数值文本输入。

负责该功能的文件

主要实现位于：

  • packages/studio/src/App.tsx
  • 整体检查器接线
  • 选择生命周期
  • 预览命中测试
  • 持久化钩子
  • 从布局分离的提交流程
  • packages/studio/src/components/editor/DomEditOverlay.tsx
  • 覆盖层方框、拖拽、调整大小、阻止拖拽反馈
  • packages/studio/src/components/editor/PropertyPanel.tsx
  • 右侧检查器 UI
  • packages/studio/src/components/editor/domEditing.ts
  • 选择解析
  • 能力门控
  • 文本字段建模
  • prompt 生成
  • packages/studio/src/components/editor/colorValue.ts
  • 颜色解析、HSV 转换和 CSS 颜色序列化
  • packages/studio/src/components/editor/floatingPanel.ts
  • 颜色拾取的视口安全浮动面板定位
  • packages/studio/src/components/editor/fontAssets.ts
  • 导入的字体资源辅助函数
  • packages/studio/src/components/editor/fontCatalog.ts
  • Google 字体目录元数据和样式表 URL
  • packages/studio/src/components/editor/gradientValue.ts
  • 渐变解析、序列化和色标编辑辅助函数
  • packages/studio/src/utils/sourcePatcher.ts
  • 源码补丁持久化

支持性的 Studio shell 变更也涉及：

  • packages/studio/src/components/nle/NLELayout.tsx
  • packages/studio/src/components/nle/NLEPreview.tsx
  • packages/studio/src/components/sidebar/CompositionsTab.tsx
  • packages/studio/src/components/sidebar/LeftSidebar.tsx
  • packages/studio/src/player/components/Player.tsx
  • packages/studio/src/player/components/Timeline.tsx
  • packages/studio/src/player/components/TimelineClip.tsx
  • packages/studio/src/player/hooks/useTimelinePlayer.ts
  • packages/studio/src/utils/mediaTypes.ts

当前限制

该功能刻意不是一个完整的通用可视化构建器。

目前仍不支持：

  • 旋转
  • 任意 transform
  • 吸附和对齐指南
  • 多选
  • 框选
  • 无论布局模型如何自由编辑每个 DOM 节点
  • 不深入就直接从主预览编辑嵌套子 composition 内部
  • 拖拽时自动转换为绝对定位（无用户确认）
  • 内联文字 span 的直接几何编辑

总结

Studio 手动 DOM 编辑现在是一个狭窄、确定性的可视化编辑层，覆盖在创作的 HTML 之上。

它不试图让整个 DOM 可自由编辑。相反，它：

  • 以源码 HTML 为真实来源
  • 只暴露可补丁的交互
  • 使用 Studio 管理的覆盖层进行直接操作
  • 为用户提供真正的检查器进行安全的样式和文字编辑
  • 将嵌套 composition 视为深入边界，而非将它们展平为不安全的编辑表面

这种权衡是当前功能感觉可靠而非具有欺骗性的原因。

测试本地 CLI 变更

如何使用本地构建在 monorepo 外部测试未发布的 CLI 变更。

采用者

在生产中使用 HyperFrames 或积极评估的组织。