Web Components 是一组 Web 原生 API 的总称，允许开发人员创建可重用的自定义组件
原生 js 创建自定义元素的方法：
// 创建一个新的 div 元素
let newDiv = document.createElement("div");
// 给它一些内容
let newContent = document.createTextNode("Hi there and greetings!");
// 添加文本节点 到这个新的 div 元素
newDiv.appendChild(newContent);
// 将这个新的元素和它的文本添加到 DOM 中
let currentDiv = document.getElementById("div1");
document.body.insertBefore(newDiv, currentDiv);
可以发现原生 js 方式实现很复杂
那么如何在 Vue 中使用自定义元素？
defineCustomElement
vue3.2 提供了一个 API：defineCustomElement 创建自定义元素，并且使用与 Vue 组件完全一致的 API
该方法接受与 defineComponent 相同的参数，但是会返回一个扩展自 HTMLElement 的自定义元素构造函数
我们新建一个文件夹 web-component，建立 index.ts
import { defineCustomElement } from 'vue'
const MyVueElement = defineCustomElement({
// 在此提供正常的 Vue 组件选项
props: {
info: String,
obj: Object
},
emits: {},
template: `<div class="test">{{ info }} - {{ obj.name }}</div>`,
// defineCustomElement 独有特性: CSS 会被注入到隐式根 (shadow root) 中
styles: [`.test { color: red; }`]
})
// 注册自定义元素
customElements.define('krry-vue-element', MyVueElement)
该文件在 main.ts 导入使用。然后我们在一个 vue 文件中使用这个自定义元素
<script setup lang="ts">
import { ref } from 'vue'
const info = ref('Krry')
const obj = ref({
name: 'My little part'
})
</script>
<template>
<krry-vue-element :info="info" :obj.prop="obj"></krry-vue-element>
</template>
会发现 console 报了两个警告，而且页面也没有渲染出来
- 第一个是因为：默认情况下，Vue 会优先尝试将一个非原生的 HTML 标签解析为一个注册的 Vue 组件，如果失败则会将其渲染为自定义元素。这种行为会导致在开发模式下的 Vue 发出“failed to resolve component”的警告
所以需要告诉 Vue 将某些确切的元素作为自定义元素处理并跳过组件解析。在 vite.config.ts 配置：
plugins: [vue({
template: {
compilerOptions: {
// 以 krry- 开头的作为自定义元素处理
isCustomElement: tag => tag.startsWith('krry-')
}
}
})],
- 第二个是因为：组件提供模板选项，但是在 Vue 这个构建中不支持运行时编译
需要配置你的 bundler 别名 vue： vue/dist/vue.esm-bundler.js
resolve: {
alias: {
'vue': 'vue/dist/vue.esm-bundler.js',
'@': resolve(__dirname, 'src')
}
}
现在正常渲染了
Props
所有使用 props 选项声明的 prop 都将在自定义元素上定义为 property。Vue 将在合适的时候自动处理 attribute / property 之间的映射。
Attribute 总是映射为相应的 property。
基础类型 (string、boolean 或 number) 的 property 会被映射为 attribute。
Vue 也会自动将声明为 Boolean 或 Number 类型的 attribute prop (始终为字符串)转换为所需的类型。例如给出以下 prop 声明：
props: {
selected: Boolean,
index: Number
}
以及自定义元素用法：
<my-element selected index="1"></my-element>
在组件中，selected 会被转换为 true (boolean)，index 会被转换为 1 (number)。
传递 DOM Property
由于 DOM attribute 只能是字符串，因此我们如果将复杂数据作为 DOM property 传递给自定义元素，按正常 :obj="obj" 方式传递会失败：浏览器会解析成 obj="[object Object]"
<krry-vue-element :info="info" :obj="obj"></krry-vue-element>
此时，可以使用 .prop 修饰符强制将一个 v-bind 绑定设置为一个 DOM property：
<!-- 本文章第一个例子就是 -->
<krry-vue-element :info="info" :obj.prop="obj"></krry-vue-element>
<!-- 官方还有一个等效的简写，但我还是推荐第一种 -->
<my-element .user="{ name: 'jack' }"></my-element>
事件
在自定义元素中，通过 this.$emit 或在 setup 方法中的 emit 发出的事件会被调度为原生 CustomEvents
附加的事件参数 (payload) 会作为数组暴露在 CustomEvent 对象的 details property 上。
插槽
在组件内部，可以像往常一样使用 <slot/> 渲染插槽。但是在解析最终生成的元素时，它只接受原生插槽语法：
- 不支持作用域插槽。
- 传递命名插槽时，请使用 slot attribute 而非 v-slot 指令：
<my-element>
<div slot="named">hello</div>
</my-element>
将 SFC 作为自定义元素
defineCustomElement 也适用于 Vue 单文件组件 (SFC)，要选用此模式，只需使用 .ce.vue 作为文件拓展名即可。
我们定义一个 little-sfc.ce.vue
<script setup lang="ts">
defineProps({
list: { type: Array, default: () => [
{
name: 'krry'
},
{
name: '2oefa'
},
{
name: 'wefae'
}
]}
})
</script>
<template>
<h3>我是一个自定义 Web Components</h3>
<ul>
<li v-for="ele in list" :key="ele.name">{{ ele.name }}</li>
</ul>
</template>
<style scoped>
ul, li {
list-style: none;
padding: 0;
}
</style>
index.ts
import { defineCustomElement } from 'vue'
import LittleSfc from './little-sfc.ce.vue'
console.log(LittleSfc.styles) // ["/* 内联的 css */"]
const LittleSfcEle = defineCustomElement(LittleSfc)
// 注册
customElements.define('krry-little-sfc', LittleSfcEle)
页面中使用
<krry-little-sfc></krry-little-sfc>
以自定义元素模式加载的 SFC 将其 <style> 标签作为 CSS 字符串内联，并在组件的 styles 选项中暴露出来，然后会被 defineCustomElement 获取并在实例化时注入隐式根。
