Histoire 项目中 Vue3 组件的可控故事模式详解

原创于 2025-06-11 09:16:31 发布 · 303 阅读

CC 4.0 BY-SA版权

Histoire 项目中 Vue3 组件的可控故事模式详解

前言

在现代前端开发中，组件开发与测试工具扮演着越来越重要的角色。Histoire 作为一个优秀的组件开发环境，提供了强大的故事(Story)功能，特别是其可控故事(Controlled Stories)模式，能够帮助开发者更高效地构建和测试组件。本文将深入探讨 Histoire 中 Vue3 组件的四种可控故事实现方式。

什么是可控故事

可控故事是指开发者可以为组件故事添加交互式控制面板，通过调整控制项来动态改变组件属性或状态，从而实时观察组件在不同参数下的表现。这种模式极大提升了组件开发的效率和体验。

基础实现方式

1. 单一控制模式

这是最基本的可控故事实现方式，适用于单个组件实例的场景：

<script lang="ts" setup>
import { reactive } from 'vue'
import MyComponent from './MyComponent.vue'

const state = reactive({
  text: 'Hello world'
})
</script>

<template>
  <Story title="我的故事">
    <MyComponent :argument="state.text" />
    <template #controls>
      <HstText v-model="state.text" title="内容" />
    </template>
  </Story>
</template>

技术要点：

使用 Vue 的 reactive 创建响应式状态对象
#controls 插槽用于定义控制面板
HstText 是 Histoire 提供的文本输入控件

适用场景：

单个组件实例的调试
不需要多状态对比的简单场景

进阶实现方式

2. 全局变体控制模式

当需要同时控制多个变体(Variant)时，可以使用全局控制模式：

<script lang="ts" setup>
import { reactive } from 'vue'
import MyComponent from './MyComponent.vue'

const state = reactive({
  text: 'Hello world'
})
</script>

<template>
  <Story title="我的故事">
    <Variant title="红色变体">
      <MyComponent :argument="state.text" color="red" />
    </Variant>
    <Variant title="蓝色变体">
      <MyComponent :argument="state.text" color="blue" />
    </Variant>
    <template #controls>
      <HstText v-model="state.text" title="内容" />
    </template>
  </Story>
</template>

技术要点：

控制面板定义在 Story 级别
所有变体共享同一状态对象
修改控制项会影响所有变体

适用场景：

需要同时观察多个变体在相同参数下的表现
对比不同变体在相同输入下的差异

3. 特定变体控制模式

当需要对不同变体进行独立控制时：

<script lang="ts" setup>
import { reactive } from 'vue'
import MyComponent from './MyComponent.vue'

const state = reactive({
  text: 'Hello world'
})
</script>

<template>
  <Story title="我的故事">
    <Variant title="红色变体">
      <MyComponent :argument="state.text" color="red" />
      <template #controls>
        <HstText v-model="state.text" title="内容" />
      </template>
    </Variant>
    <Variant title="蓝色变体">
      <MyComponent argument="hello" color="blue" />
    </Variant>
  </Story>
</template>

技术要点：

控制面板定义在 Variant 级别
每个变体可以有自己的控制逻辑
未定义控制的变体将没有控制面板

适用场景：

不同变体需要不同的控制逻辑
只需要对特定变体进行控制

4. 隔离变体控制模式

最灵活的实现方式，每个变体完全独立：

<script lang="ts" setup>
import MyComponent from './MyComponent.vue'

function initState() {
  return {
    text: 'Hello world'
  }
}
</script>

<template>
  <Story title="我的故事">
    <Variant
      title="红色变体"
      :init-state="initState"
    >
      <template #default="{ state }">
        <MyComponent :argument="state.text" color="red" />
      </template>
      <template #controls="{ state }">
        <HstText v-model="state.text" title="内容" />
      </template>
    </Variant>
    <Variant
      title="蓝色变体"
      :init-state="initState"
    >
      <template #default="{ state }">
        <MyComponent :argument="state.text" color="blue" />
      </template>
      <template #controls="{ state }">
        <HstText v-model="state.text" title="内容" />
      </template>
    </Variant>
  </Story>
</template>

技术要点：

使用 initState 函数初始化每个变体的状态
状态完全隔离，互不影响
通过作用域插槽访问变体状态

适用场景：

需要完全隔离的变体控制
复杂组件的高级调试需求
需要保存每个变体的独立状态

技术对比与选型建议

| 模式类型 | 状态共享 | 控制范围 | 复杂度 | 适用场景 | |---------|---------|---------|--------|----------| | 单一控制 | 单一状态 | 全局 | 低 | 简单组件测试 | | 全局变体控制 | 共享状态 | 全局 | 中 | 多状态对比测试 | | 特定变体控制 | 可选共享 | 变体级 | 中 | 差异化控制需求 | | 隔离变体控制 | 完全隔离 | 变体级 | 高 | 复杂场景调试 |

选型建议：