README

Bladestrap 为 Laravel Blade 组件 提供了 Bootstrap 5 前端框架的支持。

内容

• 安装
  • 安装 Bootstrap
  • 配置 Bladestrap
  • 自定义视图
• 用法
  • 警告
  • 徽章
  • 面包屑
  • 按钮
    • 按钮组
    • 按钮工具栏
  • 下拉菜单
  • 表单
    • 表单字段类型
    • 选项
    • 禁用、只读、必填
    • 输入组
    • 提示
    • 从查询参数中预填充值
    • 错误消息
  • 链接
  • 列表组
  • 模态框
  • 导航
• 不使用 Laravel 的用法

安装

首先，通过 Composer 安装包

composer require portavice/bladestrap

在 Laravel 应用程序中，包将自动注册。

注意

如果您只使用 Laravel 框架的部分（例如 illuminate/view），请确保按照 不使用 Laravel 的用法 部分的说明操作。

安装 Bootstrap

注意，您需要自己 包含 Bootstrap 文件。

1. 如果您还没有将 Bootstrap 添加为依赖项，您可以通过 npm 完成。

   npm install bootstrap

2. 将以下内容添加到您的 webpack.mix.js 中，将所需的 Bootstrap 文件复制到您的 public 目录

   let bootstrapFiles = [
       'node_modules/bootstrap/dist/css/bootstrap.min.css',
       'node_modules/bootstrap/dist/js/bootstrap.bundle.min.js',
   ];
   mix.copy(bootstrapFiles, 'public/lib');

3. 在 resources/views/layouts/app.blade.php 中包含 CSS 和 JavaScript

   <link rel="stylesheet" href="{{ mix('lib/bootstrap.min.css') }}">
   <script src="{{ mix('lib/bootstrap.bundle.min.js') }}"></script>

您可能需要根据您自定义项目的配置调整上述步骤。如果您有一个 自定义 Bootstrap 构建，您需要自己包含 Bootstrap 的必要部分。

配置 Bladestrap

通常这不应该有必要，但如果您需要覆盖默认配置，请创建并编辑 config/bladestrap.php

php artisan vendor:publish --tag="bladestrap-config"

自定义视图

如果您想自定义视图，请将它们发布到 resources\views\vendor\bladestrap\components 并根据您的需求进行编辑

php artisan vendor:publish --tag="bladestrap-views"

您可能想删除您没有更改的视图，以便自动受益于包更新。

用法

组件位于 bs 命名空间中，因此可以通过以下方式使用它们

<x-bs::component-name> <!-- Replace component-name with one of the component names described below -->

可以通过 Bootstrap 或您自己的 CSS 中的额外类来增强组件。

在 resources/views/components 下相应 Blade 模板中的 @props 中使用类型注解对特定处理的属性进行文档说明。

警告

警告 默认为 alert-info 变体，并且可以是可关闭的（带有关闭按钮）。

<x-bs::alert>My info alert</x-bs::alert>
<x-bs::alert variant="primary">My primary alert</x-bs::alert>
<x-bs::alert variant="secondary" :dismissible="true">My dismissible secondary alert</x-bs::alert>

徽章

徽章 默认为 badge-primary 变体

<x-bs::badge>My primary badge</x-bs::badge>
<x-bs::badge variant="secondary">My secondary badge</x-bs::badge>

面包屑

面包屑 容器是 <x-bs::breadcrumb>（通常放置在您的 layouts/app.blade.php 中）

@hasSection('breadcrumbs')
    <x-bs::breadcrumb container-class="mt-3" class="bg-light">
        <x-bs::breadcrumb.item href="{{ route('dashboard') }}">{{ __('Dashboard') }}</x-bs::breadcrumb.item>
        @yield('breadcrumbs')
    </x-bs::breadcrumb>
@endif

可以通过 <x-bs::breadcrumb.item :href="route('route-name')">标题</x-bs::breadcrumb.item> 添加项。

按钮

要创建 按钮 或类似按钮的链接，您可以使用 Bootstrap 的 btn-* 类

• <x-bs::button>（变成 <button>）
• 并且 <x-bs::button.link> （变为 <a>）。默认使用 btn-primary，您可以使用 variant 来更改它。

<x-bs::button href="{{ route('my-route') }}" variant="danger">{{ __('Delete') }}</x-bs::button>
<x-bs::button.link href="{{ route('my-route') }}">{{ __('My title') }}</x-bs::button.link>

要禁用按钮或链接，只需添加 disabled="true"，这将自动添加相应的类和 aria-disabled="true"，这是 Bootstrap 文档中推荐的。

按钮组

按钮可以被 分组

<x-bs::button.group>
    <x-bs::button>Button 1</x-bs::button>
    <x-bs::button variant="secondary">Button 2</x-bs::button>
</x-bs::button.group>

按钮工具栏

按钮组可以被组合成 工具栏

<x-bs:toolbar aria-label="Toolbar with two groups">
    <x-bs::button.group aria-label="First group">
        <x-bs::button>Button 1</x-bs::button>
        <x-bs::button>Button 2</x-bs::button>
    </x-bs::button.group>
    <x-bs::button.group aria-label="Second group">
        <x-bs::button variant="secondary">Button 3</x-bs::button>
        <x-bs::button variant="secondary">Button 4</x-bs::button>
    </x-bs::button.group>
</x-bs:toolbar>

下拉菜单

可以通过以下方式添加 下拉按钮

<x-bs::dropdown.button direction="end" variant="secondary">
    My button
    <x-slot:dropdown>
        <x-bs::dropdown.item href="#">Item 1</x-bs::dropdown.item>
        <x-bs::dropdown.item href="#">Item 2</x-bs::dropdown.item>
    </x-slot:dropdown>
</x-bs::dropdown.button>

可以使用 direction 属性来设置下拉覆盖的方向。默认为 down。 variant（默认 primary）从 按钮组件 继承。

在 <x-slot:dropdown> 中，您可以放置 标题 和 项

<x-bs::dropdown.header>My header</x-bs::dropdown.header>
<x-bs::dropdown.item href="#">Item</x-bs::dropdown.item>

请注意，Bootstrap 的下拉菜单需要 Popper，如果您不使用 Bootstrap 的 bootstrap.bundle.min.js，则需要单独包含它。

表单

使用 <x-bs::form> 创建 表单（方法默认为 POST），将传递给表单组件的任何其他属性也将被输出

<x-bs::form method="PUT" action="{{ route('my-route.update') }}" class="my-3">
    <!-- TODO: add form fields and buttons -->
</x-bs::form>

Bladestrap 将为所有除 GET 以外的请求方法自动注入 CSRF 令牌字段。Bladestrap 还将配置 方法欺骗 以支持 PUT、PATCH 和 DELETE 表单。

表单字段类型

Bladestrap 对 Bootstrap 的 表单字段 有广泛的支持。

<x-bs::form.field name="my_field_name" type="text" value="My value">{{ __('My label') }}</x-bs::form.field>

请注意，表单字段的 内容变为标签。这允许包含图标等。如果您不想添加标签，请不要传递任何内容

<x-bs::form.field name="my_field_name" type="text" value="My value"/>

所有属性都将传递给 <input>、<select>、<textarea> - 除了

• 以 container- 开头的属性（这些将应用于标签和输入的容器）
• 以及以 label- 开头的属性（这些将应用于标签）。

以下 类型 可作为 type 属性的值

• checkbox - 创建一个 普通复选框，需要 :options
• 颜色
• 日期
• 日期时间*
• 电子邮件
• 文件
• hidden - 忽略标签、提示和输入组的插槽
• 月份*
• 数字
• 密码
• radio - 创建一个 单选按钮，需要 :options
• 范围
• select - 创建一个 下拉菜单（带有 <option> 的 <select>），需要 :options
• switch - 创建一个 切换开关，需要 :options
• 电话
• 文本
• textarea - 创建一个 <textarea>
• 时间*
• 网址
• 周*

上述类型（标记为 *）在浏览器中不支持 完整。

选项

单选按钮、复选框和选择框需要一个提供值/标签对的 :options 属性，例如

• 一个 数组，例如 :options="[1 => 'Label 1', 2 => 'Label 2']"
• 一个 Illuminate\Support\Collection，例如
  • :options="User::query()->pluck('name', 'id')"
  • 或者 :options="User::query()->pluck('name', 'id')->prepend(__('all'), '')"
• 一个 Portavice\Bladestrap\Support\Options，允许为每个选项设置自定义属性。对于复选框、单选按钮和开关，带有前缀 check-container- 或 check-label- 的自定义属性分别应用于 .form-check 或 .form-check-label。如果标签包含 HTML，设置 :allow-html="true"。

Portavice\Bladestrap\Support\Options 可以用来根据以下内容轻松创建可迭代的对象

• 一个 array

  use Portavice\Bladestrap\Support\Options;
  
  // Array with custom attributes
  Options::fromArray(
        [
            1 => 'One',
            2 => 'Two',
        ],
        static fn ($optionValue, $label) => [
            'data-value' => $optionValue + 2,
        ]
    );

• 一个实现 BackedEnum 接口 的 enum

  use Portavice\Bladestrap\Support\Options;
  
  // All enum cases with labels based on the value
  Options::fromEnum(MyEnum::class);
  
  // ... with labels based on the name
  Options::fromEnum(MyEnum::class, 'name');
  
  // ... with labels based on the result of the myMethod function
  Options::fromEnum(MyEnum::class, 'myMethod');
  
  // Only a subset of enum cases
  Options::fromEnum([MyEnum::Case1, MyEnum::Case2]);

• 一个 Eloquent 模型的 array 或 Illuminate\Database\Eloquent\Collection（主键成为值，标签必须定义）

  use Portavice\Bladestrap\Support\Options;
  
  // Array of models with labels based on a column or accessor
  Options::fromModels([$user1, $user2, ...$moreUsers], 'name');
  
  // Collection of models with labels based on a column or accessor
  Options::fromModels(User::query()->get(), 'name');
  
  // ... with labels based on a Closure
  Options::fromModels(
      User::query()->get(),
      static fn (User $user) => sprintf('%s (%s)', $user->name, $user->id)
  );
  
  // ... with custom attributes for <option>s using a \Closure defining an ComponentAttributeBag
  Options::fromModels(User::query()->get(), 'name', static function (User $user) {
      return (new ComponentAttributeBag([]))->class([
          'user-option',
          'inactive' => $user->isInactive(),
      ]);
  });
  
  // ... with custom attributes for <option>s using a \Closure defining an array of attributes
  Options::fromModels(User::query()->get(), 'name', fn (User $user) => [
      'data-title' => $user->title,
  ]);

可以在 Options 中预先添加或附加其他选项

use Portavice\Bladestrap\Support\Options;

$options = Options::fromModels(User::query()->get(), 'name')
    ->sortAlphabetically() // call sort for current options
    ->prepend('all', '') // adds an option with an empty value before first option
    ->append('label for last option', 'value') // adds an option after the last option
    ->prependMany([ // adds options before the first option (value => label)
        'value-1' => 'first prepended option',
        'value-2' => 'second prepended option',
    ]);

单选按钮（允许从多个值中选择一个）

<x-bs::form.field name="my_field_name" type="radio" :options="$options"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>

多选复选框（允许选择多个值）

<x-bs::form.field id="my_field_name" name="my_field_name[]" type="checkbox" :options="$options"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>

单选复选框（只有一个选项）

<x-bs::form.field id="my_field_name" type="checkbox" :options="[1 => 'Option enabled']"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>
<x-bs::form.field id="my_field_name" type="checkbox" :allow-html="true"
                  :options="Options::one('Option <strong>with HTML</strong> enabled')"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>

选择（允许从多个值中选择一个）

<x-bs::form.field name="my_field_name" type="select" :options="$options"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>

多选（允许选择多个值）

<x-bs::form.field id="my_field_name" name="my_field_name[]" type="select" multi :options="$options"
                  :value="$value">{{ __('My label') }}</x-bs::form.field>

禁用、只读、必填

属性 :disabled、:readonly 和 :required 接受布尔值，例如 :disabled="true" 或 :required="isset($var)"。

输入组

要在表单字段左侧或右侧添加文本（除复选框和单选按钮外），可以使用插槽 <x-slot:prependText> 和 <x-slot:appendText>，它将创建一个 输入组

<x-bs::form.field name="my_field_name" type="number" min="0" max="100" step="0.1">
    {{ __('My label') }}
    <x-slot:prependText>≥</x-slot:prependText>
    <x-slot:appendText>€</x-slot:appendText>
</x-bs::form.field>

默认情况下，附加/预置的文本被包装在关联字段的 <label> class="input-group-text" 中。为了避免这种情况，可以在插槽上设置 :container="false" 属性，这允许添加按钮等

<x-bs::form.field name="file" type="file">
    File
    <x-slot:appendText>
        <x-bs::button.link variant="primary" href="test.pdf">Download current file</x-bs::button.link>
    </x-slot:appendText>
</x-bs::form.field>'

提示

<x-slot:hint> 可以用来在字段下方添加一个带有自定义提示的 文本（.form-text），该文本将通过 aria-describedby 自动引用输入

<x-bs::form.field name="my_field_name" type="text">
    {{ __('My label') }}
    <x-slot:hint>Hint</x-slot:hint>
</x-bs::form.field>

从查询参数中预填充值

设置 :from-query="true" 将从当前路由的查询参数中提取值。

<x-bs::form.field id="name" name="filter[name]" type="text" :from-query="true">{{ __('Name') }}</x-bs::form.field>

在页面 /my-page?filter[name]=Test 上，具有上面示例字段的表单将设置 "Test" 为字段的预填充值，而 /my-page 将有一个空值。

要传递未设置查询参数时应用的默认过滤器，请使用 ValueHelper::setDefaults

use Portavice\Bladestrap\Support\ValueHelper;

ValueHelper::setDefaults([
    'filter.name' => 'default',
])

错误消息

所有表单字段如果存在，将自动显示相应的错误消息（服务器端验证）。如果您想独立于表单字段显示它们，可以直接使用组件

<x-bs::form.feedback name="{{ $name }}"/>

两者 <x-bs::form.feedback> 和 <x-bs::form.field> 都支持使用非默认的错误包，通过 :errors 属性。

链接

可以通过 <x-bs::link> 放置 彩色链接，属性 opacity 和 opacityHover 定义 透明度。

<x-bs::link href="{{ route('my-route') }}">Link text</x-bs::link>
<x-bs::link href="{{ route('my-route') }}" variant="danger">Link text</x-bs::link>
<x-bs::link href="{{ route('my-route') }}" opacity="25">Link text</x-bs::link>

列表组

<x-bs::list> 是一个 列表组，多个 <x-bs::list.item> 的容器。:flush="true" 启用 清除行为，:horizontal="true" 将布局从垂直改为 水平。

可以通过 <x-bs::list.item> 添加项目

<x-bs::list>
    <x-bs::list.item>Item 1</x-bs::list.item>
    <x-bs::list.item :active="true">Item 2</x-bs::list.item>
</x-bs::list>

:active="true" 突出显示 活动项，:disabled="true" 使其看起来 已禁用。

模态框

可以使用 `` 创建模态框，其中可选的插槽包括标题和页脚。这两个插槽都接受额外的类和其他属性。如果您不想为标题使用 `

` 容器，可以通过 `container="h2"` 等方式更改它。

<x-bs::modal.button modal="my-modal">Open modal</x-bs::modal.button>
<x-bs::modal id="my-modal">
    <x-slot:title>My modal title</x-slot:title>
    <x-slot:footer>
        <x-bs::button>Test</x-bs::button>
    </x-slot:footer>
</x-bs::modal>

<x-bs::modal> 支持以下可选属性

• centered 用于垂直居中模态框（默认为 false）
• fade 用于打开模态框时的淡入效果（默认为 true）
• fullScreen 用于强制全屏（默认为 false，传递 true 以始终强制全屏或 sm 以强制小于 sm 断点的大小等）
• scrollable 用于为长对话框内容启用垂直滚动条（默认为 false）
• staticBackdrop 用于强制点击外部不关闭模态框（默认为 false）
• closeButton 设置模态框页脚中关闭按钮的变体（默认为 secondary，false 以禁用关闭按钮）
• closeButtonTitle 用于关闭按钮的标题（默认为 "关闭"）

<x-bs::modal.button modal="my-modal"> 会打开 ID 为 my-modal 的模态框。您可以将任何其他属性作为已知属性传递给 <x-bs::button>。

导航

<x-bs::nav> 创建一个导航容器，使用 container="ol" 将容器元素从默认的 <ul> 更改为 <ol>。

可以通过 `<x-bs::nav.item href="{{ route('route-name') }}">Current Page</x-bs::nav.item>` 添加导航项。

如果通过添加下拉插槽启用了此功能，则导航项可以打开一个 下拉菜单。

<x-bs::nav.item id="navbarUserDropdown">
    Dropdown link text
    <x-slot:dropdown class="dropdown-menu-end">
        <!-- dropdown content-->
    </x-slot:dropdown>
</x-bs::list.item>

不使用 Laravel 的用法

Bladestrap 使用 config() 和 request() 辅助函数。如果您想在 Laravel 之外使用 Bladestrap，您需要在应用程序中定义这两个辅助函数，例如（可能需要根据您使用的框架进行调整）

use Illuminate\Http\Request;
use Illuminate\Support\Arr;

$configFile = [
    'bladestrap' => require __DIR__ . '/../vendor/portavice/bladestrap/config/bladestrap.php',
];
function config(array|string|null $key, mixed $default = null): mixed
{
    global $configFile;
    return Arr::get($configFile, $key, $default);
}

$request = Request::capture();
function request(array|string|null $key = null, mixed $default = null): mixed
{
    global $request;
    return $key === null ? $request : $request->input($key, $default);
}

此外，您需要自行注册 BladestrapServiceProvider

use Illuminate\View\Factory;
use Portavice\Bladestrap\Macros\ComponentAttributeBagExtension;

// Register macros as BladestrapServiceProvider would do.
ComponentAttributeBagExtension::registerMacros();

/* @var Factory $viewFactory */
// Add components in bs namespace to your views.
$viewFactory->addNamespace('bs', __DIR__ . '/../vendor/portavice/bladestrap/resources/views');