这是第 174 篇不掺水的原创,想获取更多原创好文,请搜索公众号关注我们吧~ 本文首发于政采云前端博客:uni-app 黑魔法探秘 (一)—— 重写内置标签
一、背景
政采前端团队的移动端跨端解决方案选择的是 uni-app。跨端方案的好处就是一码多端,即书写一次就可以输出到 web、小程序、Anroid、iOS 等各端。既然是开发,那必然少不了配套的组件库和方法库,而我们公司因为历史原因存在一些的非 uni-app 的项目,vue2 和 vue3 也都在用,而重构的收益又不高,那如何开发一套多个技术栈下都能用的组件库&方法库就成为了我们最大的挑战。
在 uni-app 项目的开发过程中,我和小伙伴们不断为 uni-app 中一些写法感到好奇。譬如如何重写内置标签、类似c++中预处理器指令的条件编译、为什么 vue 文件中我没加 scoped 也会自动加上命名空间。后续深入了解才发现,uni-app 魔改了 vue 运行时,并且自制了一些 webpack 插件来实现。所以笔者希望通过《uni-app 黑魔法探秘》系列文章,将探索 uni-app、vue、webpack 的心路历程分享给大家,希望通过这一些列文章,最终读者自己也能实现一个简单的跨端框架。
开篇就先从如何重写内置标签讲起。什么是内置标签呢?就是 html 里约定的一些元素,譬如 div、button 等和 svg 里约定的一些标签譬如 image、view 等。
二、准备工作
先做些准备工作,创建两个项目。 1)通过 vue-cli 生成一个 vue2 项目,后续重写内置的组件的逻辑放在这个项目里。
vue create vue2-project
2)再通过 vue-cli 生成一个 uni-app 项目,作为对照组。
vue create -p dcloudio/uni-preset-vue uni-app-project
PS:本人 node 版本为 14.19.3,vue-cli 版本为 4.5.13,vue-cli 生成的项目中 vue 版本为 2.7.14
三、重写 html 标签,以 button 标签举例
<button>click me</button>
先让我们看看 uni-app 会把上面的 button 代码转换成什么样:
重写 button 标签有什么难的呢。我直接写一个组件,然后注册不就可以用了吗?
<template>
<uni-button>
<slot />
</uni-button>
</template>
<script>
export default {
name: 'VUniButton'
}
</script>
<template>
<div id="app">
<button>click me!</button>
</div>
</template>
<script>
import UniButton from './components/UniButton.vue'
export default {
name: 'App',
components: {
'button': UniButton,
}
}
</script>
结果是 button 根本没有被编译成 uni-button,并且控制台里能看到明显的错误
通过错误堆栈找到 vue.runtime.esm.js@4946
中对应的代码
关键词是 isBuiltInTag、config.isReservedTag,再顺藤摸瓜找到如下源码:
var isBuiltInTag = makeMap('slot,component', true);
var isHTMLTag = makeMap('html,body,base,head,link,meta,style,title,' + 'address,article,aside,footer,header,h1,h2,h3,h4,h5,h6,hgroup,nav,section,' + 'div,dd,dl,dt,figcaption,figure,picture,hr,img,li,main,ol,p,pre,ul,' + 'a,b,abbr,bdi,bdo,br,cite,code,data,dfn,em,i,kbd,mark,q,rp,rt,rtc,ruby,' + 's,samp,small,span,strong,sub,sup,time,u,var,wbr,area,audio,map,track,video,' + 'embed,object,param,source,canvas,script,noscript,del,ins,' + 'caption,col,colgroup,table,thead,tbody,td,th,tr,' + 'button,datalist,fieldset,form,input,label,legend,meter,optgroup,option,' + 'output,progress,select,textarea,' + 'details,dialog,menu,menuitem,summary,' + 'content,element,shadow,template,blockquote,iframe,tfoot');
// this map is intentionally selective, only covering SVG elements that may
// contain child elements.
var isSVG = makeMap('svg,animate,circle,clippath,cursor,defs,desc,ellipse,filter,font-face,' + 'foreignobject,g,glyph,image,line,marker,mask,missing-glyph,path,pattern,' + 'polygon,polyline,rect,switch,symbol,text,textpath,tspan,use,view', true);
var isReservedTag = function(tag) {
return isHTMLTag(tag) || isSVG(tag);
};
可以看到 vue 源码中枚举了 html 标签,这些标签默认不允许被重写。
通过搜索 uni-app 源码发现, isReservedTag 这个方法其实是可以重写的(虽然 vue 文档里没标注)。改写的代码如下:
const overrideTags = ['button']
// 1)先保存原来的 isReservedTag 逻辑
const oldIsReservedTag = Vue.config.isReservedTag;
Vue.config.isReservedTag = function (tag) {
// 2)在遇到 button 标签的时候,不认为是个内置标签
if (overrideTags.indexOf(tag) !== -1) {
return false;
}
// 3)非 button 标签再走原来的内置标签的判断逻辑
return oldIsReservedTag(tag);
};
增加上述代码后并添加样式后, uni-button 已经能成功被渲染出来了
但是控制台中还是有一行报错
还是通过错误的堆栈定位到 vue.runtime.esm.js@6274
中 isUnknownElement
这个方法。
然后发现也是可以被重写的,重写逻辑如下
// ignoredElements 默认是 [],所以直接覆盖即可
Vue.config.ignoredElements = [
'uni-button',
];
到现在为止 button 已经能被正确渲染了,main.js
中的代码如下
import Vue from 'vue'
import App from './App.vue'
Vue.config.productionTip = false
// 为了解决报错 [Vue warn]: Unknown custom element: <uni-button> - did you register the component correctly? For recursive components, make sure to provide the "name" option.
// 默认是 [],所以直接覆盖即可
Vue.config.ignoredElements = [
'uni-button',
];
// 为了解决报错 [Vue warn]: Do not use built-in or reserved HTML elements as component id: button
const overrideTags = ['button']
const oldIsReservedTag = Vue.config.isReservedTag;
Vue.config.isReservedTag = function (tag) {
if (overrideTags.indexOf(tag) !== -1) {
return false;
}
return oldIsReservedTag(tag);
};
new Vue({
render: h => h(App),
}).$mount('#app')
四、重写 svg 标签,以 image 举例
我们根据上述流程再实现一个 image 组件
<template>
<uni-image>
<img :src="src" >
</uni-image>
</template>
<script>
export default {
name: 'image',
props: {
src: {
type: String,
default: ""
}
},
}
</script>
<style>
uni-image {
width: 320px;
height: 240px;
display: inline-block;
overflow: hidden;
position: relative;
}
</style>
结果发现元素是正确的,但是没有被页面上没有展示。
通过 uni-app 源码(uni-app/lib/h5/ui.js@24)搜索发现其中有这样一段代码,添加后可以正确渲染了
const oldGetTagNamespace = Vue.config.getTagNamespace
const conflictTags = ['switch', 'image', 'text', 'view']
Vue.config.getTagNamespace = function (tag) {
if (~conflictTags.indexOf(tag)) { // svg 部分标签名称与 uni 标签冲突
return false
}
return oldGetTagNamespace(tag) || false
}
尝试理解一下,在 vue.runtime.esm.js 中搜索关键词 getTagNamespace
,最终定位在这一关键行 vue.runtime.esm.js@@2873
。有无上述一行代码的区别是 ns 的值为 svg 还是 false
继续找到 getTagNamespace 实现逻辑,发现 vue 会通过 getTagNamespace 这个方法决定创建元素时使用的方法是 createElement 还是 createElementNS。
// vue.runtime.esm.js@6263
function getTagNamespace(tag) {
if (isSVG(tag)) {
return 'svg';
}
// basic support for MathML
// note it doesn't support other MathML elements being component roots
if (tag === 'math') {
return 'math';
}
}
// vue.runtime.esm.js@6240
var namespaceMap = {
svg: 'http://www.w3.org/2000/svg',
math: 'http://www.w3.org/1998/Math/MathML'
};
// vue.runtime.esm.js@6317
function createElement(tagName, vnode) {
var elm = document.createElement(tagName);
if (tagName !== 'select') {
return elm;
}
// false or null will remove the attribute but undefined will not
if (vnode.data && vnode.data.attrs && vnode.data.attrs.multiple !== undefined) {
elm.setAttribute('multiple', 'multiple');
}
return elm;
}
function createElementNS(namespace, tagName) {
return document.createElementNS(namespaceMap[namespace], tagName);
}
命名空间存在的意义是,一个文档可能包含多个软件模块的元素和属性,在不同软件模块中使用相同名称的元素或属性,可能会导致识别和冲突问题,而 xml 命名空间可以解决该问题。
所以为什么没法渲染的原因显而易见了。因为把一个通过 svg 命名空间的创建出来的元素,挂载在非 svg 标签下。解决方案也很好理解,重写 getTagNamespace 方法,在遇到 image 标签时,认为其不是个 svg 标签,通过 createElement 方法创建在默认命名空间下即可。
最后 main.js
中的代码如下
import Vue from 'vue'
import App from './App.vue'
Vue.config.productionTip = false
// 下面三条参考 uni-app 源码实现 uni-app/lib/h5/ui.js
// ① 为了解决报错 [Vue warn]: Unknown custom element: <uni-button> - did you register the component correctly? For recursive components, make sure to provide the "name" option.
Vue.config.ignoredElements = [
'uni-button',
'uni-image',
];
// ② 为了解决报错 [Vue warn]: Do not use built-in or reserved HTML elements as component id: button
const overrideTags = ['button', 'image']
// 1)先保存原来的 isReservedTag 逻辑
const oldIsReservedTag = Vue.config.isReservedTag;
Vue.config.isReservedTag = function (tag) {
// 2)在遇到 button 标签的时候,不认为是个内置标签
if (overrideTags.indexOf(tag) !== -1) {
return false;
}
// 3)非 button 标签再走原来的内置标签的判断逻辑
return oldIsReservedTag(tag);
};
// ③ 为了解决 image 标签虽然被解析,但是渲染不出来的问题
// svg 部分标签名称与 uni 标签冲突
const conflictTags = [
'image',
// 'switch',
// 'text',
// 'view',
];
const oldGetTagNamespace = Vue.config.getTagNamespace;
Vue.config.getTagNamespace = function (tag) {
// “~”运算符(位非)用于对一个二进制操作数逐位进行取反操作。位非运算实际上就是对数字进行取负运算,再减 1
// 等价于 conflictTags.indexOf(tag) > -1
if (~conflictTags.indexOf(tag)) {
return false;
}
return oldGetTagNamespace(tag);
};
new Vue({
render: h => h(App),
}).$mount('#app')
五、总结
针对内置标签的解析,很庆幸 vue 还是留了一道后门的,不然就要魔改 vue 的源码了。uni-app 中有很多类似的黑魔法。为什么称之为黑魔法呢,因为其中使用的方法可能是官网中不会讲到的,或者是些需要巧思的。像魔术一样,看似很神奇,真的知道解决方案后就会恍然大悟。我相信这些黑魔法的出现并不是为了炫技,而更多的是在熟悉原理后的决策。
笔者上文的思路是在已知问题(内置标签无法解析)和答案(改写 Vue.config方法)的前提进行的推理,纵然是这样,也让我颇费功夫,如此一想 uni-app 一个个技术关键点的实现就让我愈发感到敬佩和好奇,这也是我打算执笔写这系列文章的初衷。
推荐阅读
开源作品
- 政采云前端小报
开源地址 www.zoo.team/openweekly/ (小报官网首页有微信交流群)
- 商品选择 sku 插件
招贤纳士
政采云前端团队(ZooTeam),一个年轻富有激情和创造力的前端团队,隶属于政采云研发部,Base 在风景如画的杭州。团队现有 80 余个前端小伙伴,平均年龄 27 岁,近 4 成是全栈工程师,妥妥的青年风暴团。成员构成既有来自于阿里、网易的“老”兵,也有浙大、中科大、杭电等校的应届新人。团队在日常的业务对接之外,还在物料体系、工程平台、搭建平台、性能体验、云端应用、数据分析及可视化等方向进行技术探索和实战,推动并落地了一系列的内部技术产品,持续探索前端技术体系的新边界。
如果你想改变一直被事折腾,希望开始能折腾事;如果你想改变一直被告诫需要多些想法,却无从破局;如果你想改变你有能力去做成那个结果,却不需要你;如果你想改变你想做成的事需要一个团队去支撑,但没你带人的位置;如果你想改变既定的节奏,将会是“5 年工作时间 3 年工作经验”;如果你想改变本来悟性不错,但总是有那一层窗户纸的模糊… 如果你相信相信的力量,相信平凡人能成就非凡事,相信能遇到更好的自己。如果你希望参与到随着业务腾飞的过程,亲手推动一个有着深入的业务理解、完善的技术体系、技术创造价值、影响力外溢的前端团队的成长历程,我觉得我们该聊聊。任何时间,等着你写点什么,发给 ZooTeam@cai-inc.com