create-vant-cli-app Vue 2 模板中的 DemoButton 示例组件：API 设计、模板占位符与生成原理

create-vant-cli-app Vue 2 模板中的 DemoButton 示例组件：API 设计、模板占位符与生成原理

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant

导读

本文聚焦于create-vant-cli-app脚手架 Vue 2 生成模板中内置的DemoButton示例按钮组件（即 demo-button/README.md 所描述的内容）。通过阅读本文，你将完整掌握该示例组件的 Props / Events / Slots 三张 API 表格、对应的.vue源码实现、配套的演示与快照测试，以及<%= name %>、<%= cssLang %>等模板占位符在van-cli项目生成过程中的替换原理，从而理解"一个规范的 van-cli 组件应该长什么样"。

DemoButton 在脚手架模板中的角色

create-vant-cli-app是用于快速初始化基于 vant-cli 的组件库项目的脚手架工具（入口见 src/index.ts）。它在generators/vue2与generators/vue3下各维护一套生成模板，其中src/demo-button就是 Vue 2 模板里唯一的内置示例组件，承担两个职责：

• 目录结构样板：向新项目作者展示 van-cli 组件目录的标准组织方式（组件源码、demo、test 三件套）；
• 文档与 API 规范样板：通过一份麻雀虽小五脏俱全的 README，示范 van-cli 组件文档的写法（介绍、引入、代码演示、Props / Events / Slots 表格）。

从模板的站点配置 vant.config.js 可以看到，DemoButton 被注册进站点导航的"基础组件"分组（path: 'demo-button'），与"开发指南"分组下的"介绍""快速上手"并列，说明生成站点后该组件会直接以文档页面形式呈现在组件库官网中。

组件的目录与文件结构

demo-button目录遵循 van-cli 组件规范，共 5 个文件（见 demo-button 目录）：

这一结构也是新组件库作者在添加自有组件时应复刻的标准范式。

API 解析：Props、Events 与 Slots

原文档用三张表格完整定义了 DemoButton 的对外接口，下面逐一对照源码 index.vue 展开说明。

Props

color上的1.0.0标记表明该属性自组件1.0.0版本起可用，这是 van-cli 文档中标注属性引入版本的约定写法。源码中的定义与文档严格对应：

props: { color: String, type: { type: String, default: 'primary', }, },

需要指出的是：在当前模板源码中type与color仅作为声明存在，尚未在模板或样式中消费（.demo-button的样式固定为红色背景#f44），因此这两个属性是"预留的 API 面"，供模板使用者在此基础上扩展按钮类型与颜色的实际渲染逻辑——例如为type增加success/warning等枚举取值并映射到不同背景色。

Events

click事件由组件根元素<button>的原生点击冒泡透传获得，组件本身未显式$emit，因此回调参数即原生MouseEvent对象。

Slots

默认插槽用于承载按钮文字或自定义内容，源码中对应<slot />一行实现，与模板结构一致：

<template> <button class="demo-button"> <slot /> </button> </template>

组件整体命名遵循 van-cli 约定：name: 'DemoButton'，根类名demo-button，样式使用lang="<%= cssLang %>"声明预处理语言（生成时按用户选择替换为scss或less）。

代码演示与站点渲染

演示文件 demo/index.vue 展示了两个用例：

<demo-section> <demo-block title="基础用法"> <demo-button type="primary" style="margin-left: 15px">按钮</demo-button> </demo-block> <demo-block title="自定义颜色"> <demo-button color="#03a9f4" style="margin-left: 15px">按钮</demo-button> </demo-block> </demo-section>

这里用到了 vant-cli 站点内置的两个演示容器组件：

• demo-section：整个演示区块的容器；
• demo-block：带标题的演示分组，title属性即文档 README 中### 基础用法等小节的演示标题。

第二个用例恰好演示了color属性的传入姿势（color="#03a9f4"），尽管当前模板样式尚未消费该值，但作为使用范例已具备完整的语义示范。

模板占位符与项目生成原理

README 中出现的import { DemoButton } from '<%= name %>';并非普通字符串，而是脚手架的模板占位符。其替换逻辑位于生成器 generator.ts：

Object.keys(args).forEach((key) => { const regexp = new RegExp(`<%= ${key} %>`, 'g'); content = content.replace(regexp, args[key]); });

生成流程为：van-generator将generators/vue2下所有文件（含本 README、index.vue、vant.config.js、package.json.tpl等）整体复制到目标目录（fs.copySync），再对每个文件内容执行<%= key %>的全局替换，最后删除.tpl后缀。传入的替换参数由用户交互决定：

• name：用户在 index.ts 中输入的包名；
• vueVersion：Vue 2 / Vue 3 二选一；
• preprocessor/cssLang：Sass / Less 二选一，其中cssLang在 Sass 时取scss（见prompting()方法）。

因此，用包名my-ui生成项目后，README 中的引入代码会自动变成import { DemoButton } from 'my-ui';，而index.vue中的样式语言声明则变成lang="scss"或lang="less"。生成结束后，脚手架会提示运行cd my-ui && git init && yarn && yarn dev启动开发，其中vant-cli dev负责编译并预览文档站点。

单元测试与快照

测试文件 index.spec.js 使用@vue/test-utils对组件做挂载快照测试：

import { mount } from '@vue/test-utils'; import DemoButton from '../../demo-button'; test('render demo button', () => { const wrapper = mount(DemoButton); expect(wrapper).toMatchSnapshot(); });

对应的快照 index.spec.js.snap 内容为：

exports[`render demo button 1`] = `<button class="demo-button"></button>`;

该用例验证了无插槽内容时组件渲染出带demo-button类名的原生<button>元素，是 van-cli 模板中"最小可用测试"的示例：仅验证核心渲染结果，不引入不必要的断言复杂度。读者可在此基础上按同样模式为type、color、插槽内容等行为补充针对性用例。

总结

DemoButton虽是一个示例组件，却完整承载了 van-cli 组件开发的全部规范要素：三张 API 文档表格、声明式 Props 定义、默认插槽、demo-section/demo-block驱动的演示页、快照测试，以及与生成器深度绑定的<%= name %>、<%= cssLang %>占位符机制。理解这一模板，等于掌握了在 vue2 生成模板基础上落地首个真实业务组件的最小闭环：复制demo-button目录 → 替换组件名与文档表格 → 在 vant.config.js 的site.nav中注册 → 运行yarn dev即可在站点中预览新组件的文档与演示。

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant