跳转到主要内容
本文档包含编写代码时需要遵循的规则。 这里的目标是拥有一个一致的代码库，易于阅读和维护。 为此，比起过于简洁，冗长一些更好。 请始终记住，人们阅读代码的次数远多于他们编写代码的次数，特别是在开源项目中，任何人都可以贡献。 有很多规则没有在此定义，但可以通过linters自动检查。

​
React

​
使用函数组件

始终使用 TSX 函数组件。 不要使用带有const的默认import，因为它更难阅读，并且更难通过代码补全功能导入。 
// ❌ 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解构。 
// ❌ 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 适用于属性类型的定义

/* ❌ - 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 />;

/* ✅ - 良好，明确定义组件的
 *      属性类型 (OwnProps)
 *    - 此方法不会自动包含 children 属性。如果
 *      您想要包含它，您必须在 OwnProps 中指定它。
 */
type EmailFieldProps = {
  value: string;
};

const EmailField = ({ value }: EmailFieldProps) => (
  <TextInput value={value} disabled fullWidth />
);

​
JSX元素中禁止单变量属性传播

避免在JSX元素中使用单个变量属性传播，如{...props}。 这种做法通常会导致代码不易读且难以维护，因为不清楚组件接收了哪些属性。 
/* ❌ - Bad, spreads a single variable prop into the underlying component
 */
const MyComponent = (props: OwnProps) => {
  return <OtherComponent {...props} />;
}

/* ✅ - 良好，明确列出所有属性
 *    - 增强可读性和可维护性
 */
const MyComponent = ({ prop1, prop2, prop3 }: MyComponentProps) => {
  return <OtherComponent {...{ prop1, prop2, prop3 }} />;
};
理由：
  • 一目了然，它更清楚哪个属性代码传递下来，这使得理解和维护更容易。
  • 这有助于防止组件间通过属性的紧密耦合。
  • Linting工具使显式列出属性时更易于识别拼写错误或未使用的属性。

​
JavaScript

​
使用nullish 合并运算符 ??

// ❌ 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';

​
使用可选链 ?.

// ❌ 糟糕
onClick && onClick();

// ✅ 良好
onClick?.();

​
TypeScript

​
使用 type 替代 interface

总是使用 type 而不是 interface，因为它们几乎总是重叠，而 type 更灵活。 
// ❌ Bad
interface MyInterface {
  name: string;
}

// ✅ Good
type MyType = {
  name: string;
};

​
使用字符串字面量代替枚举

字符串字面量是TypeScript中处理枚举值的首选方式。 它们可以更轻松地使用Pick和Omit扩展，并提供更好的开发者体验，特别是在代码补全时。 您可以查看这里了解为什么TypeScript建议避免使用枚举。 
// ❌ Bad, utilizes an enum
enum Color {
  Red = "red",
  Green = "green",
  Blue = "blue",
}

let color = Color.Red;

// ✅ Good, utilizes a string literal

let color: "red" | "green" | "blue" = "red";

​
GraphQL和内部库

应使用GraphQL codegen生成的枚举。 在使用内部库时, 使用枚举更好，这样内部库不必暴露不属于内部API的字符串文字类型。 示例： 
const {
  setHotkeyScopeAndMemorizePreviousScope,
  goBackToPreviousHotkeyScope,
} = usePreviousHotkeyScope();

setHotkeyScopeAndMemorizePreviousScope(
  RelationPickerHotkeyScope.RelationPicker,
);

​
样式

​
使用StyledComponents

使用styled-components对组件进行样式化。 
// ❌ Bad
<div className="my-class">Hello World</div>

// ✅ Good
const StyledTitle = styled.div`
  color: red;
`;
在“真实”组件和Styled 组件之间的区别，前置“Styled”命名。 
// ❌ Bad
const Title = styled.div`
  color: red;
`;

// ✅ Good
const StyledTitle = styled.div`
  color: red;
`;

​
主题

大多数组件样式首选利用主题。

​
测量单位

避免在样式化组件中直接使用px或rem值。 所需的值通常已在主题中定义，因此建议为此目的使用主题。

​
颜色

避免引入新颜色;而是使用来自主题的现有调色板。 如果遇到调色板不匹配的情况，请留下评论以便团队纠正。 
// ❌ 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;
`;

// ✅ 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代码中保持一致性和可读性。 
// ❌ Bad
import { type Meta, type StoryObj } from '@storybook/react';

// ❌ Bad
import type { Meta, StoryObj } from '@storybook/react';

// ✅ Good
import { Meta, StoryObj } from '@storybook/react';

​
为什么不允许类型导入

  • 一致性：通过避免类型导入并为类型和值导入使用单一方法，代码库在其模块导入风格上保持一致性。
  • 可读性：无类型导入提高代码可读性，使得在导入值或类型时更显而易见。 这减少了歧义，并使理解导入符号的用途更容易。
  • 可维护性：它增强了代码库的可维护性，因为开发人员可以在审查或修改代码时识别和定位仅类型导入。

​
ESLint规则

ESLint规则，@typescript-eslint/consistent-type-imports，强制执行不允许类型导入标准。 该规则会生成错误或警告以提示任何类型导入的违规。 请注意，此规则专门针对在罕见的边缘情况中发生的非预期类型导入。 TypeScript 本身也不鼓励这种做法，如TypeScript 3.8 发行说明所述。 在大多数情况下，您不需要使用仅类型导入。 为确保您的代码符合此规则，请确保在开发工作流程中运行ESLint。