From cd9bac576f09c940002750dcb802e30d12b35ec3 Mon Sep 17 00:00:00 2001 From: sundongyu <2811054731@qq.com> Date: Thu, 30 May 2024 20:17:51 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=83=20docs:=E4=BF=AE=E6=94=B9=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .eslintrc | 195 +++++++++++++++++++++++++++++++++++++++++++++++++ .eslintrc.js | 24 +++--- package.md | 2 +- tsconfig.json | 2 +- vite.config.ts | 2 +- 5 files changed, 210 insertions(+), 15 deletions(-) create mode 100644 .eslintrc diff --git a/.eslintrc b/.eslintrc new file mode 100644 index 0000000..caea809 --- /dev/null +++ b/.eslintrc @@ -0,0 +1,195 @@ +{ + "extends": [ + // 这一行告诉ESLint去使用@typescript-eslint/recommended规则集。这个规则集包含了TypeScript团队推荐的一系列规则，有助于识别TypeScript代码中的常见问题，比如语法错误、潜在的类型问题等。 + "plugin:@typescript-eslint/recommended", + // 这行配置引入了Vue 3的官方ESLint插件推荐的规则集。它包含了对于Vue 3单文件组件(SFCs)的最佳实践建议，帮助开发者遵循Vue的编码规范，包括模板、脚本和样式部分的检查 + "plugin:vue/vue3-recommended", + // 此行配置启用了Prettier的ESLint插件，并使用其推荐的规则。Prettier是一个流行的代码格式化工具，能够自动格式化代码以保持一致的风格。通过此配置，你的代码风格将与Prettier的标准保持一致，减少因格式差异导致的代码审查冲突。 + "plugin:prettier/recommended" + ], + "env": { + // 告诉ESLint你的代码将在浏览器环境中运行。因此，ESLint会启用或强化那些与浏览器环境相关的规则，比如禁止使用Node.js特有的全局变量(如require)。 + "browser": true, + // 表明你的代码设计为在Node.js环境中执行。启用这个选项后，ESLint会认识Node.js的全局变量和Node.js特有的API调用，避免这些被误报为错误。 + "node": true, + // 指出你的项目使用Jest作为测试框架。这会配置ESLint以理解Jest的全局变量和函数，确保在编写测试代码时不会因为使用了Jest的特性而触发不必要的警告或错误。 + "jest": true, + // 指示你的代码基于ECMAScript 6(ES6，也称作ES2015)或更高版本的标准。启用此选项后，ESLint会支持ES6的语法特性，并根据这些新标准调整相关规则，比如允许使用箭头函数、解构赋值等ES6特性。 + "es6": true + }, + "plugins": [ + // 这个插件使得ESLint能够理解并检查Vue.js单文件组件(SFCs)中的代码。它提供了对Vue模板语法、script部分以及style部分的 linting 规则，帮助开发者遵循Vue的最佳实践，提升代码质量和可维护性 + "vue", + // 插件是专门为TypeScript设计的，它允许ESLint理解和 lint TypeScript 代码。这个插件集成了许多有用的规则，用以识别TypeScript特有的一些潜在问题，比如类型错误提示、不必要的类型断言等，从而提高TypeScript代码的质量和类型安全性。 + "@typescript-eslint" + ], + "globals": { + // 这两个全局变量通常与Cypress测试框架相关，cy是Cypress提供的命令链方法的主入口点，用于编写测试代码；Cypress则是该框架的全局对象，包含配置和其他功能。标记为readonly表示这些变量不应在代码中被重新赋值，仅用于读取和调用。 + "cy": "readonly", + "Cypress": "readonly", + // 表示clipboardData是一个预期存在的全局变量，可能与浏览器的剪贴板操作有关，标记为只读意味着它不应该被修改 + "clipboardData": "readonly", + // 定义了一个名为PKG_VERSION的全局变量，这里的true表示这是一个可写的全局变量，没有特别限制其使用方式。这种变量可能用于存储项目版本信息等。 + "PKG_VERSION": true, + // 这两个全局变量与Vue 3的Composition API紧密相关。defineProps用于定义组件接收的props，而defineEmits用于定义组件可以发出的事件。它们都被标记为只读，意味着这些函数不应该被赋予新的值，仅用于组件内部的属性和事件声明 + "defineProps": "readonly", + "defineEmits": "readonly" + }, + "parserOptions": { + // 指定了ESLint应该使用@typescript-eslint/parser作为代码解析器。这个解析器是专门为TypeScript设计的，能够理解TypeScript的语法特性，使得ESLint能够正确地解析和 lint TypeScript 代码。 + "parser": "@typescript-eslint/parser", + // 告诉ESLint你的代码使用的是ES模块(import/export语法)，而不是传统的CommonJS模块(如require)。这会影响如何解析模块导入导出语句 + "sourceType": "module", + // 允许在代码的任何位置使用import和export语句，而不局限于模块顶层。这在某些特定的项目配置或使用场景下可能有用，但通常建议仅在模块顶层使用导入导出以遵循最佳实践。 + "allowImportExportEverywhere": true, + // 启用对JSX的支持。这意味着ESLint会正确解析包含JSX元素(一种HTML-like语法，常用于React和其他库中编写用户界面)的代码，不会将其视为错误。当你的项目中包含前端组件并使用JSX编写时，这一设置是必要的。 + "ecmaFeatures": { + "jsx": true + } + }, + "settings": { + // 这个设置指定了ESLint在检查导入语句时应考虑的文件扩展名列表。列表中的每一个扩展名都代表了一种ESLint会认为是有效导入目标的文件类型。 + "import/extensions": [ + ".js", + ".jsx", + ".ts", + ".tsx" + ] + }, + // 这段配置详细地定义了ESLint的规则设置，覆盖了代码风格、导入管理、以及TypeScript和Vue特定的规则。以下是一些关键规则及其含义的简要说明： + // 通用代码风格规则 + // "no-console": ["error", { "allow": ["info", "warn", "error"] }]: 错误级别地禁止使用console.log等方法，但允许console.info、console.warn和console.error。 + // "no-continue": "off", "no-restricted-syntax": "off", "no-plusplus": "off" 等: 这些规则被关闭，意味着允许使用continue语句、不限制特定语法结构(如for循环)、允许自增自减操作符等。 + // "no-param-reassign": "off", "no-shadow": "off": 关闭参数重赋值和变量阴影的检查。 + // "no-underscore-dangle": ["error"]: 错误级别地禁止在标识符中使用前导或尾随下划线(某些例外可能通过其他配置允许)。 + // 未使用变量和表达式 + // "no-unused-vars": "off", "no-unused-expressions": "off": 关闭未使用变量和未使用的表达式的检查。 + // 函数和循环 + // "func-names": "off", "guard-for-in": "off", "consistent-return": "off": 不强制函数命名规则、不检查for...in循环的安全性、不强制函数返回一致性。 + // 导入规则 + // "import/extensions": "off", "import/no-unresolved": "off", "import/no-extraneous-dependencies": "off": 关闭导入文件扩展名检查、未解决的导入路径检查、以及禁止导入非直接依赖。 + // "import/prefer-default-export": "off": 不强制模块使用默认导出。 + // TypeScript规则 + // @typescript-eslint: 大多数TypeScript相关的规则被关闭或放宽，如允许any类型、不强制模块边界类型、允许require导入、允许空函数、允许特定类型注释等。但也有配置，如"@typescript-eslint/no-unused-vars"，设置为警告级别，并指定了忽略模式以忽略以_开头的变量。 + // Vue规则 + // "vue/require-default-prop", "vue/multi-word-component-names", "vue/no-deprecated-slot-attribute": 这些Vue规则被关闭，意味着组件不必提供默认prop、组件名称不必多词、允许使用已废弃的slot属性。 + // 整体来看，这些规则配置放松了很多常见的代码风格和最佳实践检查，可能旨在提高开发速度或适应特定团队的编码习惯。然而，过度放宽规则可能牺牲代码质量和可维护性，因此建议根据项目实际需要仔细权衡。 + "rules": { + "no-console": [ + "error", + { + "allow": ["info", "warn", "error"] + } + ], + // code style config + "no-continue": "off", + "no-restricted-syntax": "off", + "no-plusplus": "off", + "no-param-reassign": "off", + "no-shadow": "off", + "no-underscore-dangle": ["error"], + "no-unused-vars": "off", + "no-unused-expressions": "off", + "no-return-assign": "off", + "no-use-before-define": "off", + "guard-for-in": "off", + "consistent-return": "off", + "no-restricted-globals": "off", + "default-param-last": "off", + "default-case": "off", + "prefer-spread": "off", + // import config + "import/extensions": "off", + "import/no-unresolved": "off", + "import/no-extraneous-dependencies": "off", + "import/prefer-default-export": "off", + "import/no-relative-packages": "off", + // typescript config + "@typescript-eslint/no-explicit-any": "off", + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-require-imports": 0, + "@typescript-eslint/no-var-requires": 0, + "@typescript-eslint/prefer-for-of": 0, + "@typescript-eslint/ban-types": 0, + "@typescript-eslint/no-unused-vars": [1, + { + "argsIgnorePattern": "^_", + "varsIgnorePattern": "^_" + } + ], + "@typescript-eslint/no-empty-function": 0, + "@typescript-eslint/ban-ts-comment": 0, + "vue/require-default-prop": 0, + "vue/multi-word-component-names": 0, + "vue/no-deprecated-slot-attribute": 0 + }, + "overrides": [ + { + // "files": ["*.vue"]: 指定此override应用于所有扩展名为.vue的文件，即Vue单文件组件(SFCs)。 在rules部分，针对Vue组件设置了特定的规则： + "files": ["*.vue"], + // 此规则强制组件名称在模板中必须遵循“kebab-case”(短横线连接的小写单词，例如)。数字2表示如果违反此规则，ESLint将以错误级别报告(最严格的级别，通常会导致构建失败或警告)。 + "rules": { + "vue/component-name-in-template-casing": [2, "kebab-case"], + // 这个规则被设置为0，意味着完全关闭了对组件默认属性(props)的要求。Vue通常推荐为组件的props提供默认值，以增强组件的可复用性，但此处决定不强制执行此最佳实践。 + "vue/require-default-prop": 0 + } + }, + { + // "files": 列出了覆盖规则将应用的文件路径模式。 + "files": [ + // **/_example/*: 匹配任何层级下以_example为目录名的文件。 + "**/_example/*", + // **/_example - ts/*: 类似地，匹配任何层级下以_example - ts为目录名的 + "**/_example - ts/*", + // script/**/* 和script/*: 匹配script目录下的所有文件，无论深度如何。 + "script/**/* ", + "script/*", + // *.js: 匹配任何直接位于根目录下的.js文件。 + "*.js", + // site/**/*和site/*: 匹配site目录下的所有文件，不论层级。 + "site/**/*", + // + "site/*" + ], + // "rules": 定义了在上述指定的文件范围内生效的特定规则。 + "rules": { + // "no-var-requires": 0: 禁止使用require语句中的变量声明(var关键字)，但在这些文件中该规则被关闭。 + "no-var-requires": 0, + // "no-console": 0: 允许使用console.log等console方法，不报错。 + "no-console": 0, + // "no-unused-expressions": 0: 不检查未使用的表达式，如未赋值的函数调用。 + "no-unused-expressions": 0, + // "no-alert": 0: 允许使用alert函数，不报错。 + "no-alert": 0 + } + }, + { + // "files": 指定了覆盖规则适用的文件类型，这里是所有的TypeScript (*.ts) 和 TypeScript with JSX (*.tsx) 文件。 + "files": [ + "*.ts", + "*.tsx" + ], + // "rules": 针对这些文件类型，配置了一个特定的TypeScript ESLint规则 + "rules": { + // "@typescript-eslint/explicit-function-return-type": 0: 禁用了 + "@typescript-eslint/explicit-function-return-type": 0 + } + }, + { + // "files": 指定了覆盖规则适用的文件模式，这里是所有以.test.js结尾的文件，即测试脚本文件。 + "files": [ + "*.test.js" + ], + "rules": { + // "import/no-dynamic-require": "off": 关闭了import/no-dynamic-require规则。这条规则通常禁止在运行时动态地使用require()来导入模块，以鼓励静态分析和提前发现潜在的模块加载错误。但在测试环境中，动态加载模块可能是为了模拟或测试特定条件下的行为，因此在这个上下文中关闭该规则是有道理的 + "import/no-dynamic-require": "off", + // "global-require": "off": 同样，关闭了global-require规则。这条规则通常建议避免在全局作用域使用require()，鼓励模块化的代码结构。然而，在测试文件中，有时直接在全局作用域使用require()来引入测试工具、模拟模块或设置测试环境是常见的做法，因此在此场景下关闭该规则可以减少不必要的警告。 + "global-require": "off" + } + }, + // 单独的"files": "*"}配置段在ESLint的overrides部分表示一个非常宽泛的覆盖规则，理论上意在应用于所有文件 + { + "files": "*" + } + ] +} \ No newline at end of file diff --git a/.eslintrc.js b/.eslintrc.js index 8c65b00..e741a04 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -2,23 +2,23 @@ "extends": [ // 这一行告诉ESLint去使用@typescript-eslint/recommended规则集。这个规则集包含了TypeScript团队推荐的一系列规则，有助于识别TypeScript代码中的常见问题，比如语法错误、潜在的类型问题等。 "plugin:@typescript-eslint/recommended", - // 这行配置引入了Vue 3的官方ESLint插件推荐的规则集。它包含了对于Vue 3单文件组件（SFCs）的最佳实践建议，帮助开发者遵循Vue的编码规范，包括模板、脚本和样式部分的检查 + // 这行配置引入了Vue 3的官方ESLint插件推荐的规则集。它包含了对于Vue 3单文件组件(SFCs)的最佳实践建议，帮助开发者遵循Vue的编码规范，包括模板、脚本和样式部分的检查 "plugin:vue/vue3-recommended", // 此行配置启用了Prettier的ESLint插件，并使用其推荐的规则。Prettier是一个流行的代码格式化工具，能够自动格式化代码以保持一致的风格。通过此配置，你的代码风格将与Prettier的标准保持一致，减少因格式差异导致的代码审查冲突。 "plugin:prettier/recommended" ], "env": { - // 告诉ESLint你的代码将在浏览器环境中运行。因此，ESLint会启用或强化那些与浏览器环境相关的规则，比如禁止使用Node.js特有的全局变量（如require）。 + // 告诉ESLint你的代码将在浏览器环境中运行。因此，ESLint会启用或强化那些与浏览器环境相关的规则，比如禁止使用Node.js特有的全局变量(如require)。 "browser": true, // 表明你的代码设计为在Node.js环境中执行。启用这个选项后，ESLint会认识Node.js的全局变量和Node.js特有的API调用，避免这些被误报为错误。 "node": true, // 指出你的项目使用Jest作为测试框架。这会配置ESLint以理解Jest的全局变量和函数，确保在编写测试代码时不会因为使用了Jest的特性而触发不必要的警告或错误。 "jest": true, - // 指示你的代码基于ECMAScript 6（ES6，也称作ES2015）或更高版本的标准。启用此选项后，ESLint会支持ES6的语法特性，并根据这些新标准调整相关规则，比如允许使用箭头函数、解构赋值等ES6特性。 + // 指示你的代码基于ECMAScript 6(ES6，也称作ES2015)或更高版本的标准。启用此选项后，ESLint会支持ES6的语法特性，并根据这些新标准调整相关规则，比如允许使用箭头函数、解构赋值等ES6特性。 "es6": true }, "plugins": [ - // 这个插件使得ESLint能够理解并检查Vue.js单文件组件（SFCs）中的代码。它提供了对Vue模板语法、script部分以及style部分的 linting 规则，帮助开发者遵循Vue的最佳实践，提升代码质量和可维护性 + // 这个插件使得ESLint能够理解并检查Vue.js单文件组件(SFCs)中的代码。它提供了对Vue模板语法、script部分以及style部分的 linting 规则，帮助开发者遵循Vue的最佳实践，提升代码质量和可维护性 "vue", // 插件是专门为TypeScript设计的，它允许ESLint理解和 lint TypeScript 代码。这个插件集成了许多有用的规则，用以识别TypeScript特有的一些潜在问题，比如类型错误提示、不必要的类型断言等，从而提高TypeScript代码的质量和类型安全性。 "@typescript-eslint" @@ -38,11 +38,11 @@ "parserOptions": { // 指定了ESLint应该使用@typescript-eslint/parser作为代码解析器。这个解析器是专门为TypeScript设计的，能够理解TypeScript的语法特性，使得ESLint能够正确地解析和 lint TypeScript 代码。 "parser": "@typescript-eslint/parser", - // 告诉ESLint你的代码使用的是ES模块（import/export语法），而不是传统的CommonJS模块（如require）。这会影响如何解析模块导入导出语句 + // 告诉ESLint你的代码使用的是ES模块(import/export语法)，而不是传统的CommonJS模块(如require)。这会影响如何解析模块导入导出语句 "sourceType": "module", // 允许在代码的任何位置使用import和export语句，而不局限于模块顶层。这在某些特定的项目配置或使用场景下可能有用，但通常建议仅在模块顶层使用导入导出以遵循最佳实践。 "allowImportExportEverywhere": true, - // 启用对JSX的支持。这意味着ESLint会正确解析包含JSX元素（一种HTML-like语法，常用于React和其他库中编写用户界面）的代码，不会将其视为错误。当你的项目中包含前端组件并使用JSX编写时，这一设置是必要的。 + // 启用对JSX的支持。这意味着ESLint会正确解析包含JSX元素(一种HTML-like语法，常用于React和其他库中编写用户界面)的代码，不会将其视为错误。当你的项目中包含前端组件并使用JSX编写时，这一设置是必要的。 "ecmaFeatures": { "jsx": true } @@ -59,9 +59,9 @@ // 这段配置详细地定义了ESLint的规则设置，覆盖了代码风格、导入管理、以及TypeScript和Vue特定的规则。以下是一些关键规则及其含义的简要说明： // 通用代码风格规则 // "no-console": ["error", { "allow": ["info", "warn", "error"] }]: 错误级别地禁止使用console.log等方法，但允许console.info、console.warn和console.error。 - // "no-continue": "off", "no-restricted-syntax": "off", "no-plusplus": "off" 等: 这些规则被关闭，意味着允许使用continue语句、不限制特定语法结构（如for循环）、允许自增自减操作符等。 + // "no-continue": "off", "no-restricted-syntax": "off", "no-plusplus": "off" 等: 这些规则被关闭，意味着允许使用continue语句、不限制特定语法结构(如for循环)、允许自增自减操作符等。 // "no-param-reassign": "off", "no-shadow": "off": 关闭参数重赋值和变量阴影的检查。 - // "no-underscore-dangle": ["error"]: 错误级别地禁止在标识符中使用前导或尾随下划线（某些例外可能通过其他配置允许）。 + // "no-underscore-dangle": ["error"]: 错误级别地禁止在标识符中使用前导或尾随下划线(某些例外可能通过其他配置允许)。 // 未使用变量和表达式 // "no-unused-vars": "off", "no-unused-expressions": "off": 关闭未使用变量和未使用的表达式的检查。 // 函数和循环 @@ -129,12 +129,12 @@ }, "overrides": [ { - // "files": ["*.vue"]: 指定此override应用于所有扩展名为.vue的文件，即Vue单文件组件（SFCs）。 在rules部分，针对Vue组件设置了特定的规则： + // "files": ["*.vue"]: 指定此override应用于所有扩展名为.vue的文件，即Vue单文件组件(SFCs)。 在rules部分，针对Vue组件设置了特定的规则： "files": ["*.vue"], - // 此规则强制组件名称在模板中必须遵循“kebab-case”（短横线连接的小写单词，例如）。数字2表示如果违反此规则，ESLint将以错误级别报告（最严格的级别，通常会导致构建失败或警告）。 + // 此规则强制组件名称在模板中必须遵循“kebab-case”(短横线连接的小写单词，例如)。数字2表示如果违反此规则，ESLint将以错误级别报告(最严格的级别，通常会导致构建失败或警告)。 "rules": { "vue/component-name-in-template-casing": [2, "kebab-case"], - // 这个规则被设置为0，意味着完全关闭了对组件默认属性（props）的要求。Vue通常推荐为组件的props提供默认值，以增强组件的可复用性，但此处决定不强制执行此最佳实践。 + // 这个规则被设置为0，意味着完全关闭了对组件默认属性(props)的要求。Vue通常推荐为组件的props提供默认值，以增强组件的可复用性，但此处决定不强制执行此最佳实践。 "vue/require-default-prop": 0 } }, @@ -157,7 +157,7 @@ ], // "rules": 定义了在上述指定的文件范围内生效的特定规则。 "rules": { - // "no-var-requires": 0: 禁止使用require语句中的变量声明（var关键字），但在这些文件中该规则被关闭。 + // "no-var-requires": 0: 禁止使用require语句中的变量声明(var关键字)，但在这些文件中该规则被关闭。 "no-var-requires": 0, // "no-console": 0: 允许使用console.log等console方法，不报错。 "no-console": 0, diff --git a/package.md b/package.md index 7b834fa..5953dbc 100644 --- a/package.md +++ b/package.md @@ -21,7 +21,7 @@ "dev": "vite", - + "build": "run-p type-check \"build-only {@}\" --", diff --git a/tsconfig.json b/tsconfig.json index e5c296d..00032f6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -14,7 +14,7 @@ "outDir": "lib", // 生成对应的.d.ts声明文件。 "declaration": true, - // 使用最新的模块系统（如ES模块）。 + // 使用最新的模块系统(如ES模块)。 "module": "esnext", // 使用Node.js的模块解析规则。 "moduleResolution": "node", diff --git a/vite.config.ts b/vite.config.ts index f07c45c..064d5df 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -14,7 +14,7 @@ export default defineConfig({ vueJsx(), ], resolve: { - // 通过alias属性设置了一个路径别名。在这里，@符号被映射到了项目源码目录（src）的绝对路径。这样做可以让开发者在导入模块时使用更简短的路径， + // 通过alias属性设置了一个路径别名。在这里，@符号被映射到了项目源码目录(src)的绝对路径。这样做可以让开发者在导入模块时使用更简短的路径， alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }