@zeldafox/blocks

@zeldafox/blocks

企业落地页区块组件库 · Vue 3 + TailwindCSS 4 + TypeScript 一个组件 = 一个对象 = 一个区块。零配置，五分钟搭好企业落地页。

特性

环境要求

• Vue >= 3.4（peerDependency）
• 无需安装 Tailwind：样式已预编译为 dist/style.css，直接引入即可

安装

pnpm add @zeldafox/blocks
npx @zeldafox/blocks init

init 会检测项目类型（Vite / Nuxt），改写 vite.config.ts 并在 src/main.ts 顶部引入样式。 命令幂等，重复执行不会重复写入。详见下方 CLI 初始化。

也可用 npm / yarn / pnpm dlx 调用：

npm i @zeldafox/blocks && npx @zeldafox/blocks init
pnpm dlx @zeldafox/blocks init

快速上手

<script setup lang="ts">
import type { HeroData, FeaturesData } from '@zeldafox/blocks'

const hero: HeroData = {
  title: '让每个想法都发光',
  description: '五分钟搭好企业落地页。',
  actions: [
    { text: '免费开始', link: '/signup' },
    { text: '查看文档', link: '/docs' },
  ],
  image: { src: '/hero.png', alt: '产品截图' },
}

const features: FeaturesData = {
  title: '核心能力',
  columns: 4,
  items: [
    { icon: '⚡', title: '极速', description: '零配置，开箱即用' },
    { icon: '🎨', title: '统一', description: '一致的设计语言' },
  ],
}
</script>

<template>
  <Navbar :data="navbar" />
  <Hero :data="hero" />
  <Features :data="features" />
  <Footer :data="footer" />
</template>

组件名即文件名，无需 import；XxxData 是类型，需要显式 import type。

四种接入方式

CLI 初始化

在项目根目录执行，按顺序完成三步：

1. 检测项目类型 —— 查找 vite.config.ts|js 或 nuxt.config.ts|js
2. 改写 Vite 配置 —— 插入 Components 插件与 ChatflowBlocksResolver
3. 引入样式 —— 在 src/main.ts|js 顶部加入 import '@zeldafox/blocks/style.css'

  import { defineConfig } from 'vite'
  import vue from '@vitejs/plugin-vue'
+ import Components from 'unplugin-vue-components/vite'
+ import { ChatflowBlocksResolver } from '@zeldafox/blocks/resolver'

  export default defineConfig({
-   plugins: [vue()],
+   plugins: [
+     vue(),
+     Components({ resolvers: [ChatflowBlocksResolver()] }),
+   ],
  })

CLI 做的是字符串插入，建议执行前先提交一次 Git，方便 diff 与回滚。

自动导入

pnpm add -D unplugin-vue-components

// vite.config.ts
import Components from 'unplugin-vue-components/vite'
import { ChatflowBlocksResolver } from '@zeldafox/blocks/resolver'

export default defineConfig({
  plugins: [vue(), Components({ resolvers: [ChatflowBlocksResolver()] })],
})

可用选项：

resolver 只匹配内置的 30 个组件名，其余名称放行给其他 resolver，可与 Element Plus 等共存。 Webpack 用 unplugin-vue-components/webpack，Nuxt 配到 nuxt.config.ts 的 vite.plugins。

手动引入 / 全量注册

// 手动引入
import { Hero, Features } from '@zeldafox/blocks'
import '@zeldafox/blocks/style.css'

// 全量注册
import { createApp } from 'vue'
import ChatflowBlocks from '@zeldafox/blocks'
import '@zeldafox/blocks/style.css'

createApp(App).use(ChatflowBlocks).mount('#app')

组件清单（30 个）

布局 & 导航

Hero 类

内容区块

团队 & 客户

图文组合

列表类

表格 & 定价

表单 & 互动

典型落地页的区块顺序：

Banner → Navbar → Hero → Features → Stats → ImageText
→ Testimonials → Pricing → ComparisonTable → FAQ → CTA → ContactForm → Footer

内页推荐：Navbar → Breadcrumb → PageHeader（或 NewsDetail / ProductDetail）→ Footer

数据契约

五个跨组件复用的类型，学会一次，30 个组件通用：

默认值约定

组件内部用 { ...默认值, ...props.data } 合并（即导出的 useMergedData），因此只传要改的字段即可：

const hero: HeroData = { title: '你好' } // 其余字段走内置默认值

自己封装区块时可直接复用：

const d = useMergedData(props.data, { variant: 'default', align: 'center' })

一个完整区块示例

import type { NavbarData } from '@zeldafox/blocks'

const navbar: NavbarData = {
  brand: 'Acme',
  logo: { src: '/logo.svg', alt: 'Acme' },
  links: [
    { text: '产品', link: '/products' },
    {
      text: '解决方案',
      children: [
        { text: '电商', link: '/solutions/ecommerce' },
        { text: '教育', link: '/solutions/education' },
      ],
      menuWidth: 'w-64',
    },
  ],
  actions: [{ text: '免费试用', link: '/signup' }],
}

主题定制

视觉变量全部通过 CSS 变量暴露，在组件库样式之后覆盖即可：

:root {
  --cf-primary: #0ea5e9;
  --cf-primary-hover: #0284c7;
  --cf-primary-light: #eef2ff;

  --cf-radius: 1rem;
  --cf-radius-sm: 0.5rem;
  --cf-radius-lg: 1.5rem;

  --cf-shadow: 0 10px 40px -10px rgb(0 0 0 / 0.1);
}

.dark {
  --cf-primary-light: #0c2340;
}

每个区块的 data 还支持 class 字段，可追加 Tailwind 类名做局部调整：

const hero: HeroData = { title: 'Hello', class: 'py-32' }

区块风格（variant × tone）

全局品牌变量之上还有一层区块皮肤：数据结构不变，只改一个字段即可切换整套外观。

const hero: HeroData = {
  variant: 'centered', // 结构：centered / split / background
  tone: 'classic', // 皮肤：classic / brutal / amber
  title: '<mark>企业级即时通讯</mark><br>让协作更快一步',
  actions: [{ text: '开始免费使用', link: '/signup' }],
}

const heroBrutal: HeroData = { ...hero, tone: 'brutal' } // 复用同一份数据

variant 决定 DOM 骨架，tone 只切换一组 --cf-{组件}-* 变量，两者正交。 想自定义皮肤，覆盖对应变量即可，不需要改组件：

[data-cf-tone='brutal'] {
  --cf-hero-bg: #0b1120;
  --cf-hero-btn-primary-bg: #f97316;
  --cf-hero-btn-primary-shadow: 6px 6px 0 #0ea5e9;
}

详见 区块风格指南。

深色模式

组件用 TailwindCSS 4 的 dark: 前缀配合 class 策略实现，切换 <html class="dark"> 即全量生效。

<script setup lang="ts">
import { useTheme } from '@zeldafox/blocks'

const { isDark, toggleDark } = useTheme()
</script>

<template>
  <button @click="toggleDark()">{{ isDark ? '切换浅色' : '切换深色' }}</button>
</template>

useTheme 基于 @vueuse/core 的 useDark，状态持久化在 localStorage，默认 key 为 chatflow-theme，可通过 useTheme({ storageKey: 'my-theme' }) 修改。

避免首屏闪烁，在 <head> 里同步执行：

<script>
  const saved = localStorage.getItem('chatflow-theme')
  const dark =
    saved === 'true' ||
    (!saved && window.matchMedia('(prefers-color-scheme: dark)').matches)
  document.documentElement.classList.toggle('dark', dark)
</script>

导出

import { Hero, useTheme, cn } from '@zeldafox/blocks'
import type { HeroData, BlockAction } from '@zeldafox/blocks'
import ChatflowBlocks from '@zeldafox/blocks' // 默认导出：Vue 插件
import { ChatflowBlocksResolver } from '@zeldafox/blocks/resolver'

常见问题

样式没生效？ 确认 @zeldafox/blocks/style.css 已被引入（CLI 会自动写入 src/main.ts）。 若 resolver 设为 importStyle: false，需要自己全局引入一次。

模板报 "Failed to resolve component"？ resolver 只匹配 30 个内置名称，检查是否拼错；若用了 prefix，模板里要带前缀（如 <CfHero>）。

Nuxt 项目能用吗？ 能。init 检测到 Nuxt 会提示手动配置，把 Components({ resolvers: [ChatflowBlocksResolver()] }) 配到 nuxt.config.ts 的 vite.plugins 即可。

同页能放两个 Hero 吗？ 不建议。Hero / HeroBackground / PageHeader / NewsDetail / ProductDetail 都会渲染 <h1>，一页应只保留一个。

组件数据能来自后端吗？ 可以。data 是纯 JSON 结构，直接把接口返回的对象塞进去即可，配合 useMergedData 可合并默认值。

相关链接

• npm：@zeldafox/blocks
• 文档站：https://wumacms.github.io/chatflow-blocks/
• 仓库：https://github.com/wumacms/chatflow-blocks

许可

MIT