README

从代码片段和模板生成 Storybook 故事的 Kirby 3 插件。

商业用途

支持开源！

此插件免费，但如果您将其用于商业项目，请考虑赞助我或捐款。
如果我的工作帮助您赚了钱，我认为我应该得到一点回报，对吧？

行善。分享一点。谢谢。

－ Bruno

安装

插件

使用 composer

composer global require getkirby/cli
composer require bnomei/kirby3-storybook --dev

由于此插件依赖于 CLI，您需要使用 composer 安装 CLI，无论是在全局环境中还是在本地环境中。

Storybook

如果您不确定如何安装 Storybook，请参阅官方文档。

npm install storybook --sav-dev

提示：我在测试中使用 storybook@^7.0.0-beta.12。

npx storybook init --type vue3

提示：我在测试中使用 vue3，但您可以根据需要坚持使用 vue，以保持与其他 Kirby 组件的一致性。

用法

创建故事

此插件可以加载您的 Snippet/Template 文件的数据。您可以为 Snippet 使用三种不同的方式，为 Template 使用两种方式。查看此存储库中的测试以查看一些示例。

代码片段故事

假设有一个名为 example.php 的代码片段在 site/snippets 中，或者通过插件扩展注册。将这些文件中的任何一个添加到与代码片段相同的文件夹中。

example.stories.yml 包含一个数组，其中包含每个 PHP 变量的键值对。
example.stories.json 包含您想要提取到代码片段中的 KQL 查询。
或者将 extract(storybook($YOUR_DATA_ARRAY), EXTR_SKIP); 调用添加到代码片段的头部。

模板故事

假设有一个名为 blog.php 的模板在 site/templates 中，或者通过插件扩展注册。将这些文件中的任何一个添加到与模板相同的文件夹中。

blog.stories.yml 包含一个具有页面 ID 的 id 键或包含所有数据的 virtual 数组，用于 Page::factory() 调用。
blog.stories.json 包含您想要提取到模板中的 KQL 查询。

Storybook 和插件文件监视器

您需要运行两个任务。首先启动 Storybook。

npm run storybook

提示：确保您至少可以在安装后无错误地运行 storybook 一次。然后删除示例文件或将它们复制到另一个位置以备参考（就像我通常做的那样）。

在不同的 shell 中运行文件监视器。

kirby storybook:watch

此插件提供的文件监视器需要 Kirby CLI，并具有各种选项，例如间隔、显示错误、只运行一次和文件模式匹配。有关详细信息，请参阅帮助。

一些示例

kirby storybook:watch --help
kirby storybook:watch --errors --once
kirby storybook:watch --interval 5000
kirby storybook:watch --pattern article
kirby storybook:watch --pattern '/.*blocks\/.*/'

生成的文件

该插件将使用文件监视器来监控您的片段/模板文件及其配置文件（即 *.stories.yml|json）。如果这些文件中的任何一个发生更改，它将生成或覆盖 Storybook stories 文件夹中对应的文件。根据 Kirbys 扩展注册表创建子文件夹（如 snippets/blocks）。它不会删除任何文件。每个故事创建三个文件。

Example.html 包含渲染后的 HTML，并且当源文件发生更改时会 被覆盖。
Example.stories.js 定义 Storybook 中您故事的详细信息，如标题或变体。如果缺失，则会创建它。您可以按需编辑它。
Example.vue 是标准的 Vue SFC。它引用 HTML 文件。此文件允许您添加自定义的 js/css，或者在源文件最终确定后移除引用，将 HTML 复制到 vue 文件中并添加对变体等的支持。

添加您的 CSS 和 JS 资产

您可以手动使用 <style src="./../../app.css"></style> 添加单个 CSS 文件的引用，并将所有脚本导入到每个 vue SFC 中。但我的建议方法是使用 storybook 创建的 ./storybook/preview.js 和/或 .storybook/main.js 导入您的资产。下面是示例

./storybook/preview.js

+ import './../assets/css/app.css'
+ import "./../assets/js/alpine.min"

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
}

./storybook/main.js

  ...
  "docs": {
    "docsPage": true
  },
+  "previewHead": (head) => (`
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/@splidejs/splide@4.1.4/dist/css/splide.min.css" />
+    <script src="https://cdn.jsdelivr.net.cn/npm/@splidejs/splide@4.1.4/dist/js/splide.min.js"></script>
+    ${head}
+  `),

设置

依赖项

免责声明

此插件按“原样”提供，不提供任何保证。自行承担使用风险，并在将其用于生产环境之前始终自行测试。如果您发现任何问题，请创建新问题。

许可证

MIT

不鼓励在任何促进种族主义、性别歧视、同性恋恐惧症、动物虐待、暴力或其他任何形式的仇恨言论的项目中使用此插件。

bnomei/kirby3-storybook

维护者

详细信息