Symfony UX Vue.js

編輯此頁面

Symfony UX Vue.js 是一個整合 Vue.js 到 Symfony 應用程式的 Symfony 套件。它是 Symfony UX 計畫的一部分。

Vue.js 是一個用於建構使用者介面的 JavaScript 框架。Symfony UX Vue.js 提供從 Twig 渲染 Vue 元件的工具，處理渲染和資料傳輸。

Symfony UX Vue.js 僅支援 Vue.js v3。

安裝

注意

此套件最適合搭配 WebpackEncore 使用。若要搭配 AssetMapper 使用，請參閱搭配 AssetMapper 使用。

使用 Composer 和 Symfony Flex 安裝套件

        1
        $ composer require symfony/ux-vue
    

Flex recipe 將會自動為您設定，例如將 .enableVueLoader() 新增到您的 webpack.config.js 檔案，並新增程式碼以載入 assets/app.js 內的 Vue 元件。

接下來，安裝一個協助 Vue 的套件

        1
2
        $ npm install -D vue-loader --force
$ npm run watch
    

就這樣！現在 assets/vue/controllers/ 內的任何檔案都可以渲染為 Vue 元件。

用法

Flex recipe 將會已將 registerVueControllerComponents() 程式碼新增到您的 assets/app.js 檔案

        1
2
3
4
        // assets/app.js
import { registerVueControllerComponents } from '@symfony/ux-vue';

registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/));
    

這將載入位於 assets/vue/controllers 目錄中的所有 Vue 元件。這些被稱為 **Vue 控制器元件**：旨在從 Twig 渲染的頂層元件。

您可以使用 vue_component() 在 Twig 中渲染任何 Vue 控制器元件。

        1
2
3
4
5
6
7
8
9
10
        // assets/vue/controllers/Hello.vue
<template>
    <div>Hello {{ name }}!</div>
</template>

<script setup>
    defineProps({
        name: String
    });
</script>
    

        1
2
        {# templates/home.html.twig #}
<div {{ vue_component('Hello', { 'name': app.user.fullName }) }}></div>
    

事件

事件 vue:before-mount 在元件掛載到頁面之前呼叫。如果您需要修改 Vue 應用程式（例如：新增外掛程式、新增全域指令、狀態...），這是要監聽的事件。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // assets/app.js
document.addEventListener('vue:before-mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that will be injected to the component
        app, // The Vue application instance
    } = event.detail;

    // Example with Vue Router
    const router = VueRouter.createRouter({
        history: VueRouter.createWebHashHistory(),
        routes: [
            /* ... */
        ],
    });

    app.use(router);
});
    

注意

當使用 Vue Router 時，您可以使用 "hash" 或 "memory" history 模式，以防止您的 Vue 路由通過 Symfony 控制器提供服務。如果您想要使用 web history 模式，請參閱 Symfony UX Vue.js

事件 vue:mount 在元件已掛載到頁面時呼叫

        1
2
3
4
5
6
7
        document.addEventListener('vue:mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that are injected to the component
    } = event.detail;
});
    

事件 vue:unmount 在元件已從頁面卸載時呼叫

        1
2
3
4
5
6
        document.addEventListener('vue:unmount', (event) => {
    const {
        componentName, // The Vue component's name
        props, // The props that were injected to the component
    } = event.detail;
});
    

搭配 Vue Router 的 Web History 模式

若要搭配 Vue Router 使用 "web" history 模式，將需要一個全域捕捉路由，該路由應渲染相同的範本和 Vue 元件

        1
2
3
4
5
        #Route('/survey/{path<.+>}')
public function survey($path = ''): Response
{
    // render the template
}
    

此控制器將捕捉任何以 `/survey` 開頭的 URL。然後，此字首可以用於所有 Vue 路由

        1
2
3
4
5
6
7
8
9
10
        const router = VueRouter.createRouter({
    history: VueRouter.createWebHistory(),
    routes: [
        { path: '/survey/list', component: ListSurveys },
        { path: '/survey/create', component: CreateSurvey },
        { path: '/survey/edit/:surveyId', component: EditSurvey },
    ],
});

app.use(router);
    

搭配 AssetMapper 使用

Vue 單一檔案元件（即 .vue）檔案格式不是純 JavaScript，目前無法在 Webpack Encore 或 Vite 等打包工具之外轉換為純 JavaScript。這表示 .vue 檔案格式無法與 AssetMapper 一起使用。

如果您*仍然*想要搭配 AssetMapper 使用 Vue，您可以透過避免 .vue 檔案格式來達成。例如，https://github.com/symfony/ux/blob/2.x/ux.symfony.com/assets/vue/controllers/PackageSearch.js。

向後相容性承諾

此套件旨在遵循與 Symfony 框架相同的向後相容性承諾：https://symfony.dev.org.tw/doc/current/contributing/code/bc.html

此作品，包含程式碼範例，依據 Creative Commons BY-SA 3.0 授權條款授權。

TOC

版本