CKEditor 4 Paste from Word 零边距保留配置:pasteFromWord_keepZeroMargins / pasteTools_keepZeroMargins 原理与测试解析

原创2026-10-15 21:05:341,955 阅读
文章标签:前端UI组件

CKEditor 4 Paste from Word 零边距保留配置:pasteFromWord_keepZeroMargins / pasteTools_keepZeroMargins 原理与测试解析

导读

从 Microsoft Word 粘贴内容到 CKEditor 4 时,默认清理流程会移除值为 0 的 margin 样式(如 margin-left:0、margin-bottom:0),以保证粘贴结果干净一致。但对于某些依赖零边距布局的文档,这种"净化"反而破坏了原有排版。CKEditor 4 从 4.12.0 起提供了 pasteFromWord_keepZeroMargins 配置(4.13.0 起迁移为 pasteTools_keepZeroMargins),允许开发者选择保留这类零边距样式。本文以仓库中的手动测试用例 keepzeromargins.md 为主线,结合 common.js 与 default.js 的源码实现,完整讲解该配置的用法、底层原理、边界条件与对应的自动化测试,读完即可在真实项目中正确配置并验证该行为。

一、问题背景:Word 粘贴时零边距为何被移除

Microsoft Word 导出的 HTML 中,段落(p)、列表(ul/ol/li)等元素经常带有显式的 margin-*: 0 样式。CKEditor 4 的 Paste from Word 清理过滤器(位于 plugins/pastefromword/filter/default.js)会重建 Word 的内容模型,其中包含一个"归一化 margin"的步骤:将 CSS 中各种写法的 margin 统一处理后,默认只保留值为正数的 margin,值为 0(含 0px 等带单位写法)的 margin 一律删除。

删除零边距的理由很直接:margin:0 在视觉上通常没有实际影响,保留它只会增加 HTML 冗余;且 Word 生成的零边距往往是"重置浏览器默认样式"的产物(例如 p 元素默认有上下边距,Word 常用 margin:0 显式重置),删除后由站点自身的 CSS 决定最终排版。然而这一默认行为并非总是符合需求——当粘贴内容本身依赖这些零边距来对齐布局时(例如垂直边距场景),零边距的丢失会导致样式不一致。这正是 issue #2935 引入配置项的背景,相关变更记录见 CHANGES.md。

二、配置项详解:命名、默认值与版本迁移

2.1 两个配置名:从 pasteFromWord_ 到 pasteTools_

在 plugins/pastefromword/plugin.js 中,pasteFromWord_keepZeroMargins 被标记为自 4.12.0 引入、4.13.0 起废弃,并明确指向新的 pasteTools_keepZeroMargins:

/**
 * See {@link #pasteTools_keepZeroMargins}.
 * @since 4.12.0
 * @deprecated 4.13.0
 * @cfg {Boolean} [pasteFromWord_keepZeroMargins=false]
 * @member CKEDITOR.config
 */

而新配置在 plugins/pastetools/filter/common.js 中有完整的 JSDoc 定义:

/**
 * Whether the `margin` style of a pasted element that equals to 0 should be removed.
 *
 * ```js
 *	// Disable removing `margin:0`, `margin-left:0`, etc.
 *	config.pasteTools_keepZeroMargins = true;
 * ```
 *
 * **Note**: Please remember to update the Advanced Content Filter
 * when you want to keep margins that other plugins don't use like `top` and `bottom`.
 *
 * @since 4.13.0
 * @cfg {Boolean} [pasteTools_keepZeroMargins=false]
 * @member CKEDITOR.config
 */

要点:

  • 默认值均为 false,即默认删除粘贴内容中的零边距;
  • 设为 true 时,"值为 0 的 margin 样式不再被移除";
  • 4.13.0 起优先使用 pasteTools_keepZeroMargins,旧名 pasteFromWord_keepZeroMargins 保留兼容但仍可用。

2.2 底层命名兼容机制:getConfigValue()

新旧两个配置名之所以都能生效,是因为 Paste Tools 在读取配置时做了三层命名兜底。见 plugins/pastetools/plugin.js 中的 getConfigValue():

getConfigValue: function( editor, configVariable ) {
	if ( !editor || !editor.config ) {
		return;
	}

	var tools = CKEDITOR.tools,
		config = editor.config,
		configVariables = tools.object.keys( config ),
		names = [
			'pasteTools_' + configVariable,
			'pasteFromWord_' + configVariable,
			'pasteFromWord' + tools.capitalize( configVariable, true )
		],
		found = tools.array.find( names, function( name ) {
			return tools.array.indexOf( configVariables, name ) !== -1;
		} );

	return config[ found ];
},

当过滤器内部以 getConfigValue( editor, 'keepZeroMargins' ) 取值时,会依次尝试 pasteTools_keepZeroMargins、pasteFromWord_keepZeroMargins 以及驼峰变体 pasteFromWordKeepZeroMargins,命中任何一个即生效。这意味着:

  • 4.13.0 之前的旧项目无需改配置名即可继续工作;
  • 新项目推荐使用 pasteTools_keepZeroMargins;
  • 配置了旧名而未配置新名时,取到的仍是旧值(不会因"新名缺失"而回退到默认值)。

三、源码级原理:零边距在哪里被保留或删除

3.1 通用样式归一化路径(common.js)

Paste Tools 通用过滤器在 plugins/pastetools/filter/common.js 中对每个元素的 style 做收尾处理:

var keepZeroMargins = CKEDITOR.plugins.pastetools.getConfigValue( editor, 'keepZeroMargins' );
// Still some elements might have shorthand margins or longhand with zero values.
parseShorthandMargins( styles );
normalizeMargins();

return CKEDITOR.tools.writeCssText( styles );

function normalizeMargins() {
	var keys = [ 'top', 'right', 'bottom', 'left' ];
	CKEDITOR.tools.array.forEach( keys, function( key ) {
		key = 'margin-' + key;
		if ( !( key in styles ) ) {
			return;
		}

		var value = CKEDITOR.tools.convertToPx( styles[ key ] );
		// We need to get rid of margins, unless they are allowed in config (#2935).
		if ( value || keepZeroMargins ) {
			styles[ key ] = value ? value + 'px' : 0;
		} else {
			delete styles[ key ];
		}
	} );
}

这段代码揭示了精确的判定逻辑:

  1. 只处理 margin-top / margin-right / margin-bottom / margin-left 四个长写属性;
  2. 先用 CKEDITOR.tools.convertToPx() 把 0、0px、0pt、0em 等统一换算成数值(0 换算后仍为 0);
  3. 当 value 非 0(即正边距)时无条件保留,统一序列化为 Npx;
  4. 当 value 为 0 且 keepZeroMargins 为 true 时保留为字面量 0;
  5. 当 value 为 0 且未开启配置时,直接从 style 中删除该键。

parseShorthandMargins()(common.js)是前置步骤:它把 Word 常见的简写 margin:16px 0 0 展开为四个长写属性,再交给 normalizeMargins() 逐边判定。正是这个展开,让"简写中某一边为 0"也能被精确识别:

function parseShorthandMargins( style ) {
	var marginCase = style.margin ? 'margin' : style.MARGIN ? 'MARGIN' : false,
		key, margin;
	if ( marginCase ) {
		margin = CKEDITOR.tools.style.parse.margin( style[ marginCase ] );
		for ( key in margin ) {
			style[ 'margin-' + key ] = margin[ key ];
		}
		delete style[ marginCase ];
	}
}

(注意它同时兼容 IE8 输出的全大写 MARGIN 键名。)

3.2 列表边距的专门路径(pastefromword/filter/default.js)

对于列表元素,Paste from Word 过滤器在 default.js 的 getMargin() 中独立处理:

function getMargin( element, margin ) {
	var parsedStyles = CKEDITOR.tools.parseCssText( element.attributes.style ),
		keepZeroMargins = CKEDITOR.plugins.pastetools.getConfigValue( editor, 'keepZeroMargins' ),
		searchedMargin = 'margin-' + margin;

	if ( !( searchedMargin in parsedStyles ) ) {
		return '';
	}

	var value = CKEDITOR.tools.convertToPx( parsedStyles[ searchedMargin ] );

	// Preserve keeping zero list margins when pasteTools_keepZeroMargins is ON (#5316).
	if ( value === 0 && keepZeroMargins ) {
		return searchedMargin + ': ' + value + '; ';
	}

	// Preserve keeping margins by default.
	if ( value > 0 ) {
		return searchedMargin + ': ' + value + 'px; ';
	}

	return '';
}

可以看到列表场景沿用同一套规则:正边距默认保留、零边距仅在开启配置时保留。此处源码注释明确关联了 issue #5316——即 4.22.0 之后为列表元素补上的垂直边距支持(详见下文第五节),对应变更记录见 CHANGES.md。

四、手动测试用例详解:keepzeromargins.md

仓库中的 keepzeromargins.md 是一个 Bender 手动测试(manual test)用例,用于在真实浏览器中验证配置行为,其配套页面为 keepzeromargins.html。

4.1 测试环境声明

文档头部的 bender 注释声明了测试属性:

@bender-tags: feature, 4.12.0, 2935, pastefromword
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, undo, pastefromword, sourcearea
  • 该用例属于 feature 类,对应 4.12.0 版本引入的 #2935 功能;
  • 运行所需插件:wysiwygarea、toolbar、undo、pastefromword、sourcearea(sourcearea 用于切换到源码模式检查粘贴结果)。

4.2 测试页面与两个对照编辑器

配套页面 keepzeromargins.html 创建了两个编辑器形成对照实验:

<p>Empty margins allowed:</p>
<textarea id="editor1"></textarea>
<p>No empty margins allowed:</p>
<textarea id="editor2"></textarea>

<script>
	if ( bender.tools.env.mobile ) {
		bender.ignore();
	}
	CKEDITOR.replace( 'editor1', {
		allowedContent: true,
		pasteFromWord_keepZeroMargins: true
	} );
	CKEDITOR.replace( 'editor2', {
		allowedContent: true
	} );
</script>
编辑器 配置 预期行为
editor1 allowedContent: true + pasteFromWord_keepZeroMargins: true 保留零边距样式
editor2 仅 allowedContent: true(默认配置) 移除零边距样式

另外,页面在移动端环境下直接 bender.ignore() 跳过测试(移动端不支持完整的 Word 粘贴模拟)。注意此处使用的是旧配置名 pasteFromWord_keepZeroMargins,恰好验证了上文 2.2 节的命名兼容机制——即使过滤器中以 keepZeroMargins 为键取值,该配置依然能被 getConfigValue() 命中。

4.3 操作步骤与判定标准

手动测试步骤(原文完整继承):

  1. 将测试夹具 Vertical_margin.docx 中的内容复制并粘贴到两个编辑器中;
  2. 切换到源码模式(Source),检查生成的 HTML 样式。

Expected(预期结果):

  • 第一个编辑器(开启配置):第一个 p 元素应带有样式
    margin-right:0; margin-bottom:0; margin-left:0;
    
    或在 IE 中为:
    margin: 16px 0px 0px
    
  • 第二个编辑器(默认配置):所有元素都不应带有值为 0 或 0+单位 的 margin。

Unexpected(非预期结果):

  • 第一个编辑器缺少 Expected 中列出的样式(说明零边距被误删);
  • 第二个编辑器的元素带有值为 0 的 margin(说明零边距未被清理)。

值得注意的判定细节:IE 中的预期结果是 margin: 16px 0px 0px(简写形式、0px 带单位),而其他浏览器中是三个零值长写属性。这反映了 IE 系浏览器输出 Word HTML 的样式书写习惯不同,但语义一致——margin-top 为 16px(正边距,默认保留),其余三边为 0(在开启配置时被保留)。这也印证了 parseShorthandMargins() 需要同时兼容 margin 与 MARGIN 两种键名、以及 0 与 0px 多种写法的原因。

五、自动化测试与列表扩展场景(#5316)

5.1 生成式测试:vertical_margin.js

除手动测试外,该功能还有对应的生成式自动化测试 vertical_margin.js:

var config = {
	allowedContent: true,
	language: 'en',
	removePlugins: pfwTools.defaultConfig.removePlugins,
	pasteFromWord_keepZeroMargins: true
};

bender.editor = {
	config: config
};

bender.test( createTestSuite( {
	browsers: [ 'chrome', 'edge', 'firefox', 'safari', 'ie11' ],
	wordVersions: [ 'word2013', 'word2016' ],
	tests: {
		'Vertical_margin': true
	},
	ignoreAll: CKEDITOR.env.ie || bender.tools.env.mobile,
	customFilters: [ pfwTools.filters.font ]
} ) );

该测试用 Word 2013 / Word 2016 两个版本生成的真实粘贴内容,在开启配置的前提下断言 Vertical_margin 夹具(位于 tests/plugins/pastefromword/generated/_fixtures/Vertical_margin)经过过滤器后保留零边距。手动测试中的 Vertical_margin.docx 正是由同一夹具而来。

5.2 列表零边距:keep_zero_margins_in_lists.js

4.22.0 的 #5316 把零边距支持扩展到了列表元素,配套的生成式测试 keep_zero_margins_in_lists.js 展示了 ACF(Advanced Content Filter)配合这一关键实操要点:

var config = {
	extraAllowedContent: 'p{text-indent,margin,margin-top,margin-bottom};' +
		'ul{margin,margin-top,margin-bottom};' +
		'ol{margin,margin-top,margin-bottom}',
	disallowedContent: 'span;p{text-align,margin-left,margin-right}',
	pasteTools_keepZeroMargins: true,
	language: 'en'
};

这里用 extraAllowedContent 显式允许 p、ul、ol 上的 margin-top / margin-bottom(以及其他边距),同时用 disallowedContent 排除 span 和 p 上的 text-align、margin-left、margin-right。这正是配置文档中那句提醒的落地实践:开启 keepZeroMargins 只是让过滤器"不再删除"零边距,元素最终能否把样式写进编辑内容,还取决于 ACF 是否允许该样式(margin-left、margin-right 通常不在默认允许集内,margin-top/margin-bottom 更是如此)。配置了 pasteTools_keepZeroMargins: true 却在 ACF 处被拦截,粘贴结果中依然不会出现零边距——这一点极易踩坑。

同目录下的另外两个手动用例可组合验证:keepzeromarginsinlists.md(预期 ul/ol 上出现 margin-bottom:0; margin-top:0;)与 keepmarginsinlists.md(预期保留 margin-bottom:32px; margin-top:32px; 的正边距对照),分别位于 keepzeromarginsinlists.md 与 keepmarginsinlists.md。

六、实战配置建议与注意事项

综合以上源码与测试证据,在实际项目中启用该功能的完整做法如下:

CKEDITOR.replace( 'editor', {
	// 4.13.0+ 推荐新配置名(旧名 pasteFromWord_keepZeroMargins 仍受兼容支持)
	pasteTools_keepZeroMargins: true,

	// 若目标元素(如 ul/ol/p)的上下边距不在 ACF 允许集内,需要显式放行
	extraAllowedContent: 'p{margin,margin-top,margin-bottom};' +
		'ul{margin,margin-top,margin-bottom};' +
		'ol{margin,margin-top,margin-bottom}'
} );

需要特别留意的三点:

  1. 默认值为 false:不配置即不保留零边距,符合大多数站点的"干净粘贴"预期;只有确实依赖 Word 零边距排版时才开启;
  2. ACF 是第二道闸门:过滤器保留样式只是第一步,common.js 的 JSDoc 已明确要求同步更新 Advanced Content Filter,否则 margin-top/margin-bottom 这类默认不被允许的样式仍会被丢弃;
  3. 配置名兼容:pasteFromWord_keepZeroMargins(4.12.0)与 pasteTools_keepZeroMargins(4.13.0)均可生效,由 getConfigValue() 按 pasteTools_ → pasteFromWord_ → 驼峰变体的顺序兜底解析,升级版本无需改动旧配置。

七、小结

pasteFromWord_keepZeroMargins / pasteTools_keepZeroMargins 是 CKEditor 4 Paste from Word 清理流程中一个"小而关键"的开关:它让值为 0 的 margin 样式从"一律删除"变为"按需保留",由 common.js 的 normalizeMargins() 与 default.js 的 getMargin() 共同实现,并通过三层配置名兜底保证新旧版本兼容。手动用例 keepzeromargins.md 用"双编辑器对照 + 源码模式检查"的方式,直观展示了配置开启前后的差异;而 keep_zero_margins_in_lists.js 则提醒我们:真正的样式落地还受 ACF 约束。理解了这条链路,你就能在"保持 Word 原始排版"与"输出干净 HTML"之间做出准确权衡。

登录后查看全文
ckeditor4