@ domternal/ 扩展图像

图像 永远 编辑器,带有调整大小、对齐、, 文本包、备选文本和文件粘贴/投放支持。 通过自己的文件存储 上传处理器或嵌入它们作为数据URL. 图像默认为块节点; 内置图像是可选的.

文档 • 妇女 实例

安装

软件包宣布Node.js 22或后作工具.

pnpm add @domternal/core @domternal/pm @domternal/extension-image @domternal/theme

核心和 pm 是同龄人, 范围 >=1.8.0 <2.0.0。为所有人使用1.8.1版 安装了 DOMTERNAL 免费软件包。 可选主题提供 调整大小的手柄, 放置样式和上传指标; 省略时提供等同的 CSS 。 导出 HTML 包括 独立于主题的放置样式 .

快开始

<div id="editor" class="dm-editor"></div>

import { Editor, StarterKit } from '@domternal/core';
import { Image } from '@domternal/extension-image';
import '@domternal/theme';

const editor = new Editor({
  element: document.getElementById('editor')!,
  extensions: [StarterKit, Image],
  content: '<p>Paste an image or add one by URL.</p>',
});

使用您的应用程序服务的 URL 添加图像 :

editor.chain().focus().setImage({
  src: '/uploads/photo.jpg',
  alt: 'A mountain reflected in a lake',
}).run();

打电话 editor.destroy() 当删除编辑器时。 扩展贡献图像 当这些 UI 组件是时, 控制到 Domternal 的工具栏和泡泡菜单 挂载; 赤色 Core 编辑器不会创建这些组件.

上传文件到您的应用程序

没有上传处理器, 所接受的文件将作为数据嵌入到文档中 URLs (英语). 要将文件存放到其他地方, 请替换 Image 在带 a 的扩展阵列中 已配置实例 。 此示例期望您自己 /api/upload 结束点到 返回 JSON 包含 url 字符串 :

Image.configure({
  allowBase64: false,
  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
  maxFileSize: 5 * 1024 * 1024,
  maxFiles: 5,
  uploadHandler: async (file) => {
    const form = new FormData();
    form.append('file', file);
    const response = await fetch('/api/upload', { method: 'POST', body: form });
    if (!response.ok) throw new Error('Image upload failed');

    const result = await response.json() as { url?: unknown };
    if (typeof result.url !== 'string' || !result.url) {
      throw new Error('The upload endpoint did not return an image URL');
    }
    return result.url;
  },
  onUploadError: (error) => {
    console.error(error.message);
  },
});

相同的MIME、大小和计数规则适用于粘贴、投放和取出文件者 图像。 验证服务器上的上传 。 文件保持其插入顺序 同时同步上传完成。 主题使 .domternal-image-uploading 占位符作为本地装入状态 轻/暗指标。 它尊重减少运动,在打印时被隐藏. 它只查看,没有键盘站,从未输入已保存的内容或撤消 历史 上传或删除插入点失败将删除 装入指标。 见 文件插入并撤消 用于选择替换、取消和协作编辑.

共同选项

与 allowBase64: false 没有 uploadHandler,无法插入文件. 远程图像 URL 仍然可以使用 。 这个 完全选项参考 还覆盖了HTML属性并上传回调.

命令和备选案文文本

浮动和对齐每个接受 'none', (中文(简体) ), 'left', (中文(简体) ), 'center' 财务报告和审定财务报表 'right'; 设置 一者清净. 命令在当前选择上运行.

使用描述 alt 为有意义的图像. alt: '' 将图像标记为 装饰和制作 alt=""· ; null 表示未提供说明 并省略属性。 见 备选文本编辑。 。 。 .

裁剪、旋转和镜像图像

自由 1. 6.0 增加了无损图像几何. 在编辑器中明确启用 扩展数组 :

Image.configure({ enableTransforms: true });

默认的图像图案和普通图像JSON保持不变. 启用此功能 选项 imageTransform 属性,默认为 null。更新任意 严格应用方案,允许该字段,并允许在每段 在存储已转换的图像之前合作编辑器 。 没有编辑器 选项无法从启用的编辑器中保存几何.

这个 imageTransform 属性保持源字节不变。 裁剪 使用原始图像的分数,然后是水平/垂直镜像 顺时针旋转。 编辑器和保存的 HTML 使用可旋转的视图 边框; 调整该框宽度的修改,同时保留其宽度比 .

editor.commands.setImageTransform({
  naturalWidth: 1600,
  naturalHeight: 900,
  crop: { left: 0.1, right: 0.1 },
  rotation: 90,
  flipX: true,
});

命令需要图像节点选择 。 奥米 naturalWidth 财务报告和审定财务报表 naturalHeight 仅在图像被装入时, 或其当前变换时 已经录下来了. setImage({ src, imageTransform: { ... } }) 总是需要 明确的内在维度。 一个命令取代完整的变换并 可撤销;在文档中装入、渲染和导出绝不是作者几何. 无 enableTransforms: true, (中文(简体) ), setImageTransform 财务报告和审定财务报表 setImage 带有 明确转换或 null 返回时 false 不更改文档. 默认菜单中不添加作物/旋转控制 .

每个作物边缘必须在0到1之间,图像至少为1/65,536 保持双向。 内在维度必须是有限度的,必须在 1和1,000,000;旋转必须在1 000 000度以内有限度. 整个转弯都正常了 无效的命令返回 false错误 存储的几何作为普通图像,无效或身份转换 保持普通图像标记不变。 这个 ImageTransform 财务报告和审定财务报表 SetImageTransformOptions 类型导出用于应用程序控制.

剪贴板和源策略

截图或仅图像剪贴板插入图像文件 。 复制内容时 hTML/文本具有优先级, 所以 Word 的相片被复制 选择不取代实际内容。 办公室 HTML 正常化是一个 单独的选入 粘贴清除 特性; 图像本身并不适用其光栅或结构限制.

内建解析,命令和渲染应用 Core 的 URL 策略. 拒绝 存储源仍然保存在JSON中,但没有被节点视图所加载. URL 检查完成 不检查远程响应字节 。 见 图像安全 编辑 URL 政策参考。 。 。 .

更多文档

• 图像指南: 内置模式, popovers, 调整大小, 文件处理和节点视图 .
• 剪贴板目的地:与自定义图像节点合作.
• 本地化数字 : imageMessages 和可选 @domternal/extension-image/locales/de 目录. 作者的备选案文从未被翻译 .

许可证

麻省理工学院。 。 。 .