{"id":19810754,"url":"https://github.com/sj-distributor/react-coding-conventions","last_synced_at":"2025-05-01T08:32:04.642Z","repository":{"id":115598042,"uuid":"563627968","full_name":"sj-distributor/react-coding-conventions","owner":"sj-distributor","description":"👨‍💻 让代码变得更加赏心悦目","archived":false,"fork":false,"pushed_at":"2024-02-26T03:20:33.000Z","size":22,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T11:48:45.912Z","etag":null,"topics":["coding-conventions","react","react-coding-conventions","react-conventions","react-native","react-native-conventions","react-style-guide","style-guide"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sj-distributor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-09T01:52:01.000Z","updated_at":"2025-02-22T00:37:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"11acb3a6-e729-4346-a01a-a17ae1185c9a","html_url":"https://github.com/sj-distributor/react-coding-conventions","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sj-distributor%2Freact-coding-conventions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sj-distributor%2Freact-coding-conventions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sj-distributor%2Freact-coding-conventions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sj-distributor%2Freact-coding-conventions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sj-distributor","download_url":"https://codeload.github.com/sj-distributor/react-coding-conventions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251847828,"owners_count":21653582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding-conventions","react","react-coding-conventions","react-conventions","react-native","react-native-conventions","react-style-guide","style-guide"],"created_at":"2024-11-12T09:23:15.607Z","updated_at":"2025-05-01T08:32:04.380Z","avatar_url":"https://github.com/sj-distributor.png","language":null,"readme":"# 👨‍💻 React 编码约定\n\n良好的代码规范能够提高代码的可读性，便于 `写作`、`沟通`、`PR Reivew`、减少 `bug`的出现等等，而 `React Coding Conventions` 主要围绕了这几点进行 `React`、`React Native` 的编码约定，统一编码规范，让代码看的更加赏心悦目。\n\n# 状态管理和样式系统\n\n为了减少开发资源之间的学习成本，尽量使用以下建议的状态管理和样式系统，如有添加应该提议题在委员会会议上讨论。\n\n#### 状态管理\n\n- zustand\n- mobx state tree\n- recoil\n- hox\n\n#### 样式系统\n\n- css in js\n- css module\n- sass\n- less\n- tailwind css\n\n# 命名约定\n\n#### 文件、目录命名\n\n文件、目录命名必须以烤串 **（kebab-case）** 命名，例如：`axios-logger`、`home-screen.tsx`、`api-config.ts`\n\n#### 组件\n\n```tsx\n// React 组件必须采用大驼峰命名法（CamelCase）\nconst BaseButton = () =\u003e {...}\n\n// 建议使用接口（interface）声明 props，并以 IxxxProps 的形式命名\ninterface IModalProps {...}\n\nconst Modal = (props: IModalProps) =\u003e {...}\n\n// 组件的回调属性建议以 onXXX 命名\ninterface IModalProps {\n  onClose: () =\u003e void;\n}\n\n// 组件内部处理回调属性函数建议以 handleXXX 命名\nconst handleClose = () =\u003e {...}\n\n\u003cModal onClose={handleClose} /\u003e\n```\n\n#### 变量\n\n```tsx\n// 变量命名应采用小驼峰命名法（camelCase）\nconst userName = \"Tom Lee\";\n```\n\n#### 常量\n\n```tsx\n// 常量应采用大写字母命名\nconst PI = 3.14;\n\n// 多个单词间要用 下划线（_）分割命名\nconst MIN_COUNT = 1;\nconst MAX_COUNT = 2;\n```\n\n#### 函数\n\n```tsx\n// 函数命名建议采用小驼峰命名法（camelCase）\nconst handleClick = () =\u003e {...}\n```\n\n#### Interface\n\n```tsx\n// Interface 建议以 I 开头，采用大驼峰命名法（CamelCase），例如 IUser\ninterface IUser {\n  id: number;\n  name: string;\n}\n```\n\n#### Type\n\n```tsx\n// Type 类型应采用大驼峰命名法（CamelCase），并以 Type 结尾，例如 MethodType\ntype MethodType = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n```\n\n#### Enum\n\n```tsx\n// Enum 枚举类型应采用大驼峰命名法（CamelCase），并以 Enum 结尾，例如 LoginTypeEnum\nenum LoginTypeEnum {\n  Password,\n  VerifyCode,\n}\n```\n\n# 目录结构\n\n#### 总体结构\n\n```\n|- app\n  |- components - 公共组件\n  |- config - 环境配置文件\n  |- hooks - 自定义钩子\n  |- i18n - 多国语言翻译资源\n  |- model - 状态管理文件\n  |- navigation - 导航组件（仅限react native）\n  |- routes - 路由组件（仅限react web）\n  |- screens - 应用屏幕组件（仅限react native）\n  |- pages - 应用页面组件（仅限react web）\n  |- services - 外界连接服务\n  |- theme - 应用主题、间距、颜色、排版\n  |- types - 公共类型\n  |- utils - 辅助工具\n\n```\n\n#### components\n\n应用内可复用组件存放位置，一个目录对应一个组件，如出现组件比较庞大的情况，可拆分数个小组件存放在对应组件目录下，不需要建 `components` 目录。\n\n```\n|- app\n  |- components\n    |- base-button\n      |- base-button.tsx\n      |- base-button-text.tsx\n      |- base-button-left.tsx\n      |- base-button-right.tsx\n```\n\n#### hooks\n\n应用内可复用 `hooks` 或者 `Context Providers`，例如 `use-loading`、`use-popup`、`use-confirm`、`use-keyboard-status`，简单的 `hooks` 可以创建一个文件存放，但是遇到比较复杂的 `hooks` 或者需要结合 `Context Provider` 使用的 `hooks`，需要创建对应目录，并且目录内放置 `index.tsx` 导出。\n\n```\n|- app\n  |- hooks\n    |- use-keyboard-status.ts\n    |- use-confirm\n      |- confirm-context.tsx\n      |- confirm-dialog.tsx\n      |- use-confirm.tsx\n      |- index.tsx\n```\n\n#### screen and pages\n\n应用的页面 **（屏幕）** 组件存放位置，一个页面 **（屏幕）** 组件对应一个目录，如出现页面 **（屏幕）** 比较庞大的情况，可在页面 **（屏幕）** 目录创建 `components` 目录，存放拆分的小组件，但是小组件不能继续有 `components` 目录，\n如果页面 **（屏幕）** 组件逻辑比较多，可使用 `hooks` 拆分逻辑存放到页面（屏幕）目录下。\n\n```\n|- app\n  |- pages\n    |- home\n      |- components\n        |- header\n          |- header.tsx\n        |- footer\n          |- footer.tsx\n      |- home.tsx\n      |- hooks.ts\n```\n\n#### services/api\n\n建议 `api service` 根据 **模块拆分**，并且目录放置 `index.ts` 导出，避免随着功能迭代，单个文件代码超长，影响代码阅读性。\n\n```\n|- app\n  |- services\n    |- api\n      |- api.ts\n      |- api-auth.ts\n      |- api-user.ts\n      |- api-order.ts\n      |- index.ts\n```\n\n#### utils\n\n简单的 `utils` 可以创建一个文件存放，如果遇到比较复杂的 `utils` 可以创建对应目录，并且目录内放置 `index.tsx` 导出。\n\n```\n|- app\n  |- utils\n    |- event-emitter\n      |- event-emitter.ts\n      |- event-emitter.types.ts\n      |- index.ts\n```\n\n\n# 代码规范\n\n#### 不要使用默认导出\n\n使用默认导出会导致命名不一致的问题，使用时需要为其命名。\n\n```tsx\n// Bad\nconst getUsers = () =\u003e {...};\n\nexport default getUsers;\n\n// Good\nexport const getUsers = () =\u003e {...};\n```\n\n#### 使用 ES6 箭头函数\n\n箭头函数能够以更简洁的方式编写函数。\n\n```tsx\n// Bad\nfunction getUsers() {...};\n\n// Good\nconst getUsers = () =\u003e {...};\n```\n\n#### 其他规范\n\n其他规范已写在 ESLint 规则里面\n\nreact：[sj-distributor/eslint-plugin-react](https://github.com/sj-distributor/eslint-plugin-react)\n\nreact-native：[sj-distributor/eslint-plugin-react-native](https://github.com/sj-distributor/eslint-plugin-react-native)\n\n# 关于注释\n\n如何使用注释，其实一直是一个备受争议的话题，在 `《Clean Code》` 这本书说到好的代码是不需要注释的，但是我觉得毕竟现在 `99%` 的语言都是以英语表达为主，并非我们的母语，阅读起来并没有这么流畅，所以合适添加注释是很有必要的，特别我们都是开发业务系统多，适量的注释，对日后维护项目和新接手项目的同事会有一定的帮助。\n\n# 关于依赖锁定\n\n为了确保开发团队成员都使用相同的依赖版本，避免出现依赖冲突，依赖版本不一致的情况，导致影响团队合作效率和项目稳定性 ，采用以下依赖锁定策略：\n\n- 必须将依赖的锁定文件（如 `yarn.lock`、`package-lock.json`、`pnpm-lock.yaml`）上传到 **版本控制系统**。\n- 锁定文件的更新需要严格的代码审查流程控制 `(PR Review)` ，以防止意外的依赖更新和潜在的问题。\n\n# 使用 tailwind css + antd 的一些建议\n\n- 尽可能使用 `className` 去调用 `tailwind css` 的样式。\n- 所有颜色样式需定义在颜色主题配置文件中 `/src/theme/colors.ts`。\n- 所有字体大小样式需定义在 `tailwind.config.ts/.js` 配置文件中的 `theme` 属性中。\n- 一些可以共用的样式也可以考虑定义在主题配置里面: `tailwind.config.ts/.js`\n- 如果需要修改 `Ant Design` 组件的样式，可以利用 `Ant Design` 的[自定义主题功能进行样式配置](https://ant.design/theme-editor-cn#component-style)，然后将样式定义在 `Ant Design` 主题配置文件中。\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsj-distributor%2Freact-coding-conventions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsj-distributor%2Freact-coding-conventions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsj-distributor%2Freact-coding-conventions/lists"}