README

什么是 Blast？

Blast 是一个低维护组件库，使用 Storybook 服务器构建，旨在集成到您的 Laravel 应用程序中。

Blast 允许您在 Laravel 应用程序中使用 Storybook 服务器，并通过 blade 模板引擎渲染应用程序组件的示例。

我们发布了一些文章，帮助您开始使用 Blast 及其功能。

• 开始使用 Blast – Storybook for Laravel Blade
• 使用 Blast 自动可视化 Tailwind Tokens 并记录设计系统属性

安装

composer require area17/blast

安装后，您可能需要配置应用程序的资产在 config/blast.php 中。要发布配置文件，请使用

php artisan vendor:publish --provider="A17\Blast\BlastServiceProvider" --tag="blast-config"

启动 Storybook

从应用程序的根目录运行

php artisan blast:launch

这将安装所有依赖项，生成故事，并启动 Storybook 实例，以及一个监视任务，以便在 resources/views/stories 中的 .md 和 .blade.php 文件以及 resources/views/stories/data 中的 .php 文件更新时自动重新生成故事并更新 Storybook。

选项

• --install - 强制安装依赖项
• --noGenerate - 跳过基于现有组件自动生成故事
• --port - 用于运行 Storybook 的端口

生成故事

Blast 还可以在 launch 任务之外生成故事。您可以通过运行

php artisan blast:generate-stories

选项

• --watch - 监视故事 blade 文件并更新故事

Storybook 配置

全局配置可以通过 config/blast.php 完成。

Blast 使用 public_path() 来引用任何静态资产。这意味着在该目录中的任何资产都将在开发期间以及在公共目录中发布的静态构建期间可用，使用 blast:publish 任务。

选项

storybook_version

允许使用 Storybook 的不同版本。Blast 只测试到 7.1.1。

默认值: '7.1.1'

storybook_server_url

Storybook 服务器用于渲染组件的路由。您不需要更改此设置，因为它在 FE 上从不可见。

默认值: config('app.url') . '/storybook_preview'

auto_documentation

Blast 可以根据 Tailwind 配置自动生成故事形式的故事文档页面。使用此数组指定要生成的文档页面。所有选项默认加载。

默认

[
    'border-radius',
    'border-width',
    'colors',
    'font-size',
    'font-weight',
    'height',
    'layout',
    'letter-spacing',
    'line-height',
    'max-height',
    'max-width',
    'min-height',
    'min-width',
    'opacity',
    'shadows',
    'spacing',
    'transition',
    'typesets',
    'width',
]

tailwind_config_path

Tailwind 配置文件的路径。用于解析自动文档。

默认值: base_path('tailwind.config.js')

storybook_expanded_controls

见 https://storybook.org.cn/docs/react/essentials/controls 将其设置为 true 以启用控制选项卡上的完整文档。启用此功能将需要在 @storybook blade 指令中进行配置，请参阅 blade 指令配置中的 description、defaultValue 和 table 数组键。

默认值: true

storybook_theme

Storybook 使用的主题选项数组。更多信息 这里。选项为 normal、dark 或 custom。normal 和 dark 主题是来自 @storybook-theming 插件的默认主题。要添加自定义主题，请编辑 config/blast.php 中的 storybook_custom_theme 数组中的值。

默认值: 'normal'

storybook_docs_theme

与 storybook_theme 相同的选项，此配置配置应用于文档选项卡的主题。

默认值: 'normal'

storybook_custom_theme

将数组传递给 @storybook-theming 插件以创建自定义主题。支持 HTML 颜色名称、RGB 和 HEX 颜色。

canvas_bg_color

设置组件画布区域的背景颜色。Storybook 主题不允许在不更改 UI 其他区域的背景的情况下更改此设置。

默认值: ''

autoload_assets

Blast 将尝试从 mix-manifest.json（Laravel Mix）或 manifest.json（Vite - 1.7 版本中添加）自动加载资源，如果资源数组为空。此选项允许您禁用此功能。请注意，Vite 资源仅从生产构建自动加载。如果您想与 Vite 的热重载一起使用它，您需要手动在 asset 数组中使用完整的本地 URL（例如，http://127.0.0.1:5173/resources/css/app.css）定义它，或者您可以发布并修改 storybook.blade.php 视图以使用 Laravel 的 @vite 辅助函数。

默认值: true

mix_manifest_path

允许您自定义用于自动加载资源的 mix-manifest 文件的路径。

默认值: public_path('mix-manifest.json')

vite_manifest_path

允许您自定义用于自动加载资源的 vite manifest 文件的路径。

默认值: public_path('build/manifest.json')

assets

一个包含您组件使用的 css 和 js URL 的数组。将 css 和 js URL 分开，因为 css 包含在 head 中，而 js 包含在关闭的 body 标签之前。js 资产可以有 类型（默认：text/javascript）。

您还可以将资源分组并指定用于不同组件的资源。

'assets' => [
    'css' => [
        'path/to/default.css', // default, loaded in all stories
        'blast' => 'path/to/blast.css', // load a single file
        'area17' => [ // use array to load multiple files
            'path/to/area17.css',
            'path/to/area17-other.css'
        ]
    ],
    'js' => [
        'path/to/default.js', // default, loaded in all stories
        [ // load as a module
            'path' => 'path/to/default.js',
            'type' => 'module'
        ]
        'blast' => 'path/to/blast.js', // load a single file
        'area17' => [ // use array to load multiple files
            'path/to/area17.js'
            'path/to/area17-other.js'
        ],
    ]
]

在您的故事 blade 文件中，您将使用 assetGroup 选择要使用的资源。

@storybook([
    'assetGroup' => 'blast',
]);

默认值: [ 'css' => [], 'js' => [], ]

storybook_statuses

Blast 内置了 Etch 的 Status 插件。这允许您为每个组件添加自定义状态指示器。此选项允许您自定义这些状态指示器。更多信息请参阅下面的自定义状态部分。

默认

[
'deprecated' => [
'background' => '#e02929',
'color' => '#ffffff',
'description' =>
'This component is deprecated and should no longer be used',
],
'wip' => [
'background' => '#f59506',
'color' => '#ffffff',
'description' => 'This component is a work in progress',
],
'readyForQA' => [
'background' => '#34aae5',
'color' => '#ffffff',
'description' => 'This component is complete and ready to qa',
],
'stable' => [
'background' => '#1bbb3f',
'color' => '#ffffff',
'description' => 'This component is stable and released',
],
]

storybook_sort_order

定义故事的自定义顺序。接受故事名称的数组，可以包含嵌套数组以设置二级故事的顺序。更多信息请参阅 官方 Storybook 文档。

默认值: []（按字母顺序排序）

storybook_global_types

全局类型可用于扩展和编辑工具栏。这是 Storybook 使用的工具栏和全局选项数组。更多信息请参阅 此处。

默认值: []

storybook_default_view_mode

设置每个故事的默认视图为 Canvas 或 Docs 视图。这可以使用 @storybook 指令中的 viewMode 属性在每个故事中进行覆盖。使用值 story 表示 canvas 视图，使用 docs 表示文档视图。如果设置为 false，则将在切换故事时使用最后使用的视图。

默认值: false

build_timeout

为 launch 和 generate-stories 中的任务设置自定义超时。

默认值: 300

vendor_path

Blast 包目录的相对路径

默认值: vendor/area17/blast

components

一个包含 Blast 使用的自定义组件的数组。

默认值: [ 'docs-page' => Components\DocsPages\DocsPage::class ]

storybook_viewports

配置 Storybook 预览工具栏中的自定义视口。

它支持在 Storybook 文档中找到的数组结构（点击查看），还可以通过设置值为 'tailwind' 使用你的 Tailwind 配置来为你生成视口。默认值为 'tailwind'，但如果 blast 找不到 Tailwind 配置，它将静默失败。可以通过设置值为 false 来禁用视口。

它支持使用这些规则在 Tailwind 中定义断点的各种方式

• 如果值是字符串，则使用该字符串
• 如果值是一个仅包含 min 或仅包含 max 的数组，则将使用该值
• 如果值是一个包含 min 和 max 值的数组，则将使用 min 值
• 将忽略 raw 值

默认值: 'tailwind'

故事配置

您可以从故事 blade 文件内部配置某些 Storybook 元素。您可以通过在文件顶部添加 @storybook 指令来完成此操作

@storybook([
    'preset' => 'file.option'
    'name' => 'Component Name',
    'layout' => 'fullscreen',
    'status' => 'stable',
    'order' => 1,
    'design' => "https://www.figma.com/file/LKQ4FJ4bTn\CSjedbRpk931/Sample-File",
    'design' => [
        [
            'name' => 'Foo',
            'type' => "figma",
            'url' => "https://www.figma.com/file/LKQ4FJ4bTn\CSjedbRpk931/Sample-File",
        ],
        [
            'name' => 'Bar',
            'type' => "link",
            'url' => "https://www.figma.com/file/LKQ4FJ4bTn\CSjedbRpk931/Sample-File",
        ],
    ],
    'args' => [
        'label' => 'Lorem Ipsum',
        'icon' => 'lorem-icon-dolor'
    ],
    'argTypes' => [
        'icon' =>[
            'options' => [
                'lorem-icon-dolor', 'another-icon'
            ],
            'control' => [
                'type' => 'select'
            ],
            'description' => 'descriptive text',
            'defaultValue' => 'lorem-icon-dolor',
            'table' => [
                'type' => [
                    'summary' => 'string'
                ],
                'defaultValue' => [
                    'summary' => 'lorem-icon-dolor'
                ],
            ],
        ]
    ],
    'actions' => [
        'handles' => ['mouseover', 'click']
    ]
])

此指令支持以下选项

• preset - 将预设用作组件故事的基座。在此指令中设置选项将覆盖预设
• name - 覆盖 Storybook 侧边栏中自动生成的名称。
• layout - 在画布区域设置组件布局。选项包括 fullscreen、padded、centered（默认）。
• status - 在组件故事中添加状态徽章。可以在包配置中配置。更多信息请见下文。
• order - 自定义每个故事顺序。支持浮点值。默认为字母顺序。
• design - 组件或设计参数数组的 Figma URL。您可以在此处了解有关支持选项的更多信息（点击查看）
• args - 用于创建 Storybook 字段的静态数据数组。您可以在此处了解有关更多信息（点击查看）。数组中的键传递给 blade 视图，并在 Storybook 中更新字段时更新。
• argTypes - 定义用于控制的 args 的数组。您可以在此处了解有关更多信息（点击查看）
• actions.handles - 定义传递给 @storybook-actions 插件的事件的数组。您可以在此处了解有关操作更多信息（点击查看） - 请参阅操作事件处理程序部分。

自定义故事视图

您可以从 config/blast.php 中自定义许多故事组件视图，但如果您需要更进一步，您可以将视图发布到应用程序文件夹并对其进行修改。

php artisan vendor:publish --provider="A17\Blast\BlastServiceProvider" --tag="blast-views"

这将发布 storybook.blade.php 和所有 ui-docs 组件到 resources/views/vendor/blast。

演示组件

运行 php artisan blast:demo 将创建显示演示组件所需的所有文件。它在您的 resources/views/components 和 resources/views/stories 目录中创建文件，并生成故事。

您可以在 php artisan blast:launch 任务旁边运行它，或者您可以在启动演示任务后运行 launch 任务来初始化 Storybook。

预设故事选项

您可以为组件创建预设选项，以便在整个 Storybook 实例中重复使用。

预设选项使用与 Laravel 配置文件相同的结构

return [
    'primary' => [
        'args' => [
            'href' => '#',
            'label' => 'Primary',
        ],
    ],
    'primaryIcon' => [
        'args' => [
            'label' => 'Primary',
            'icon' => 'search-24',
            'iconPosition' => 'after',
        ],
        'argTypes' => [
            'icon' => [
                'control' => 'select',
                'options' => ['search-24', 'chevron-right-24', 'external-24'],
            ],
            'iconPosition' => [
                'control' => 'radio',
                'options' => ['Before' => 'before', 'After' => 'after'],
            ],
        ],
    ],
];

您可以预设 @storybook 指令中可用的任何选项。

要使用预设，请将 preset 选项设置为数组路径（使用“点”表示法），其中第一部分是文件名，后跟您要访问的选项。

@storybook([
    'preset' => 'button.primary',
    'args' => [
        'label' => 'Read More',
    ],
]);

在此示例中，它将更新标签从“主要”更改为“阅读更多”。

预设数据

在某些情况下，重新使用其他组件中的数据在新组件中很有益。例如，帖子列表可能使用多个帖子组件的数据。

为此，您可以以与在故事中设置预设类似的方式，在您新组件的数据文件中引用数据。

使用 presetArgs 键定义您想要从另一个组件获取数据的参数。您可以将预设设置为引用数组的引用，或单个引用。

下面的示例使用来自 card 故事的生成 items 数组，该数组用于 card-list 组件。

// stories/data/card.php
return [
    'post' => [
        'args' => [
            'href' => '#',
            'title' => 'Euismod Vulputate',
            'subtitle' => 'Purus Malesuada',
            'description' => 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id ligula porta felis euismod semper.'
        ]
    ],
    'post_alt' => [
        'args' => [
            'href' => '#',
            'title' => 'Cursus Aenean Quam',
            'subtitle' => 'Pharetra Quam',
            'description' => 'Etiam porta sem malesuada magna mollis euismod.',
        ]
    ],
    'post_alt_2' => [
        'args' => [
            'href' => '#',
            'title' => 'Etiam Cras Euismod',
            'subtitle' => 'Risus Etiam Pharetra Fusce',
            'description' => 'Maecenas faucibus mollis interdum. Vestibulum id ligula porta felis euismod semper.',
        ]
    ]
];

// stories/data/card-list.php
return [
    'posts' => [
        'presetArgs' => [
            'items' => [
                'card.post_alt_2',
                'card.post_alt',
                'card.post'
            ]
        ]
    ]
];

// output stories.json
"args": {
    "items": [
        {
            "href": "#",
            "title": "Etiam Cras Euismod",
            "subtitle": "Risus Etiam Pharetra Fusce",
            "description": "Maecenas faucibus mollis interdum. Vestibulum id ligula porta felis euismod semper."
        },
        {
            "href": "#",
            "title": "Cursus Aenean Quam",
            "subtitle": "Pharetra Quam",
            "description": "Etiam porta sem malesuada magna mollis euismod."
        },
        {
            "href": "#",
            "title": "Euismod Vulputate",
            "subtitle": "Purus Malesuada",
            "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id ligula porta felis euismod semper."
        }
    ]
},

自定义状态

Blast 附带 4 个预设状态，可在您的故事中使用 - 已弃用、进行中、准备QA 和 稳定。您可以在 config/blast.php 中通过传递包含状态的数组来定义自定义状态，并使用 storybook_statuses 配置。例如

'storybook_statuses' => [
    "phase1" => [
      "background" => '#333333',
      "color" => '#ffffff',
      "description" => 'This component is part of phase 1',
    ]
]

有关此插件的更多信息，请参阅此处。

注意：定义自定义状态将覆盖现有状态。

文档

将 README.md 添加到您的 Storybook blade 目录中，您可以为组件添加 Storybook 中的文档页面。Markdown 文件的内容将输出在自动生成的 Storybook 内容之上。

您还可以添加一个与您的故事文件同名的 markdown 文件，它将在文档页面上添加组件变体的文档。

发布静态 Storybook

Blast 可以构建静态 Storybook 应用程序并将其发布到您的公共文件夹。您可以通过运行以下命令来完成此操作：

php artisan blast:publish

生成 Tailwind 文档故事

Blast 可以自动生成故事来可视化您的 Tailwind 配置。请参阅上面的“自动文档”以了解如何配置要生成哪些故事。

php artisan blast:generate-docs

您可以将 --force 选项传递以自动覆盖现有文档故事，或使用 --update-data 选项更新故事数据而不复制任何文件（此选项仅在您之前已运行任务时才有效）。

选项

• --o, --output-dir - 相对于您的 public 目录存储构建文件的目录

发布 Storybook 配置

有时您可能需要将 Storybook 配置文件发布到应用程序目录中（例如，更改 Storybook 版本）。这会将 .storybook 目录复制到您的应用程序根目录，并更新启动和发布任务以使用此目录进行任何 Storybook 配置。

php artisan blast:publish-storybook-config

故障排除

当您查看故事时，如果看到“无法获取”消息，您需要转到 Storybook 尝试加载的路径（打开开发者工具 > 网络，右键单击失败的路径并在新标签页中打开）并在那里进行调试。任何 PHP 错误或 dd 将触发“无法获取”消息。

已知问题

• 有时重命名故事 blade 文件会导致该组件的故事重复。您可以通过运行 php artisan blast:generate-stories 来解决这个问题。