html-editor-mvp

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

html-editor-mvp

★ 14 Open GitHub ↗

一个支持在Codex 里手动微调UI 细节，并支持源码写回本地的轻量级 HTML 可视化编辑器。

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# HTML 可视化编辑器框架 MVP

一个基于原生 ES Modules、无第三方运行时依赖的 HTML 可视化编辑框架，用于编辑符合组件协议的页面。

## 界面预览

![HTML 可视化编辑器界面](https://raw.githubusercontent.com/2zvsnxry6f-prog/html-editor-mvp/main/output/playwright/html-editor-mvp.png)

## 运行

通过 HTTP 服务启动本目录并访问 `index.html`。当前画布仅用于框架集成验收，不属于具体业务页面。

## 接入

```html
<link rel="stylesheet" href="/editor/ui/editor.css" data-editor-runtime>
<div data-editor-shell></div>
<main data-editor-canvas>
  <h1 data-editor-type="text" data-editor-id="title" data-editor-editable="true">标题</h1>
</main>
<script type="module" data-editor-runtime>
  import { EditorCore } from '/editor/index.js';
  window.editor = EditorCore.init();
</script>
```

支持的组件类型：`text`、`image`、`button`、`card`、`container`、`shape`。

## MVP 边界

- 拖拽使用独立的 CSS `translate` 属性，不覆盖页面已有的 `transform` 动画。
- DOM 克隆可保留属性、内联事件、样式和 CSS 动画。通过 `addEventListener` 绑定的监听器需要后续通过自定义组件适配器恢复。
- 导出生成独立 HTML，并删除编辑器运行时节点；本地上传图片以 Data URL 形式内嵌。
- 预览模式隐藏编辑器界面并关闭选择、拖拽和文本编辑；按 `Esc` 返回编辑模式。

## 组件能力

组件属性由 Capability 决定，不再由 Inspector 硬编码组件类型。默认能力包括：

- `text`：字体、字号、字重、行高和文字颜色。
- `box`：填充、圆角和描边。
- `image`：图片尺寸与资源替换。
- `appearance`：不透明度。
- `transform`：旋转、变换和定位。
- `interactive`：拥有业务交互，编辑模式拦截，预览模式恢复。
- `children`：允许包含子组件。

页面可以使用 `data-editor-capabilities="box,appearance,transform"` 覆盖组件默认能力。

编辑模式会阻止可编辑组件的业务点击和表单提交，避免选择按钮时触发跳转或提交；Preview Mode 会恢复页面原始交互。

## 画布操作

- 选中组件后可通过八方向手柄调整尺寸，通过顶部旋转手柄调整角度。
- 按方向键每次移动 `1px`，按住 `Shift` 时每次移动 `10px`。
- 调整尺寸时按住 `Shift` 可保持组件原始宽高比。
- 移动、缩放和旋转均进入撤销/重做历史。
- 所有组件在属性面板中提供并列的 W 宽度与 H 高度输入。
- 文字组件支持左对齐、居中、右对齐和两端对齐四种形式。
- 拖动组件时会显示与上下左右最近组件之间的实时像素间距。

## 多选与对齐

- 按住 `Shift` 点击可增减多选组件。
- 在画布空白或容器空白区域拖动可框选，框选时自动避免父子组件重复入选。
- 多选组件可整组拖动、方向键微调和批量删除。
- 属性面板支持六种对齐方式，以及三个以上组件的水平、垂直等距分布。
- 拖动组件接近其他组件的边缘或中心时，会自动吸附并显示智能参考线。

## 项目保存

- 编辑操作会在 400ms 防抖后自动保存到当前浏览器的 `localStorage`。
- 刷新页面时会在组件扫描前自动恢复已保存画布。
- 工具栏“保存”或 `Ctrl/Cmd + S` 可立即保存。
- 向上箭头用于导入 `.editor.json` 项目，向下箭头用于下载项目 JSON。
- 项目快照包含画布 HTML、页面信息、保存时间和 Schema 版本。
- 项目保存不会改写磁盘中的 HTML/CSS 源文件；“导出 HTML”仍用于生成独立页面。
- 圆角、填充和描边属于可视盒子能力，不会出现在纯文字组件属性中。
- 按钮、卡片、容器和形状组件支持圆角、填充颜色、描边颜色、描边宽度，以及无描边、实线、虚线和点线样式。

## 图层系统（第一阶段）

- 左侧图层树直接根据页面真实 DOM 父子关系生成，不维护重复的树数据。
- 图层支持展开与收起；点击图层可选中画布组件，画布选中状态也会同步到图层。
- 每个组件都可以锁定或隐藏，这两类操作支持撤销、重做和项目保存恢复。
- 桌面端可收起侧栏，移动端使用抽屉展示，不占用画布宽度。
- 当前阶段不包含拖动排序、跨容器移动和 Flex/Grid 重排。

## 源码回写（MVP）

- 点击“关联源码”并选择包含 `data-editor-canvas` 的 HTML 文件，浏览器会请求该文件的读写权限。
- 点击“写回源码”后，编辑器重新读取磁盘上的最新文件，只用当前画布内容替换其中的 `data-editor-canvas`。
- 编辑器运行时引用、业务脚本、CSS 引用、动画和页面其他区域均从磁盘最新源码保留。
- 写回前会显示覆盖确认；选择错误文件、文件缺少画布协议或没有写权限时不会执行覆盖。
- 受浏览器安全限制，页面无法根据 HTTP 地址自动获得本地文件权限，首次使用必须手动关联源文件。
- HTML 会经过浏览器 DOM 解析器重新序列化，标签缩进和属性格式可能发生变化，但页面结构和行为保持不变。

### Codex 本地写回桥接

在项目根目录运行：

```bash
npm run editor
```

默认打开 `http://127.0.0.1:4173`，并将写回目标固定为项目根目录的 `index.html`。需要指定其他入口时运行：

```bash
node editor/server.mjs --root . --entry pages/home.html --port 4173
```

- 编辑器检测到桥接后会显示“源码已连接”，点击“写回源码”即可直接修改当前 Codex 工作区文件，不再弹出文件选择器。
- 浏览器不能提交目标路径，服务只允许写入启动时固定的项目内 HTML。
- 每次写入前比较 SHA-256；文件被其他工具修改后会拒绝覆盖。
- 写入前在 `.editor-backups/` 创建磁盘备份，每个入口最多保留最近 10 份。
- 落盘使用同目录临时文件和原子重命名，写入中断不会留下不完整源码。

## 页面与项目管理

- 工作区支持多个项目，每个项目支持多个独立页面。
- 支持项目的新建、切换、重命名和删除；支持页面的新建、复制、切换、重命名和删除。
- 编辑历史严格按当前页面隔离，切换页面时会清空撤销栈和当前选区。
- 自动保存和手动保存始终更新当前项目的当前页面，刷新后恢复上次打开的项目与页面。
- 旧版单页面存档会自动迁移为默认项目的“页面 1”。
- 项目 JSON 已升级为多页面格式，仍可导入旧版单页面项目 JSON。

## 备份与异常恢复

- 每个项目分别保留最近 10 个完整工作区快照。
- 源码写回、删除项目和删除页面之前自动创建备份，也可随时手动备份。
- 备份面板显示原因、项目、页面和创建时间，并支持一键恢复。
- 不再需要的快照可以单独删除；系统仍会自动限制每个项目最多 10 份。
- 恢复旧备份之前会先保存当前工作区，避免恢复操作本身造成数据丢失。
- 支持下载包含当前工作区和全部本地快照的完整 JSON 备份。
- 主工作区存档无法解析时，启动过程会从新到旧查找最近的有效备份；全部不可用时创建新的安全工作区并显示状态。

## 界面规范

- 编辑器采用 Figma 式克制暗色工作台语言，统一外壳衬托业务画布，蓝色只用于选中、焦点和主操作。
- UI 令牌、控件尺寸、状态和无障碍规则记录在 `DESIGN.md`，产品定位与反向约束记录在 `PRODUCT.md`。
- 基础无障碍目标为 WCAG 2.2 AA，包括可见键盘焦点、对比度、非颜色状态表达和减少动画支持。

html-editor-mvp

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README