CKEditor 4 链接插件电话链接(tel:)功能:手动测试指南与源码原理解析

原创2026-10-15 18:24:141,362 阅读
文章标签:前端UI组件

CKEditor 4 链接插件电话链接(tel:)功能:手动测试指南与源码原理解析

导读

本文围绕 CKEditor 4 仓库中的手动测试文档 phone.md 展开,系统讲解 Link 插件在 4.11.0 版本引入的**电话链接(Phone Link)**功能:如何在链接对话框中创建 tel: 协议链接、如何配置电话号码格式校验规则,以及底层对话框与校验逻辑的源码实现。读完本文,你将掌握该功能的完整操作路径、linkPhoneRegExp 与 linkPhoneMsg 两个核心配置项的实际用法,并能依据仓库源码理解其校验与生成 href 的底层机制。

功能背景:从 Issue #2154 到 4.11.0

电话链接功能源于 CHANGES.md 中记录的变更条目:

#2154:The Link plugin now supports phone number links.

即从 CKEditor 4.11.0 起,Link 插件在“链接类型(Link Type)”下拉框中新增了 Phone(电话) 选项,允许用户在编辑器中生成形如 <a href="tel:123123123">Foo</a> 的超链接,方便移动端一键拨号等场景。

与该功能配套的手动测试位于 tests/plugins/link/manual/ 目录,包含多组测试资源:

手动测试文档全解析:操作步骤与预期结果

phone.md 顶部通过 Bender 标签声明了测试环境:

@bender-tags: feature, link, 2154, 4.11.0
@bender-ckeditor-plugins: link, toolbar, wysiwygarea, sourcearea
@bender-ui: collapsed
  • feature:本测试覆盖的是新功能;
  • link:被测插件为 Link;
  • 2154:关联的 GitHub Issue 编号;
  • 4.11.0:该功能引入的版本;
  • 插件集合 link, toolbar, wysiwygarea, sourcearea 表明测试同时依赖工具栏(触发对话框)、所见即所得编辑区与源码视图(用于核对生成的 HTML)。

测试页面 phone.html 创建了两个编辑器,分别对应“无校验”与“有校验”两种场景:

<h2>No validation</h2>
<textarea id="editor1"></textarea>

<h2>Validation</h2>
<textarea id="editor2"></textarea>
<script>
	CKEDITOR.replace( 'editor1' );
	CKEDITOR.replace( 'editor2', {
		linkPhoneRegExp: /^[0-9]{9}$/,
		linkPhoneMsg: 'Invalid number'
	} );
</script>

测试步骤 1:创建电话链接

对两个编辑器执行以下操作:

  1. 点击工具栏上的 链接(Link) 按钮,打开链接对话框;
  2. 在“链接类型(Link Type)”下拉框中选择 Phone(电话);
  3. 点击 OK。

预期结果:弹出提示框(Alert),提示需要输入电话号码。这是因为电话号码输入框(telNumber)被声明为必填项(required: true),未填写时触发非空校验并弹出提示。

测试步骤 2:填写合法号码

在对话框中填写以下内容并点击 OK:

Display name: Foo
Phone number: 123123123

预期结果:编辑器中出现链接。

测试步骤 3:源码视图核对

点击 Source(源代码) 按钮,切换到源码模式:

预期结果:编辑器内容为

<a href="tel:123123123">Foo</a>

即电话号码被完整写入 href 的 tel: 协议中,显示文本为 Foo。

测试步骤 4:非法号码的差异化表现

重复步骤 1、2(重新打开对话框并选择 Phone 类型),随后填写:

Display name: Foo
Phone number: Bar

预期结果:

  • 第一个编辑器(无校验):链接照常出现在编辑器中;
  • 第二个编辑器(配置了校验):弹出提示框,告知号码无效。

测试备注

Valid phone number for this test is XXXXXXXXX (9 digits).

即测试用例约定的“合法”号码为 9 位数字,这正是第二个编辑器中 linkPhoneRegExp: /^[0-9]{9}$/ 所表达的格式约束。

源码实现:链接对话框如何承载电话类型

类型下拉框与选项联动

链接对话框在 plugins/link/dialogs/link.js 中定义“链接类型”下拉框:

{
	id: 'linkType',
	type: 'select',
	label: linkLang.type,
	'default': 'url',
	items: [
		[ linkLang.toUrl, 'url' ],
		[ linkLang.toAnchor, 'anchor' ],
		[ linkLang.toEmail, 'email' ],
		[ linkLang.toPhone, 'tel' ]
	],
	onChange: linkTypeChanged,
	...
}

类型值 'tel' 与显示文案 linkLang.toPhone(即语言包中的“电话”)一一对应。切换类型时,linkTypeChanged 函数(dialogs/link.js#L153-L189)会维护一组选项容器:

var partIds = [ 'urlOptions', 'anchorOptions', 'emailOptions', 'telOptions' ],

它根据当前类型只显示对应的选项区,并隐藏其余选项区;同时,非 URL 类型还会隐藏“目标(Target)”页签与上传相关页签:

} else {
	dialog.hidePage( 'target' );
	...
}

电话选项区与输入框定义

电话选项区在 dialogs/link.js#L583-L612 定义:

{
	type: 'vbox',
	id: 'telOptions',
	padding: 1,
	children: [ {
		type: 'tel',
		id: 'telNumber',
		label: linkLang.phoneNumber,
		required: true,
		validate: validateTelNumber,
		setup: function( data ) {
			if ( data.tel ) {
				this.setValue( data.tel );
			}
			...
		},
		commit: function( data ) {
			data.tel = this.getValue();
		}
	} ],
	...
}

关键点:

  • type: 'tel' 是 HTML5 原生电话输入框类型,在移动端会弹出数字键盘;
  • required: true 保证号码非空,对应手动测试步骤 1 中“未填号码即确认”时的弹窗提示;
  • setup 负责打开对话框时回填已有电话号码;
  • commit 负责在确认时将输入值写入对话框数据对象 data.tel。

tel: 地址的生成与识别

对话框确认后,plugins/link/plugin.js#L688-L690 将 data.tel 组装为最终的 href:

case 'tel':
	set[ 'data-cke-saved-href' ] = 'tel:' + data.tel;
	break;

data-cke-saved-href 是 CKEditor 内部的“保存用 href”,随后会被同步到真实的 href 属性(plugin.js#L747-L749),最终得到 <a href="tel:123123123">Foo</a>。

反向地,当用户重新选中一个已有的 tel: 链接并再次打开对话框时,插件通过正则识别并回填类型与号码。相关正则定义于 plugin.js#L231:

telRegex = /^tel:(.*)$/;

识别逻辑位于 plugin.js#L515-L523:

if ( !retval.type ) {
	if ( ( anchorMatch = href.match( anchorRegex ) ) ) {
		...
	} else if ( ( telMatch = href.match( telRegex ) ) ) {
		retval.type = 'tel';
		retval.tel = telMatch[ 1 ];
	}
	...
}

由此,链接类型下拉框会自动切回“电话”,号码输入框也会回填 tel: 之后的部分。

校验机制:linkPhoneRegExp 与 linkPhoneMsg

校验函数 validateTelNumber

电话号码校验入口是 dialogs/link.js#L1049-L1068 中的 validateTelNumber:

function validateTelNumber() {
	var dialog = this.getDialog(),
		editor = dialog._.editor,
		regExp =  editor.config.linkPhoneRegExp,
		msg = editor.config.linkPhoneMsg,
		linkLang = editor.lang.link,
		messageWhenEmpty = CKEDITOR.dialog.validate.notEmpty( linkLang.noTel ).apply( this );

	if ( !dialog.getContentElement( 'info', 'linkType' ) || dialog.getValueOf( 'info', 'linkType' ) != 'tel' ) {
		return true;
	}

	if ( messageWhenEmpty !== true ) {
		return messageWhenEmpty;
	}

	if ( regExp ) {
		return CKEDITOR.dialog.validate.regex( regExp, msg ).call( this );
	}
}

校验分三层执行:

  1. 类型闸门:只有当前链接类型为 tel 时才触发校验,否则直接返回 true(放行);
  2. 非空校验:使用语言包中的 noTel 文案(简体中文为“请输入电话号码”,见 plugins/link/lang/zh-cn.js)提示用户必须填写号码;
  3. 正则校验(可选):仅当配置了 linkPhoneRegExp 时,才用 CKEDITOR.dialog.validate.regex 结合 linkPhoneMsg 进行格式校验。

这正是手动测试步骤 4 中“第一个编辑器不校验、第二个编辑器弹窗报错”两种表现差异的来源:未配置 linkPhoneRegExp 时校验函数在正则环节直接跳过,任何非空字符串(包括 Bar)都能通过。

两个配置项的定义

两个配置项在 plugin.js#L937-L959 中以文档注释形式定义:

/**
 * Optional JavaScript regular expression used whenever phone numbers in the Link dialog should be validated.
 *
 * ```js
 * config.linkPhoneRegExp = /^[0-9]{9}$/;
 * ```
 *
 * @since 4.11.0
 * @cfg {RegExp} [linkPhoneRegExp]
 * @member CKEDITOR.config
 */

/**
 * Optional message for the alert popup used when the phone number in the Link dialog does not pass the validation.
 *
 * ```js
 * config.linkPhoneMsg = "Invalid number";
 * ```
 *
 * @since 4.11.0
 * @cfg {String} [linkPhoneMsg]
 * @member CKEDITOR.config
 */
配置项 类型 默认值 作用 引入版本
linkPhoneRegExp RegExp 未定义(不校验) 定义电话号码的合法格式,用于校验 telNumber 输入框内容 4.11.0
linkPhoneMsg String 未定义 号码未通过正则校验时弹出的提示文案 4.11.0

在全局配置(如 config.js)或实例化参数中均可设置,例如:

CKEDITOR.replace( 'editor', {
	linkPhoneRegExp: /^[0-9]{9}$/,
	linkPhoneMsg: '请输入 9 位数字电话号码'
} );

实际使用建议:

  • 若业务不限定号码格式(如允许国际区号、分机号、+、-、空格等),可以不配置 linkPhoneRegExp,仅保留非空校验;
  • 若需要严格约束(如仅允许固定位数的数字),务必同时配置 linkPhoneMsg 提供可读的报错信息;
  • 正则应以 ^ 和 $ 锚定首尾,避免“部分匹配”导致的误通过(例如 /^[0-9]{9}$/ 不会放行 1234567890 或 123-456-789)。

国际化:电话相关界面文案

电话链接的界面文案分散在 Link 插件的各语言包中,以简体中文 plugins/link/lang/zh-cn.js 与繁体中文 plugins/link/lang/zh.js 为例:

语言键 简体中文 繁体中文 用途
toPhone 电话 電話 链接类型下拉框中的“电话”选项
phoneNumber 电话号码 電話號碼 电话选项区的输入框标签
noTel 请输入电话号码 請輸入電話號碼 号码为空时的非空校验提示

这三处文案分别对应源码中的 linkLang.toPhone、linkLang.phoneNumber 与 linkLang.noTel 引用,覆盖了从类型选择、输入提示到校验反馈的完整交互链路。

与其他链接类型的对比与集成

电话链接与 Link 插件的既有类型共用同一套对话框架构:类型下拉框(linkType)、选项容器(urlOptions / anchorOptions / emailOptions / telOptions)以及“提交(commit)/回填(setup)”模式。与其余类型的差异主要体现在两点:

  1. 协议固定:URL 类型可选 http://、https://、ftp://、news:// 等协议(见 dialogs/link.js#L285-L293),而电话类型固定生成 tel: 前缀,无需选择协议;
  2. 无目标页签:切换为电话类型时“目标(Target)”页签会被隐藏(dialogs/link.js#L167-L172),因为 tel: 链接没有打开新窗口之类的目标语义。

从编辑与解析角度看,电话链接与锚点链接(# 前缀)一样,通过正则模式识别后回填对话框(telRegex / anchorRegex),因此对既有 tel: 链接可以反复编辑,符合链接插件“所见即所得、可重编辑”的设计惯例。

小结:在项目中使用电话链接功能

要在你自己的 CKEditor 4 项目中启用电话链接,只需满足两个前提:

  1. 版本 ≥ 4.11.0,并加载 link 插件(含 toolbar 等依赖插件);
  2. 需要格式校验时,通过 linkPhoneRegExp 与 linkPhoneMsg 配置号码规则与报错文案。

之后用户在链接对话框中即可选择“电话”类型,填写显示文本与号码,生成 <a href="tel:..."> 链接;编辑已有 tel: 链接时对话框会自动识别并回填。验证该功能是否正常,可直接运行 phone.html 手动测试页,按 phone.md 的四步操作逐一核对预期结果,其中“有校验编辑器”配置了 /^[0-9]{9}$/(9 位数字)这一典型格式约束,可作为业务落地时的参照模板。

登录后查看全文
ckeditor4