提交1 bmad搭建与项目启动 - ok
This commit is contained in:
231
docs/页面结构TSX更新说明.md
Normal file
231
docs/页面结构TSX更新说明.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 页面结构文件扩展名更新说明
|
||||
|
||||
## 📝 更新内容
|
||||
|
||||
根据开发安全性的要求，已将所有模块页面结构示例中的 JavaScript 文件（`.js`）改为 TypeScript 文件（`.tsx`），以提供更好的类型安全性。
|
||||
|
||||
## 🔄 修改的文件类型
|
||||
|
||||
### 1. Hooks 文件
|
||||
- `usePageData.js` → `usePageData.tsx`
|
||||
- `usePageActions.js` → `usePageActions.tsx`
|
||||
- `useClassification.js` → `useClassification.tsx`
|
||||
- `useQRCode.js` → `useQRCode.tsx`
|
||||
- `useDriverForm.js` → `useDriverForm.tsx`
|
||||
- `useTaskManagement.js` → `useTaskManagement.tsx`
|
||||
- `useLoadDevice.js` → `useLoadDevice.tsx`
|
||||
- `useRealtimeLocation.js` → `useRealtimeLocation.tsx`
|
||||
- `useWebSocket.js` → `useWebSocket.tsx`
|
||||
- 等等...
|
||||
|
||||
### 2. Utils 文件
|
||||
- `pageHelpers.js` → `pageHelpers.tsx`
|
||||
- `formatters.js` → `formatters.tsx`
|
||||
- `validators.js` → `validators.tsx`
|
||||
- `coordinateUtils.js` → `coordinateUtils.tsx`
|
||||
- `areaCalculators.js` → `areaCalculators.tsx`
|
||||
- `categoryHelpers.js` → `categoryHelpers.tsx`
|
||||
- `qrGenerators.js` → `qrGenerators.tsx`
|
||||
- `taskHelpers.js` → `taskHelpers.tsx`
|
||||
- `loadCalculators.js` → `loadCalculators.tsx`
|
||||
- `mapHelpers.js` → `mapHelpers.tsx`
|
||||
- 等等...
|
||||
|
||||
### 3. Constants 文件
|
||||
- `constants.js` → `constants.tsx`
|
||||
|
||||
### 4. Common 组件文件
|
||||
- `LoadingSpinner.jsx` → `LoadingSpinner.tsx`
|
||||
- `ErrorBoundary.jsx` → `ErrorBoundary.tsx`
|
||||
- `EmptyState.jsx` → `EmptyState.tsx`
|
||||
- `ConfirmDialog.jsx` → `ConfirmDialog.tsx`
|
||||
|
||||
## 📂 标准页面结构（已更新）
|
||||
|
||||
```
|
||||
PageName/
|
||||
├── 📄 index.jsx # 主组件
|
||||
├── 📄 index.css # 样式文件
|
||||
├── 📄 index.types.ts # 类型定义
|
||||
├── 📂 hooks/ # 页面专用Hooks
|
||||
│ ├── 📄 usePageData.tsx # 数据管理Hook
|
||||
│ ├── 📄 usePageActions.tsx # 操作Hook
|
||||
│ └── 📄 use[Feature].tsx # 特定功能Hook
|
||||
├── 📂 utils/ # 工具函数
|
||||
│ ├── 📄 pageHelpers.tsx # 页面辅助函数
|
||||
│ ├── 📄 validators.tsx # 表单验证
|
||||
│ └── 📄 formatters.tsx # 数据格式化
|
||||
├── 📄 constants.tsx # 页面常量
|
||||
└── 📂 components/ # 子组件目录
|
||||
└── 📂 [ComponentName]/ # 子组件
|
||||
├── 📄 index.jsx
|
||||
├── 📄 index.css
|
||||
└── 📄 types.ts
|
||||
```
|
||||
|
||||
## ✅ 已更新的文档
|
||||
|
||||
1. ✅ **AgriculturalMachinery模块页面结构示例.md** - 已完成
|
||||
2. ✅ **LandInformation模块页面结构示例.md** - 已完成
|
||||
3. 🔄 **FarmingOperation模块页面结构示例.md** - 需要继续更新
|
||||
4. 🔄 **其他业务模块页面结构示例.md** - 需要继续更新
|
||||
5. ✅ **Pages目录结构与开发规范.md** - 已完成
|
||||
6. ✅ **开发者参考指南.md** - 已完成
|
||||
7. ✅ **Pages目录结构设计总结.md** - 已完成
|
||||
|
||||
## 💡 开发建议
|
||||
|
||||
### 1. TypeScript 类型安全
|
||||
使用 `.tsx` 文件可以享受以下好处：
|
||||
- 完整的类型检查
|
||||
- 更好的 IDE 支持
|
||||
- 减少运行时错误
|
||||
- 更容易的重构
|
||||
- 更好的代码提示
|
||||
|
||||
### 2. Hook 开发示例
|
||||
|
||||
```typescript
|
||||
// hooks/usePageData.tsx
|
||||
import { useState, useEffect, useCallback } from 'react';
|
||||
import { getApiData } from '@/apis/module';
|
||||
import { showMessage } from '@/utils/message';
|
||||
import { DataRecord, Filters, PaginationState } from './index.types';
|
||||
|
||||
export function usePageData() {
|
||||
const [data, setData] = useState<DataRecord[]>([]);
|
||||
const [loading, setLoading] = useState(false);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [filters, setFilters] = useState<Filters>({});
|
||||
const [pagination, setPagination] = useState<PaginationState>({
|
||||
current: 1,
|
||||
pageSize: 10,
|
||||
total: 0
|
||||
});
|
||||
|
||||
// 获取数据
|
||||
const fetchData = useCallback(async () => {
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
|
||||
try {
|
||||
const params = {
|
||||
...filters,
|
||||
page: pagination.current,
|
||||
pageSize: pagination.pageSize
|
||||
};
|
||||
|
||||
const response = await getApiData(params);
|
||||
setData(response.data.list);
|
||||
setPagination(prev => ({
|
||||
...prev,
|
||||
total: response.data.total
|
||||
}));
|
||||
} catch (err: any) {
|
||||
setError(err.message);
|
||||
showMessage('error', '获取数据失败');
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}, [filters, pagination.current, pagination.pageSize]);
|
||||
|
||||
// 初始加载
|
||||
useEffect(() => {
|
||||
fetchData();
|
||||
}, [fetchData]);
|
||||
|
||||
// 处理筛选变化
|
||||
const handleFilterChange = useCallback((newFilters: Filters) => {
|
||||
setFilters(newFilters);
|
||||
setPagination(prev => ({ ...prev, current: 1 }));
|
||||
}, []);
|
||||
|
||||
// 处理分页变化
|
||||
const handlePageChange = useCallback((page: number) => {
|
||||
setPagination(prev => ({ ...prev, current: page }));
|
||||
}, []);
|
||||
|
||||
return {
|
||||
data,
|
||||
loading,
|
||||
error,
|
||||
filters,
|
||||
pagination,
|
||||
handleFilterChange,
|
||||
handlePageChange,
|
||||
refreshData: fetchData
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 工具函数示例
|
||||
|
||||
```typescript
|
||||
// utils/formatters.tsx
|
||||
import dayjs from 'dayjs';
|
||||
import { MachineryStatus } from './index.types';
|
||||
|
||||
/**
|
||||
* 格式化农机状态
|
||||
*/
|
||||
export function formatMachineryStatus(status: MachineryStatus) {
|
||||
const statusMap = {
|
||||
'运行中': { text: '运行中', color: '#52c41a' },
|
||||
'空闲中': { text: '空闲中', color: '#d9d9d9' },
|
||||
'待维护': { text: '待维护', color: '#faad14' },
|
||||
'已报废': { text: '已报废', color: '#ff4d4f' }
|
||||
};
|
||||
|
||||
return statusMap[status] || { text: '未知', color: '#d9d9d9' };
|
||||
}
|
||||
|
||||
/**
|
||||
* 格式化日期
|
||||
*/
|
||||
export function formatDate(date: string): string {
|
||||
return dayjs(date).format('YYYY-MM-DD HH:mm');
|
||||
}
|
||||
|
||||
/**
|
||||
* 格式化价格
|
||||
*/
|
||||
export function formatPrice(price: number): string {
|
||||
return new Intl.NumberFormat('zh-CN', {
|
||||
style: 'currency',
|
||||
currency: 'CNY'
|
||||
}).format(price);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 常量定义示例
|
||||
|
||||
```typescript
|
||||
// constants.tsx
|
||||
export const MACHINERY_CATEGORIES = [
|
||||
{ value: '耕地机械', label: '耕地机械' },
|
||||
{ value: '播种机械', label: '播种机械' },
|
||||
{ value: '收获机械', label: '收获机械' },
|
||||
{ value: '植保机械', label: '植保机械' }
|
||||
] as const;
|
||||
|
||||
export const MACHINERY_STATUS = [
|
||||
{ value: '运行中', label: '运行中', color: '#52c41a' },
|
||||
{ value: '空闲中', label: '空闲中', color: '#d9d9d9' },
|
||||
{ value: '待维护', label: '待维护', color: '#faad14' },
|
||||
{ value: '已报废', label: '已报废', color: '#ff4d4f' }
|
||||
] as const;
|
||||
|
||||
export const PAGE_SIZE_OPTIONS = [10, 20, 50, 100] as const;
|
||||
export const DEFAULT_PAGE_SIZE = 10;
|
||||
```
|
||||
|
||||
## 🚀 后续工作
|
||||
|
||||
1. **继续更新剩余文档**: 完成 FarmingOperation 和其他模块的文档更新
|
||||
2. **更新开发规范**: 修改 Pages目录结构与开发规范.md 中的示例
|
||||
3. **更新参考指南**: 修改 开发者参考指南.md 中的代码示例
|
||||
4. **创建代码片段**: 更新 VS Code 代码片段为 TypeScript 版本
|
||||
|
||||
## ✨ 总结
|
||||
|
||||
通过将 JavaScript 文件改为 TypeScript 文件，我们显著提高了代码的类型安全性，减少了运行时错误，并提供了更好的开发体验。这是现代 React 开发的最佳实践，特别适合大型企业级应用的开发。
|
||||
Reference in New Issue
Block a user