Documentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
本文档包含编写代码时需要遵循的规则。
这里的目标是拥有一个一致的代码库，易于阅读和维护。
为此，比起过于简洁，冗长一些更好。
请始终记住，人们阅读代码的次数远多于他们编写代码的次数，特别是在开源项目中，任何人都可以贡献。
有很多规则没有在此定义，但可以通过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>;
};
(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
使用Linaria styled对组件进行样式化。
// ❌ Bad
<div className="my-class">Hello World</div>
// ✅ Good
const StyledTitle = styled.div`
color: red;
`;
// ❌ 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};
`;
强制不允许类型导入
避免类型导入。 为强制实施此标准，Oxlint 规则会检查并报告所有类型导入。 这有助于在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';
为什么不允许类型导入
-
一致性：通过避免类型导入并为类型和值导入使用单一方法，代码库在其模块导入风格上保持一致性。
-
可读性：无类型导入提高代码可读性，使得在导入值或类型时更显而易见。 这减少了歧义，并使理解导入符号的用途更容易。
-
可维护性：它增强了代码库的可维护性，因为开发人员可以在审查或修改代码时识别和定位仅类型导入。
Oxlint 规则
Oxlint 规则，typescript/consistent-type-imports，强制执行不允许类型导入标准。 该规则会生成错误或警告以提示任何类型导入的违规。
请注意，此规则专门针对在罕见的边缘情况中发生的非预期类型导入。 TypeScript 本身也不鼓励这种做法，如TypeScript 3.8 发行说明所述。 在大多数情况下，您不需要使用仅类型导入。
为确保您的代码符合此规则，请确保在开发工作流程中运行 Oxlint。