292 lines
7.6 KiB
Plaintext
292 lines
7.6 KiB
Plaintext
---
|
|
title: 样式指南
|
|
icon: 画笔
|
|
---
|
|
|
|
本文档包含编写代码时需要遵循的规则。
|
|
|
|
这里的目标是拥有一个一致的代码库，易于阅读和维护。
|
|
|
|
为此，比起过于简洁，冗长一些更好。
|
|
|
|
请始终记住，人们阅读代码的次数远多于他们编写代码的次数，特别是在开源项目中，任何人都可以贡献。
|
|
|
|
有很多规则没有在此定义，但可以通过linters自动检查。
|
|
|
|
## React
|
|
|
|
### 使用函数组件
|
|
|
|
始终使用 TSX 函数组件。
|
|
|
|
不要使用带有`const`的默认`import`，因为它更难阅读，并且更难通过代码补全功能导入。
|
|
|
|
```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>;
|
|
};
|
|
```
|
|
|
|
### 属性
|
|
|
|
创建props类型并称为`(ComponentName)Props`，如果不需要导出它。
|
|
|
|
使用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
|
|
/* ✅ - 良好，明确定义组件的
|
|
* 属性类型 (OwnProps)
|
|
* - 此方法不会自动包含 children 属性。如果
|
|
* 您想要包含它，您必须在 OwnProps 中指定它。
|
|
*/
|
|
type EmailFieldProps = {
|
|
value: string;
|
|
};
|
|
|
|
const EmailField = ({ value }: EmailFieldProps) => (
|
|
<TextInput value={value} disabled fullWidth />
|
|
);
|
|
```
|
|
|
|
#### JSX元素中禁止单变量属性传播
|
|
|
|
避免在JSX元素中使用单个变量属性传播，如`{...props}`。 这种做法通常会导致代码不易读且难以维护，因为不清楚组件接收了哪些属性。
|
|
|
|
```tsx
|
|
/* ❌ - Bad, spreads a single variable prop into the underlying component
|
|
*/
|
|
const MyComponent = (props: OwnProps) => {
|
|
return <OtherComponent {...props} />;
|
|
}
|
|
```
|
|
|
|
```tsx
|
|
/* ✅ - 良好，明确列出所有属性
|
|
* - 增强可读性和可维护性
|
|
*/
|
|
const MyComponent = ({ prop1, prop2, prop3 }: MyComponentProps) => {
|
|
return <OtherComponent {...{ prop1, prop2, prop3 }} />;
|
|
};
|
|
```
|
|
|
|
理由：
|
|
|
|
* 一目了然，它更清楚哪个属性代码传递下来，这使得理解和维护更容易。
|
|
* 这有助于防止组件间通过属性的紧密耦合。
|
|
* Linting工具使显式列出属性时更易于识别拼写错误或未使用的属性。
|
|
|
|
## JavaScript
|
|
|
|
### 使用nullish 合并运算符 `??`
|
|
|
|
```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
|
|
// ❌ 糟糕
|
|
onClick && onClick();
|
|
|
|
// ✅ 良好
|
|
onClick?.();
|
|
```
|
|
|
|
## TypeScript
|
|
|
|
### 使用 `type` 替代 `interface`
|
|
|
|
总是使用 `type` 而不是 `interface`，因为它们几乎总是重叠，而 `type` 更灵活。
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
interface MyInterface {
|
|
name: string;
|
|
}
|
|
|
|
// ✅ Good
|
|
type MyType = {
|
|
name: string;
|
|
};
|
|
```
|
|
|
|
### 使用字符串字面量代替枚举
|
|
|
|
[字符串字面量](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types)是TypeScript中处理枚举值的首选方式。 它们可以更轻松地使用Pick和Omit扩展，并提供更好的开发者体验，特别是在代码补全时。
|
|
|
|
您可以查看[这里](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums)了解为什么TypeScript建议避免使用枚举。
|
|
|
|
```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和内部库
|
|
|
|
应使用GraphQL codegen生成的枚举。
|
|
|
|
在使用内部库时, 使用枚举更好，这样内部库不必暴露不属于内部API的字符串文字类型。
|
|
|
|
示例：
|
|
|
|
```TSX
|
|
const {
|
|
setHotkeyScopeAndMemorizePreviousScope,
|
|
goBackToPreviousHotkeyScope,
|
|
} = usePreviousHotkeyScope();
|
|
|
|
setHotkeyScopeAndMemorizePreviousScope(
|
|
RelationPickerHotkeyScope.RelationPicker,
|
|
);
|
|
```
|
|
|
|
## 样式
|
|
|
|
### 使用StyledComponents
|
|
|
|
使用[Linaria styled](https://github.com/callstack/linaria)对组件进行样式化。
|
|
|
|
```tsx
|
|
// ❌ Bad
|
|
<div className="my-class">Hello World</div>
|
|
```
|
|
|
|
```tsx
|
|
// ✅ Good
|
|
const StyledTitle = styled.div`
|
|
color: red;
|
|
`;
|
|
```
|
|
|
|
在“真实”组件和Styled 组件之间的区别，前置“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};
|
|
`;
|
|
```
|
|
|
|
## 强制不允许类型导入
|
|
|
|
避免类型导入。 为强制实施此标准，Oxlint 规则会检查并报告所有类型导入。 这有助于在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';
|
|
```
|
|
|
|
### 为什么不允许类型导入
|
|
|
|
* **一致性**：通过避免类型导入并为类型和值导入使用单一方法，代码库在其模块导入风格上保持一致性。
|
|
|
|
* **可读性**：无类型导入提高代码可读性，使得在导入值或类型时更显而易见。 这减少了歧义，并使理解导入符号的用途更容易。
|
|
|
|
* **可维护性**：它增强了代码库的可维护性，因为开发人员可以在审查或修改代码时识别和定位仅类型导入。
|
|
|
|
### Oxlint 规则
|
|
|
|
Oxlint 规则，`typescript/consistent-type-imports`，强制执行不允许类型导入标准。 该规则会生成错误或警告以提示任何类型导入的违规。
|
|
|
|
请注意，此规则专门针对在罕见的边缘情况中发生的非预期类型导入。 TypeScript 本身也不鼓励这种做法，如[TypeScript 3.8 发行说明](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html)所述。 在大多数情况下，您不需要使用仅类型导入。
|
|
|
|
为确保您的代码符合此规则，请确保在开发工作流程中运行 Oxlint。
|