122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# Component Guidelines
|
|
|
|
> This document defines the standards for creating, naming, and organizing React components in this project.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
We follow a strict functional component pattern with a focus on style isolation, type safety, and clean logic separation. Every component should be modular, self-contained, and well-documented.
|
|
|
|
---
|
|
|
|
## Naming Conventions
|
|
|
|
### 1. File and Folder Naming
|
|
- Use **kebab-case** (`xx-xx`) for component folders and files.
|
|
- If the name is short, a single word is acceptable (e.g., `button.tsx`).
|
|
- Example: `search-bar/reveal.tsx`, `user-list-item.tsx`.
|
|
|
|
### 2. Function Naming
|
|
- Use **PascalCase** (`XxXx`) for the component function name.
|
|
- Example: `const SearchBar = () => { ... }`.
|
|
|
|
---
|
|
|
|
## Component Structure
|
|
|
|
### 1. Functional Implementation
|
|
All components must be written as **Functional Components**.
|
|
|
|
### 2. Styling & Isolation
|
|
- **File**: Create an `index.scss` file in the same directory as the component.
|
|
- **Root Class**: The root `div` (or container) of the component must have a **unique class name**.
|
|
- **Isolation**: Use **SCSS nesting** with the unique root class as the parent to ensure style isolation.
|
|
|
|
```tsx
|
|
// reveal.tsx
|
|
import './index.scss';
|
|
|
|
export const UserCard = () => {
|
|
return (
|
|
<div className="user-card-wrapper">
|
|
<h1 className="title">User Info</h1>
|
|
</div>
|
|
);
|
|
};
|
|
|
|
```
|
|
```scss
|
|
// index.scss
|
|
.user-card-wrapper {
|
|
// Nested styles for isolation
|
|
.title {
|
|
color: blue;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
## Props and Type Safety
|
|
- Props Constraint: Every component with props must define a type/interface to constrain them.
|
|
- Type Location:
|
|
- Single Interface: If the component only needs one interface (usually the Props), define it at the top of the component file, directly below the import statements.
|
|
- Multiple Interfaces: If there are 2 or more interfaces/types, create a types.ts file in the same directory. Move all types, including the Props interface, into this file.
|
|
## Logic and Data Management
|
|
### 1. Static Data Extraction
|
|
If a component requires a large amount of static data (e.g., "dead" data for rendering, initialization configs, or constants), do not define them inside the component file.
|
|
- Move the data to a separate .ts file in the same directory.
|
|
- Import it using: import { CONFIG_DATA } from "./config.ts".
|
|
### 2.Commenting Standards
|
|
**Every method, property, interface, and complex logic block MUST be documented.**
|
|
|
|
- **Language Requirement**: All comments inside the code (JSDoc and internal) **MUST be written in Chinese**.
|
|
- **Mandatory Positive Constraint**: Every new **interface**, **type**, **exported or module-level constant**, **function component**, and **business logic function** MUST have a JSDoc `/** */` comment in **Chinese**. The only exception is for local variables within a function that are immediately obvious and self-explanatory.
|
|
- **Public API/Props/Interfaces**: Use JSDoc style `/** ... */` **mandatory** for every interface definition and **every single property** within that interface.
|
|
- **Methods & Functions**: Every function (exported or internal) **must** have a `/** ... */` comment explaining its purpose, parameters, and return value.
|
|
- **Internal Logic**: Use double-slash `//` for step-by-step explanations inside function bodies.
|
|
```tsx
|
|
/**
|
|
* 用户数据
|
|
*/
|
|
interface UserDetail {
|
|
id: number;
|
|
name: string;
|
|
}
|
|
|
|
interface UserCardProps {
|
|
/** 用户数据详情 */
|
|
data: UserDetail;
|
|
}
|
|
|
|
export const UserCard = ({ data }: UserCardProps) => {
|
|
/**
|
|
*点击用户中心
|
|
*/
|
|
const handleProfileClick = () => {
|
|
// 检查用户id
|
|
if (data.id) {
|
|
console.log('Navigating...');
|
|
}
|
|
};
|
|
|
|
return <div className="user-card" onClick={handleProfileClick}>...</div>;
|
|
};
|
|
```
|
|
|
|
## Summary Checklist
|
|
|
|
- [ ] Folder/File name is kebab-case.
|
|
|
|
- [ ] Function name is PascalCase.
|
|
|
|
- [ ] Props are constrained by a type/interface.
|
|
|
|
- [ ] Styles are in index.scss using a unique root class and nesting.
|
|
|
|
- [ ] Large static data is moved to a separate .ts file.
|
|
|
|
- [ ] Proper use of /** */ for definitions and // for logic.
|
|
|
|
- [ ] Types are organized: in-file if single, types.ts if multiple.
|
|
- [ ] **CRITICAL**: Every interface, property, and method must have **Chinese comments** using JSDoc (`/** */`) style. |