⚠️ 注意： 本节仍在开发中，尚未完全准备好使用。🚧

可能缺乏完整的信息或包含不准确之处。如果您不是爱好者或经验丰富的用户，建议等到本节完成并验证后再依赖此处提供的信息。我们会尽快更新以确保本节完整准确。感谢您的耐心和理解。

包服务提供者

在 Laravel 中，服务提供者是一个关键组件，用于设置和配置包的各种功能。 Orchid 包也需要一个服务提供者来与您的 Laravel 应用集成。

初学者注意： 请注意，Orchid 文档页面主要侧重于展示 Orchid 平台的使用和功能。 它不涉及创建 Composer 包、在 Packagist 上注册或基本的 Laravel 包开发等更基础的主题。 如果您是 PHP 和 Laravel 的新手，建议在深入 Orchid 文档之前，先查阅其他专门针对这些主题的初学者友好资源。↩

要了解有关 Laravel 中服务提供者及其工作原理的更多信息，您可以参考 Laravel 官方文档关于服务提供者的部分。

Orchid 包提供了自己的服务提供者，称为 Orchid\Platform\OrchidServiceProvider。 该服务提供者扩展了核心 Laravel ServiceProvider 类，并提供了特定于 Orchid 包的附加功能。 它允许您在 Orchid 仪表板中注册菜单、权限、路由和其他功能。

要为您的包创建一个自定义服务提供者以扩展 OrchidServiceProvider 的功能，可以按照以下示例操作：

• 在您的包目录中创建一个名为 MyPackageServiceProvider.php 的新文件。
• 在 MyPackageServiceProvider 类中，扩展 Orchid 提供的 OrchidServiceProvider 类：

use Orchid\Platform\OrchidServiceProvider;

class MyPackageServiceProvider extends OrchidServiceProvider
{
   // 您的包特定代码在此
}

这样，您可以利用 OrchidServiceProvider 类提供的功能和方法，同时添加您自己的特定于包的自定义和配置。

定义路由

要在您的包中定义路由，请在您的服务提供者中创建一个 routes 方法。 您可以使用标准的 Laravel 路由机制通过 Router 实例注册您的路由。

use Illuminate\Routing\Router;

/**
 * 定义路由设置。
 *
 * @param \Illuminate\Routing\Router $router
 *
 * @return void
 */
public function routes(Router $route): void
{
    // 在此定义您的路由
    $route->screen('private-route', MyPackageScreen::class)
        ->name('package');
}

定义权限

Laravel Orchid 提供了一个灵活的权限系统来控制对包中不同部分的访问。 要定义权限，请在您的服务提供者中重写 permissions 方法。 此方法应返回由 Orchid 包提供的 ItemPermission 实例数组。

use Orchid\Platform\ItemPermission;

/**
 * 为应用注册权限。
 *
 * @return ItemPermission[]
 */
public function permissions(): array
{
    // 在此定义您的权限
    return [
        ItemPermission::group('包名称')
            ->addPermission('platform.package.option', '查看选项')
            ->addPermission('platform.package.other', '查看内容'),
    ];
}

为每个权限指定组名、权限键和描述。

定义导航

要为您的包定义导航菜单，请在您的服务提供者中重写 menu 方法。 此方法应返回由 Orchid 包提供的 Menu 实例数组。

use Orchid\Screen\Actions\Menu;

/**
 * 注册应用菜单。
 *
 * @return Menu[]
 */
public function menu(): array
{
    // 在此定义您的菜单项
    return [
        Menu::make('我的包')
            ->icon('bs.book')
            ->route('package.index'),
    ];
}

定义资源

Laravel Orchid 允许您注册自定义资源，如样式表和脚本，可以在仪表板中包含。要注册这些资源，您需要通过重写适当的方法在您的服务提供者中定义它们。

样式表

要定义要注册的样式表，请在您的服务提供者中重写 stylesheets 方法。此方法应返回一个字符串数组，其中每个字符串代表您要包含的样式表的路径。

/**
 * 定义要注册的样式表。
 *
 * @return string[]
 */
protected function stylesheets(): array
{
    return [
        'https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css', // CDN 路径
        '/absolute/path/to/your/styles.css', // 绝对路径
        Vite::asset('resources/css/app.css'), // Vite 资源
    ];
}

脚本

要定义要注册的脚本，请在您的服务提供者中重写 scripts 方法。此方法应返回一个字符串数组，其中每个字符串代表您要包含的 JavaScript 文件的路径。

/**
 * 定义要注册的脚本。
 *
 * @return string[]
 */
protected function scripts(): array
{
    return [
        'https://cdn.jsdelivr.net/npm/vue@3.2.26/dist/vue.global.js', // CDN 路径
        '/absolute/path/to/your/script.js', // 绝对路径
        Vite::asset('resources/js/app.js'), // Vite 资源
    ];
}

定义图标

要在您的包中使用不同图标集的图标，您可以在服务提供者的 icons 方法中指定图标路径和前缀。

/**
 * 获取图标路径和前缀。
 *
 * @return array
 */
public function icons(): array
{
    // 在此定义您的图标集
    return ['fa' => '/path/to/fontawesome'];
}

在此示例中，您可以定义不同图标集的路径和前缀。一旦注册，您可以在包的视图或组件中使用这些图标。

版本管理

在开发支持多个版本的包时，建议使用 Composer 进行版本管理。 Composer 提供了解决版本冲突的全面工具。如果由于某种原因，Composer 不适合您的项目，您可以考虑使用以下常量：

Orchid\Platform\Dashboard::version()

此常量返回当前使用版本的字符串表示形式。

扩展布局

Layouts 类是多个布局的集合；要向其添加新功能，只需在服务提供者中指定即可：

use Orchid\Screen\Layout;
use Orchid\Screen\LayoutFactory;
use Orchid\Screen\Repository;

/**
 * 为 LayoutFactory 定义自定义宏。
 *
 * @param string $name
 * @return Layout
 */
LayoutFactory::macro('hello', fn (string $name) => new class($name) extends Layout
{
    /**
     * 在视图中使用的名称。
     *
     * @var string
     */
    public function __construct(
        private string $name
    ) {}

    /**
     * 构建布局并返回视图。
     *
     * @param Repository $repository
     * @return \Illuminate\View\View
     */
    protected function build(Repository $repository)
    {
        return view('hello', ['name' => $this->name]);
    }
});

然后在屏幕上调用将如下所示：

use Orchid\Support\Facades\Layout;

public function layout(): array
{
    return [
        Layout::hello('Alexandr Chernyaev')
    ];
}

扩展列

在处理相同类型的数据时，通常需要以相同的方式处理它，为了不在层中重复代码，可以使用自己的方法扩展 TD 类。为此，需要在服务提供者中注册闭包函数。

注册示例：

// AppServiceProvider.php
TD::macro('bool', function () {

    $column = $this->column;

    $this->render(function ($datum) use ($column) {
        return view('bool',[
            'bool' => $datum->$column
        ]);
    });

    return $this;
});

模板示例：

// bool.blade.php

<span class="{{ $bool ? 'text-success' : 'text-danger' }}">●</span>

使用示例：

public function grid(): array
{
    return [
        TD::make('status')->bool(),
    ];
}