Histoire 项目中的 Vue 3 组件变体(Variant)使用指南

Histoire 项目中的 Vue 3 组件变体(Variant)使用指南

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

什么是 Variant

在 Histoire 项目中，Variant（变体）是一个强大的功能，它允许开发者围绕同一个组件创建多个不同的子故事。通过在一个 Story 标签内使用多个 Variant 标签，可以轻松展示组件在不同状态或配置下的表现。

基本用法

Variant 的基本结构非常简单：

<template>
  <Story title="组件示例">
    <Variant title="默认状态">
      <!-- 组件内容 -->
    </Variant>
    <Variant title="特殊状态">
      <!-- 组件内容 -->
    </Variant>
  </Story>
</template>

Variant 的核心属性

1. title 属性

title 属性用于设置变体的显示名称，帮助用户快速识别不同的组件状态。

<Variant title="默认按钮">
  <Button>点击我</Button>
</Variant>
<Variant title="禁用状态">
  <Button disabled>禁用按钮</Button>
</Variant>

2. id 属性

id 属性用于设置变体的唯一标识符。如果不指定，系统会自动生成基于顺序的 ID。手动设置 ID 可以确保 URL 参数不会因变体顺序变化而改变。

<Variant id="primary-btn">
  <Button type="primary">主要按钮</Button>
</Variant>

3. initState 属性

initState 是一个返回初始状态的函数，非常适合用于需要状态管理的场景。

<script setup>
function initState() {
  return {
    count: 0,
    isLoading: false
  }
}
</script>

<template>
  <Variant :init-state="initState">
    <template #default="{ state }">
      <Counter :count="state.count" />
    </template>
  </Variant>
</template>

4. setupApp 属性

setupApp 函数允许你对 Vue 应用实例进行配置，非常适合需要提供全局配置或插件的场景。

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

高级功能

1. 自定义图标

通过 icon 和 iconColor 属性，可以为变体设置自定义图标和颜色。

<Variant icon="mdi:alert" iconColor="#FF0000">
  <Alert message="警告信息" />
</Variant>

2. 源代码控制

source 属性允许你指定变体的源代码，便于用户复制。

<script setup>
const btnSource = `<Button type="primary">主要按钮</Button>`
</script>

<Variant :source="btnSource">
  <Button type="primary">主要按钮</Button>
</Variant>

3. 响应式控制

responsiveDisabled 属性可以禁用响应式菜单和预览调整功能。

<Variant responsive-disabled>
  <FixedSizeComponent />
</Variant>

插槽功能

1. 默认插槽

默认插槽用于渲染变体的主要内容，可以接收 state 参数。

<Variant>
  <template #default="{ state }">
    <div>当前计数: {{ state.count }}</div>
  </template>
</Variant>

2. 控制面板插槽

controls 插槽允许你自定义控制面板的内容。

<Variant>
  <template #controls="{ state }">
    <button @click="state.count++">增加计数</button>
  </template>
</Variant>

3. 源代码插槽

source 插槽允许你手动定义源代码内容。

<Variant>
  <template #source>
    <pre>
      <Button>自定义按钮</Button>
    </pre>
  </template>
</Variant>

最佳实践

1. 命名规范：为变体使用清晰、描述性的标题，便于团队成员理解
2. 状态管理：对于复杂组件，优先使用 initState 来管理状态
3. ID 设置：对于重要的变体，建议设置固定的 ID 以保证 URL 稳定性
4. 图标使用：合理使用图标可以提升 UI 的可读性和美观性
5. 源代码：为关键变体提供源代码，方便文档使用者参考

通过合理使用 Variant 功能，你可以创建出结构清晰、易于维护的组件文档，极大提升开发效率和团队协作体验。

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