构建你自己的 Block

这份指南教你如何从 Base Kit 组件沉淀一个可本地维护、可安装、可贡献的业务区块（block）。示例使用匿名的筛选区块，不包含真实 API、凭证、私有 URL 或内部需求编号。

当前可安装 Blocks

REGISTRY BLOCKS

先看界面，再生成源码

每张卡片都来自真实小程序 Block：Headless 负责状态与交互，Base Kit 负责视觉。确认界面后，复制一条命令即可生成源码和递归依赖。

13 BLOCKS

搜索

显示 13 个 Block预览图为 Weapp 实际运行界面

WeappH5

login-form

登录表单

business

手机号、密码、记住状态、错误与加载反馈。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/login-form

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/login-form.vue

<script setup lang="ts">
import LoginForm from '@/components/blocks/login-form.vue'

function handleLogin(credentials: unknown) {
  console.log(credentials)
}
</script>

<template>
  <LoginForm @submit="handleLogin" />
</template>

WeappH5

profile-card

用户资料卡

business

头像、身份状态、统计信息与编辑动作。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/profile-card

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/profile-card.vue

<script setup lang="ts">
import ProfileCard from '@/components/blocks/profile-card.vue'

const user = { name: 'Varo User', status: 'Active' }
const stats = [{ label: 'Orders', value: 12 }]
function openEditor() {}
</script>

<template>
  <ProfileCard :user="user" :stats="stats" @edit="openEditor" />
</template>

WeappH5

profile-edit

资料编辑

business

姓名、手机号、城市搜索、简介与提交状态。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/profile-edit

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/profile-edit.vue

<script setup lang="ts">
import ProfileEdit from '@/components/blocks/profile-edit.vue'

const cities = [{ label: '杭州', value: 'hangzhou' }]
function saveProfile(profile: unknown) {
  console.log(profile)
}
</script>

<template>
  <ProfileEdit :cities="cities" @submit="saveProfile" />
</template>

WeappH5

product-list

商品列表

business

商品、库存、价格、空状态、选择与加购动作。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/product-list

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/product-list.vue

<script setup lang="ts">
import ProductList from '@/components/blocks/product-list.vue'

const products = []
function addToCart(payload: unknown) {
  console.log(payload)
}
</script>

<template>
  <ProductList :items="products" @add-to-cart="addToCart" />
</template>

WeappH5

order-filter

订单筛选

business

多状态选择、金额区间校验、重置与应用事件。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/order-filter

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/order-filter.vue

<script setup lang="ts">
import OrderFilter from '@/components/blocks/order-filter.vue'

function loadOrders(filters: unknown) {
  console.log(filters)
}
</script>

<template>
  <OrderFilter :result-count="128" @apply="loadOrders" />
</template>

WeappH5

agent-chat

Agent 对话

agent

增量 Markdown、工具状态、审批与输入组合。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/agent-chat

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/agent-chat.vue

<script setup lang="ts">
import AgentChat from '@/components/blocks/agent-chat.vue'

const messages = [{ id: 'welcome', role: 'assistant', content: '你好' }]
function runAgent(prompt: string) {
  console.log(prompt)
}
</script>

<template>
  <AgentChat :messages="messages" @submit="runAgent" />
</template>

Weapp

retail-home

零售首页

retail

搜索、分类、精选商品与购物车入口。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-home

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-home.vue

<script setup lang="ts">
import RetailHome from '@/components/blocks/retail-home.vue'

const categories = []
const products = []
</script>

<template>
  <RetailHome :categories="categories" :products="products" />
</template>

Weapp

retail-category

零售分类

retail

双栏分类导航、商品网格与加购动作。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-category

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-category.vue

<script setup lang="ts">
import { shallowRef } from 'wevu'
import RetailCategory from '@/components/blocks/retail-category.vue'

const activeId = shallowRef('women')
const categories = []
const products = []
</script>

<template>
  <RetailCategory v-model:active-id="activeId" :categories="categories" :products="products" />
</template>

Weapp

retail-cart

购物车

retail

商品选择、数量、合计、空状态与结算。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-cart

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-cart.vue

<script setup lang="ts">
import RetailCart from '@/components/blocks/retail-cart.vue'

const cartItems = []
const total = 0
function checkout() {}
</script>

<template>
  <RetailCart :items="cartItems" :total="total" @checkout="checkout" />
</template>

Weapp

retail-product-detail

商品详情

retail

商品主图、价格、库存、数量、加购与购买。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-product-detail

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-product-detail.vue

<script setup lang="ts">
import { shallowRef } from 'wevu'
import RetailProductDetail from '@/components/blocks/retail-product-detail.vue'

const quantity = shallowRef(1)
const product = {}
</script>

<template>
  <RetailProductDetail v-model:quantity="quantity" :product="product" />
</template>

Weapp

retail-checkout

结算确认

retail

地址、商品、优惠、发票、金额与提交订单。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-checkout

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-checkout.vue

<script setup lang="ts">
import RetailCheckout from '@/components/blocks/retail-checkout.vue'

const address = {}
const items = []
const total = 0
function submitOrder() {}
</script>

<template>
  <RetailCheckout :address="address" :items="items" :total="total" @submit="submitOrder" />
</template>

Weapp

retail-order-list

订单列表

retail

订单状态、商品摘要与履约操作。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-order-list

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-order-list.vue

<script setup lang="ts">
import RetailOrderList from '@/components/blocks/retail-order-list.vue'

const orders = []
function handleOrder(order: unknown) {
  console.log(order)
}
</script>

<template>
  <RetailOrderList :orders="orders" @action="handleOrder" />
</template>

Weapp

retail-profile

会员中心

retail

会员信息、订单、地址、优惠券与售后入口。

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-profile

查看代码与使用方法展开

一键生成在项目根目录执行，CLI 会递归写入 Block 与所需组件源码。

使用示例src/components/blocks/retail-profile.vue

<script setup lang="ts">
import RetailProfile from '@/components/blocks/retail-profile.vue'

const orderCounts = {}
</script>

<template>
  <RetailProfile name="Varo User" :points="2680" :order-counts="orderCounts" />
</template>

1. 先分清分层

层	负责	不负责
Primitives	状态、事件、parts、跨端交互语义	视觉 token、业务文案
Base Kit / UI	可复制的低层组件源码与默认样式	远程数据、权限、领域模型
业务 wrapper	接口、权限、字段映射、产品文案	通用交互状态机
Blocks	可复用页面切片与本地组合	私有后端细节、一次性页面胶水

经验法则：block 应该像“可搬运的页面切片”，不是“绑死某业务接口的页面”。

2. 定义 block 契约

在写代码前先写清合同：

// 示例：本地筛选 block 的契约
export interface StatusOption {
  label: string
  value: string
  disabled?: boolean
}

export interface FilterBarProps {
  /** 可选状态列表，由业务层注入 */
  options: StatusOption[]
  /** 受控选中值 */
  modelValue?: string[]
  /** 是否禁用 */
  disabled?: boolean
}

export interface FilterBarEmits {
  (e: 'update:modelValue', value: string[]): void
  (e: 'change', value: string[]): void
}

契约里要写明：

• 输入：options、默认值、disabled
• 输出：update:modelValue / change
• 本地状态：仅 UI 需要的临时状态
• 依赖：Base Kit 组件名（如 select）
• 排除项：远程字典、鉴权、埋点 SDK、私有域名

3. 选择 Base Kit 依赖

优先依赖业务项目中的：

src/components/ui/*

而不是在 block 里直接 import registry 源码路径。远程数据和产品策略放在业务 wrapper，不放进 block。

安装底座组件：

pnpm dlx @varo-ui/cli add --target weapp components/select

4. 创建本地 block

建议路径：

src/components/blocks/status-filter.vue

最小实现示例：

<script setup lang="ts">
import { computed } from 'vue'
import { VSelect } from '../ui/select'

export interface StatusOption {
  label: string
  value: string
  disabled?: boolean
}

const props = withDefaults(
  defineProps<{
    options: StatusOption[]
    modelValue?: string[]
    disabled?: boolean
    placeholder?: string
  }>(),
  {
    modelValue: () => [],
    disabled: false,
    placeholder: '选择状态'
  }
)

const emit = defineEmits<{
  'update:modelValue': [value: string[]]
  'change': [value: string[]]
}>()

const value = computed({
  get: () => props.modelValue,
  set: (next) => {
    const normalized = next ?? []
    emit('update:modelValue', normalized)
    emit('change', normalized)
  }
})
</script>

<template>
  <section class="status-filter">
    <header class="status-filter__head">
      <strong>状态筛选</strong>
      <span>{{ value.length }} 项</span>
    </header>
    <VSelect
      v-model:value="value"
      multiple
      :disabled="disabled"
      :options="options"
      :placeholder="placeholder"
    />
  </section>
</template>

要求：

• props / emits 类型完整
• 布局小而可读
• 不写死业务接口

5. 测试 block

至少覆盖：

• 初始渲染
• 用户选择后的 emit 值
• disabled 行为
• 依赖边界（不请求网络、不读私有环境变量）

import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import StatusFilter from '../status-filter.vue'

describe('StatusFilter', () => {
  it('emits selected statuses', async () => {
    const wrapper = mount(StatusFilter, {
      props: {
        options: [
          { label: '待支付', value: 'pending' },
          { label: '已完成', value: 'done' }
        ],
        modelValue: []
      }
    })

    await wrapper.setProps({ modelValue: ['pending'] })
    expect(wrapper.props('modelValue')).toEqual(['pending'])
  })
})

6. 本地使用与维护

<script setup lang="ts">
import { ref } from 'vue'
import StatusFilter from '@/components/blocks/status-filter.vue'

const statuses = ref<string[]>([])
const options = [
  { label: '待支付', value: 'pending' },
  { label: '已完成', value: 'done' }
]
</script>

<template>
  <StatusFilter v-model="statuses" :options="options" />
</template>

复制进业务仓库的源码归业务团队所有，可以继续改布局、token 和交互，不必回灌到 Varo。

7. 准备 registry 元数据

若要让别人通过 CLI 安装，新增：

registry/blocks/status-filter/registry.json
registry/blocks/status-filter/status-filter.vue

registry.json 示例：

{
  "name": "status-filter",
  "type": "block",
  "title": "Status Filter",
  "description": "A local filter bar for selecting multiple anonymized statuses with VSelect.",
  "targets": ["weapp"],
  "dependencies": ["vue"],
  "registryDependencies": ["components/select"],
  "files": [
    {
      "target": "weapp",
      "from": "registry/blocks/status-filter/status-filter.vue",
      "to": "src/components/blocks/status-filter.vue"
    }
  ],
  "docs": "/blocks/status-filter"
}

字段要点：

• type：block
• targets：如 weapp
• registryDependencies：递归安装的底座组件
• files：from/to 映射
• docs：文档路由

8. 补充双语文档

每个公开 block 至少说明：

• 用途
• 依赖
• target
• 安装后的文件落点
• 可定制边界 / 不可放入的业务逻辑

现有示例：

• Profile Edit
• Order Filter

9. 校验安装

建议清单：

# 类型与测试
pnpm typecheck
pnpm test

# 打包 CLI 后在临时目录验证安装
pnpm --filter @varo-ui/cli build
pnpm dlx @varo-ui/cli add --target weapp blocks/status-filter

确认：

• 依赖组件会递归安装
• 目标文件已存在时默认不覆盖（no-clobber）
• 需要覆盖时使用显式 force 流程
• 安装结果不带私有域名、token、内部任务号

10. 贡献回 Varo

提交前过一遍隐私与可移植清单：

• 无真实 API / 凭证 / 私有 URL
• 无内部需求号、工单号、客户名
• 依赖写在 registryDependencies，拼写正确
• 中英文档齐全
• 单测覆盖主路径
• packed CLI 安装通过

贡献物通常包括：源码、registry.json、测试、双语文档。

故障排查

现象	处理
依赖没装上	检查 registryDependencies 拼写，如 components/select
目标文件冲突	确认 to 路径；默认 no-clobber，覆盖需显式 force
block 难复用	把远程数据/权限/埋点移到业务 wrapper
小程序不可用	删除 H5-only API，保持双端契约
单测过但安装失败	用 packed CLI + 临时 fixture 复现，检查 files 映射

安装现有 block

pnpm dlx @varo-ui/cli add --target weapp blocks/profile-edit
pnpm dlx @varo-ui/cli add --target weapp blocks/order-filter

安装后：

src/components/ui/*        # 底座组件源码
src/components/blocks/*    # block 源码
src/components/biz/*       # 建议放置业务二次封装

相关文档

• shadcn 模式
• 安装指南
• Primitives 总览
• 组件文档