README

教程

教程是一个创建教程、引导和用户体验的完整工具。这是一个简单易用的库，只需几行代码即可将其集成到项目中。

尚未准备就绪！

当前教程插件处于alpha版本，因此尚未准备好投入生产。使用风险自负。

展示

视频展示 1 视频展示 2

支持我们

您的支持是我们插件不断进步的关键。我们感谢每一位至今为止为我们的旅程做出贡献的用户。

虽然我们的插件对所有用户都可用，但如果您正在将其用于商业目的，并认为它为您的事业增加了显著价值，我们恳请您考虑通过GitHub Sponsors支持我们。这种赞助将帮助我们进行持续的开发和维护，以保持我们的插件强大且更新。您提供的任何金额都将极大地帮助我们实现目标。加入我们，让这个插件变得更好，推动进一步的创新。

先决条件

• Laravel 10+
• PHP 8.0+
• Filament 3
• Livewire 3

Filament目前是先决条件，但它也可以在任何前端livewire组件中用于Filament Panels之外的地方。

文档

以下是您开始所需的所有信息。我们尽可能遵循Filament约定，因此这些步骤中的许多应该对您来说已经很熟悉。

安装

composer require guava/tutorials

将资产添加到您的主题

您需要自定义主题才能使用此插件。在您的主题的tailwind.config.js文件中，将以下内容添加到您的内容数组中

export default {
    presets: [preset],
    content: [
        // ... 
        './vendor/guava/tutorials/resources/**/*.php',
    ],
}

将插件添加到您的filament仪表板

use Guava\Tutorials\TutorialsPlugin;

$panel->plugins([
    TutorialsPlugin::make(),
    //
])

将教程添加到您的livewire组件（或filament页面）

要开始，您需要执行以下操作

1. 实现HasTutorials接口并使用InteractsWithTutorials特性。
2. 实现tutorial()函数。
3. 在tutorial()函数中配置您的教程。
4. 在mount()函数中使用mountTutorial()挂载教程。

假设我们有一个允许我们编辑项目name和description的项目资源。当创建项目时，我们想使用教程引导用户。这是我们的最终创建页面类的样子

use Guava\Tutorials\Concerns\InteractsWithTutorials;
use Guava\Tutorials\Contracts\HasTutorials;
use Guava\Tutorials\Steps\Step;

class CreateProject extends CreateRecord implements HasTutorials
{
    use InteractsWithTutorials;
    
    public function mount(): void
    {
        parent::mount();
        
        $this->mountTutorial();
    }
    
    public function tutorial(Tutorial $tutorial) : Tutorial
    {
        return $tutorial->steps([
            Step::make('name'),
            Step::make('description'),
        ]);
    }
}

就是这样！您刚刚创建了一个教程。

请注意，这个教程将在每次页面加载时挂载。您需要定义挂载教程的逻辑。

教程

教程是一组步骤，应该引导用户通过您的livewire组件（或filament页面）。

教程生命周期

您可以挂钩到教程生命周期的不同部分。

挂载后

教程挂载后，您可以调用自己的代码

$tutorial->steps([
    //
])
->afterMount(
    fn() => // Your code here
)

卸载后

教程卸载后，您可以调用自己的代码

$tutorial->steps([
    //
])
->afterUnmount(
    fn() => // Your code here
)

跳过后

如果您有可跳过的教程，您可以在教程被跳过后调用自己的代码

$tutorial->steps([
    //
])
->afterSkipped(
    fn() => // Your code here
)

步骤

每个教程都由步骤组成，其中每个步骤代表用户可以执行的操作或他们应该注意的部分。例如填写表单字段、点击按钮或只是查看小部件。

步骤基本上是在您的目标（表单字段、操作按钮等）周围的一个覆盖层。

1. 步骤覆盖层左上角定位的标签。
2. 步骤覆盖层右上角定位的提示。默认情况下，提示显示教程进度：当前步骤和总步骤数。
3. 步骤左下角定位的描述。
4. 步骤右下角定位的操作。

步骤提供了丰富的自定义选项，我们将在下面尝试描述。

选择器

每个步骤都需要一个选择器，用于定位要渲染覆盖层的元素。

当创建一个 Step 时，它接受一个 Selector 实例或一个 string 选择器作为参数。

当传递一个 string 选择器时，默认使用 FormSelector/FieldSelector（两者相同）。

但您不仅限于只针对表单字段，您还可以针对页面上的其他元素，例如 Widget 或 Action 按钮。

表单字段选择器

这是步骤默认使用的选择器。

use Guava\Tutorials\Selectors\FormSelector;
use Guava\Tutorials\Selectors\FieldSelector;
use Guava\Tutorials\Selectors\ComponentSelector;

// All variants are the same
Step::make('username');
Step::make(FormSelector::make('username'));
Step::make(FieldSelector::make('username'));
Step::make(ComponentSelector::make('username'));

所有变体都是相同的，使用您喜欢的任何一种。

小部件选择器

使用此选择器来定位小部件。

use Guava\Tutorials\Selectors\WidgetSelector;

// Currently only the "index" of the widget is supported
// So first widget = '1', second widget = '2', etc.
Step::make(WidgetSelector::make('1'));

(通用) 选择器

一个通用选择器可以用来定位使用 CSS 选择器的元素，例如

use \Guava\Tutorials\Selectors\Selector;

Step::make(Selector::make('div'));
Step::make(Selector::make('#my-id'));
Step::make(Selector::make('.my-class'));
Step::make(Selector::make('[data-attribute]'));

自定义标签

默认情况下，标签是隐藏的。以下是设置标签的方法

Step::make('username')
    ->label('Enter a username');

您还可以使用条件隐藏标签

Step::make('username')
    ->hiddenLabel(true); // or a closure

自定义描述

默认情况下，描述是隐藏的。以下是设置描述的方法

Step::make('username')
    ->description('Pick an easy-to-remember, unique username');

您还可以使用条件隐藏描述

Step::make('username')
    ->hiddenDescription(true); // or a closure

自定义提示

默认情况下，提示以当前步骤数（相对于总步骤数）的形式显示教程的当前进度。您可以使用以下内容覆盖步骤

Step::make('username')
    ->hint('Min. 6 characters');

您还可以使用条件隐藏提示

Step::make('username')
    ->hiddenHint(true); // or a closure

自定义颜色

默认情况下，每个步骤使用 Filament 管理面板中的 primary 颜色。但是，您可以使用以下内容自定义颜色

Step::make('username')
    ->color('danger'); // or any other acceptable filament color parameter

传递通过

默认情况下，步骤周围有一个覆盖层，但用户仍然可以与目标元素（表单字段、操作按钮等）交互。

如果您想阻止这种情况，例如在只想向用户展示而不允许他们与元素本身交互的情况下，您可以使用以下内容禁用事件传递

Step::make('username')
    ->passThrough(false);

这样他们就无法与目标元素交互。

拦截点击

类似地，您可能已经创建了一个用于 Action 按钮的 Step，您希望用户点击以显示将要发生的事情。

例如，您可能有一个按钮，当点击时，将生成一个随机用户名。作为教程的一部分，您想要用户点击该按钮，触发其功能（生成用户名），但还要 继续到下一个步骤。

这正是此功能派上用场的地方，因为点击也会使教程继续到下一个步骤。

您可以使用以下内容将其添加到步骤中

Step::make('username')
    ->interceptClick();

自定义操作

默认情况下，步骤使用所有内置操作。

要覆盖这些操作，您可以使用以下函数

Step::make('username')
    ->nextStepAction(
        fn(NextStepAction $action) =>  // customize $action here
    )
    ->previousStepAction(
        fn(PreviousStepAction $action) =>  // customize $action here
    )
    ->skipTutorialAction(
        fn(SkipTutorialAction $action) =>  // customize $action here
    )
    ->completeTutorialAction(
        fn(CompleteTutorialAction $action) =>  // customize $action here
    );

您也可以将这些方法传递自己的 TutorialAction 或传递 null 以禁用操作。

要完全控制为步骤渲染的操作，您可以使用 actions 函数并传递您想要渲染的操作数组

Step::make('username')
    ->actions([
        PreviousStepAction::make(),
        NextStepAction::make(),
        MyCustomAction::make(),
    ])

实用工具注入

几乎每个函数也接受一个闭包作为参数。这些闭包为您注入了各种工具，以下将进行描述。

注入当前记录

如果您想从给定的 Step 访问记录

use Illuminate\Database\Eloquent\Model;

function (?Model $record) {
    // ...
}

注入当前步骤

如果您想访问 Step 实例本身

use Guava\Tutorials\Steps\Step;

function (Step $step) {
    // ...
}

注入教程

如果您想访问 Tutorial 实例，该实例属于 Step

use Guava\Tutorials\Tutorial;

function (Tutorial $tutorial) { // or $container
    // ...
}

注入表单组件

如果您的步骤针对 表单字段，您可以注入表单组件实例

use Filament\Forms\Components\Component;

function (Component $component) {
    // ...
}

注入其他表单字段的状态

如果您的 Livewire 组件也包含 表单，您可以使用 get 回调访问任何表单字段的州

use Filament\Forms\Get;

function (Get $get) {
    // ...
}

注入当前 Livewire 组件实例

您可以使用以下方法注入当前 Livewire 组件 实例

use Livewire\Component;

function (Component $livewire) {
    // ...
}

动作

您可以为步骤添加多个动作以执行各种任务。

该插件包含一些内置的动作，例如

1. NextStepAction：处理跳转到下一个步骤。
2. PreviousStepAction：处理跳转到上一个步骤。
3. SkipTutorialAction：处理跳过整个教程。
4. CompleteTutorialAction：处理完成教程（最后一步）。

这些动作都是从 TutorialAction 派生的，如果您想创建自己的动作，可以扩展它。

动作具有所有常规 Filament 动作的定制选项。您可以定义颜色、标签、图标或条件隐藏它们。

使用多个教程

默认情况下，InteractsWithTutorials 特性只处理 Livewire 组件的每个教程 - tutorial()。要向 Livewire 组件添加更多教程，您可以在 getTutorials() 方法中定义它们，并返回一个包含每个教程名称的数组

protected function getTutorials() : array
{
    return [
        'simpleTutorial',
        'advancedTutorial',
];
}

现在，这些教程都可以在 Livewire 组件内部定义，使用与名称相同的方法

public function simpleTutorial(Tutorial $tutorial) : Tutorial
{
    $tutorial->steps([
        //
    ]);
}
    
public function advancedTutorial(Tutorial $tutorial) : Tutorial
{
    $tutorial->steps([
        //
    ]);
}

要安装特定的教程，只需在 mountTutorial(string $name) 函数中传递教程的名称，例如

public function mount(): void
{
    parent::mount();
    
    $this->mountTutorial('simpleTutorial');
}

同样，何时安装哪个教程完全取决于您。

致谢

• Guava
• 所有贡献者

我们的文档高度受 Filament 文档的启发。部分原因也是因为我们试图尽可能接近熟悉的 Filament API，并且很多功能都是相同的。