426 lines
8.0 KiB
Markdown
426 lines
8.0 KiB
Markdown
# 🚀 快速开始指南 - 使用新规范开发
|
||
|
||
## 📖 目录
|
||
|
||
1. [快速创建新页面](#快速创建新页面)
|
||
2. [遵循编码规范](#遵循编码规范)
|
||
3. [常见问题](#常见问题)
|
||
4. [参考资料](#参考资料)
|
||
|
||
## 快速创建新页面
|
||
|
||
### 方法 1: 使用模板 (推荐) ⭐
|
||
|
||
#### 步骤 1: 复制模板
|
||
|
||
从 `pages/mall/admin/_TEMPLATE_simple-page.uvue` 复制
|
||
|
||
#### 步骤 2: 创建新文件
|
||
|
||
```bash
|
||
pages/mall/admin/your-new-page.uvue
|
||
```
|
||
|
||
#### 步骤 3: 修改模板值
|
||
|
||
```uvue
|
||
<script setup lang="uts">
|
||
// 改这三个值
|
||
const currentPage = ref<string>('your-page-id') // 修改此处
|
||
const title = ref<string>('你的页面标题') // 修改此处
|
||
const subtitle = ref<string>('你的副标题') // 修改此处
|
||
const params = ref<string>('')
|
||
|
||
onLoad((options: Record<string, string | undefined>) => {
|
||
params.value = JSON.stringify(options ?? {})
|
||
})
|
||
</script>
|
||
```
|
||
|
||
#### 步骤 4: 添加页面内容
|
||
|
||
在 `<view class="card">` 中添加你的内容
|
||
|
||
#### 完成！✅
|
||
|
||
### 方法 2: 手动创建
|
||
|
||
如果需要复杂的页面结构，遵循以下规范:
|
||
|
||
#### 1. 模板结构
|
||
|
||
```uvue
|
||
<template>
|
||
<AdminLayout :currentPage="currentPage">
|
||
<view class="page">
|
||
<!-- 页面标题 -->
|
||
<view class="header">
|
||
<text class="title">{{ title }}</text>
|
||
<text class="sub-title">{{ subtitle }}</text>
|
||
</view>
|
||
|
||
<!-- 页面内容 -->
|
||
<view class="card">
|
||
<!-- 你的内容 -->
|
||
</view>
|
||
</view>
|
||
</AdminLayout>
|
||
</template>
|
||
```
|
||
|
||
#### 2. 脚本编写
|
||
|
||
```uts
|
||
<script setup lang="uts">
|
||
import { ref } from 'vue'
|
||
import { onLoad } from '@dcloudio/uni-app'
|
||
import AdminLayout from '@/layouts/admin/AdminLayout.uvue'
|
||
|
||
// 声明页面状态（都要有类型）
|
||
const currentPage = ref<string>('page-id')
|
||
const title = ref<string>('页面标题')
|
||
const subtitle = ref<string>('副标题')
|
||
|
||
// 处理路由参数
|
||
onLoad((options: Record<string, string | undefined>) => {
|
||
// options 中可以获取路由参数
|
||
})
|
||
|
||
// 事件处理
|
||
const handleAction = (id: string) => {
|
||
// 处理点击事件
|
||
}
|
||
</script>
|
||
```
|
||
|
||
#### 3. 样式编写
|
||
|
||
```scss
|
||
<style scoped lang="scss">
|
||
// 使用设计变量，不要硬编码！
|
||
.page {
|
||
padding: $space-lg; // 不要写 padding: 24rpx;
|
||
}
|
||
|
||
.header {
|
||
padding: $space-lg;
|
||
border-radius: $radius;
|
||
background: $background-primary; // 不要写 background: #ffffff;
|
||
box-shadow: $shadow-xs;
|
||
}
|
||
|
||
.title {
|
||
font-size: $font-size-lg; // 不要写 font-size: 36rpx;
|
||
font-weight: $font-weight-bold;
|
||
color: $text-primary; // 不要写 color: #000;
|
||
}
|
||
|
||
.card {
|
||
margin-top: $space-lg;
|
||
padding: $space-lg;
|
||
background: $background-primary;
|
||
border-radius: $radius;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
## 遵循编码规范
|
||
|
||
### ✅ 必须做的事
|
||
|
||
#### 1. 类型注解 (Type Annotations)
|
||
|
||
```uts
|
||
// ✅ 好的
|
||
const title = ref<string>('标题')
|
||
const count = ref<number>(0)
|
||
const items = ref<Array<Item>>([])
|
||
const config = ref<Record<string, any>>({})
|
||
|
||
// ❌ 不好 - 没有类型
|
||
const title = ref('标题')
|
||
const count = ref(0)
|
||
```
|
||
|
||
#### 2. CSS 命名规范 (Naming Convention)
|
||
|
||
```scss
|
||
// ✅ 好的 - kebab-case
|
||
.page-header {
|
||
}
|
||
.user-list {
|
||
}
|
||
.action-button {
|
||
}
|
||
.form-field {
|
||
}
|
||
|
||
// ❌ 不好 - PascalCase
|
||
.PageHeader {
|
||
}
|
||
.UserList {
|
||
}
|
||
.ActionButton {
|
||
}
|
||
.FormField {
|
||
}
|
||
```
|
||
|
||
#### 3. 设计变量 (Design Variables)
|
||
|
||
```scss
|
||
// ✅ 好的 - 使用变量
|
||
.header {
|
||
padding: $space-lg;
|
||
background: $background-primary;
|
||
color: $text-primary;
|
||
font-size: $font-size-lg;
|
||
}
|
||
|
||
// ❌ 不好 - 硬编码
|
||
.header {
|
||
padding: 24rpx;
|
||
background: #ffffff;
|
||
color: #000000;
|
||
font-size: 36rpx;
|
||
}
|
||
```
|
||
|
||
### ❌ 不要做的事
|
||
|
||
#### 1. 不要使用硬编码颜色
|
||
|
||
```uts
|
||
// ❌ 错误
|
||
background: #ffffff
|
||
color: #333333
|
||
border-color: #dddddd
|
||
|
||
// ✅ 正确
|
||
background: $background-primary
|
||
color: $text-primary
|
||
border-color: $border-default
|
||
```
|
||
|
||
#### 2. 不要硬编码间距
|
||
|
||
```uts
|
||
// ❌ 错误
|
||
margin-top: 20rpx
|
||
padding: 30rpx
|
||
|
||
// ✅ 正确
|
||
margin-top: $space-md
|
||
padding: $space-lg
|
||
```
|
||
|
||
#### 3. 不要混合命名规范
|
||
|
||
```uts
|
||
// ❌ 错误 - 混合 kebab-case 和 camelCase
|
||
.page-header { }
|
||
.PageContent { }
|
||
.footer-bar { }
|
||
|
||
// ✅ 正确 - 统一 kebab-case
|
||
.page-header { }
|
||
.page-content { }
|
||
.footer-bar { }
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 我该在哪里声明 ref?
|
||
|
||
A: 在 `<script setup>` 中，在组件逻辑之前声明：
|
||
|
||
```uts
|
||
const title = ref<string>('标题') // ✅
|
||
const count = ref<number>(0) // ✅
|
||
// ... 其他逻辑
|
||
```
|
||
|
||
### Q: 如何添加多个卡片？
|
||
|
||
A: 为每个卡片创建一个 `.card` div：
|
||
|
||
```uvue
|
||
<view class="card">
|
||
<text class="label">卡片 1</text>
|
||
<!-- 内容 -->
|
||
</view>
|
||
|
||
<view class="card">
|
||
<text class="label">卡片 2</text>
|
||
<!-- 内容 -->
|
||
</view>
|
||
```
|
||
|
||
### Q: 我可以修改 $space-lg 的值吗?
|
||
|
||
A: 可以，在 `uni.scss` 中修改，所有页面会自动更新：
|
||
|
||
```scss
|
||
// 在 uni.scss 中
|
||
$space-lg: 32rpx; // 所有使用 $space-lg 的页面都会变化
|
||
```
|
||
|
||
### Q: 我该如何处理条件样式?
|
||
|
||
A: 使用 Vue 的动态绑定：
|
||
|
||
```uvue
|
||
<view :class="{ 'is-active': isActive }">
|
||
内容
|
||
</view>
|
||
|
||
<style scoped lang="scss">
|
||
.is-active {
|
||
background: $primary;
|
||
color: #ffffff;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Q: 如何定义自定义颜色变量?
|
||
|
||
A: 在 `uni.scss` 中添加新变量：
|
||
|
||
```scss
|
||
// 在 uni.scss 中
|
||
$my-brand-color: #ff5722;
|
||
$my-light-bg: #fff3e0;
|
||
|
||
// 然后在页面中使用
|
||
.brand-header {
|
||
background: $my-brand-color;
|
||
}
|
||
```
|
||
|
||
### Q: 我可以使用内联样式吗?
|
||
|
||
A: 不推荐，使用 CSS 类更好：
|
||
|
||
```uvue
|
||
<!-- ❌ 不推荐 -->
|
||
<view style="padding: 20rpx; background: #fff;">
|
||
|
||
<!-- ✅ 推荐 -->
|
||
<view class="my-card">
|
||
|
||
<style scoped lang="scss">
|
||
.my-card {
|
||
padding: $space-md;
|
||
background: $background-primary;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
## 参考资料
|
||
|
||
### 核心设计变量
|
||
|
||
#### 颜色系统
|
||
|
||
```scss
|
||
$primary: #1677ff; // 主色
|
||
$success: #52c41a; // 成功
|
||
$warning: #faad14; // 警告
|
||
$danger: #ff4d4f; // 危险
|
||
|
||
$background-primary: #ffffff; // 主背景
|
||
$background-secondary: #fafafa; // 次要背景
|
||
$text-primary: #000000; // 主文本
|
||
$text-secondary: #666666; // 次要文本
|
||
$text-tertiary: #999999; // 弱化文本
|
||
```
|
||
|
||
#### 间距系统 (8px 基准)
|
||
|
||
```scss
|
||
$space-xs: 8rpx; // 最小间距
|
||
$space-md: 16rpx; // 中等间距
|
||
$space-lg: 24rpx; // 大间距
|
||
$space-xl: 32rpx; // 超大间距
|
||
```
|
||
|
||
#### 字体系统
|
||
|
||
```scss
|
||
$font-size-sm: 24rpx; // 小字体
|
||
$font-size-md: 26rpx; // 正常字体
|
||
$font-size-lg: 36rpx; // 大字体
|
||
|
||
$font-weight-normal: 400;
|
||
$font-weight-semibold: 600;
|
||
$font-weight-bold: 700;
|
||
```
|
||
|
||
#### 其他常用变量
|
||
|
||
```scss
|
||
$radius: 16rpx; // 圆角半径
|
||
$shadow-xs: 0 2px 8px rgba(0, 0, 0, 0.06);
|
||
$line-height: 1.5; // 行高
|
||
```
|
||
|
||
### 已改版页面参考
|
||
|
||
所有这些页面都遵循新规范，可以作为参考：
|
||
|
||
**P0 主页面:**
|
||
|
||
- user-management.uvue
|
||
- product-management.uvue
|
||
- order-management.uvue
|
||
- system-settings.uvue
|
||
- marketing-management.uvue
|
||
|
||
**P1 维护页面:** (maintain 文件夹中的所有文件)
|
||
|
||
- maintain/data/\*.uvue
|
||
- maintain/dev-config/\*.uvue
|
||
- maintain/dev-tools/\*.uvue
|
||
- maintain/security/\*.uvue
|
||
- maintain/i18n/\*.uvue
|
||
|
||
**P2 产品页面:**
|
||
|
||
- product-specifications.uvue
|
||
- product-classification.uvue
|
||
- product-parameters.uvue
|
||
- 等等...
|
||
|
||
### 查看完整文档
|
||
|
||
- [ADMIN_REFACTOR_PROGRESS.md](./ADMIN_REFACTOR_PROGRESS.md) - 详细的重构列表
|
||
- [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md) - 重构总结
|
||
- [REFACTOR_BEFORE_AFTER.md](./REFACTOR_BEFORE_AFTER.md) - 改进对比
|
||
|
||
## 💡 最佳实践清单
|
||
|
||
在开始开发前，检查以下项目:
|
||
|
||
- [ ] 使用了 `ref<Type>()` 声明所有状态
|
||
- [ ] 所有 CSS 类名都是 kebab-case
|
||
- [ ] 没有硬编码的颜色值
|
||
- [ ] 没有硬编码的间距值
|
||
- [ ] 添加了 `lang="scss"` 到 style 标签
|
||
- [ ] 添加了 `lang="uts"` 到 script 标签
|
||
- [ ] 函数参数都有类型定义
|
||
- [ ] 使用了 AdminLayout 布局
|
||
- [ ] 遵循了 page/header/card 的结构
|
||
|
||
## 🎉 开始编码吧!
|
||
|
||
现在你已经准备好使用新规范开发了！
|
||
|
||
记住：
|
||
|
||
1. 使用模板作为起点
|
||
2. 遵循编码规范
|
||
3. 参考已改版的页面
|
||
4. 有问题查看文档
|
||
|
||
祝你编码愉快！🚀
|