如何构建一个故事书插件

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

加载
Varun Vachhar
@winkerVSbecks

Storybook是一个用于在应用程序之外的隔离环境中开发UI组件的工具. 故事书插件允许你增强和自动化你的工作流程的一部分. 而故事书社区提供了200多种, 您还可以根据自己的特定需求定制一个.

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

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

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

插件大纲增加了一个工具栏按钮,概述所有的用户界面元素使用CSS.  这使得它很容易验证定位和位置在一瞥. 看看下面的例子.

附件的解剖结构

Addons允许你扩展Storybook的功能. 从接口到api的一切. 他们⚡supercharge⚡UI工程工作流.

有两大类插件:

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

基于ui插件

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

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

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

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

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

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

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

开始

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

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

构建用户界面 & 注册插件

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

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

/ / OutlineSelector.js 

从React中导入React, {useState, memo};
import {图标, IconButton} from '@storybook /组件';

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

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

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

/ /注册.js

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

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

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

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

// .故事书/主要.js

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

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

跟踪状态

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

Storybook架构的基础知识

从表面上看,Storybook提供了一个统一的用户界面. 然而,在内部,它被分成了两个部分,通过a 通信通道:

  • 一个经理: Storybook的搜索、导航、工具栏和插件的UI.
  • 预览: 渲染你的故事的iframe.

十博体育备用网址需要跟踪切换状态 十博体育备用网址还需要在Manager和Preview中共享这个状态. 因此,而不是 useState 十博体育备用网址要用 use全局变量.

跟踪全局状态

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

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

/ / OutlineSelector.js

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

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

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

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

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

与故事设计者互动

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

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

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

/ / withOutline.js

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

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

/ / withOutline.js

import {usemo, useEffect} from '@storybook /插件';
import {clearStyles, addoutlinestyle} from './帮手”;
import {PARAM_KEY} from './常量”;
从'中导入outlineCSS./ 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, outlinestyle, 上下文 ..id]);

  返回StoryFn ();
};

好吧,这似乎是一个大跳跃. 让十博体育备用网址浏览一下所有的更改.

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

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

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

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

预设以启用所有故事的大纲

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

预设 允许你组合一堆不同的故事书配置,并一次性应用它们. 十博体育备用网址有两个配置,十博体育备用网址的预设负责:

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

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

从'导入{withOutline}../ withOutline”;
 
导出const decorators = [withOutline];

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

// .故事书/主要.js

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

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

结论

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

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

Storybook最受欢迎的特性都是作为插件实现的. 例如“文档”、“控件”、“操作”和“视图”. 本文只触及了可能实现的一些皮毛. 我很期待看到你的成果.

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

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


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

这篇文章对你有帮助吗?

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

4,428 开发人员和计数

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

加入故事书和彩色后面的团队. 构建被成千上万的开发人员用于生产的工具. Remote-first.

视图的工作

受欢迎的文章

UI测试的自动对焦

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