huangzhenbao/medical-mall

Fork 0

Files

huangzhenbao 3922409a25 完善

2026-02-03 21:35:57 +08:00

8.0 KiB

Raw Blame History

🚀 快速开始指南 - 使用新规范开发

📖 目录

快速创建新页面
遵循编码规范
常见问题
参考资料

快速创建新页面

方法 1: 使用模板 (推荐) ⭐

步骤 1: 复制模板

从 pages/mall/admin/_TEMPLATE_simple-page.uvue 复制

步骤 2: 创建新文件

pages/mall/admin/your-new-page.uvue

步骤 3: 修改模板值

<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. 模板结构

<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. 脚本编写

<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. 样式编写

<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)

// ✅ 好的
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)

// ✅ 好的 - kebab-case
.page-header {
}
.user-list {
}
.action-button {
}
.form-field {
}

// ❌ 不好 - PascalCase
.PageHeader {
}
.UserList {
}
.ActionButton {
}
.FormField {
}

3. 设计变量 (Design Variables)

// ✅ 好的 - 使用变量
.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. 不要使用硬编码颜色

// ❌ 错误
background: #ffffff
color: #333333
border-color: #dddddd

// ✅ 正确
background: $background-primary
color: $text-primary
border-color: $border-default

2. 不要硬编码间距

// ❌ 错误
margin-top: 20rpx
padding: 30rpx

// ✅ 正确
margin-top: $space-md
padding: $space-lg

3. 不要混合命名规范

// ❌ 错误 - 混合 kebab-case 和 camelCase
.page-header { }
.PageContent { }
.footer-bar { }

// ✅ 正确 - 统一 kebab-case
.page-header { }
.page-content { }
.footer-bar { }

常见问题

Q: 我该在哪里声明 ref?

A: 在 <script setup> 中，在组件逻辑之前声明：

const title = ref<string>('标题')      // ✅
const count = ref<number>(0)            // ✅
// ... 其他逻辑

Q: 如何添加多个卡片？

A: 为每个卡片创建一个 .card div：

<view class="card">
  <text class="label">卡片 1</text>
  <!-- 内容 -->
</view>

<view class="card">
  <text class="label">卡片 2</text>
  <!-- 内容 -->
</view>

Q: 我可以修改 $space-lg 的值吗?

A: 可以，在 uni.scss 中修改，所有页面会自动更新：

// 在 uni.scss 中
$space-lg: 32rpx; // 所有使用 $space-lg 的页面都会变化

Q: 我该如何处理条件样式?

A: 使用 Vue 的动态绑定：

<view :class="{ 'is-active': isActive }">
  内容
</view>

<style scoped lang="scss">
.is-active {
  background: $primary;
  color: #ffffff;
}
</style>

Q: 如何定义自定义颜色变量?

A: 在 uni.scss 中添加新变量：

// 在 uni.scss 中
$my-brand-color: #ff5722;
$my-light-bg: #fff3e0;

// 然后在页面中使用
.brand-header {
  background: $my-brand-color;
}

Q: 我可以使用内联样式吗?

A: 不推荐，使用 CSS 类更好：

<!-- ❌ 不推荐 -->
<view style="padding: 20rpx; background: #fff;">

<!-- ✅ 推荐 -->
<view class="my-card">

<style scoped lang="scss">
.my-card {
  padding: $space-md;
  background: $background-primary;
}
</style>

参考资料

核心设计变量

颜色系统

$primary: #1677ff; // 主色
$success: #52c41a; // 成功
$warning: #faad14; // 警告
$danger: #ff4d4f; // 危险

$background-primary: #ffffff; // 主背景
$background-secondary: #fafafa; // 次要背景
$text-primary: #000000; // 主文本
$text-secondary: #666666; // 次要文本
$text-tertiary: #999999; // 弱化文本

间距系统 (8px 基准)

$space-xs: 8rpx; // 最小间距
$space-md: 16rpx; // 中等间距
$space-lg: 24rpx; // 大间距
$space-xl: 32rpx; // 超大间距

字体系统

$font-size-sm: 24rpx; // 小字体
$font-size-md: 26rpx; // 正常字体
$font-size-lg: 36rpx; // 大字体

$font-weight-normal: 400;
$font-weight-semibold: 600;
$font-weight-bold: 700;

其他常用变量

$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 - 详细的重构列表
REFACTOR_SUMMARY.md - 重构总结
REFACTOR_BEFORE_AFTER.md - 改进对比

💡 最佳实践清单

在开始开发前，检查以下项目:

使用了 ref<Type>() 声明所有状态
所有 CSS 类名都是 kebab-case
没有硬编码的颜色值
没有硬编码的间距值
添加了 lang="scss" 到 style 标签
添加了 lang="uts" 到 script 标签
函数参数都有类型定义
使用了 AdminLayout 布局
遵循了 page/header/card 的结构

🎉 开始编码吧!

现在你已经准备好使用新规范开发了！

记住：

使用模板作为起点
遵循编码规范
参考已改版的页面
有问题查看文档

祝你编码愉快！🚀

8.0 KiB Raw Blame History Unescape Escape