README

使用此包，您可以在任何页面上快速添加一个聊天气泡，该气泡可以打开支持表单。它包含了一切

默认提供 TailwindCSS 样式
如果用户已登录，则不会询问用户信息
包含一些元数据，如 URL 和 IP 地址
可以使用自定义视图、语言文件和事件监听器轻松扩展
包含 Honeybadger，并设置为阻止垃圾邮件发送者

您可以在下面的视频中看到它的实际效果，在 Flare 和 Oh Dear 上！

支持我们

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，注明您正在使用我们哪些包。您可以在我们的联系页面上找到我们的地址。我们将在我们的虚拟明信片墙上发布所有收到的明信片。

您是视觉学习者吗？

在 YouTube 上的这个直播中，您将看到如何安装该包以及它是如何工作的。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-support-bubble

包含 TailwindCSS

此包中包含的视图都使用了 TailwindCSS 类。我们坚持使用默认的 Tailwind 配置类。如果您还没有使用 TailwindCSS，您可以从他们的 CDN 轻松包含它

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

如果您使用 Tailwind 即时模式，则应将这些附加行添加到您的 tailwind.config.js 文件中

content: [
    './vendor/spatie/laravel-support-bubble/config/**/*.php',
    './vendor/spatie/laravel-support-bubble/resources/views/**/*.blade.php',
    // other places
],

这样 Tailwind JIT 就会构建您的样式，包括用于支持气泡的属性。

将组件添加到您的视图中

安装此包后，您需要在您的相关视图文件中添加此 Blade 组件

<x-support-bubble />

如果您希望它在所有页面上显示，您可以将它添加到您的 layout.blade.php 文件中。

接下来，您需要注册支持表单的路由。在您的 routes/api.php 文件中添加以下宏

Route::supportBubble();

这将注册一个 /support-bubble 路由

⚠️ 此包不使用 CSRF 令牌，因此请确保将路由宏添加到您的应用程序的 API 路由中或向 VerifyCsrfToken 中间件添加一个排除项。

// in app/Http/Middleware/VerifyCsrfToken.php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    protected $except = [
        'support-bubble',
        // other entries
    ];
    
    // ...
}

在 Laravel 11 中，这将在 bootstrap/app.php 中完成

->withMiddleware(function (Middleware $middleware) {
        $middleware->validateCsrfTokens(except: [
			'support-bubble',
		]);
    })

配置消息目的地

最后，您需要决定要将支持气泡的提交发送到何处。

默认情况下，该包可以将提交通过电子邮件发送到指定的电子邮件地址。要采取此路线，发布配置文件并在 mail_to 中输入电子邮件。

或者，您也可以注册一个事件监听器来监听Spatie\SupportBubble\Events\SupportBubbleSubmittedEvent事件并自行处理。此事件包含已提交的表单值作为公共属性。

可以使用以下命令发布配置文件：

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag="support-bubble-config"

以下是发布的配置文件的默认内容：

<?php

return [
    /*
     * Enable or disable fields in the support bubble.
     * Keep in mind that `name` and `email` will be hidden automatically
     * when a logged in user is detected and `prefill_logged_in_user` is set.
     */
    'fields' => [
        'name' => true,
        'email' => true,
        'subject' => true,
        'message' => true,
    ],
    
    /*
     * We'll send any chat bubble responses to this e-mail address.
     *
     * Set this to
     */
    'mail_to' => null,

    /*
     * When set to true we'll use currently logged in user to fill in
     * the name and email fields. Both fields will also be hidden.
     */
    'prefill_logged_in_user' => true,

    /*
     * The TailwindCSS classes used on a couple of key components.
     *
     * To customize the components further, you can publish
     * the views of this package.
     */
    'classes' => [
        'container' => 'text-base items-end z-10 flex-col m-4 gap-3',
        'bubble' => 'hidden sm:block | bg-purple-400 rounded-full shadow-lg w-14 h-14 text-white p-4',
        'input' => 'bg-gray-100 border border-gray-200 w-full max-w-full p-2 rounded-sm shadow-input text-gray-800 text-base',
        'button' => 'inline-flex place-center px-4 py-3 h-10 border-0 bg-purple-500 hover:bg-purple-600 active:bg-purple-600 overflow-hidden rounded-sm text-white leading-none no-underline',
    ],
    
    /*
     * The default route and controller will be registered using this route name.
     * This is a good place to hook in your own route and controller if necessary.
     */
    'form_action_route' => 'supportBubble.submit',

     /**
     * The positioning of the bubble and the form, change this between right-to-left and left-to-right, if you want to use RTL, you must have your layout set to RTL like this 
     * <html lang="ar-TN" dir="rtl">
     * By default, the value of this is LTR
     */
    'direction' => 'left-to-right',
];

自定义选项

支持气泡默认外观应该看起来很不错。然而，我们已经记录了自定义标签、文本、视图和功能的一些方法。

自定义表单字段

目前无法向支持气泡表单添加新字段。但是，您可以在配置文件中禁用您不喜欢的任何字段。

自定义文本/本地化

如果您只想自定义字段标签、简介文本或提交后的成功文本，可以发布包的语言文件

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag=support-bubble-translations

这些发布的文件可以在resources/lang/vendor/laravel-support-bubble/en/中找到并修改。

自定义样式

您可以通过更改support-bubble.class配置键来自定义用于气泡弹出、输入字段和提交按钮的TailwindCSS类。这是更改气泡默认紫色或使用自己的.input或.button类的理想位置。

如果您想要更改更高级的样式，请继续阅读，了解如何发布和自定义支持气泡组件中使用的Blade视图。

自定义视图

您可以发布并更改此包中的所有视图（包括JavaScript代码）

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag=support-bubble-views

这些发布的视图可以在resources/views/vendor/laravel-support-bubble/中找到并修改。

请注意，无法（或者至少非常困难且复杂）向支持气泡添加新字段。

自定义支持表单目的地

如果您不想将支持消息发送到配置文件中配置的mail_to电子邮件，您可以定义自己的事件监听器并监听Spatie\SupportBubble\Events\SupportBubbleSubmittedEvent。该事件包含支持表单中提交的所有数据，可用于例如向Freshdesk发起API请求。

提交后自定义行为（高级）

如果您确实想要，可以将提交的表单数据发送到自己的端点。支持表单使用在support-bubble.form_action_route配置键中配置的路由。您可以通过从路由文件中删除Route::supportBubble()宏并将form_action_route设置为应用程序中的任何其他路由名称来覆盖此路由。

此路由上的传入请求将是\Spatie\SupportBubble\Http\Requests\SupportBubbleRequest。

测试

composer test

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅我们的安全策略。

spatie / laravel-support-bubble

维护者

详细信息