如何在VuePress中使用Web Components？集成Stoplight组件报错求助

问题原因 #

Vue会默认将所有自定义标签视为Vue组件进行解析，而elements-api是原生Web组件，未被Vue识别，因此抛出"Unknown custom element"错误。同时如果脚本加载时机晚于组件渲染，也会导致组件无法被找到。

解决方案步骤 #

1. 配置Vue忽略Web组件标签 #

根据你使用的VuePress版本，添加对应的配置，告诉Vue哪些标签是原生Web组件：

针对VuePress 1.x（基于Vue 2）

在.vuepress/config.js中修改webpack配置：

module.exports = {
  // 其他已有配置...
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        options.compilerOptions = {
          ...options.compilerOptions,
          // 匹配所有以elements-开头的标签
          isCustomElement: tag => tag.startsWith('elements-')
        }
        return options
      })
  },
  // 可移除之前在head中添加的script，后续改为组件内动态加载
}

针对VuePress 2.x（基于Vue 3）

1. 在.vuepress/config.js中指定客户端配置文件：

module.exports = {
  // 其他已有配置...
  clientConfigFile: '.vuepress/client.js'
}

2. 创建.vuepress/client.js文件，配置Vue忽略Web组件：

import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  enhance({ app }) {
    app.config.isCustomElement = tag => tag.startsWith('elements-')
  }
})

2. 修改组件，确保脚本加载完成后再渲染 #

修改APIStopLight.vue，动态加载Stoplight脚本并等待加载完成后渲染组件，避免脚本未就绪导致的错误：

<template>
  <main class="apis-page">
    <elements-api 
      v-if="isElementsLoaded"
      class="stoplight"
      apiDescriptionUrl="/asgardeo/docs/content/apiDocs/scim2.yaml"
      router="hash"
    ></elements-api>
  </main>
</template>

<script>
export default {
  name: 'APIStopLight',
  data() {
    return {
      isElementsLoaded: false
    }
  },
  mounted() {
    // 检查Web组件是否已注册
    if (window.customElements.get('elements-api')) {
      this.isElementsLoaded = true
      return
    }
    // 动态加载Stoplight Elements脚本
    const script = document.createElement('script')
    script.src = 'https://unpkg.com/@stoplight/elements/web-components.min.js'
    script.onload = () => {
      this.isElementsLoaded = true
    }
    document.head.appendChild(script)
  }
}
</script>

<style src="../theme/styles/components/apiOverview.styl" lang="stylus"></style>

3. 验证效果 #

重启VuePress开发服务器，访问对应的API页面，elements-api组件应该能正常渲染，不再出现未知组件的警告。

内容的提问来源于stack exchange，提问作者Pavindu