docs: add upage usage instructions document
This commit is contained in:
LIlGG
156
docs/content/contributing/code-standards.md
Normal file
156
docs/content/contributing/code-standards.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
id: code-standards
|
||||
title: 代码规范
|
||||
---
|
||||
|
||||
# 代码规范
|
||||
|
||||
UPage 项目遵循严格的代码规范和最佳实践，以确保代码质量和一致性。本文档概述了这些规范，所有贡献者在提交代码前应确保遵循这些规范。
|
||||
|
||||
## JavaScript/TypeScript 规范
|
||||
|
||||
UPage 使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting。Biome 是一个快速的代码格式化工具和 linter，可以帮助我们保持代码风格的一致性。
|
||||
|
||||
### 代码检查
|
||||
|
||||
在提交代码前，请确保您的代码符合项目的代码规范：
|
||||
|
||||
```bash
|
||||
pnpm check
|
||||
```
|
||||
|
||||
### 自动修复
|
||||
|
||||
您也可以使用以下命令自动修复格式问题：
|
||||
|
||||
```bash
|
||||
pnpm check --write
|
||||
```
|
||||
|
||||
### 主要规范
|
||||
|
||||
- **缩进**: 使用 2 个空格
|
||||
- **分号**: 必须使用分号
|
||||
- **引号**: 使用单引号
|
||||
- **命名约定**:
|
||||
- 变量和函数使用 camelCase
|
||||
- 类和接口使用 PascalCase
|
||||
- 常量使用 UPPER_SNAKE_CASE
|
||||
- **类型注解**: 尽可能使用类型注解提高代码可读性和类型安全性
|
||||
- **注释**: 对复杂逻辑和公共 API 添加适当的注释
|
||||
|
||||
## Git 提交规范
|
||||
|
||||
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来格式化 Git 提交信息。提交信息应遵循以下格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### 类型 (Type)
|
||||
|
||||
提交类型必须是以下之一：
|
||||
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复 bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码风格更改（不影响代码功能）
|
||||
- `refactor`: 代码重构（既不是新功能，也不是修复 bug）
|
||||
- `perf`: 性能优化
|
||||
- `test`: 添加或修改测试
|
||||
- `chore`: 构建过程或辅助工具的变动
|
||||
- `ci`: CI 配置文件和脚本的更改
|
||||
- `revert`: 回滚之前的提交
|
||||
|
||||
### 范围 (Scope)
|
||||
|
||||
范围是可选的，用于指定更改的范围（例如组件或文件名）。
|
||||
|
||||
### 描述 (Description)
|
||||
|
||||
描述是对更改的简短摘要：
|
||||
|
||||
- 使用现在时态（"change"，而不是"changed"或"changes"）
|
||||
- 不要首字母大写
|
||||
- 不要以句号结尾
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
feat(editor): 添加拖拽调整组件大小功能
|
||||
|
||||
添加了一个新的拖拽句柄，允许用户直接调整组件的大小。
|
||||
同时优化了调整过程中的性能。
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix: 修复用户认证失败问题
|
||||
|
||||
修复了当用户凭证包含特殊字符时认证失败的问题。
|
||||
|
||||
Fixes #456
|
||||
```
|
||||
|
||||
## CSS/SCSS 规范
|
||||
|
||||
UPage 使用 SCSS 和 CSS Modules 来组织样式代码。
|
||||
|
||||
### 命名约定
|
||||
|
||||
- 使用 kebab-case 命名 CSS 类和 ID
|
||||
- 使用有意义的名称，避免过于简短或抽象的名称
|
||||
- 使用 BEM（Block Element Modifier）命名方法论
|
||||
|
||||
### 组织结构
|
||||
|
||||
- 将全局样式放在 `app/styles` 目录下
|
||||
- 将组件特定样式放在组件同级目录下的 `.scss` 或 `.module.scss` 文件中
|
||||
|
||||
## 可访问性标准
|
||||
|
||||
UPage 致力于创建可访问的 Web 应用程序。所有贡献的代码应遵循 [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/) 标准。
|
||||
|
||||
- 确保适当的颜色对比度
|
||||
- 提供替代文本和 ARIA 标签
|
||||
- 确保键盘导航功能
|
||||
- 支持屏幕阅读器
|
||||
|
||||
## 测试规范
|
||||
|
||||
所有新功能和 bug 修复应包含适当的测试：
|
||||
|
||||
- **单元测试**: 测试单个函数和组件
|
||||
- **集成测试**: 测试多个组件或功能的交互
|
||||
- **端到端测试**: 测试完整的用户流程
|
||||
|
||||
测试应该：
|
||||
|
||||
- 覆盖正常和边缘情况
|
||||
- 清晰描述测试的目的
|
||||
- 保持独立性，不依赖于其他测试的状态
|
||||
|
||||
## 性能考虑
|
||||
|
||||
贡献的代码应考虑性能影响：
|
||||
|
||||
- 避免不必要的重新渲染
|
||||
- 优化大型列表和表格
|
||||
- 懒加载大型资源
|
||||
- 减少网络请求
|
||||
- 优化打包大小
|
||||
|
||||
## 安全最佳实践
|
||||
|
||||
所有代码应遵循安全最佳实践：
|
||||
|
||||
- 防止 XSS 攻击
|
||||
- 避免 SQL 注入
|
||||
- 正确处理用户输入
|
||||
- 保护敏感数据
|
||||
- 实施适当的访问控制
|
||||
Reference in New Issue
Block a user