3.5: custom elements (#2295)

Author: tkworks1214

.vitepress/config.ts

@@ -421,6 +421,7 @@ export const sidebar: ThemeConfig['sidebar'] = {
     {
       text: '高度な API',
       items: [
+        { text: 'カスタム要素', link: '/api/custom-elements' },
         { text: 'レンダー関数', link: '/api/render-function' },
         { text: 'サーバーサイドレンダリング', link: '/api/ssr' },
         { text: 'TypeScript ユーティリティー', link: '/api/utility-types' }, // /api/ で折り返されないよう「型」を省略

src/api/custom-elements.md

@@ -0,0 +1,86 @@
+# カスタム要素 API {#custom-elements-api}
+
+## defineCustomElement() {#definecustomelement}
+
+このメソッドは [`defineComponent`](#definecomponent) と同じ引数を受け取りますが、代わりにネイティブの[カスタム要素](https://developer.mozilla.org/ja/docs/Web/Web_Components/Using_custom_elements)クラスのコンストラクタを返します。
+
+- **型**
+
+  ```ts
+  function defineCustomElement(
+    component:
+      | (ComponentOptions & CustomElementsOptions)
+      | ComponentOptions['setup'],
+    options?: CustomElementsOptions
+  ): {
+    new (props?: object): HTMLElement
+  }
+
+  interface CustomElementsOptions {
+    styles?: string[]
+
+    // 以下のオプションは 3.5 以上で利用可能
+    configureApp?: (app: App) => void
+    shadowRoot?: boolean
+    nonce?: string
+  }
+  ```
+
+  > 読みやすくするため、型は単純化されています。
+
+- **詳細**
+
+  通常のコンポーネントオプションに加えて、 `defineCustomElement()` はカスタム要素固有のいくつかのオプションをサポートします:
+
+  - **`styles`**: 要素のシャドウルートに注入する CSS を提供するためのインラインの CSS 文字列の配列。
+
+  - **`configureApp`** <sup class="vt-badge" data-text="3.5+"/>: カスタム要素に対して Vue アプリケーションインスタンスを設定するために使用できる関数。
+
+  - **`shadowRoot`** <sup class="vt-badge" data-text="3.5+"/>: `boolean`、デフォルトは `true`。`false` に設定すると、シャドウルートなしでカスタム要素をレンダリングします。これは、カスタム要素 SFC の `<style>` タグがカプセル化されなくなることを意味します。
+
+  - **`nonce`** <sup class="vt-badge" data-text="3.5+"/>: `string`、指定された場合、シャドウルートに注入される `<style>` タグの `nonce` 属性として設定されます。
+
+  これらのオプションは、コンポーネント自体の一部として渡される代わりに、第 2 引数として渡すこともできることに注意してください:
+
+  ```js
+  import Element from './MyElement.ce.vue'
+
+  defineCustomElement(Element, {
+    configureApp(app) {
+      // ...
+    }
+  })
+  ```
+
+  戻り値は [`customElements.define()`](https://developer.mozilla.org/ja/docs/Web/API/CustomElementRegistry/define) を使って登録できるカスタム要素のコンストラクタです。
+
+- **例**
+
+  ```js
+  import { defineCustomElement } from 'vue'
+
+  const MyVueElement = defineCustomElement({
+    /* コンポーネントオプション */
+  })
+
+  // カスタム要素を登録する。
+  customElements.define('my-vue-element', MyVueElement)
+  ```
+
+- **参照**
+
+  - [ガイド - Vue によるカスタム要素のビルド](/guide/extras/web-components#building-custom-elements-with-vue)
+
+  - また、`defineCustomElement()` は単一ファイルコンポーネントで使用する場合、[特別な設定](/guide/extras/web-components#sfc-as-custom-element)が必要なので注意してください。
+
+## useHost() <sup class="vt-badge" data-text="3.5+"/> {#usehost}
+
+現在の Vue カスタム要素のホスト要素を返す Composition API ヘルパーです。
+
+## useShadowRoot() <sup class="vt-badge" data-text="3.5+"/> {#useshadowroot}
+
+現在の Vue カスタム要素のシャドウルートを返す Composition API ヘルパーです。
+
+## this.$host <sup class="vt-badge" data-text="3.5+"/> {#this-host}
+
+現在の Vue カスタム要素のホスト要素を公開するための Options API の属性です。

src/api/general.md

@@ -225,46 +225,3 @@ Vue の現在のバージョンを公開します。
   ```
 
 - **参照** [ガイド - 非同期コンポーネント](/guide/components/async)
-
-## defineCustomElement() {#definecustomelement}
-
-このメソッドは [`defineComponent`](#definecomponent) と同じ引数を受け取りますが、代わりにネイティブの[カスタム要素](https://developer.mozilla.org/ja/docs/Web/Web_Components/Using_custom_elements)クラスのコンストラクタを返します。
-
-- **型**
-
-  ```ts
-  function defineCustomElement(
-    component:
-      | (ComponentOptions & { styles?: string[] })
-      | ComponentOptions['setup']
-  ): {
-    new (props?: object): HTMLElement
-  }
-  ```
-
-  > 読みやすくするため、型は単純化されています。
-
-- **詳細**
-
-  通常のコンポーネントオプションに加えて、 `defineCustomElement()` は特別なオプション `styles` をサポートします。これはインラインの CSS 文字列の配列で、要素のシャドウルートに注入する CSS を提供するためのものです。
-
-  戻り値は [`customElements.define()`](https://developer.mozilla.org/ja/docs/Web/API/CustomElementRegistry/define) を使って登録できるカスタム要素のコンストラクタです。
-
-- **例**
-
-  ```js
-  import { defineCustomElement } from 'vue'
-
-  const MyVueElement = defineCustomElement({
-    /* コンポーネントオプション */
-  })
-
-  // カスタム要素を登録する。
-  customElements.define('my-vue-element', MyVueElement)
-  ```
-
-- **参照**
-
-  - [ガイド - Vue によるカスタム要素のビルド](/guide/extras/web-components#building-custom-elements-with-vue)
-
-  - また、`defineCustomElement()` は単一ファイルコンポーネントで使用する場合、[特別な設定](/guide/extras/web-components#sfc-as-custom-element)が必要なので注意してください。

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: {
           // ion- で始まるタグはすべてカスタム要素として扱う
-          isCustomElement: tag => tag.startsWith('ion-')
+          isCustomElement: (tag) => tag.startsWith('ion-')
         }
       }))
   }
@@ -81,7 +81,7 @@ DOM 属性は文字列のみしか扱えないため、複雑なデータをカ
 
 ### defineCustomElement {#definecustomelement}
 
-Vue は [`defineCustomElement`](/api/general#definecustomelement) メソッドを介したまったく同じ Vue コンポーネント API 群を使ってカスタム要素の作成をサポートします。このメソッドは [`defineComponent`](/api/general#definecomponent) と同じ引数を受け付けますが、代わりに `HTMLElement` を拡張したカスタム要素を返します:
+Vue は [`defineCustomElement`](/api/custom-elements#definecustomelement) メソッドを介したまったく同じ Vue コンポーネント API 群を使ってカスタム要素の作成をサポートします。このメソッドは [`defineComponent`](/api/general#definecomponent) と同じ引数を受け付けますが、代わりに `HTMLElement` を拡張したカスタム要素を返します:
 
 ```vue-html
 <my-vue-element></my-vue-element>
@@ -171,6 +171,20 @@ document.body.appendChild(
 
 [Provide / Inject API](/guide/components/provide-inject#provide-inject) と [Composition API](/api/composition-api-dependency-injection#provide) も、Vue で定義されたカスタム要素間で動作します。しかしながら、これは**カスタム要素間**のみ動作するということに注意してください。つまり、Vue で定義されたカスタム要素は、カスタム要素ではない Vue コンポーネントによってプロパティを注入することはできません。
 
+#### アプリケーションレベルの設定 <sup class="vt-badge" data-text="3.5+" /> {#app-level-config}
+
+`configureApp` オプションを使うことで、Vue のカスタム要素のアプリケーションインスタンスを設定できます:
+
+```js
+defineCustomElement(MyComponent, {
+  configureApp(app) {
+    app.config.errorHandler = (err) => {
+      /* ... */
+    }
+  }
+})
+```
+
 ### カスタム要素としての SFC {#sfc-as-custom-element}
 
 `defineCustomElement` は、Vue の単一ファイルコンポーネント（SFC: Single-File Components）でも動作します。しかしながら、デフォルトのツール設定では、SFC 内の `<style>` は、プロダクションビルド時に抽出され、単一の CSS ファイルにマージされます。SFC をカスタム要素として使用する場合は、代わりにカスタム要素の shadow root に `<style>` タグを注入するのが望ましいことが多いです。