深入理解area17/twill项目中的区块编辑器创建

深入理解area17/twill项目中的区块编辑器创建

twill Twill is an open source CMS toolkit for Laravel that helps developers rapidly create a custom admin console that is intuitive, powerful and flexible. Chat with us on Discord at https://discord.gg/cnWk7EFv8R. 项目地址: https://gitcode.com/gh_mirrors/tw/twill

区块编辑器是现代内容管理系统中的核心功能之一，它允许内容编辑者灵活地组合不同类型的内容区块来构建页面。本文将详细介绍如何在area17/twill项目中创建和使用区块编辑器。

区块编辑器基础配置

在area17/twill项目中，为模块添加区块编辑器非常简单。开发者可以通过三种方式实现：

1. 使用FormBuilder方式

BlockEditor::make()->blocks(['title', 'quote', 'text'])

2. 使用FormView方式

@php
    $blocks = ['title', 'quote', 'text'];
@endphp
<x-twill::block-editor :blocks="$blocks" />

3. 使用Directive方式

@formField('block_editor', [
    'blocks' => ['title', 'quote', 'text']
])

这三种方式各有优势，开发者可以根据项目需求和个人偏好选择最适合的方式。

区块组件类（Twill 3+新特性）

从Twill 3开始，引入了区块组件类这一强大特性。这些组件本质上是常规的Blade组件，但同时负责区块的表单定义和渲染逻辑。

创建区块组件

使用以下命令创建区块组件：

php artisan twill:make:componentBlock Namespace/Name

生成的区块组件会放置在App\View\Components\Twill\Blocks目录下。

区块组件结构

一个典型的区块组件类如下：

namespace App\View\Components\Twill\Blocks;

use A17\Twill\Services\Forms\Form;
use A17\Twill\View\Components\Blocks\TwillBlockComponent;

class Example extends TwillBlockComponent
{
    public function render()
    {
        return view('components.twill.blocks.example');
    }

    public function getForm(): Form
    {
        return Form::make([
            Input::make()->name('title'),
            Wysiwyg::make()->name('text')
        ]);
    }
}

自定义区块属性

开发者可以重写以下方法来定制区块属性：

public static function getBlockTitle(): string
{
    return '自定义区块标题';
}

public static function getBlockGroup(): string
{
    return 'custom-group';
}

public static function getBlockIcon(): string
{
    return 'custom-icon';
}

图像裁剪配置

在区块组件中，可以直接定义图像裁剪规则：

public static function getCrops(): array
{
    return [
        'content_image' => [
            'default' => [
                'name' => 'default',
                'ratio' => 16 / 9,
                'minValues' => ['width' => 100, 'height' => 100]
            ]
        ]
    ];
}

表单验证

区块组件支持字段验证：

public function getValidationRules(): array
{
    return ['title' => 'required|max:100'];
}

public function getTranslatableValidationRules(): array
{
    return ['description' => 'required'];
}

渲染辅助方法

区块组件提供了一系列便捷的渲染辅助方法：

{{ $input('title') }}          // 获取普通输入值
{{ $translatedInput('title') }} // 获取翻译输入值
{{ $image('cover', 'default') }} // 获取图片URL

@foreach ($repeater('items') as $item)
  {{ $item->input('name') }}
@endforeach

传统Blade模板方式

除了组件方式，Twill仍然支持传统的Blade模板方式定义区块。区块模板存放在views/twill/blocks目录中。

基本区块模板示例

@twillBlockTitle('引用区块')
@twillBlockIcon('text')

<x-twill::input 
    name="quote"
    type="textarea"
    label="引用内容"
    :maxlength="250"
    :rows="4"
/>

高级区块模板示例

@twillBlockTitle('媒体区块')
@twillBlockIcon('image')
@twillBlockGroup('media')

<x-twill::medias name="image" label="图片" :max="5" />
<x-twill::input name="caption" label="说明文字" :translated="true" />

动态区块标题

Twill 2.5+支持动态区块标题：

@twillBlockTitle('区块')
@twillBlockTitleField('title', ['hidePrefix' => true])

从现有模板创建新区块

可以使用命令行工具基于现有区块创建新区块：

php artisan twill:make:block 新区块名称 基础区块名称 图标名称

区块列表查看

查看所有可用区块：

php artisan twill:list:blocks

自定义图标

要在区块中使用自定义图标，需要在配置文件中指定图标目录：

'block_editor' => [
    'directories' => [
        'source' => [
            'icons' => [
                resource_path('assets/admin/icons'),
            ],
        ],
    ],
],

模型和仓库集成

要在模块中使用区块编辑器，需要在模型和仓库中添加相应特性：

模型配置

use A17\Twill\Models\Behaviors\HasBlocks;

class Article extends Model
{
    use HasBlocks;
}

仓库配置

use A17\Twill\Repositories\Behaviors\HandleBlocks;

class ArticleRepository extends ModuleRepository
{
    use HandleBlocks;
}

通过以上配置，您的模块就可以完整支持区块编辑器功能了。区块编辑器为内容管理提供了极大的灵活性，使编辑者能够创建丰富多样的页面布局。

twill Twill is an open source CMS toolkit for Laravel that helps developers rapidly create a custom admin console that is intuitive, powerful and flexible. Chat with us on Discord at https://discord.gg/cnWk7EFv8R. 项目地址: https://gitcode.com/gh_mirrors/tw/twill