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 项目，后续重写内置的组件的逻辑放在这个项目里。

lua

vue create vue2-project

2）再通过 vue-cli 生成一个 uni-app 项目，作为对照组。

bash

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 标签举例

css

复制代码

<button>click me</button>

先让我们看看 uni-app 会把上面的 button 代码转换成什么样：

重写 button 标签有什么难的呢。我直接写一个组件，然后注册不就可以用了吗？

xml

<template> <uni-button> <slot /> </uni-button> </template> <script> export default { name: 'VUniButton' } </script>

xml

<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，再顺藤摸瓜找到如下源码：

css

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 文档里没标注）。改写的代码如下：

arduino

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这个方法。

然后发现也是可以被重写的，重写逻辑如下

ini

// ignoredElements 默认是 []，所以直接覆盖即可 Vue.config.ignoredElements = [ 'uni-button', ];

到现在为止 button 已经能被正确渲染了，main.js中的代码如下

javascript

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 组件

xml

<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）搜索发现其中有这样一段代码，添加后可以正确渲染了

arduino

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。

javascript

// 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中的代码如下

javascript

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 中有很多类似的黑魔法。为什么称之为黑魔法呢，因为其中使用的方法可能是官网中不会讲到的，或者是些需要巧思的。像魔术一样，看似很神奇，真的知道解决方案后就会恍然大悟。我相信这些黑魔法的出现并不是为了炫技，而更多的是在熟悉原理后的决策。