3.5: custom elements

Author: yyx990803

.vitepress/config.ts

@@ -421,6 +421,7 @@ export const sidebar: ThemeConfig['sidebar'] = {
     {
       text: 'Advanced APIs',
       items: [
+        { text: 'Custom Elements', link: '/api/custom-elements' },
         { text: 'Render Function', link: '/api/render-function' },
         { text: 'Server-Side Rendering', link: '/api/ssr' },
         { text: 'TypeScript Utility Types', link: '/api/utility-types' },

src/api/custom-elements.md

@@ -0,0 +1,86 @@
+# Custom Elements API {#custom-elements-api}
+
+## defineCustomElement() {#definecustomelement}
+
+This method accepts the same argument as [`defineComponent`](#definecomponent), but instead returns a native [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) class constructor.
+
+- **Type**
+
+  ```ts
+  function defineCustomElement(
+    component:
+      | (ComponentOptions & CustomElementsOptions)
+      | ComponentOptions['setup'],
+    options?: CustomElementsOptions
+  ): {
+    new (props?: object): HTMLElement
+  }
+
+  interface CustomElementsOptions {
+    styles?: string[]
+
+    // the following options are 3.5+
+    configureApp?: (app: App) => void
+    shadowRoot?: boolean
+    nonce?: string
+  }
+  ```
+
+  > Type is simplified for readability.
+
+- **Details**
+
+  In addition to normal component options, `defineCustomElement()` also supports a number of options that are custom-elements-specific:
+
+  - **`styles`**: an array of inlined CSS strings for providing CSS that should be injected into the element's shadow root.
+
+  - **`configureApp`** <sup class="vt-badge" data-text="3.5+"/>: a function that can be used to configure the Vue app instance for the custom element.
+
+  - **`shadowRoot`** <sup class="vt-badge" data-text="3.5+"/>: `boolean`, defaults to `true`. Set to `false` to render the custom element without a shadow root. This means `<style>` in custom element SFCs will no longer be encapsulated.
+
+  - **`nonce`** <sup class="vt-badge" data-text="3.5+"/>: `string`, if provided, will be set as the `nonce` attribute on style tags injected to the shadow root.
+
+  Note that instead of being passed as part of the component itself, these options can also be passed via a second argument:
+
+  ```js
+  import Element from './MyElement.ce.vue'
+
+  defineCustomElement(Element, {
+    configureApp(app) {
+      // ...
+    }
+  })
+  ```
+
+  The return value is a custom element constructor that can be registered using [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
+
+- **Example**
+
+  ```js
+  import { defineCustomElement } from 'vue'
+
+  const MyVueElement = defineCustomElement({
+    /* component options */
+  })
+
+  // Register the custom element.
+  customElements.define('my-vue-element', MyVueElement)
+  ```
+
+- **See also**
+
+  - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
+
+  - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.
+
+## useHost() <sup class="vt-badge" data-text="3.5+"/> {#usehost}
+
+A Composition API helper that returns the host element of the current Vue custom element.
+
+## useShadowRoot() <sup class="vt-badge" data-text="3.5+"/> {#useshadowroot}
+
+A Composition API helper that returns the shadow root of the current Vue custom element.
+
+## this.$host <sup class="vt-badge" data-text="3.5+"/> {#this-host}
+
+An Options API property that exposes the host element of the current Vue custom element.

src/api/general.md

@@ -225,46 +225,3 @@ Define an async component which is lazy loaded only when it is rendered. The arg
   ```
 
 - **See also** [Guide - Async Components](/guide/components/async)
-
-## defineCustomElement() {#definecustomelement}
-
-This method accepts the same argument as [`defineComponent`](#definecomponent), but instead returns a native [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) class constructor.
-
-- **Type**
-
-  ```ts
-  function defineCustomElement(
-    component:
-      | (ComponentOptions & { styles?: string[] })
-      | ComponentOptions['setup']
-  ): {
-    new (props?: object): HTMLElement
-  }
-  ```
-
-  > Type is simplified for readability.
-
-- **Details**
-
-  In addition to normal component options, `defineCustomElement()` also supports a special option `styles`, which should be an array of inlined CSS strings, for providing CSS that should be injected into the element's shadow root.
-
-  The return value is a custom element constructor that can be registered using [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
-
-- **Example**
-
-  ```js
-  import { defineCustomElement } from 'vue'
-
-  const MyVueElement = defineCustomElement({
-    /* component options */
-  })
-
-  // Register the custom element.
-  customElements.define('my-vue-element', MyVueElement)
-  ```
-
-- **See also**
-
-  - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
-
-  - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.

src/guide/extras/web-components.md

@@ -47,15 +47,15 @@ export default {
 ```js
 // vue.config.js
 module.exports = {
-  chainWebpack: config => {
+  chainWebpack: (config) => {
     config.module
       .rule('vue')
       .use('vue-loader')
-      .tap(options => ({
+      .tap((options) => ({
         ...options,
         compilerOptions: {
           // treat any tag that starts with ion- as custom elements
-          isCustomElement: tag => tag.startsWith('ion-')
+          isCustomElement: (tag) => tag.startsWith('ion-')
         }
       }))
   }
@@ -81,7 +81,7 @@ The primary benefit of custom elements is that they can be used with any framewo
 
 ### defineCustomElement {#definecustomelement}
 
-Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElement`](/api/general#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/general#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
+Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElement`](/api/custom-elements#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/general#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
 
 ```vue-html
 <my-vue-element></my-vue-element>
@@ -171,6 +171,20 @@ Inside the component, slots can be rendered using the `<slot/>` element as usual
 
 The [Provide / Inject API](/guide/components/provide-inject#provide-inject) and its [Composition API equivalent](/api/composition-api-dependency-injection#provide) also work between Vue-defined custom elements. However, note that this works **only between custom elements**. i.e. a Vue-defined custom element won't be able to inject properties provided by a non-custom-element Vue component.
 
+#### App Level Config <sup class="vt-badge" data-text="3.5+" /> {#app-level-config}
+
+You can configure the app instance of a Vue custom element using the `configureApp` option:
+
+```js
+defineCustomElement(MyComponent, {
+  configureApp(app) {
+    app.config.errorHandler = (err) => {
+      /* ... */
+    }
+  }
+})
+```
+
 ### SFC as Custom Element {#sfc-as-custom-element}
 
 `defineCustomElement` also works with Vue Single-File Components (SFCs). However, with the default tooling setup, the `<style>` inside the SFCs will still be extracted and merged into a single CSS file during production build. When using an SFC as a custom element, it is often desirable to inject the `<style>` tags into the custom element's shadow root instead.
@@ -242,7 +256,7 @@ export const Counter = defineCustomElement(CounterSFC)
 // register global typings
 declare module 'vue' {
   export interface GlobalComponents {
-    'Counter': typeof Counter,
+    Counter: typeof Counter
   }
 }
 ```