Storybook项目教程：组件命名与层级结构的最佳实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00820/article/details/148323294

Storybook项目教程：组件命名与层级结构的最佳实践

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

前言

在大型前端项目中，组件管理是一个重要课题。Storybook作为业界领先的UI组件开发环境，提供了强大的组件组织和展示能力。本文将深入探讨如何在Storybook中合理命名组件并构建清晰的层级结构，帮助开发者打造更易维护的组件库。

两种组织方式：隐式与显式

Storybook提供了两种主要的组件组织方式：

隐式组织：基于文件系统的物理位置自动生成侧边栏结构
显式组织：通过title参数显式定义组件在侧边栏中的位置

对于小型项目，隐式组织简单直接；而对于大型企业级项目，显式组织提供了更灵活的控制能力。

层级结构详解

一个完整的Storybook层级结构通常包含以下元素：

分类(Category)：顶层分组，如"UI组件"、"业务组件"等
文件夹(Folder)：中层组织单元，可按功能或模块划分
组件(Component)：基础单元，对应具体的React/Vue组件
文档(Docs)：自动生成的组件文档页面
故事(Story)：展示组件特定状态的用例

Storybook侧边栏层级结构示意图

命名规范实践

基础命名

通过title参数定义组件位置是最直接的方式：

export default {
  title: 'Button',
  component: Button,
};

分组命名

使用/作为分隔符可以创建嵌套分组：

// Button组件
export default {
  title: 'UI/Button',
  component: Button,
};

// Checkbox组件
export default {
  title: 'UI/Checkbox',
  component: Checkbox,
};

这种方式会创建一个可展开的"UI"分组，包含所有相关组件。

高级组织技巧

根节点处理

默认情况下，顶级分组会显示为"ROOT"。可以通过配置修改这一行为：

export const parameters = {
  options: {
    showRoots: false,
  },
};

单故事提升(Single-story Hoisting)

当组件只有一个故事且名称匹配时，Storybook会自动提升显示层级：

export default {
  title: 'UI/Button',
  component: Button,
};

export const ButtonStory = () => <Button />;

这将直接在UI中显示为"Button"，而非嵌套结构。

故事排序策略

Storybook默认按照导入顺序排列故事，但可以通过storySort参数自定义：

函数式排序

export const parameters = {
  options: {
    storySort: (a, b) =>
      a[1].kind === b[1].kind ? 0 : a[1].id.localeCompare(b[1].id),
  },
};

配置对象排序

export const parameters = {
  options: {
    storySort: {
      method: 'alphabetical',
      order: ['Intro', 'Components', '*', 'WIP'],
      locales: 'en-US',
    },
  },
};

支持多种排序方式：