如何建立一个故事书插件

增强UI开发工作流的部分并使其自动化.

加载
Varun Vachhar
@winkerVSbecks

Storybook是一个用于在独立环境中开发应用程序外部UI组件的工具. Storybook插件允许您增强和自动化您的工作流的部分. 而Storybook社区提供了超过200种, 您还可以根据您的特定需求构建一个.

构建插件很简单. 在这篇文章中,我将帮助你建立你的第一个Storybook插件. 十博体育备用网址将介绍api和体系结构.

十博体育备用网址要建造什么?

很难判断你的CSS布局是否与设计相匹配. 当DOM元素相距较远或形状奇怪时,肉眼观察的对齐是很棘手的.

adddon Outline添加了一个工具栏按钮,概述了使用CSS的所有UI元素.  这使得验证位置和位置一目了然. 看看下面的示例.

附加物的解剖结构

插件允许您扩展Storybook的功能. 从接口到api的一切. 他们⚡增压⚡UI工程工作流.

有两大类插件:

  • 基于ui: 自定义界面, 添加重复任务的快捷方式或格式化和显示附加信息. 例如:文档、易访问性测试、交互控件和设计预览.
  • 预设: 自动应用的Storybook配置集合. 它们通常用于将Storybook与特定技术快速配对. 例如,pre -create-react-app, pre - nunext和preset-scss.

基于ui插件

插件可以创建三种类型的界面元素:

1. 您可以添加一个工具到 工具栏,例如 网格和背景 工具

2. 创建一个插件 面板 类似于 行动插件 哪个显示操作日志

3. 创建一个新的 选项卡 就像 某人文档 哪个显示组件文档.

很明显,插件可以做很多事情. 那么如何构建一个插件呢?

用于Outline插件, 用户应该能够单击工具栏中的按钮来绘制故事中每个元素的轮廓. 再次单击该按钮以删除所有轮廓. 十博体育备用网址的插件代码有四个部分:

  • UI 这将在工具栏中创建“工具”按钮. 这是用户点击的内容.
  • 登记 的插件与故事书.
  • 状态管理 跟踪工具的切换状态. 它控制轮廓是否可见.
  • 装饰 在预览iframe中注入CSS来绘制轮廓.

开始

十博体育备用网址需要能够测试这个插件,因为十博体育备用网址正在开发它. 我使用 init npx某人 引导一个基本的React Storybook设置. 所有插件的代码都在顶级目录src中.

作为参考,您可以查看完整的源代码 在这里.

构建用户界面 & 注册插件

Storybook有自己的组件库, @storybook /组件,由反应和情感组成. 十博体育备用网址用它来构建Storybook (演示). 这非常方便,因为你也可以使用这些组件来构建你的插件. 在本例中,十博体育备用网址将使用图标和IconButton组件来创建大纲选择器工具. 在很大程度上,这是一个普通的React组件.

在本例中,十博体育备用网址将使用 图标IconButton 组件来创建大纲选择器工具. 在很大程度上,这是一个普通的React组件.

/ / OutlineSelector.js 

import React, {useState, memo} from ' React ';
import {图标, IconButton} from ` @storybook /组件 `;

export const OutlineSelector = memo(() => {
  const [outline, setOutline] = useState(false);
  const toggleOutline = () => setOutline(!大纲);

  回报(
    
      <图标 icon="outline" />
    
  );
});

注册插件与故事书使用唯一 ADDON_ID. 我建议你这样做 故事书/ addon-name. 注意到 匹配 财产. 它允许你控制插件可以在哪种视图模式下使用. 在这种情况下,插件将在故事和文档模式下可用.

/ /注册.js

import React from ' React ';
从'@storybook /插件'中导入{插件, types};

从` `中导入{ADDON_ID}./常量”;
import {OutlineSelector} from `./ OutlineSelector”;

插件.注册(ADDON_ID, () => {
  插件.添加(ADDON_ID, {
    标题:“大纲”,
    类型:类型.工具,
    匹配: ({ viewMode }) => !!(viewMode && viewMode.匹配(/ ^(故事|文档)/美元)),
    render: () => ,
  });
});

要开始使用插件,请添加对的引用 注册.js 在你的 .故事书/主要.js 文件,并开始您的故事书.

// .故事书/主要.js

模块.出口= {
 故事:[
   '../ * * / * /故事.故事.mdx’,
   '../ * * / * /故事.故事.@ (js | jsx | ts | tsx)”,
 ],
 插件:[“@storybook / addon-essentials”、“../ src /注册.js'],
};

此时,您应该在工具栏🎉中看到大纲选择器工具

跟踪状态

一开始我用了 useState 钩子控制切换状态. 通常,这就足够了. 然而,在这种情况下,事情要稍微复杂一些. 让十博体育备用网址花点时间讨论一下Storybook是如何构建的.

Storybook架构的基础知识

从表面上看,Storybook提供了一个统一的用户界面. 然而,在引擎盖下,它被分为两个部分,通过一个 通信通道:

  • 一个经理: 用于呈现Storybook的搜索、导航、工具栏和插件的UI.
  • 预览: 用于呈现故事的iframe.

十博体育备用网址需要跟踪切换状态 十博体育备用网址还需要在管理器和预览中共享该状态. 因此,而不是 useState 十博体育备用网址会用到 use全局变量.

跟踪全局状态

全局变量 代表了 “全球” (如在不特定于故事的)故事书的上下文. 它们是在不同的故事、插件和装饰器之间共享信息的方便方法. 的 use全局变量 钩子,它允许你访问你正在构建的工具中的全局上下文. 你可以找到这个和其他插件相关的api @storybook /插件 包.

让十博体育备用网址更新 OutlineSelector 使用全局变量. 同样,使用唯一标识符 PARAM_KEY 跟踪大纲切换状态. 此时,您不仅应该能够看到大纲选择器工具,而且还可以打开和关闭它👉🏽🔘

/ / OutlineSelector.js

import React, {memo, useCallback} from ' React ';
import {use全局变量} from ` @storybook/api `;
import {图标, IconButton} from ` @storybook /组件 `;
import {PARAM_KEY} from `./常量”;

export const OutlineSelector = memo(() => {
  const [globals, update全局变量] = use全局变量();

  const isActive = 全局变量(PARAM_KEY) || false;

  const toggleOutline = useCallback()
    () =>
      update全局变量 ({
        [PARAM_KEY]: !isActive,
      }),
    (isActive)
  );

  回报(
    
      <图标 icon="outline" />
    
  );
});

与故事交互-装饰器

几乎有. 到目前为止,十博体育备用网址创建了一个工具,并将其添加到工具栏中,它甚至可以跟踪状态. 十博体育备用网址现在需要响应这个状态并显示/隐藏轮廓.

修饰符 包装故事和附加的额外渲染功能. 农药的使用 一些CSS来绘制所有HTML元素的轮廓. 十博体育备用网址将创建一个decorator来响应大纲全局并处理CSS注入.

在前面的步骤中,十博体育备用网址定义了大纲全局,让十博体育备用网址连接它! 方法在装饰器中使用新的全局变量 上下文.全局变量(PARAM_KEY) 价值.

/ / withOutline.js

import {PARAM_KEY} from `./常量”;
 
export const withOutline = (StoryFn, 上下文) => {
 Const {globals} = 上下文;
 const isActive = 全局变量(PARAM_KEY) === true;
 
 返回StoryFn ();
};

添加和清除样式是一个副作用,因此,十博体育备用网址需要将该操作打包 useEffect. 哪个是由大纲全局触发的.

/ / withOutline.js

从'@storybook /插件'中导入{useMemo, useEffect};
import {clearStyles, addoutlinestles} from `./帮手”;
import {PARAM_KEY} from `./常量”;
import outlineCSS from `./ outlineCSS”;

export const withOutline = (StoryFn, 上下文) => {
  Const {globals} = 上下文;
  const isActive = 全局变量(PARAM_KEY) === true;
  const isInDocs = 上下文.viewMode = = =“文档”;

  const outlineStyles = useMemo(() => {
    const selector = isInDocs
      ? “#锚——${上下文.id} .docs-story”
      : '.sb-show-main ';

    返回outlineCSS(选择);
  },(上下文.id]);

  useEffect(() => {
    const selectorId = isInDocs
      ? “addon-outline-docs——${上下文.id}`
      :“addon-outline”;

    if (!isActive) {
      clearStyles (selectorId);
      返回;
    }

    addOutlineStyles (selectorId outlineStyles);

    回报() => {
      clearStyles (selectorId);
    };
  }, [isActive,大纲样式,上下文.id]);

  返回StoryFn ();
};

好吧,这似乎是一个很大的飞跃. 让十博体育备用网址来看看所有的变化.

这个插件可以在文档和故事视图模式中激活. 在这两种模式中,预览的实际DOM节点是不同的. 事实上,docs模式在一个页面上呈现多个故事预览. 因此, 十博体育备用网址需要为将要注入样式的DOM节点选择合适的选择器. 此外,CSS需要限定到那个特定的选择器.

下一个, 当十博体育备用网址将样式注入DOM时,十博体育备用网址需要跟踪它们,以便在用户关闭样式或切换视图模式时清除它们.

至于实际的CSS逻辑,我有一些 助手 使用DOM api注入和删除样式表.

请注意, useMemouseEffect 这里来自 @storybook /插件 而不反应. 这是因为装饰器代码在Storybook的预览部分中运行. 这是加载用户代码的地方,其中可能不包含React. 因此, 框架不可知, Storybook实现了一个简单的类似react的钩子库,十博体育备用网址可以使用它!

预设,使大纲为所有故事

现在,装饰器已经不存在了,让十博体育备用网址使用预置来包装每个故事.

预设 允许您组合一堆不同的Storybook配置,并一次性应用它们. 预置负责两个位的配置:

  • 将每个故事包装在一个装饰器中
  • 注册插件
/ /预设/索引.js

导出函数配置(entry = []) {
 返回(...条目,需要.解决('./ add装饰 '));
}
 
导出函数managerEntries(entry = []) {
 返回(...条目,需要.解决('../注册'));
}
/ /预设/ add装饰.js

import {withOutline} from `../ withOutline”;
 
导出const decorators = [withOutline];

最后你需要更新 .故事书/主要.js 文件使用预设而不是直接使用寄存器.

// .故事书/主要.js

模块.出口= {
 故事:[
   '../ * * / * /故事.故事.mdx’,
   '../ * * / * /故事.故事.@ (js | jsx | ts | tsx)”,
 ],
 插件:[“@storybook / addon-essentials”、“../ src /预设.js'],
};

重新启动你的故事书,你现在有一个功能齐全的插件!

结论

成功! 十博体育备用网址使用Storybook的插件API来创建新的大纲插件(GitHub). API为十博体育备用网址完成了大部分集成工作. 十博体育备用网址所需要提供的只是创意和定制.

你今天可以试试这个插件 npm i -D storybook-addon-outline. 它需要故事书6.1或更高. 安装最新的 NPX sb升级——预发布.

Storybook最受欢迎的功能是作为插件实现的. 例如文档、控件、操作和视图. 这篇文章只触及了可能性的表面. 我很期待你能想出什么来.

在下一篇文章中,我将向你展示如何打包和发布你的插件到官方目录.

如果你正在创建一个插件,请给出 me 推特上的呐喊. 注册十博体育备用网址的通讯,成为第一个听到它的人.


大纲插件的灵感来自于 农药 Chrome扩展.

这篇文章对你有帮助吗?

获得免费的UI开发指南和教程,就像这个电子邮件给你.

4402个开发者,还在增加

十博体育备用网址正在招聘!

加入故事书和彩色的团队. 构建成千上万开发人员在生产环境中使用的工具. Remote-first.

视图的工作

受欢迎的文章

UI测试的自动焦点

更快地发现细微的视觉变化
加载
多米尼克阮
通过彩色
面向专业UI开发人员的深入指南和教程,来自Storybook团队
指南
介绍故事书为开发人员设计系统视觉测试手册
关于
订阅
加入墨水时事通讯,以获得免费的教程、指南和通过电子邮件发送给您的资源.
友情链接: 1 2 3 4 5 6 7 8 9 10