自定义元素互操作

breaking

概述

• 重大变更: 确定标签是否应被视为自定义元素的检查现在在模板编译期间执行，应通过编译器选项而不是运行时配置进行配置。
• 重大变更: 特殊的 is 属性用法仅限于保留的 <component> 标签。
• 新增: 为了支持 2.x 中使用 is 在原生元素上绕过原生 HTML 解析限制的用例，请在值前添加 vue: 前缀以将其解析为 Vue 组件。

自主自定义元素

如果我们想添加在 Vue 之外定义的自定义元素（例如使用 Web Components API），我们需要“指示”Vue 将其视为自定义元素。让我们以以下模板为例。

<plastic-button></plastic-button>

2.x 语法

在 Vue 2.x 中，通过 Vue.config.ignoredElements 配置标签作为自定义元素。

// This will make Vue ignore custom element defined outside of Vue
// (e.g., using the Web Components APIs)

Vue.config.ignoredElements = ['plastic-button']

3.x 语法

在 Vue 3.0 中，此检查在模板编译期间执行。 要指示编译器将 <plastic-button> 视为自定义元素

• 如果使用构建步骤：将 isCustomElement 选项传递给 Vue 模板编译器。如果使用 vue-loader，则应通过 vue-loader 的 compilerOptions 选项传递。

  // in webpack config
  rules: [
    {
      test: /\.vue$/,
      use: 'vue-loader',
      options: {
        compilerOptions: {
          isCustomElement: tag => tag === 'plastic-button'
        }
      }
    }
    // ...
  ]

• 如果使用即时模板编译，则通过 app.config.compilerOptions.isCustomElement 传递。

  const app = Vue.createApp({})
  app.config.compilerOptions.isCustomElement = tag => tag === 'plastic-button'

  重要的是要注意，运行时配置仅影响运行时模板编译 - 它不会影响预编译的模板。

自定义内置元素

Custom Elements 规范提供了一种将自定义元素用作 自定义内置元素 的方法，方法是在内置元素中添加 is 属性。

<button is="plastic-button">Click Me!</button>

Vue 对 is 特殊属性的使用模拟了原生属性在浏览器中普遍可用之前的工作方式。但是，在 2.x 中，它被解释为渲染名为 plastic-button 的 Vue 组件。这阻止了上面提到的自定义内置元素的原生用法。

在 3.0 中，我们将 Vue 对 is 属性的特殊处理限制在 <component> 标签上。

• 当在保留的 <component> 标签上使用时，它的行为与 2.x 中完全相同；

• 当在普通组件上使用时，它的行为就像一个普通属性

  <foo is="bar" />

  • 2.x 行为：渲染 bar 组件。
  • 3.x 行为：渲染 foo 组件并传递 is 属性。

• 当在普通元素上使用时，它将作为 is 属性传递给 createElement 调用，并作为原生属性渲染。这支持自定义内置元素的用法。

  <button is="plastic-button">Click Me!</button>

  • 2.x 行为：渲染 plastic-button 组件。

  • 3.x 行为：通过调用渲染原生按钮

    document.createElement('button', { is: 'plastic-button' })

迁移构建标志：COMPILER_IS_ON_ELEMENT

vue: 用于 DOM 内模板解析解决方法的前缀

注意：本节仅影响 Vue 模板直接写入页面 HTML 的情况。当使用 DOM 内模板时，模板会受到原生 HTML 解析规则的约束。一些 HTML 元素，例如 <ul>、<ol>、<table> 和 <select> 对其内部可以出现的元素有限制，而一些元素，例如 <li>、<tr> 和 <option> 只能出现在某些其他元素内部。

2.x 语法

在 Vue 2 中，我们建议使用原生标签上的 is 属性来解决这些限制。

<table>
  <tr is="blog-post-row"></tr>
</table>

3.x 语法

随着 is 行为的改变，现在需要 vue: 前缀才能将元素解析为 Vue 组件。

<table>
  <tr is="vue:blog-post-row"></tr>
</table>

迁移策略

• 将 config.ignoredElements 替换为 vue-loader 的 compilerOptions（使用构建步骤）或 app.config.compilerOptions.isCustomElement（使用即时模板编译）。

• 将所有非 <component> 标签的 is 用法更改为 <component is="...">（对于 SFC 模板）或在前面添加 vue: 前缀（对于 DOM 内模板）。

另请参阅

• 指南 - Vue 和 Web Components