简体中文
组件开发指南
约 2579 字大约 9 分钟
2026-06-25
快速上手
仓库地址
项目仓库：https://git.firstshare.cn/fs-hera/ava_ui.git
1. 创建组件目录结构
根据组件类型选择对应的目录创建组件：
基础组件（fxui）
在 package/fxui 目录下创建基础组件，例如 fs-button、fs-input、fs-avatar 等：
适用场景：
- 通用的UI基础组件（按钮、输入框、头像等）
- 无业务逻辑的纯展示组件
- 可复用的交互组件
- 组件库的核心组件
目录结构：
package/fxui/your-component/ # 基础组件目录
├── index.js # 组件逻辑
├── index.wxml # 组件模板
├── index.wxss # 组件样式
├── index.json # 组件配置
├── README.md # 组件文档
└── _example/ # 使用示例目录
├── index.js # 示例逻辑
├── index.wxml # 示例模板
├── index.wxss # 示例样式
└── index.json # 示例配置非基础组件（分包）
在 avaui-sub 目录下创建业务组件或复杂组件，例如 your-component：
适用场景：
- 包含业务逻辑的组件
- 复杂的复合组件
- 特定场景的专用组件
- 需要分包加载的大型组件
目录结构：
avaui-sub/
└── your-component/ # 组件目录
├── index.js # 组件逻辑
├── index.wxml # 组件模板
├── index.wxss # 组件样式
├── index.json # 组件配置
├── README.md # 组件文档
├── _example/ # 使用示例目录
│ ├── index.js # 示例逻辑
│ ├── index.wxml # 示例模板
│ ├── index.wxss # 示例样式
│ └── index.json # 示例配置
└── test/ # 测试用例组件类型选择指南
选择基础组件（fxui）的条件：
- ✅ 纯UI组件，无业务逻辑
- ✅ 高复用性，多个项目可使用
- ✅ 功能单一，职责明确
- ✅ 体积较小，不影响主包大小
- ✅ 符合设计规范的通用组件
示例： fs-button、fs-input、fs-avatar、fs-badge、fs-notice-bar
选择非基础组件（分包）的条件：
- ✅ 包含特定业务逻辑
- ✅ 组件体积较大，需要分包加载
- ✅ 依赖特定的业务数据或API
- ✅ 复合型组件，由多个基础组件组合
- ✅ 特定场景专用，复用性相对较低
示例： shop-product-card、order-status-tracker、payment-method-selector
2. 编写组件基础代码
2.1 组件配置 (index.json)
{
"component": true,
"usingComponents": {}
}2.2 组件逻辑 (index.js)
Component({
properties: {
// 组件对外属性
},
data: {
// 组件内部数据
},
methods: {
// 组件方法
}
})2.3 组件模板 (index.wxml)
<view class="your-component">
<!-- 组件模板 -->
</view>2.4 组件样式 (index.wxss)
.your-component {
/* 组件样式 */
}3. 创建示例代码
在 _example 目录下创建以下文件：
3.1 示例逻辑 (_example/index.js)
Page({
data: {
// 示例数据
},
methods: {
// 示例方法
}
})3.2 示例模板 (_example/index.wxml)
<view class="example">
<your-component prop1="value" bind:event="handler" />
</view>3.3 示例样式 (_example/index.wxss)
.example {
padding: 16px;
}4. 编写组件文档
创建 README.md 文件，参考以下结构：
---
title: Radio # 组件名称（必填）
description: 单选组件 # 组件描述（可选）
group: 数据录入 # 组件分组（必填），用于文档分类展示
---
## 简介
[详细说明组件的主要功能和适用场景]
## 使用方法
局部引入，在需要引入的页面或组件的`index.json`中配置。
**基础组件引用路径：**
\`\`\`json
"usingComponents": {
"fs-button": "ava-ui/fxui/fs-button/index",
"fs-avatar": "ava-ui/fxui/fs-avatar/index"
}
\`\`\`
**分包组件引用路径：**
\`\`\`json
"usingComponents": {
"your-component": "/avaui-sub/your-component/index"
}
\`\`\`
## 代码演示
### 基础用法
**基础组件示例：**
<RecoDemo :collapse="true">
<template slot="code-wxml">
<<< @/docs/src/fxui/[组件名]/_example/index.html
</template>
<template slot="code-js">
<<< @/docs/src/fxui/[组件名]/_example/index.js
</template>
<template slot="code-wxss">
<<< @/docs/src/fxui/[组件名]/_example/index.css
</template>
<template slot="code-json">
<<< @/docs/src/fxui/[组件名]/_example/index.json
</template>
</RecoDemo>
**分包组件示例：**
<RecoDemo :collapse="true">
<template slot="code-wxml">
<<< @/docs/src/avaui-sub/[组件名]/_example/index.html
</template>
<template slot="code-js">
<<< @/docs/src/avaui-sub/[组件名]/_example/index.js
</template>
<template slot="code-wxss">
<<< @/docs/src/avaui-sub/[组件名]/_example/index.css
</template>
<template slot="code-json">
<<< @/docs/src/avaui-sub/[组件名]/_example/index.json
</template>
</RecoDemo>
## API
### 参数
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|------|------|------|--------|--------|
| prop1 | 属性说明 | String | - | '' |
### Events
| 名称 | 参数 | 描述 |
|------|------|------|
| event | {value} | 事件描述 |
**基础组件预览：**
<PreviewPhone :path="`pages/fxui/[组件名]/index`" />
**分包组件预览：**
<PreviewPhone :path="`pages/avaui-sub/[组件名]/index`" />4.1 Front Matter 说明
组件文档必须包含 front matter，用于生成文档路由和分类：
title（必填）：组件名称
- 用于显示在文档导航中
- 例：
Radio、Button、DateTimePicker
description（可选）：组件描述
- 用于补充说明组件功能
- 会与 title 组合显示在文档导航中
- 例：
单选组件、按钮
group（必填）：组件分组
- 用于文档分类展示
- 常用分组：
- 基础
- 导航
- 数据录入
- 数据展示
- 状态反馈
生成的文档导航示例：
{
title: '数据录入',
children: [
['src/fxui/Radio/', "Radio 单选组件"], // title + description
['src/fxui/Actionsheet/', "Actionsheet"] // 仅 title
]
}5. 文档和Demo生成
完成以上步骤后，执行文档生成脚本(npm run copy-docs)，它会：
- 复制 README.md 到 site/docs/src 目录
- 复制并转换 _example 目录内容：
- 复制到 site/docs/src 时转换文件后缀
- 复制到 pages 目录时保持原始后缀
- 自动更新页面配置：
- 更新 app.json 添加页面路径
- 更新 pages/test/test.js 添加导航配置
- 把文档添加到合适的分组中：site/docs/.vuepress/routes.js
6. 开发检查清单
开发完成后，确保：
详细规范
1. 命名规范
1.1 命名规则
- 采用 kebab-case 命名方式（例：
image-previewer） - 业务组件需添加业务域前缀（例：
shop-product-card） - 基础组件使用 base- 前缀（例：
base-button）
1.2 命名禁忌
- 禁止使用保留字/关键字（如：switch, input 等）
- 禁止使用拼音缩写
- 禁止使用非业务相关数字编号
2. 组件设计原则
2.1 SOLID原则
- 单一职责：每个组件只解决一个问题
- 开放封闭：对扩展开放，对修改关闭
- 依赖倒置：通过 props/provide-inject 通信
2.2 可配置性
- 通过 props 控制组件行为
- 提供 slot 插槽扩展能力
- 支持 CSS 自定义属性样式覆盖
3. 代码规范
3.1 组件结构
Component({
behaviors: [], // 复用逻辑
properties: { // 对外属性
size: {
type: String,
value: 'medium',
observer: function(newVal) {
// 属性变化处理
}
}
},
data: {}, // 内部状态
lifetimes: { // 生命周期
attached() {},
detached() {}
},
methods: { // 方法
handleTap() {
this.triggerEvent('confirm', { value: this.data.value })
}
}
})3.2 事件规范
- 自定义事件命名使用 kebab-case
- 事件数据遵循
{ key: value }格式 - 事件冒泡配置：
this.triggerEvent('cell-click', { id }, {
bubbles: true, // 是否冒泡
composed: true // 是否跨越组件边界
})3.3 样式规范
- 使用 BEM 命名规范
/* 组件根元素 */
.your-component {
position: relative;
}
/* 子元素选择器 */
.your-component__header {
font-size: 16px;
}
/* 状态类名 */
.your-component--disabled {
opacity: 0.6;
}4. 文档规范
4.1 README.md 结构
- 组件名称
- 功能描述
- 使用示例
- API 文档（属性、事件、方法）
- 注意事项
4.2 示例代码要求
- 示例代码应该简洁明了
- 覆盖组件的主要功能和常见用法
- 包含必要的注释说明
- 展示不同属性和事件的使用方法
5. 文档生成规范
5.1 目录结构
your-component/
├── README.md # 自动复制到 site/docs/src
└── _example/ # 示例目录
├── index.js # 自动复制到两个位置
├── index.wxml # 1. site/docs/src/[type]/[name]/_example
├── index.wxss # 2. pages/[type]/[name]
└── index.json5.2 文件转换规则
- site/docs/src 目录：
- .wxss -> .css
- .wxml -> .html
- pages 目录：
- 保持原始后缀
5.3 页面配置生成
- app.json 页面路径格式：
pages/[组件类型]/[组件名]/[js文件名] - test.js 导航配置格式：
{ label: "组件名", onClick() { wx.navigateTo({ url: "/pages/组件类型/组件名/index" }); } }
6. 测试规范
6.1 单元测试
- 测试组件渲染
- 测试属性变化
- 测试事件触发
- 测试方法调用
describe('Component Test', () => {
test('should render correct size', () => {
const component = renderComponent({ size: 'large' })
expect(component).toMatchSnapshot()
})
test('should emit confirm event', async () => {
const mockFn = jest.fn()
const component = mountComponent({
methods: { onConfirm: mockFn }
})
await component.trigger('click')
expect(mockFn).toBeCalled()
})
})7. 版本管理
7.1 语义化版本
- 主版本号：不兼容的 API 修改
- 次版本号：向下兼容的功能新增
- 修订号：问题修复
7.2 CHANGELOG 格式
## [1.2.0] - 2023-08-20
### Added
- 新增 size 属性支持
### Fixed
- 修复 Android 平台点击穿透问题8. 代码审查清单
8.1 基础检查
8.2 文档检查
8.3 质量检查
质量保证
通过遵循以上规范，可确保组件库的： ✅ 可维护性 ✅ 可扩展性 ✅ 一致性 ✅ 可测试性 ✅ 文档完整性
建议配合以下工具实现自动化质量检测：
- ESLint：代码质量检查
- StyleLint：样式规范检查
- Jest：单元测试
- Prettier：代码格式化
业务组件文档
业务组件文档开发步骤
业务组件与基础组件不同，业务组件通常维护在各自的业务仓库中，而不是在ava-ui仓库中。业务组件文档的开发流程主要是为了在统一的文档站点中展示和管理这些分散的业务组件。
1. 在目录 site/docs/src/business 新增业务组件的目录和README
在 site/docs/src/business 目录下创建你的业务组件文档目录，例如 your-business-component：
site/docs/src/business/
└── your-business-component/ # 业务组件文档目录
├── README.md # 组件文档2. 更新文档树路由配置
在 site/docs/.vuepress/routes.js 文件中，找到业务组件节点，新增你的组件配置：
{
title: "业务组件",
children: [
// 现有的业务组件...
['src/business/your-business-component/', "YourBusinessComponent 业务组件名称"],
]
}发布流程
仅发布文档
- 只需在小程序发布对象选择模块（ava_ui）发布即可。
发布预览页面
如需在文档中预览最新发布的小程序内容，请依次完成以下3步：
- 小程序发布对象
- 在小程序后台选择模块名称：ava_ui，设备类型：H5，进行发布。
- 发布完成后获取发布后的 md5
- 发布成功后，平台会生成新的 md5 值（如：e392d98b0a1c710a10896188cabf31ba）。
- 记录下该 md5 值，后续文档预览需要用到。
- 修改文档预览地址中的 md5
- 打开
site/docs/.vuepress/components/PreviewPhone.vue文件。 - 找到 iframe 的
src属性，形如：:src="`https://a.fspage.com/FSR/avah5/ava_ui/【md5】/index.html?avapage=${path}`" - 将其中的 md5 替换为最新发布后获得的 md5。
- 打开
- 再次发布ava_ui小程序
- 在小程序后台选择模块名称：ava_ui，设备类型：H5，进行发布。
- 确保文档预览页面能够正确显示最新的小程序内容。