Voyager BREAD系统全攻略：从Browse到Delete的完整流程-优快云博客

Voyager BREAD系统全攻略：从Browse到Delete的完整流程

【免费下载链接】voyager 项目地址: https://gitcode.com/gh_mirrors/voy/voyager

BREAD（Browse, Read, Edit, Add, Delete）是Voyager管理系统的核心功能，它允许用户无需编写代码即可创建完整的数据管理界面。本文将详细介绍如何使用BREAD系统实现从数据浏览到删除的全流程操作，帮助普通用户和运营人员快速掌握这一强大工具。

BREAD基础概念

BREAD是Voyager提供的一套数据管理解决方案，通过简单的配置即可生成完整的CRUD（增删改查）界面。其核心思想是将数据库表映射为可视化的管理界面，主要包含以下五个操作：

Browse（浏览）：查看数据列表，对应docs/bread/introduction.md中提到的BROWSE选项
Read（查看）：查看单条数据详情，对应READ选项
Edit（编辑）：修改已有数据，对应EDIT选项
Add（添加）：创建新数据，对应ADD选项
Delete（删除）：移除数据，对应DELETE选项

BREAD系统的配置主要通过两个部分完成：基础信息设置和字段配置。基础信息包括显示名称、URL别名、图标、模型和控制器命名空间等；字段配置则允许你指定每个数据库字段在不同操作中的可见性和表现形式。

BREAD创建流程

1. 基础信息配置

创建BREAD的第一步是设置基础信息。在Voyager管理后台中，选择"Database"->"BREAD"，然后点击"Add BREAD"按钮，你将看到如下配置项：

Display Name：显示名称，用于界面展示
Slug：URL别名，用于生成访问路径
Icon：图标，从Voyager图标库中选择
Model Namespace：模型命名空间，指定对应的Eloquent模型
Controller Namespace：控制器命名空间，指定处理请求的控制器
Policy Name：策略名称，用于权限控制
Generate Permissions：是否自动生成权限

配置示例：

{
    "display_name": "文章",
    "slug": "posts",
    "icon": "voyager-file-text",
    "model_namespace": "App\\Models\\Post",
    "controller_namespace": "App\\Http\\Controllers\\PostController",
    "policy_name": "PostPolicy",
    "generate_permissions": true
}

这些配置将保存在src/Models/DataType.php模型中，用于生成对应的管理界面。

2. 字段配置

基础信息设置完成后，需要配置每个数据库字段的属性。对于每个字段，你可以指定它在BROWSE、READ、EDIT、ADD操作中的可见性，以及表单字段类型和验证规则。

BREAD字段配置界面

通用配置选项

所有表单字段都支持以下通用配置：

Description：字段描述，帮助用户理解字段用途
Display Options：显示选项，如宽度和自定义ID
Default Value：默认值，新增数据时自动填充
Null Values：空值处理，指定什么值应被视为NULL
Validation Rules：验证规则，确保数据符合要求

示例配置：

{
    "description": "文章标题，将显示在列表和详情页",
    "display": {
        "width": "6",
        "id": "post_title"
    },
    "default": "新文章标题",
    "null": "",
    "validation": {
        "rule": "required|max:255",
        "messages": {
            "required": "标题不能为空",
            "max": "标题不能超过255个字符"
        }
    }
}

这些配置在docs/bread/formfields/introduction.md中有详细说明。

常用表单字段类型

Voyager提供了多种表单字段类型，适用于不同的数据类型和使用场景：

Text：单行文本，适用于短文本如标题
Textarea：多行文本，适用于描述等长文本
Number：数字输入，支持整数和小数
Checkbox：复选框，适用于布尔值
Radio Button：单选按钮，适用于互斥选项
Select Dropdown：下拉选择框，适用于有限选项
Image：图片上传，支持图片预览和管理
File：文件上传，支持各种文件类型
Date：日期选择器，支持日期格式化
DateTime：日期时间选择器，精确到时分秒

每种字段类型的具体配置可参考docs/bread/formfields/目录下的对应文档，如docs/bread/formfields/number.md详细介绍了数字字段的配置选项。

3. 关系配置

BREAD系统支持数据库表之间的关系配置，包括belongsTo、belongsToMany、hasOne和hasMany四种关系类型。通过关系配置，可以实现关联数据的联动管理。

BREAD关系配置按钮

配置步骤：

在BREAD编辑页面底部点击"Create Relationship"按钮
选择关系类型（如belongsTo）
选择关联表和关联字段
配置显示字段和排序方式

示例：为文章添加分类关系

{
    "type": "belongsTo",
    "table": "categories",
    "column": "category_id",
    "display": "name",
    "sort": {
        "field": "name",
        "direction": "asc"
    }
}

关系配置的详细说明可参考docs/bread/relationships.md。

高级功能

数据排序

Voyager允许你定义BREAD数据的默认排序方式，只需在BREAD设置中指定排序字段和方向：

{
    "order_column": "created_at",
    "order_direction": "desc"
}

此外，你还可以通过拖拽方式手动调整数据顺序，这需要在BREAD设置中启用排序功能并指定排序字段：

BREAD排序设置

排序功能的实现细节可参考docs/bread/introduction.md中的"Ordering Bread Items"部分。

数据筛选

通过在模型中定义局部作用域（Scope），可以实现BREAD数据的筛选。例如，创建一个只显示 active 状态文章的作用域：

// 在Post模型中
public function scopeActive($query)
{
    return $query->where('status', 'active');
}

然后在BREAD设置中指定该作用域：

{
    "scope": "active"
}

这样，在浏览文章时只会显示状态为active的记录。更多关于作用域的使用可参考docs/bread/introduction.md中的"Scope browse-results"部分。

自定义视图

如果默认的BREAD界面不能满足需求，你可以为特定操作自定义视图。只需在字段配置中指定自定义视图路径：

{
    "view_browse": "voyager::posts.browse",
    "view_read": "voyager::posts.read",
    "view_add": "voyager::posts.add",
    "view_edit": "voyager::posts.edit"
}

自定义视图需要放在resources/views目录下，Voyager会将必要的数据传递给视图，包括当前操作类型、字段内容、数据模型等。详细说明可参考docs/bread/formfields/introduction.md中的"Custom view"部分。

实际应用示例

下面以一个博客系统为例，展示如何使用BREAD系统管理文章数据：

1. 创建文章表迁移

首先创建文章表的数据库迁移：

// database/migrations/XXXX_XX_XX_XXXXXX_create_posts_table.php
public function up()
{
    Schema::create('posts', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->slug('slug')->unique();
        $table->text('excerpt')->nullable();
        $table->text('content');
        $table->foreignId('category_id')->constrained();
        $table->foreignId('author_id')->constrained('users');
        $table->boolean('published')->default(false);
        $table->timestamp('published_at')->nullable();
        $table->timestamps();
    });
}

2. 创建BREAD配置

在Voyager后台创建新的BREAD，基础信息配置如下：

Display Name: Posts
Slug: posts
Icon: voyager-file-text
Model Namespace: App\Models\Post
Controller Namespace: App\Http\Controllers\Voyager\PostController
Generate Permissions: Yes

3. 配置字段属性

为每个字段配置属性，以下是几个关键字段的配置：

Title字段

{
    "display": {
        "width": "6"
    },
    "validation": {
        "rule": "required|max:255"
    }
}

Content字段

{
    "type": "rich_text_box",
    "validation": {
        "rule": "required"
    }
}

Published字段

{
    "type": "checkbox",
    "default": "0",
    "validation": {
        "rule": "boolean"
    }
}

4. 配置关系

添加与分类表的belongsTo关系：

Relationship Type: Belongs To
Table: categories
Column: category_id
Display Column: name

5. 完成配置并使用

保存BREAD配置后，Voyager会自动生成完整的文章管理界面。你可以通过/admin/posts访问该界面，进行文章的浏览、查看、编辑、添加和删除操作。

文章管理界面

总结

Voyager的BREAD系统为数据管理提供了强大而灵活的解决方案，通过简单的配置即可实现复杂的数据管理功能。无论是小型网站还是大型应用，BREAD都能显著提高开发效率，让开发者和运营人员专注于业务逻辑而非重复的CRUD操作。

通过本文的介绍，你应该已经掌握了BREAD系统的基本使用方法和高级特性。如需进一步学习，建议参考官方文档的docs/bread/部分，以及探索src/Models/DataType.php和src/FormFields/目录下的源代码，深入了解BREAD系统的实现原理。

最后，BREAD系统的强大之处在于其可扩展性。如果你需要更复杂的功能，可以通过自定义表单字段、添加钩子函数或扩展控制器等方式进行扩展，这些高级主题将在后续文章中详细介绍。

【免费下载链接】voyager 项目地址: https://gitcode.com/gh_mirrors/voy/voyager

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考