修改页面结构
This commit is contained in:
425
docs/admin/QUICK_START_NEW_DEVELOPMENT.md
Normal file
425
docs/admin/QUICK_START_NEW_DEVELOPMENT.md
Normal file
@@ -0,0 +1,425 @@
|
||||
# 🚀 快速开始指南 - 使用新规范开发
|
||||
|
||||
## 📖 目录
|
||||
|
||||
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. 有问题查看文档
|
||||
|
||||
祝你编码愉快！🚀
|
||||
Reference in New Issue
Block a user