README

Twig Storybook是一个Composer包，通过引入两个新的Twig标签stories和story来增强Twig模板语言。使用Twig Storybook，您可以轻松地在Twig模板中创建和管理Storybook故事，使其成为记录和展示前端组件的强大工具。

安装

您可以通过Composer安装Twig Storybook

composer require e0ipso/twig-storybook

用法

与Drupal一起使用

您不需要直接使用此包，而是使用Storybook Drupal模块。此库与Drupal 10及其后续版本兼容。

添加Twig标签

安装包后，您需要在Twig环境中注册这些标签。以下是操作方法

use Twig\Environment;
use Twig\Loader\FilesystemLoader;
use E0ipso\TwigStorybook\Twig\StorybookExtension;

// Initialize the Twig environment
$loader = new FilesystemLoader('path/to/your/templates');
$twig = new Environment($loader);

// Register the Storybook extension
$twig->addExtension(new \TwigStorybook\Twig\TwigExtension());

创建故事

一旦注册了Twig Storybook扩展，您就可以开始在Twig模板中创建故事。我们建议将故事写入一个名为<file-name>.stories.twig的文件中。

使用{% stories %}标签定义一组故事。
使用{% story %}标签定义单个故事。

以下是一个示例

{% stories my_card with {
  title: 'Components/Examples/Card',
  argTypes: {
    iconType: {
      options: { Power: 'power', Like: 'like', External: 'external' },
      control: 'radio'
    }
  }
} %}

  {% story default with {
    name: '1. Default',
    args: { header: 'I am a header!', text: 'Learn more', iconType: 'power' }
  } %}
    {% embed '@examples/my-card' with { header } %}
      {% block card_body %}
        <p>I am the <em>card</em> contents.</p>
        {% include '@examples/my-button' with { text, iconType } %}
      {% endblock %}
    {% endembed %}
  {% endstory %}

{% endstories %}

这将渲染为

Storybook配置

按照常规安装Storybook

# Make use of modern versions of yarn.
yarn set version berry
# Avoid pnp.
echo 'nodeLinker: node-modules' >> .yarnrc.yml
# Install and configure stock Storybook.
yarn dlx sb init --builder webpack5 --type server

然后更新.storybook/main.js以扫描应用程序存储故事的位置。

将Twig故事编译成JSON

Storybook应用程序无法理解Twig格式的故事。它将无法渲染它们。您需要将它们编译成*.stories.json。为此，您可以利用StoryRenderer::generateStoriesJsonFile($template_path, $url)方法。其中$template_path是*.stories.twig模板的位置，而$url是应用程序中渲染故事的基准URL。Storybook将对"$url . '/' . $hash"发起请求，因此请确保您的应用程序处理该路由（见下文）。

Drupal模块实现包括一个控制台命令，用于查找所有*.stories.twig并将它们编译成*.stories.json。请参阅实现。

渲染故事

要渲染Storybook故事，您可以使用StoryRenderer服务。每个框架处理路由的方式不同，但我们建议在控制器中使用故事渲染器。

  public function renderStoryControllerHandler(string $hash, Request $request): array {
    $data = $this->storyRenderer->renderStory($hash, $request);
    return new Response($data);
  }

要使用此服务，将服务连接到容器。Twig Storybook Drupal模块就是这样做的

services:
  logger.channel.twig_storybook:
    parent: logger.channel_base
    arguments: ['twig_storybook']

  TwigStorybook\Service\StoryCollector: {}
  TwigStorybook\Service\StoryRenderer:
    arguments:
      - '@TwigStorybook\Service\StoryCollector'
      - '@logger.channel.twig_storybook'
      - '%app.root%'
    calls:
      - ['setTwigEnvironment', ['@twig']]

  TwigStorybook\Twig\TwigExtension:
    arguments:
      - '@TwigStorybook\Service\StoryCollector'
      - '%app.root%'
    tags:
      - { name: twig.extension }

贡献

我们欢迎社区的贡献。如果您想为Twig Storybook做出贡献，请遵循以下指南

对仓库进行Fork。
为您的功能或错误修复创建一个新的分支。
进行更改并确保所有测试通过。
提交一个带有对更改描述的pull request。

在与该社区互动时，请确保遵守行为准则。

许可证

Twig Storybook 是开源软件，许可协议为 GPL-2 许可协议。

e0ipso / twig-storybook

维护者

详细信息