CKEditor 4 链接插件电话链接(tel:)功能:手动测试指南与源码原理解析
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 与 phone.html:核心功能与校验测试;
- phoneinputkama.md、phoneinputmoono.md、phoneinputmoonolisa.md:分别验证三种皮肤(kama / moono / moono-lisa)下电话号码输入框的样式表现。
手动测试文档全解析:操作步骤与预期结果
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:创建电话链接
对两个编辑器执行以下操作:
- 点击工具栏上的 链接(Link) 按钮,打开链接对话框;
- 在“链接类型(Link Type)”下拉框中选择 Phone(电话);
- 点击 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 );
}
}
校验分三层执行:
- 类型闸门:只有当前链接类型为
tel时才触发校验,否则直接返回true(放行); - 非空校验:使用语言包中的
noTel文案(简体中文为“请输入电话号码”,见 plugins/link/lang/zh-cn.js)提示用户必须填写号码; - 正则校验(可选):仅当配置了
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)”模式。与其余类型的差异主要体现在两点:
- 协议固定:URL 类型可选
http://、https://、ftp://、news://等协议(见 dialogs/link.js#L285-L293),而电话类型固定生成tel:前缀,无需选择协议; - 无目标页签:切换为电话类型时“目标(Target)”页签会被隐藏(dialogs/link.js#L167-L172),因为
tel:链接没有打开新窗口之类的目标语义。
从编辑与解析角度看,电话链接与锚点链接(# 前缀)一样,通过正则模式识别后回填对话框(telRegex / anchorRegex),因此对既有 tel: 链接可以反复编辑,符合链接插件“所见即所得、可重编辑”的设计惯例。
小结:在项目中使用电话链接功能
要在你自己的 CKEditor 4 项目中启用电话链接,只需满足两个前提:
- 版本 ≥ 4.11.0,并加载
link插件(含toolbar等依赖插件); - 需要格式校验时,通过
linkPhoneRegExp与linkPhoneMsg配置号码规则与报错文案。
之后用户在链接对话框中即可选择“电话”类型,填写显示文本与号码,生成 <a href="tel:..."> 链接;编辑已有 tel: 链接时对话框会自动识别并回填。验证该功能是否正常,可直接运行 phone.html 手动测试页,按 phone.md 的四步操作逐一核对预期结果,其中“有校验编辑器”配置了 /^[0-9]{9}$/(9 位数字)这一典型格式约束,可作为业务落地时的参照模板。