Histoire 项目中的 Vue3 故事文件编写指南

Histoire 项目中的 Vue3 故事文件编写指南

histoire ⚡ Fast and beautiful interactive component playgrounds, powered by Vite 项目地址: https://gitcode.com/gh_mirrors/hi/histoire

前言

在 Vue3 生态系统中，Histoire 是一个强大的组件开发和测试工具。本文将详细介绍如何在 Histoire 项目中编写 Vue3 故事文件，帮助开发者更好地组织和展示组件。

故事文件基础结构

每个 Vue3 故事文件必须包含一个顶级 <Story> 组件，这是 Histoire 的核心概念。基础结构如下：

<template>
  <Story>
    <!-- 你的组件内容 -->
  </Story>
</template>

故事属性详解

1. 标题设置 (title)

title 属性用于定义故事的显示名称，便于在导航中识别：

<template>
  <Story title="按钮组件示例">
    <MyButton />
  </Story>
</template>

2. 唯一标识符 (id)

默认情况下，Histoire 会根据文件路径自动生成 ID，但你可以手动指定以确保 URL 稳定性：

<template>
  <Story id="unique-button-demo">
    <MyButton />
  </Story>
</template>

3. 布局控制 (layout)

layout 属性提供了强大的布局控制能力：

<template>
  <Story :layout="{ type: 'grid', width: '50%' }">
    <!-- 内容将以网格布局显示，宽度为50% -->
  </Story>
</template>

支持两种布局类型：

• single: 单一样式布局，可配置 iframe 隔离
• grid: 网格布局，可定义列宽

4. 初始状态 (initState)

通过 initState 函数可以定义组件的初始状态：

<script setup>
function initState() {
  return {
    buttonText: '点击我',
    disabled: false,
    size: 'medium'
  }
}
</script>

<template>
  <Story :init-state="initState">
    <template #default="{ state }">
      <MyButton 
        :disabled="state.disabled"
        :size="state.size"
      >
        {{ state.buttonText }}
      </MyButton>
    </template>
  </Story>
</template>

5. 应用配置 (setupApp)

setupApp 允许你在故事级别配置 Vue 应用：

<script setup>
function setupApp({ app }) {
  // 注册全局组件或插件
  app.component('GlobalComponent', MyComponent)
}
</script>

<template>
  <Story :setup-app="setupApp">
    <!-- 可以使用GlobalComponent -->
  </Story>
</template>

高级功能

故事分组 (group)

将相关故事组织在一起：

<template>
  <Story group="表单组件">
    <MyForm />
  </Story>
</template>

自定义图标 (icon & iconColor)

使用 Iconify 图标库自定义故事图标：

<template>
  <Story icon="mdi:button" icon-color="#4CAF50">
    <MyButton />
  </Story>
</template>

纯文档模式 (docsOnly)

创建仅包含文档的页面：

<template>
  <Story docs-only>
    <docs lang="md">
    # 组件使用指南
    
    这里是详细的组件使用说明...
    </docs>
  </Story>
</template>

源代码控制 (source)

自定义显示的源代码：

<script setup>
const demoCode = `
<MyButton 
  type="primary"
  @click="handleClick"
/>
`
</script>

<template>
  <Story :source="demoCode">
    <MyButton type="primary" />
  </Story>
</template>

交互控制

控制面板 (controls slot)

创建交互式控制面板：

<template>
  <Story>
    <template #controls="{ state }">
      <input v-model="state.buttonText" />
      <select v-model="state.size">
        <option>small</option>
        <option>medium</option>
        <option>large</option>
      </select>
    </template>
    
    <template #default="{ state }">
      <MyButton :size="state.size">
        {{ state.buttonText }}
      </MyButton>
    </template>
  </Story>
</template>

禁用自动属性检测 (autoPropsDisabled)

<template>
  <Story auto-props-disabled>
    <!-- 不会自动检测组件属性 -->
  </Story>
</template>

响应式控制

<template>
  <Story responsive-disabled>
    <!-- 禁用响应式调整功能 -->
  </Story>
</template>

最佳实践建议

1. 命名规范：使用有意义的 title 和 id，便于团队协作
2. 状态管理：合理使用 initState 管理组件状态
3. 文档优先：为重要组件添加详细的文档说明
4. 分组组织：使用 group 属性保持项目结构清晰
5. 交互设计：充分利用 controls 插槽创建丰富的交互体验

通过掌握这些技巧，你可以充分利用 Histoire 的功能，创建出结构清晰、易于维护的组件文档和测试环境。

histoire ⚡ Fast and beautiful interactive component playgrounds, powered by Vite 项目地址: https://gitcode.com/gh_mirrors/hi/histoire