ShadowUI3

# 开发指南

本指南将帮助您了解 Shadow UI 组件库的开发流程和规范，以便您能够更好地参与到 Shadow UI 的开发中来。

# 目录结构

Shadow UI 组件库采用模块化设计，目录结构清晰，便于维护和扩展：

uni_modules/shadow-ui/
├── components/        # 核心组件
├── static/           # 样式和静态资源
├── libs/             # 核心库
├── utils/            # 工具函数
└── index.js          # 框架入口

# 目录说明

  • components/：存放所有 UI 组件，每个组件一个目录，包含组件的 Vue 文件、样式文件和 props 定义文件
  • static/：存放框架的样式文件、图标字体和其他静态资源
  • libs/：存放框架的核心功能库，如事件总线、混入等
  • utils/：存放工具函数，如城市选择、日期处理等
  • index.js：框架的入口文件，用于注册所有组件

# 组件开发规范

# 组件命名

  1. 组件名称使用 ui- 前缀（例如 ui-button）
  2. 组件目录名称与组件名称保持一致
  3. 避免使用过于复杂或模糊的名称

# 组件结构

每个组件应包含以下文件：

ui-component-name/
├── ui-component-name.vue    # 组件的 Vue 文件
├── style.scss               # 组件的样式文件
└── props.js                 # 组件的 props 定义文件（可选）

# 代码风格

  1. 使用 Vue 3 的 Composition API 和 <script setup> 语法（新项目）
  2. CSS 类名遵循 BEM 命名规范
  3. 确保组件的跨平台兼容性
  4. 提供完整的 props、events 和 slots
  5. 编写清晰的文档和使用示例

# BEM 命名规范

BEM（Block, Element, Modifier）是一种 CSS 命名规范，用于保持 CSS 代码的清晰性和可维护性：

/* Block */
.ui-button {
  /* 块样式 */
}

/* Element */
.ui-button__icon {
  /* 元素样式 */
}

/* Modifier */
.ui-button--primary {
  /* 修饰符样式 */
}

# Props 设计

  1. 为每个 prop 提供清晰的类型定义
  2. 为必填 prop 添加 required: true
  3. 为每个 prop 提供合理的默认值
  4. 避免使用过于复杂的 prop 结构

# Events 设计

  1. 使用 kebab-case 命名事件（例如 update:model-value）
  2. 为事件提供清晰的描述
  3. 传递必要的参数

# Slots 设计

  1. 为默认插槽提供合理的默认内容
  2. 为命名插槽提供清晰的描述
  3. 避免使用过多的命名插槽

# 跨平台兼容性

Shadow UI 组件库需要支持 H5、小程序和 APP 多平台，因此在开发组件时需要注意以下几点：

  1. 避免使用平台特定的 API
  2. 使用 uni-app 提供的跨平台 API
  3. 注意不同平台的样式差异
  4. 进行充分的跨平台测试

# 样式兼容性

  1. 使用 flex 布局，避免使用 table 布局
  2. 避免使用 CSS 变量（在某些旧版小程序中不支持）
  3. 注意单位转换，使用 rpx 作为主要单位
  4. 避免使用复杂的 CSS 选择器

# API 兼容性

  1. 使用 uni-app 提供的跨平台 API，如 uni.request、uni.navigateTo 等
  2. 避免使用浏览器特定的 API，如 window、document 等
  3. 避免使用 Node.js 特定的 API

# 组件开发流程

  1. 需求分析：明确组件的功能和使用场景
  2. 设计：设计组件的 API、样式和交互
  3. 开发：按照规范开发组件
  4. 测试：在不同平台上测试组件
  5. 文档：编写组件的文档和示例
  6. 提交：提交代码并进行代码审查

# 测试

# 本地开发

  1. 克隆仓库
  2. 安装依赖：npm install
  3. 运行开发服务器：npm run dev:h5（针对 H5）
  4. 打开浏览器并导航到提供的 URL

# 平台测试

  • H5：使用浏览器开发者工具进行测试
  • 小程序：使用各自的小程序开发工具
  • APP：使用 uni-app 调试器或物理设备

# 测试重点

  1. 组件的基本功能是否正常
  2. 组件的样式是否符合设计要求
  3. 组件的交互是否流畅
  4. 组件的性能是否良好
  5. 组件在不同平台上的表现是否一致

# 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进 Shadow UI 组件库。

# 开发流程

  1. Fork 仓库
  2. 创建功能分支
  3. 提交修改
  4. 提交 Pull Request

# 提交信息规范

提交信息应遵循以下格式：

<类型>: <简要描述>

<详细说明>（可选）

<相关 issue>（可选）

类型包括：

  • feat: 添加新功能
  • fix: 修复 bug
  • docs: 更新文档
  • style: 代码风格修改
  • refactor: 代码重构
  • test: 添加或更新测试
  • chore: 构建或工具配置修改

# 代码审查

  1. 代码审查将检查代码的质量、风格和功能
  2. 请确保代码符合项目的规范和要求
  3. 请提供清晰的提交信息和修改说明

# 版本控制

我们使用语义化版本控制：

  • MAJOR 版本：不兼容的 API 变更
  • MINOR 版本：向后兼容的新功能
  • PATCH 版本：向后兼容的 bug 修复

# 发布流程

  1. 更新组件库的版本号
  2. 更新 CHANGELOG.md
  3. 提交代码
  4. 发布到 npm 或其他平台

# 常见问题

# 如何添加新组件？

  1. 在 components/ 目录下创建新的组件目录
  2. 创建组件的 Vue 文件、样式文件和 props 定义文件
  3. 在 index.js 中注册新组件
  4. 编写组件的文档和示例
  5. 测试组件的功能和兼容性

# 如何修改现有组件？

  1. 充分理解要修改的组件的功能和实现
  2. 在本地环境中进行修改和测试
  3. 确保修改不会破坏现有功能
  4. 提交修改并进行代码审查

# 如何调试组件？

  1. 使用浏览器开发者工具调试 H5 版本
  2. 使用小程序开发工具调试小程序版本
  3. 使用 uni-app 调试器调试 APP 版本

# 技术依赖

Shadow UI 项目使用了以下开源库：

  1. async-validator (opens new window) - 表单验证库
  2. xe-utils (opens new window) - 实用工具库
  3. luch-request (opens new window) - 网络请求库
  4. p-limit (opens new window) - 限制并发数量库

# 注意事项

  1. 部分版本的小程序不支持使用 text 标签作为图标容器
  2. 页面的背景色样式不能使用 scoped 修饰符，否则在小程序中可能不生效
  3. 使用组件时，请确保传入的 props 类型正确
  4. 对于需要异步加载数据的组件，请确保在数据加载完成后再渲染组件

# 许可证

MIT License (opens new window)

← 主题定制 →