8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
296 lines
13 KiB
Plaintext
296 lines
13 KiB
Plaintext
---
|
|
title: Οδηγός Στυλ
|
|
image: /images/user-guide/notes/notes_header.png
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/user-guide/notes/notes_header.png" alt="Header" />
|
|
</Frame>
|
|
|
|
Αυτό το έγγραφο περιλαμβάνει τους κανόνες που πρέπει να ακολουθούνται κατά τη συγγραφή κώδικα.
|
|
|
|
Ο στόχος εδώ είναι να έχουμε μια συνεπή βάση κώδικα, που είναι εύκολη στην ανάγνωση και στη συντήρηση.
|
|
|
|
Για αυτό, είναι καλύτερο να είμαστε λίγο πιο επεξηγηματικοί παρά υπερβολικά περιεκτικοί.
|
|
|
|
Να θυμάστε πάντα ότι οι άνθρωποι διαβάζουν κώδικα πιο συχνά από ό,τι τον γράφουν, ειδικά σε ένα έργο ανοιχτού κώδικα, όπου ο καθένας μπορεί να συμβάλει.
|
|
|
|
Υπάρχουν πολλοί κανόνες που δεν ορίζονται εδώ, αλλά ελέγχονται αυτόματα από τα εργαλεία ανάλυσης κώδικα.
|
|
|
|
## React
|
|
|
|
### Χρησιμοποιήστε συναρτησιακές συνιστώσες
|
|
|
|
Πάντα να χρησιμοποιείτε συναρτησιακές συνιστώσες με TSX.
|
|
|
|
Μην χρησιμοποιείτε την προεπιλογή `import` με `const`, γιατί είναι πιο δύσκολο να διαβαστεί και πιο δύσκολο να εισαχθεί με την αυτόματη ολοκλήρωση του κώδικα.
|
|
|
|
```tsx
|
|
// ❌ Bad, harder to read, harder to import with code completion
|
|
const MyComponent = () => {
|
|
return <div>Hello World</div>;
|
|
};
|
|
|
|
export default MyComponent;
|
|
|
|
// ✅ Good, easy to read, easy to import with code completion
|
|
export function MyComponent() {
|
|
return <div>Hello World</div>;
|
|
};
|
|
```
|
|
|
|
### Ιδιότητες
|
|
|
|
Δημιουργήστε τον τύπο των ιδιοτήτων και ονομάστε τον `(ComponentName)Props` αν δεν υπάρχει ανάγκη να εξάγεται.
|
|
|
|
Χρησιμοποιήστε αποδόμηση των ιδιοτήτων.
|
|
|
|
```tsx
|
|
// ❌ Bad, no type
|
|
export const MyComponent = (props) => <div>Hello {props.name}</div>;
|
|
|
|
// ✅ Good, type
|
|
type MyComponentProps = {
|
|
name: string;
|
|
};
|
|
|
|
export const MyComponent = ({ name }: MyComponentProps) => <div>Hello {name}</div>;
|
|
```
|
|
|
|
#### Αποφύγετε τη χρήση `React.FC` ή `React.FunctionComponent` για τον ορισμό τύπων ιδιοτήτων.
|
|
|
|
```tsx
|
|
/* ❌ - Bad, defines the component type annotations with `FC`
|
|
* - With `React.FC`, the component implicitly accepts a `children` prop
|
|
* even if it's not defined in the prop type. This might not always be
|
|
* desirable, especially if the component doesn't intend to render
|
|
* children.
|
|
*/
|
|
const EmailField: React.FC<{
|
|
value: string;
|
|
}> = ({ value }) => <TextInput value={value} disabled fullWidth />;
|
|
```
|
|
|
|
```tsx
|
|
/* ✅ - Good, a separate type (OwnProps) is explicitly defined for the
|
|
* component's props
|
|
* - This method doesn't automatically include the children prop. If
|
|
* you want to include it, you have to specify it in OwnProps.
|
|
*/
|
|
type EmailFieldProps = {
|
|
value: string;
|
|
};
|
|
|
|
const EmailField = ({ value }: EmailFieldProps) => (
|
|
<TextInput value={value} disabled fullWidth />
|
|
);
|
|
```
|
|
|
|
#### Όχι Μονομεταβλητή Διάδοση Ιδιοτήτων (Prop Spreading) σε Στοιχεία JSX
|
|
|
|
Αποφύγετε τη χρήση μονομεταβλητής διάδοσης ιδιοτήτων σε στοιχεία JSX, όπως `{...props}`. Αυτή η πρακτική συχνά οδηγεί σε κώδικα που είναι λιγότερο ευανάγνωστος και πιο δύσκολος στη συντήρηση επειδή δεν είναι σαφές ποιες ιδιότητες λαμβάνει η συνιστώσα.
|
|
|
|
```tsx
|
|
/* ❌ - Bad, spreads a single variable prop into the underlying component
|
|
*/
|
|
const MyComponent = (props: OwnProps) => {
|
|
return <OtherComponent {...props} />;
|
|
}
|
|
```
|
|
|
|
```tsx
|
|
/* ✅ - Good, Explicitly lists all props
|
|
* - Enhances readability and maintainability
|
|
*/
|
|
const MyComponent = ({ prop1, prop2, prop3 }: MyComponentProps) => {
|
|
return <OtherComponent {...{ prop1, prop2, prop3 }} />;
|
|
};
|
|
```
|
|
|
|
Αιτιολογία:
|
|
|
|
- Με μια ματιά, είναι σαφέστερο ποιες ιδιότητες περνά ο κώδικας, καθιστώντας το πιο πιο εύκολο να κατανοηθεί και να συντηρηθεί.
|
|
- Βοηθά στην αποφυγή στενού συσχετισμού μεταξύ συνιστωσών μέσω των ιδιοτήτων τους.
|
|
- Τα εργαλεία ανάλυσης κώδικα βοηθούν στον εντοπισμό ορθογραφικά λανθασμένων ή αχρησιμοποίητων ιδιοτήτων όταν καταγράφετε ρητά τις ιδιότητες.
|
|
|
|
## JavaScript
|
|
|
|
### Χρησιμοποιήστε τον τελεστή `??` του nullish-coalescing
|
|
|
|
```tsx
|
|
// ❌ Bad, can return 'default' even if value is 0 or ''
|
|
const value = process.env.MY_VALUE || 'default';
|
|
|
|
// ✅ Good, will return 'default' only if value is null or undefined
|
|
const value = process.env.MY_VALUE ?? 'default';
|
|
```
|
|
|
|
### Χρησιμοποιήστε την προαιρετική διοχέτευση `?.`
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
onClick && onClick();
|
|
|
|
// ✅ Good
|
|
onClick?.();
|
|
```
|
|
|
|
## TypeScript
|
|
|
|
### Χρησιμοποιήστε `τύπο` αντί του `interface`
|
|
|
|
Πάντα να χρησιμοποιείτε `τύπο` αντί του `interface`, γιατί συνήθως υπερκαλύπτονται και το `τύπο` είναι πιο ευέλικτο.
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
interface MyInterface {
|
|
name: string;
|
|
}
|
|
|
|
// ✅ Good
|
|
type MyType = {
|
|
name: string;
|
|
};
|
|
```
|
|
|
|
### Χρησιμοποιήστε λεκτικά string αντί για enum
|
|
|
|
Οι [Λεκτικές συμβολικές τιμές](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) είναι ο προτιμώμενος τρόπος για να διαχειριστείτε τιμές που μοιάζουν με enum στο TypeScript. Είναι ευκολότερο να επεκταθούν με Pick και Omit, και προσφέρουν καλύτερη εμπειρία προγραμματιστή, ειδικά με την αυτόματη ολοκλήρωση του κώδικα.
|
|
|
|
Μπορείτε να δείτε γιατί το TypeScript προτείνει την αποφυγή χρήσης enum [εδώ](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).
|
|
|
|
```tsx
|
|
// ❌ Bad, utilizes an enum
|
|
enum Color {
|
|
Red = "red",
|
|
Green = "green",
|
|
Blue = "blue",
|
|
}
|
|
|
|
let color = Color.Red;
|
|
```
|
|
|
|
```tsx
|
|
// ✅ Good, utilizes a string literal
|
|
|
|
let color: "red" | "green" | "blue" = "red";
|
|
```
|
|
|
|
#### GraphQL και εσωτερικές βιβλιοθήκες
|
|
|
|
Πρέπει να χρησιμοποιείτε τα enum που δημιουργούνται από το GraphQL codegen.
|
|
|
|
Είναι επίσης καλύτερο να χρησιμοποιείται ένα enum όταν χρησιμοποιείται μια εσωτερική βιβλιοθήκη, ώστε η εσωτερική βιβλιοθήκη να μην χρειάζεται να αποκαλύπτει έναν τύπο λεκτικού string που δεν σχετίζεται με το εσωτερικό API.
|
|
|
|
Παράδειγμα:
|
|
|
|
```TSX
|
|
const {
|
|
setHotkeyScopeAndMemorizePreviousScope,
|
|
goBackToPreviousHotkeyScope,
|
|
} = usePreviousHotkeyScope();
|
|
|
|
setHotkeyScopeAndMemorizePreviousScope(
|
|
RelationPickerHotkeyScope.RelationPicker,
|
|
);
|
|
```
|
|
|
|
## Στυλιστική
|
|
|
|
### Χρησιμοποιήστε StyledComponents
|
|
|
|
Στυλιζάρετε τις συνιστώσες με [styled-components](https://emotion.sh/docs/styled).
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
<div className="my-class">Hello World</div>
|
|
```
|
|
|
|
```tsx
|
|
// ✅ Good
|
|
const StyledTitle = styled.div`
|
|
color: red;
|
|
`;
|
|
```
|
|
|
|
Προθέστε στους στυλιζάρισμένους συνιστούσες την ένδειξη "Styled" για να τις διαφοροποιήσετε από τις "πραγματικές" συνιστώσες.
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
const Title = styled.div`
|
|
color: red;
|
|
`;
|
|
```
|
|
|
|
```tsx
|
|
// ✅ Good
|
|
const StyledTitle = styled.div`
|
|
color: red;
|
|
`;
|
|
```
|
|
|
|
### Θεματική
|
|
|
|
Η χρησιμοποίηση του θέματος για την πλειονότητα της στυλιζάρισης των συνιστωσών είναι η προτιμώμενη προσέγγιση.
|
|
|
|
#### Μονάδες μέτρησης
|
|
|
|
Αποφύγετε τη χρήση των τιμών `px` ή `rem` απευθείας στις στυλιζαρισμένες συνιστωσών. Οι αναγκαίες τιμές συνήθως έχουν ήδη καθοριστεί στο θέμα, έτσι είναι συνιστώμενο να αξιοποιείτε το θέμα για αυτούς τους σκοπούς.
|
|
|
|
#### Χρώματα
|
|
|
|
Αποφύγετε την εισαγωγή νέων χρωμάτων· χρησιμοποιήστε αντ' αυτού τη υπάρχουσα παλέτα από το θέμα. Αν υπάρξει κατάσταση όπου η παλέτα δεν ευθυγραμμίζεται, αφήστε ένα σχόλιο ώστε η ομάδα να μπορεί να το διορθώσει.
|
|
|
|
```tsx
|
|
// ❌ Bad, directly specifies style values without utilizing the theme
|
|
const StyledButton = styled.button`
|
|
color: #333333;
|
|
font-size: 1rem;
|
|
font-weight: 400;
|
|
margin-left: 4px;
|
|
border-radius: 50px;
|
|
`;
|
|
```
|
|
|
|
```tsx
|
|
// ✅ Good, utilizes the theme
|
|
const StyledButton = styled.button`
|
|
color: ${({ theme }) => theme.font.color.primary};
|
|
font-size: ${({ theme }) => theme.font.size.md};
|
|
font-weight: ${({ theme }) => theme.font.weight.regular};
|
|
margin-left: ${({ theme }) => theme.spacing(1)};
|
|
border-radius: ${({ theme }) => theme.border.rounded};
|
|
`;
|
|
```
|
|
|
|
## Επιβολή Εισαγωγών Χωρίς Τύπο
|
|
|
|
Αποφύγετε τις εισαγωγές τύπου. Για την επιβολή αυτού του προτύπου, υπάρχει μια κανόνας ESLint που ελέγχει και αναφέρει οποιεσδήποτε παραβιάσεις εισαγωγής τύπου. Αυτό βοηθά στη διατήρηση της συνέπειας και της αναγνωσιμότητας στον κώδικα TypeScript.
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
import { type Meta, type StoryObj } from '@storybook/react';
|
|
|
|
// ❌ Bad
|
|
import type { Meta, StoryObj } from '@storybook/react';
|
|
|
|
// ✅ Good
|
|
import { Meta, StoryObj } from '@storybook/react';
|
|
```
|
|
|
|
### Why No-Type Imports
|
|
|
|
- **Συνέπεια**: Με την αποφυγή εισαγωγών τύπου και τη χρήση μιας μεθόδου για τις εισαγωγές τύπων και τιμών, η βάση κώδικα παραμένει συνεπής στο στυλ εισαγωγής.
|
|
|
|
- **Αναγνωσιμότητα**: Οι εισαγωγές χωρίς τύπους βελτιώνουν την αναγνωσιμότητα του κώδικα καθιστώντας σαφές όταν εισάγετε τιμές ή τύπους. Αυτό μειώνει την αβεβαιότητα και διευκολύνει την κατανόηση του σκοπού των εισαγωμένων συμβόλων.
|
|
|
|
- **Συντηρησιμότητα**: Ενισχύει τη συντηρησιμότητα της βάσης κώδικα επειδή οι προγραμματιστές μπορούν να εντοπίζουν και να βρίσκουν εισαγωγές μόνο τύπων κατά την αναθεώρηση ή τροποποίηση του κώδικα.
|
|
|
|
### Κανόνας ESLint
|
|
|
|
Ένας κανόνας ESLint, `@typescript-eslint/consistent-type-imports`, επιβάλλει το πρότυπο εισαγωγής χωρίς τύπο. Αυτός ο κανόνας θα δημιουργήσει σφάλματα ή προειδοποιήσεις για οποιεσδήποτε παραβιάσεις εισαγωγής τύπου.
|
|
|
|
Παρακαλώ σημειώστε ότι αυτός ο κανόνας συγκεκριμένα αντιμετωπίζει σπάνιες περιπτώσεις όπου η εισαγωγή τύπων γίνεται κατά λάθος. Το ίδιο το TypeScript αποθαρρύνει αυτήν την πρακτική, όπως αναφέρεται στις [σημειώσεις κυκλοφορίας της έκδοσης 3.8 του TypeScript](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html). Στις περισσότερες περιπτώσεις, δεν θα χρειαστεί να χρησιμοποιήσετε εισαγωγές μόνο τύπων.
|
|
|
|
Για να διασφαλίσετε ότι ο κώδικάς σας συμμορφώνεται με αυτόν τον κανόνα, φροντίστε να εκτελείτε το ESLint ως μέρος της ροής εργασίας ανάπτυξής σας.
|