@ domternal/ 核心

无头编辑器引擎 永远,在 作是说已. 直接用在 JavaScript 或 TypeScript 中,或通过 Angular, 反应,Vue和香草包装. 它提供 Editor 类,可堆肥 扩展名,可链条命令,文档序列化和服务器侧辅助.

文档 • 妇女 开始 • 妇女 实例

安装

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

pnpm add @domternal/core

核心没有框架依赖性,包括: @domternal/pm。使用1.8.1版本 用于所有已安装的 DOMTERNAL 免费软件包。 包装和扩展需要核心 >=1.8.0 <2.0.0;扩展也要求PM在这个范围内. 1.8.1 所需核心资源 首相 >=1.8.1 <2.0.0 在运行时间. 从 @domternal/pm/* 保留 一个共享副本。 。 。 .

对于现成的编辑器外型,也安装 @domternal/theme 并导入 您的应用程序条目,与 class="dm-editor" 在山上或祖先. Core没有捆绑的编辑器主题,工具栏或框架UI.

快开始

在页面上添加挂载元素 :

<div id="editor"></div>

然后在浏览器入口点创建编辑器 :

import { Editor, StarterKit } from '@domternal/core';

const editor = new Editor({
  element: document.getElementById('editor')!,
  extensions: [StarterKit],
  content: '<p>Hello <strong>world</strong>!</p>',
});

editor.on('update', () => {
  console.log(editor.getJSON());
});

StarterKit 包括段落、标题、列表、任务、链接、通用文本标记、, 历史与编辑密钥图. 它不包括表格、图像、办公室粘贴 清理或其他可选扩展包.

通过同一实例读取或更改文档:

editor.chain().focus().toggleBold().run();
editor.commands.insertContent('<p>Another paragraph</p>');

const json = editor.getJSON();
const html = editor.getHTML();
const text = editor.getText();

打电话 editor.destroy() 当从您的应用程序中删除编辑器时。 框架 包装器管理它们创建的例的寿命.

选择您的扩展名

配置或禁用单个 StarterKit 特性 :

StarterKit.configure({
  heading: { levels: [1, 2, 3] },
  link: { openOnClick: false },
  codeBlock: false,
});

通过已配置的启动 Kit 替换 StarterKit 内 extensions标题 默认情况下支持级别1至4. listIndent 默认关闭, 因为启用 它还在列表之后的一段中抓住 Tab .

对于一个较小的计划,用您需要的单个出口替换StarterKit, 例如 Document, (中文(简体) ), Paragraph, (中文(简体) ), Text, (中文(简体) ), Bold, (中文(简体) ), BaseKeymap 财务报告和审定财务报表 History。 。 。 . 在同一扩展阵列中注册可选软件包 :

• 表格 财务报告和审定财务报表 图像。 。 。 .
• 块控件 用于斜线命令、拖动手柄和 SmartPaste .
• 粘贴清除 用于选入 Word 和 Google Docs HTML 清理.
• 标记 用于Markdown解析和序列化.

只有导入的扩展输入您的 JavaScript 捆绑 . preset: 'notion' 选择 逗号演示文稿和行为; 它不安装可选扩展. 见 配置指南。 。 。 .

可编辑的文档注释

免费 1. 6.0 添加选入 DocumentNotes,该附件不是 StarterKit。它安装 内入 documentNoteReference 原子和一个可编辑 documentNote 块。 都住在这里 普通编辑器 JSON 和共享的ProseMirror 文档,所以合作和 历史在相同的内容上运行,没有单独的应用说明店. 启用 DocumentNotes 在存储这些节点之前,请先在每一个协作写器上输入.

import { DocumentNotes, Editor, StarterKit, getDocumentNotes } from '@domternal/core';

const editor = new Editor({ extensions: [StarterKit, DocumentNotes] });
editor.commands.insertDocumentNote({
  noteId: 'source-note',
  kind: 'footnote',
  content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Editable note body' }] }],
});
editor.commands.insertDocumentNoteReference({ noteId: 'source-note', kind: 'footnote' });
editor.commands.focusDocumentNote({ noteId: 'source-note', kind: 'footnote' });
const notes = getDocumentNotes(editor.state.doc);

同样的命令接受 kind: 'endnote'。 。 。 . insertDocumentNote 可以生成一个 身份当 noteId 被省略并接受可选文字 label (单位:千美元) 自定义标记。 机构和参考资料份额 noteId 财务报告和审定财务报表 kind; 重复引用 指向现有机构。 插入是一个不可撤销的交易 。 点击 a 引用, 按 Enter 或其中的空格, 或调用 focusDocumentNote 选择 相应的身体。 机体标题链接到其第一次引用.

各种类型的自动标签分别取自参考顺序; 自定义标签不推进计数器。 永不重写 JSON 或 YJs 状态。 删除一个引用使其身体保持可视性以供编辑. 失踪尸体 并显示未解决的状态,而不是猜测或 丢弃内容 。 2. 复制一个机构及其参考文献; 仅复制的引用保留其目标身份.

身份限制为256个UTF-16单元和64个非空白单元的自定义标签, 没有控制字符 或未给付代孕。 衍生导航索引 512个机构、512个参考文献、10万个节点、64个级别和200万个 文本单位。 超过索引绑定值会保留内容并禁用未解决 导航. getDocumentNoteTypes(schema) 承认实际的第一当事方 合同,包括保留其属性的更名节点。 它没有通过 与此无关的节点只是因为它们使用相同的名称.

Free 1. 7.0 显示为应用程序拥有的、只读的 DOM 预览构建的助手 与计划序列器. annotateDocumentNotes(root, getDocumentNotes(doc), editor.i18n) 获得相同的 没有改变JSON的标签。 完整文档快照保存编号 仅提供文件的一部分。 见 静态注释演示文稿。 。 。 .

1.6.0 与所支持的可选模式相融合 DOCX笔记. Free 提供了可编辑模型;这些 DOCX/PDF 适配器属于 专业 这个模型不是被标注的脚注编辑器 .

可读文字颜色

核心和主题 1.4.0 添加文字颜色的可选显示策略. 通过将配置的扩展名添加到编辑器中来明确启用 :

import { StarterKit, TextStyle, TextColor } from '@domternal/core';
import '@domternal/theme';

const extensions = [
  StarterKit,
  TextStyle,
  TextColor.configure({ contrast: 'auto' }),
];

默认, original,保留作者的颜色. auto 测量活编辑器 背景和调整一个不透明的字形颜色,只有当其对比度低于时 4.5:1. 它混合了向着黑或白的颜色,而不是取代每一种颜色 带有主题文本颜色。 可读的颜色和命名的颜色符号保持不变. 这对只读编辑器中保存的文档也是有效的;它并不针对 字导入.

调整仅影响屏幕显示. JSON, HTML, 剪贴板 HTML, 导出、打印和共享文档数据保留了原始颜色。 主题变化 在不编辑文档的情况下重新计算演示文稿。 透明背景 和祖先不透明,包括已检查的任务标签,在 完全扎实的背景是已知的。 政策保持不透明;如果没有文本 颜色可以通过这种不透明达到4.5:1,被作者的颜色保持不变. 透明文本, 未解决或未支持的颜色空格、图像或梯度背景、已绘制 伪元素等堆肥效应不变. 自定义文本Style 高度优先的标志性观点也优先。 这是可读性 援助,而不是任意应用CSS的无障碍保障.

核心产生视图属性,匹配的主题提供他们的屏幕样式. 具有自己风格的应用程序可以使用相同的狭义范围规则:

@media screen {
  .dm-editor .ProseMirror [data-dm-text-contrast='adjusted'] {
    color: var(--dm-readable-color) !important;
  }
}

只读预览

免费 1.8.0 曝光 TextColorStorage.preview(root, marks) 页:1 应用程序自有的,Schema-rested只读预览. 从 配置内容 TextColor 扩展并传递预览 .ProseMirror 根号 其成形的字形- 颜色跨度及其当前内线 style.color 数值。 它回来了 null 何时 contrast 实值 original; 与 auto 它会返回 refresh() 财务报告和审定财务报表 destroy() 方法。 。 。 打电话 refresh() 附加预览后 财务报告和审定财务报表 destroy() 当取去时。 预览需要相同的主题/可读性 CSS担任编辑. 能力只增加临时列报属性; 它不安装编辑插件或重写文档内容.

从 editor.storage['textColor'] 作为 TextColorStorage 之后 注册 TextColor启用 TextColorPreviewMark 用于提供每个跨度/颜色 双对和 TextColorPreview 用于返回的生命周期把手。 宽度从 您信任的编辑器计划; 能力不是 HTML 消毒器。 附上 在匹配主题下预览 .dm-editor 刷新前的屏幕样式. 保持所供应的跨度和字面颜色不变的指针寿命; 当替换渲染的内容时, 销毁并重现它.

可选打印准备

免费 1. 6.0 添加 Print.configure({ prepareResources: true }) 等待时间 命令驱动打印前的活图像和字体. 默认保留 马上 时间已定, cancelPrintPreparation() 选项 storage.print.preparation 承诺让申请报告或取消等待. 匹配的主题和标准表节点视图也支持符合条件的多行 在不修改文档 JSON 或选择的情况下打印页眉。 浏览器 pagination 当地对话的限制依然存在。 见 打印指南 用于配置、资源限制和支持的标题结构.

完整块背景

从1.5.0起, BlockColor 保持明确的六分卫, rgb() 财务报告和审定财务报表 rgba() 填写其现有 bgColor 节点属性. 有内含的段落或标题 background-color 因此,在整个街区保留一个填充,包括一个空的 页:1 在 HTML 中命名 CSS 颜色成为 literal 十六进制值; transparent 成为透明的 rgba() 填满 内嵌的亮点仍然独立. 阿尔法值被保留.

调色板符号, 如 red 财务报告和审定财务报表 gray 保留其主题含义并带走 优先于内在背景时 data-bg-color 已存在。 调色板 命令仍然只接受其配置的选择。 字形填充序列化为 background-color; 符号继续序列化为 data-bg-color。 。 。 .

只查看音调属性让匹配主题保持默认文本可读 已知的光或暗填充而不修改文档。 未解决的半透明 填充没有获得被猜测的音调。 明确文本颜色保留选中的 TextColor 上述对比政策.

可选列表标签

自1.5.0起提供, ListLabels 可以在边上添加 StarterKit 保留a 绑定自定义子弹或有文本前缀和后缀的定购计数器. 它不包括在 StarterKit 中. 在省略此扩展时,现有的计划及存储的JSON保持不变.

import { ListLabels, StarterKit } from '@domternal/core';

const extensions = [StarterKit, ListLabels];
// On an orderedList node:
const attrs = {
  start: 4,
  listLabel: { kind: 'counter', format: 'decimal', prefix: 'Section ', suffix: ') ' },
};

浏览器在项目编辑时更新了标记. 标记仍然是本地列表 演示文稿,在剪贴板文本或文档文本中不重复标记文本. 扩展在编辑器还活着的时候安装了被瞄准的同伴CSS. 设定 nonce 申请的CSP政策,或 injectCSS: false 当主机 提供CSS. getListLabelStyleSheet(json) 提供配套样式表 为已实现的 HTML。 HTML 不保留普通列表倒置. 纯洁 @domternal/core/list-labels 输入会暴露验证器,对于事项, 工人和服务器代码的样式表采集器和标签类型,不加载 编辑运行时间.

为了兼容性, ListLabel, (中文(简体) ), readListLabel, (中文(简体) ), formatListLabel 财务报告和审定财务报表 getNodeListLabel 保留原件 counter 财务报告和审定财务报表 text 合同。 读者 和物料返回 null 用于化合物和图片标签。 使用 ExtendedListLabel, (中文(简体) ), readExtendedListLabel, (中文(简体) ), parseExtendedListLabel, (中文(简体) ), formatExtendedListLabel 财务报告和审定财务报表 getNodeExtendedListLabel 当选择进入 其他变体。 除了节点读取器之外,除了纯度读取器之外,其他都可用 @domternal/core/list-labels 输入。 现有的详尽类型Script 开关 不需要新病例.

在1.6.0中,复合标签可以指附加订购的物品而不储存 复制的编号, 如 1.2 文档中。 例如,一个内部列表可以使用 { kind: 'compound', parts: [{ ancestor: 1, format: 'inherit' }, '.', { ancestor: 0, format: 'inherit' }, ') '], fallback: 'decimal' }。 。 。 . 标记在祖先的编号或格式更改后更新,包括撤消 和协作编辑。 缺少或未排序的被引用的祖先使用 普通的倒计时。 序列化的 HTML 是快照; 编辑后再生成它 源文档。 受约束的模板规则见下文合同.

免费 1. 6.0 也支持 { kind: 'image', src: pngDataUrl, text: '◆' } (单位:千美元) 子弹列表上的小本地图片标记. 限定配置接受静态 8- 位 RGB/ RGBA PNG最高可达32×32像素和4KiB,需要可读文本倒置. 这个 不获取远程标记资产或接受 SVG。 伴奏 CSS 显示 图片;当 CSS 不存在时,现有的标记仍然可用.

所有合作作者必须启用相同的列表标签方案。 老一点 没有扩展名的编剧可以在编辑一个时删除未知属性 列表中选择一个选项。 见 列表标签合同 页:1 支持记录、诊断、序列化和渲染限制.

完整 HTML 列表中从嵌入列表开始的项目接收空段落 解析时的标签,所以他们的外接编号,检查状态和后来的兄弟姐妹 呆在一起,别走 此功能用于负载、 粘贴、 滴放和服务器侧 HTML 转换 不粘贴清理。 原生部分复制品保持开阔的分界线; 初始 DOM 和已有效的列表项目不变.

内容和审定

在应用程序需要时使用 JSON 用于结构化存储和 HTML 或纯文本 这些格式。 正在装入 JSON 规范不支持的属性并拒绝链接; onContentDiagnostic 报告这些修复。 渲染现有共享文档 可以不重写其存储的数据而显示正态值.

在移民持续或合作内容之前,请阅读 内容正常化指南 财务报告和审定财务报表 发布注释。 。 。 . URL和样式检查适用于内置的内容路径. 自定义渲染器、 导出器 而上传仍然需要应用程序验证; 自定义 IconSet SVG 必须信任 应用程序代码。 见 安全指南。 。 。 .

onUpdate 运行用于已接受的文档更改,包括由 插件 。 被插件否决的交易不会运行更新回调 。 见 交易合同 当连接自动保存或外部状态时.

服务器侧渲染

generateHTML, (中文(简体) ), generateJSON 财务报告和审定财务报表 generateText 没有编辑实例的工作. HTML序列化和解析需要DOM. 在 Node.js 中,安装可选选项 linkedom 端点 :

pnpm add linkedom

没有 document 选项, generateHTML 财务报告和审定财务报表 generateJSON 装入已安装 linkedom 本身:来自22.3节点或以后的ES模块,以及来自 每个支持版本的普通JS. 直接通过文档选择 DOM 执行,或者运行时间无法加载时:

import { generateHTML, generateText, StarterKit } from '@domternal/core';
import { parseHTML } from 'linkedom';

const content = {
  type: 'doc',
  content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello' }] }],
};
const { document } = parseHTML('<!doctype html><html><body></body></html>');

const html = generateHTML(content, [StarterKit], { document });
const text = generateText(content, [StarterKit]);

generateJSON(html, extensions, { document }) 将 HTML 解析为 JSON . generateText 不需要一个DOM。 浏览器呼叫使用浏览器文档. 见 服务器侧公用事业。 。 。 .

免费 1. 6.0 添加 createSchema(extensions) 工人或无头人转换 输油管。 帮助者只使用相同的扩展构建ProseMirror 计划 作为编辑器的配置 :

import { createSchema, StarterKit } from '@domternal/core';

const schema = createSchema([StarterKit.configure({ heading: { levels: [1, 2, 3] } })]);
const doc = schema.nodeFromJSON(savedContent);
doc.check();

这个帮助器没有创建编辑器视图,插件或编辑器生命周期. 自定义方案 和存储工厂必须工作 没有浏览器或活编辑器。 分享一个 编辑器和工人之间的扩展工厂,包括自定义节点、标记 和配置属性。 它不规范导入的 JSON; 使用现有的 内容正常化 API .

本地化

自定义翻译目录使用 CompleteMessages<typeof definitions>。在核心中 1.4.0 定义不包含 optionalTranslation: true 仍须如此。 定义 标记 optionalTranslation: true 可能回到其英语默认状态,直到 应用程序翻译它,因此添加剂信息不需要打破已存在的目录. 使用 Required<CompleteMessages<typeof definitions>> 以要求每个当前消息 在一个保留的语言包。 运行时间 i18n.messages 超过部分. 六个 core.documentNotes.* 1.6.0中添加的信件是可选的,因此已有 完整 Core 目录继续键入并使用英文注释标签直至 这些译文已经提供.

指南

• 编辑器 API:命令,事件,生命周期和DOM收养.
• 本地化: 逐编语言,英语回落和可选 /locales/de 目录.
• 他们 财务报告和审定财务报表 打印。 。 。 .
• 内容正常化和移徙。 。 。 .
• URL 和样式策略: 海关联系控制和出口商.
• 剪贴板协调:用于扩展作者的实验性API.

许可证

麻省理工学院。 。 。 .