Cara menggunakan defineCustomElement untuk menentukan komponen dalam Vue3

Gunakan Vue untuk membina elemen tersuai

Komponen Web ialah nama kolektif untuk set API asli web yang membenarkan pembangun mencipta elemen tersuai yang boleh digunakan semula ( tersuai unsur).

Kelebihan utama menggunakan elemen tersuai ialah ia boleh digunakan dalam mana-mana bingkai atau persekitaran bukan bingkai. Ia sesuai apabila anda menyasarkan pengguna akhir yang mungkin menggunakan tindanan teknologi bahagian hadapan yang berbeza, atau apabila anda ingin memisahkan aplikasi akhir daripada butiran pelaksanaan komponen yang digunakannya.

Vue dan Komponen Web ialah teknologi pelengkap, dan Vue menyediakan sokongan yang sangat baik untuk menggunakan dan mencipta elemen tersuai. Dalam aplikasi Vue, anda boleh menyepadukan elemen tersuai, dan anda juga boleh menggunakan Vue untuk membina dan menerbitkan elemen tersuai.

Vue mencapai skor 100% dalam ujian Di Mana-mana Elemen Tersuai. Menggunakan elemen tersuai dalam aplikasi Vue pada asasnya mempunyai kesan yang sama seperti menggunakan elemen HTML asli, tetapi memerlukan beberapa konfigurasi tambahan untuk berfungsi:

Langkau resolusi komponen

Secara lalai, Vue Mana-mana HTML bukan asli teg akan dianggap sebagai komponen Vue terlebih dahulu, dengan "menjadikan elemen tersuai" sebagai pilihan sandaran. Ini akan menyebabkan Vue membuang amaran "Gagal menghuraikan komponen" semasa pembangunan.

• Untuk memberitahu Vue bahawa elemen tertentu harus dianggap sebagai elemen tersuai dan langkau penghuraian komponen, kami boleh menentukan pilihan compilerOptions.isCustomElement Nilai yang ditetapkan pada objek pilihan ini akan Ia digunakan semasa penyusunan templat dalam penyemak imbas dan akan menjejaskan semua komponen aplikasi yang dikonfigurasikan.

• Sebagai alternatif, pilihan ini boleh ditindih atas dasar setiap komponen melalui pilihan compilerOptions (dengan keutamaan yang lebih tinggi untuk komponen semasa).

Oleh kerana ia adalah pilihan masa kompilasi, alat binaan perlu menghantar konfigurasi ke @vue/compiler-dom:

• vue -loader: Pilihan melalui compilerOptions loader.

// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          // 将所有带 ion- 的标签名都视为自定义元素
          isCustomElement: tag => tag.startsWith('ion-')
        }
      }))
  }
}

• vite: Lulus sebagai pilihan kepada @vitejs/plugin-vue.

// vite.config.js
import vue from '@vitejs/plugin-vue'
export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 将所有带短横线的标签名都视为自定义元素
          isCustomElement: (tag) => tag.includes('-')
        }
      }
    })
  ]
}

• Konfigurasi kompilasi dalam penyemak imbas.

// src/main.js
// 仅在浏览器内编译时才会工作
const app = createApp(App)
app.config.compilerOptions.isCustomElement = (tag) => tag.includes('-')

Melalui atribut DOM

Memandangkan atribut DOM hanya boleh menjadi nilai rentetan, kami hanya boleh menggunakan atribut objek DOM untuk menghantar data yang kompleks. Apabila menetapkan prop untuk elemen tersuai, Vue 3 akan menyemak secara automatik sama ada sifat itu sudah wujud pada objek DOM melalui operator in dan jika kunci wujud, ia akan memilih untuk menetapkan nilai kepada sifat objek DOM. Ini bermakna, dalam kebanyakan kes, anda tidak perlu memikirkan isu ini jika elemen tersuai anda mengikut amalan terbaik yang disyorkan.

Walau bagaimanapun, terdapat beberapa kes khas: data mesti dihantar sebagai sifat objek DOM, tetapi elemen tersuai tidak dapat mentakrifkan/mencerminkan sifat ini dengan betul (kerana semakan in gagal). Dalam kes ini, anda boleh memaksa penggunaan v-bind mengikat dan menetapkan sifat objek DOM melalui .prop pengubah suai:

<my-element :user.prop="{ name: &#39;jack&#39; }"></my-element>
<!-- 等价简写 -->
<my-element .user="{ name: &#39;jack&#39; }"></my-element>

defineCustomElement()

Vue menyediakan A defineCustomElement kaedah yang hampir sama dengan mentakrifkan komponen Vue am menyokong penciptaan elemen tersuai. defineComponent adalah sama dengan parameter yang diterima oleh kaedah ini. Tetapi ia mengembalikan pembina untuk kelas unsur tersuai asli yang diwarisi daripada HTMLElement (boleh didaftarkan melalui customElements.define()).

function defineCustomElement(
  component:
    | (ComponentOptions & { styles?: string[] })
    | ComponentOptions['setup']
): {
  new (props?: object): HTMLElement
}

Selain daripada pilihan komponen biasa, defineCustomElement() juga menyokong gaya pilihan khas, yang merupakan susunan rentetan CSS sebaris CSS yang disediakan akan disuntik ke dalam ShadowRoot elemen.

<my-vue-element></my-vue-element>

rrree

Jika konsol melaporkan ralat pada masa ini: warna{red}{Jika konsol melaporkan ralat pada masa ini:} Jika konsol melaporkan ralat pada masa ini: Komponen menyediakan pilihan templat tetapi kompilasi masa jalan tidak disokong, dalam vite.config Tambahkan konfigurasi berikut pada js:

import { defineCustomElement } from 'vue'
const MyVueElement = defineCustomElement({
  // 这里是同平常一样的 Vue 组件选项
  props: {},
  emits: {},
  template: `...`,
  // defineCustomElement 特有的：注入进 ShadowRoot 的 CSS
  styles: [`/* css */`]
})
// 注册自定义元素之后，所有此页面中的 `<my-vue-element>` 标签都会被升级
customElements.define(&#39;my-vue-element&#39;, MyVueElement)
// 也可以在注册之后实例化元素：
document.body.appendChild(
  new MyVueElement({
    // 初始化 props（可选）
  })
)

Kitaran hayat

• Apabila connectionCallback elemen dipanggil pertama kali, elemen tersuai Vue akan dipasang contoh komponen Vue secara dalaman kepada ShadowRootnya.

• Apabila Elemen ini terputusCallback dipanggil, Vue akan menyemak selepas microtask sama ada elemen itu masih dalam dokumen.

• Jika elemen masih dalam dokumen, maka ia adalah operasi alih dan tika komponen akan dikekalkan; Jika elemen Jika elemen tidak lagi wujud dalam dokumen, maka ini adalah operasi pengalihan keluar dan contoh komponen akan dimusnahkan.

• Props

Semua prop yang diisytiharkan dalam pilihan props akan ditakrifkan sebagai atribut elemen tersuai. Vue boleh mengendalikan secara automatik dengan sewajarnya sama ada ia ditunjukkan sebagai harta atau harta.

attribute 总是根据需要反射为相应的属性类型。原话已经非常清晰明了，可以直接重述。重新表述如下： 基本数据类型的属性值（例如字符串、布尔值或数字）可以通过反射反映为属性。

当它们被设为 attribute 时 (永远是字符串)，Vue 也会自动将以 Boolean 或 Number 类型声明的 prop 转换为所期望的类型。比如下面这样的 props 声明：

props: {
  selected: Boolean,
  index: Number
}

并以下面这样的方式使用自定义元素：

<my-element selected index="1"></my-element>

在组件中，selected 会被转换为 true (boolean 类型值) 而 index 会被转换为 1 (number 类型值)。

事件

• emit 触发的事件都会通过以 CustomEvents 的形式从自定义元素上派发。

• 额外的事件参数 (payload) 将会被暴露为 CustomEvent 对象上的一个 detail 数组。

插槽

• 在一个组件中，插槽将会照常使用 渲染。但是，使用最终元素时，只能使用原生插槽的语法，无法使用作用域插槽。

• 当传递具名插槽时，应使用 slot attribute 而不是 v-slot 指令：

<my-element>
  <div slot="named">hello</div>
</my-element>

依赖注入

• Provide / Inject API 和相应的组合式 API 在 Vue 定义的自定义元素中都可以正常工作。

• 但是，依赖关系只在自定义元素之间起作用。一个由常规 Vue 组件提供的属性无法被注入到由 Vue 定义的自定义元素中。

将 SFC 编译为自定义元素

defineCustomElement 也可以搭配 Vue 单文件组件 (SFC) 使用。但是，根据默认的工具链配置，SFC 中的 c9ccee2e6ea535a969eb3f532ad9fe89 在生产环境构建时仍然会被抽取和合并到一个单独的 CSS 文件中。当正在使用 SFC 编写自定义元素时，通常需要改为注入 c9ccee2e6ea535a969eb3f532ad9fe89 标签到自定义元素的 ShadowRoot 上。

官方的 SFC 工具链支持以“自定义元素模式”导入 SFC (需要 @vitejs/plugin-vue@^1.4.0 或 vue-loader@^16.5.0)。一个以自定义元素模式加载的 SFC 将会内联其 c9ccee2e6ea535a969eb3f532ad9fe89 标签为 CSS 字符串，并将其暴露为组件的 styles 选项。这会被 defineCustomElement 提取使用，并在初始化时注入到元素的 ShadowRoot 上。

要开启这个模式，将组件文件以 .ce.vue 结尾即可：

// Example.ce.vue
<template>
  <h2>Example.ce</h2>
</template>
<script>
</script>
<style>
  h2 {
    color: red;
  }
</style>

import { defineCustomElement } from 'vue'
import Example from './Example.ce.vue'
console.log(Example.styles)
// 转换为自定义元素构造器
const ExampleElement = defineCustomElement(Example)
// 注册
customElements.define('my-example', ExampleElement)

基于 Vue 构建自定义元素库

按元素分别导出构造函数，以便用户可以灵活地按需导入它们，还可以通过导出一个函数来方便用户自动注册所有元素。

// Vue 自定义元素库的入口文件
import { defineCustomElement } from 'vue'
import Foo from './MyFoo.ce.vue'
import Bar from './MyBar.ce.vue'
const MyFoo = defineCustomElement(Foo)
const MyBar = defineCustomElement(Bar)
// 分别导出元素
export { MyFoo, MyBar }
export function register() {
  customElements.define('my-foo', MyFoo)
  customElements.define('my-bar', MyBar)
}

defineComponent()

用来在定义 Vue 组件时为 TypeScript 提供类型推导的辅助函数。

• 对于一个 ts 文件，如果我们直接写 export default {}，无法有针对性的提示 vue 组件里应该有哪些属性。

• 但是，增加一层 defineComponet 的话，export default defineComponent({})，就可以对参数进行一些类型推导和属性的提示等操作。

function defineComponent(
  component: ComponentOptions | ComponentOptions['setup']
): ComponentConstructor

参数是一个组件选项对象。返回值将是该选项对象本身，因为该函数实际上在运行时没有任何操作，仅用于提供类型推导，注意返回值的类型有一点特别：它是一个构造函数类型，它是根据选项推断出的组件实例类型。这样做可以在 TSX 中将返回值用作标签时提供类型推断支持。

你可以像这样从 defineComponent() 的返回类型中提取出一个组件的实例类型 (与其选项中的 this 的类型等价)：

const Foo = defineComponent(/* ... */)
type FooInstance = InstanceType<typeof Foo>

defineAsyncComponent()

用来定义一个异步组件。在大型项目中，我们可能会将应用拆分成更小的模块，并在需要时从服务器加载相关组件。defineAsyncComponent 在运行时是懒加载的，参数可以是一个返回 Promise 的异步加载函数（resolve 回调方法应该在从服务器获得组件定义时调用），或是对加载行为进行更具体定制的一个选项对象。

import { defineAsyncComponent } from 'vue'
const AsyncComp = defineAsyncComponent(() => {
  return new Promise((resolve, reject) => {
    // ...从服务器获取组件
    resolve(/* 获取到的组件 */)
  })
})
// ... 像使用其他一般组件一样使用 `AsyncComp`
// 也可以使用 ES 模块动态导入
const AsyncComp = defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
)

得到的 AsyncComp 是一个外层包装过的组件，仅在页面需要它渲染时才会调用加载内部实际组件的函数。它会将接收到的 props 和插槽传给内部组件，所以你可以使用这个异步的包装组件无缝地替换原始组件，同时实现延迟加载。

与普通组件一样，异步组件可以使用 app.component() 全局注册：

app.component('MyComponent', defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
))

也可以直接在父组件中直接定义它们：

<script setup>
import { defineAsyncComponent } from &#39;vue&#39;
const AdminPage = defineAsyncComponent(() =>
  import(&#39;./components/AdminPageComponent.vue&#39;)
)
</script>
<template>
  <AdminPage />
</template>

异步操作不可避免地会涉及到加载和错误状态，因此 defineAsyncComponent() 也支持在高级选项中处理这些状态：

const AsyncComp = defineAsyncComponent({
  // 加载函数
  loader: () => import('./Foo.vue'),
  // 加载异步组件时使用的组件
  loadingComponent: LoadingComponent,
  // 展示加载组件前的延迟时间，默认为 200ms
  delay: 200,
  // 加载失败后展示的组件
  errorComponent: ErrorComponent,
  // 如果提供了一个时间限制，并超时了，也会显示这里配置的报错组件，默认值是：Infinity
  timeout: 3000
})

Atas ialah kandungan terperinci Cara menggunakan defineCustomElement untuk menentukan komponen dalam Vue3. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!