From cfc67d8dce3bb0498a4e511c19e4af476d22e646 Mon Sep 17 00:00:00 2001 From: Rui Wu Date: Mon, 29 Jul 2024 15:20:40 +0800 Subject: [PATCH] chore: update description and docs --- README.md | 22 ++ packages/uni-app-types/README.md | 276 +++++++++++++------------- packages/uni-app-types/package.json | 2 +- packages/uni-cloud-types/README.md | 260 ++++++++++++------------ packages/uni-cloud-types/package.json | 2 +- packages/uni-types/README.md | 199 +++++++++++++++++++ packages/uni-types/package.json | 2 +- packages/uni-ui-types/README.md | 262 ++++++++++++------------ packages/uni-ui-types/package.json | 2 +- 9 files changed, 610 insertions(+), 417 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ca8d577 --- /dev/null +++ b/README.md @@ -0,0 +1,22 @@ +# @uni-helper/uni-types + +为 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型。 + +## 子包 + +|名称|描述| +|---|---| +|[@uni-helper/uni-app-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types)|为 Vue v3 uni-app 组件提供 TypeScript 类型。| +|[@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-cloud-types)|为 Vue v3 uni-cloud 组件提供 TypeScript 类型。| +|[@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-ui-types)|为 Vue v3 uni-ui 组件提供 TypeScript 类型。| +|[@uni-helper/uni-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-types)|为 Vue v3 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型支持，即以上三者的集合。| + +## 赞助 + +如果这个包对你有所帮助，请考虑 [赞助](https://github.com/ModyQyW/sponsors) 支持。 + +

+ + + +

diff --git a/packages/uni-app-types/README.md b/packages/uni-app-types/README.md index 39713cd..a769f0a 100644 --- a/packages/uni-app-types/README.md +++ b/packages/uni-app-types/README.md @@ -1,143 +1,116 @@ # @uni-helper/uni-app-types -[![License](https://img.shields.io/github/license/uni-helper/uni-app-types)](https://github.com/uni-helper/uni-app-types/blob/main/LICENSE) +
-[![npm](https://img.shields.io/npm/v/@uni-helper/uni-app-types)](https://www.npmjs.com/package/@uni-helper/uni-app-types) +[![License](https://img.shields.io/github/license/uni-helper/uni-types?style=for-the-badge)](https://github.com/uni-helper/uni-types/blob/main/LICENSE) -- [@uni-helper/uni-app-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types) 提供 `uni-app` 组件 TypeScript 类型 -- [@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-cloud-types) 提供 `uni-cloud` 组件 TypeScript 类型 -- [@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-ui-types) 提供 `uni-ui` 组件 TypeScript 类型 -- [@uni-helper/uni-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-types) 集合以上三者 +[![npm](https://img.shields.io/npm/v/%40uni-helper%2Funi-app-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-app-types) -基于 [这个 PR](https://github.com/vuejs/core/pull/3399)，[Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar)（即 Volar） 已经支持。 +[![npm downloads](https://img.shields.io/npm/dm/%40uni-helper%2Funi-app-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-app-types) -安装之后，请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 配置你的 VS Code。启用或安装后需要重启 VS Code。 +
-维护直到官方类型推出。 +- 【当前】[@uni-helper/uni-app-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types) 为 Vue v3 uni-app 组件提供 TypeScript 类型。 +- [@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-cloud-types) 为 Vue v3 uni-cloud 组件提供 TypeScript 类型。 +- [@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-ui-types) 为 Vue v3 uni-ui 组件提供 TypeScript 类型。 +- [@uni-helper/uni-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-types) 为 Vue v3 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型支持，即以上三者的集合。 -**类型和文档的冲突之处，请以文档为准。** +## 起步 -类型源代码在 [uni-helper/uni-app-types](https://github.com/uni-helper/uni-app-types)。欢迎提交 ISSUE 和 PR 改进类型。 +### 配置编辑器/IDE + +请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 将 Volar（Vue 语言服务工具）添加到你的编辑器或 IDE，配置完毕后请重启你的编辑器或 IDE 以确保服务启动。 + +> [!WARNING] +> Volar 需要 v2.0.22 或更高版本，对应地，TypeScript 需要 v5.0.0 或更高版本。 + +### 安装依赖 + +```shell +npm i -D @uni-helper/uni-app-types +``` + +此外你需要确保项目已经安装 Vue v3.0.0 或更高版本，以及 TypeScript v5 或更高版本。 + +> [!TIP] +> 为了避免幽灵依赖（又称幻影依赖，详见 [这篇文章](https://rushjs.io/zh-cn/pages/advanced/phantom_deps/)），请检查你的包管理器。 +> +> 如果你正在使用 yarn v2 或以上版本，请参考 [文档](https://yarnpkg.com/configuration/yarnrc/#nodeLinker) 设置 `nodeLinker` 为 `node_modules`。 +> +> 如果你正在使用 pnpm，请参考 [文档](https://pnpm.io/npmrc#shamefully-hoist) 设置 `shamefully-hoist` 为 `true`。 + +### 配置 TypeScript + +更新 `tsconfig.json`，确保： + +- `compilerOptions.types` 包含 `@uni-helper/uni-app-types` +- `vueCompilerOptions.plugins` 包含 `@uni-helper/uni-app-types/volar-plugin` +- `include` 包含 `vue` 相关文件 + +以下是一个 `tsconfig.json` 示例，你可以直接复制它并粘贴到项目内。请注意，你可能需要稍微调整以匹配你的开发需求，相关依赖需要自行安装。 + +> [!WARNING] +> 再次提醒，TypeScript 需要 v5.0.0 或更高版本。 +> +> 截至 2024-07-28，uni-app 官方提供的 Vue3 + Vite + TypeScript 模板版本相对落后，如果你正在使用它，你需要手动升级。 +> +> 你也可以在这里获取 [社区模板](https://github.com/uni-helper/awesome-uni-app#%E6%A8%A1%E6%9D%BF) 以起步。 + +```jsonc +{ + "compilerOptions": { + "lib": ["DOM", "DOM.Iterable", "ESNext"], + "module": "ESNext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "jsx": "preserve", + "jsxImportSource": "vue", + "noImplicitThis": true, + "strict": true, + "verbatimModuleSyntax": true, + "target": "ESNext", + "useDefineForClassFields": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "skipLibCheck": true, + "types": [ + // uni-app + Vue 3 使用 Vite 构建，需要安装 vite + "vite/client", + // uni API 相关的 TypeScript 类型 + "@dcloudio/types", + // my API 相关的 TypeScript 类型 + "@mini-types/alipay", + // wx API 相关的 TypeScript 类型，需要手动安装依赖 + "miniprogram-api-typings", + // 为 uni-app 组件提供 TypeScript 类型 + "@uni-helper/uni-app-types" + ] + }, + "vueCompilerOptions": { + // 调整 Volar（Vue 语言服务工具）解析行为，用于为 uni-app 组件提供 TypeScript 类型 + "plugins": ["@uni-helper/uni-app-types/volar-plugin"] + }, + "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue", "*.d.ts"] +} +``` + +再次重启你的编辑器或 IDE 以确保服务启动并正确加载配置。如果一切顺利，你应该可以看到类似的 TypeScript 类型提示。 + +![示例](../../assets/uni-app-example.png) ## 使用 -### 配置 - -- 安装依赖 - - ```shell - npm i -D @uni-helper/uni-app-types - ``` - -
- yarn v2 或以上 -

请参考 文档 设置 nodeLinker 为 node_modules。

-
- -
- pnpm -

请参考 文档 设置 shamefully-hoist 为 true。

-
- -
- -- 配置 `tsconfig.json`，确保 `compilerOptions.types` 中含有 `@dcloudio/types` 和 `@uni-helper/uni-app-types`，且 `include` 包含了对应的 `vue` 文件 - -
- 2.0.14 <= Vue Language Features (Volar) & vue-tsc - - ```json - { - "compilerOptions": { - "types": ["@dcloudio/types", "@uni-helper/uni-app-types"] - }, - "vueCompilerOptions": { - "plugins": ["@uni-helper/uni-app-types/volar-plugin"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.7.12 <= Vue Language Features (Volar) & vue-tsc < 2.0.14 - - ```json - { - "compilerOptions": { - "types": ["@dcloudio/types", "@uni-helper/uni-app-types"] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.5.1 <= Vue Language Features (Volar) & vue-tsc < 1.7.12 - - ```json - { - "compilerOptions": { - "types": ["@dcloudio/types", "@uni-helper/uni-app-types"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.0.10 <= Vue Language Features (Volar) & vue-tsc < 1.5.1 - - ```json - { - "compilerOptions": { - "types": ["@dcloudio/types", "@uni-helper/uni-app-types"] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 0.34.16 <= Vue Language Features (Volar) & vue-tsc < 1.0.10 - - ```json - { - "compilerOptions": { - "types": ["@dcloudio/types", "@uni-helper/uni-app-types"] - }, - "vueCompilerOptions": { - "experimentalRuntimeMode": "runtime-uni-app" - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- -- 重启编辑器 / IDE - -### 标注类型 - -推荐使用 `@uni-helper/uni-app-types` 导出的类型为变量标注类型。 +### Template -```vue - +自动为 Template 内对应组件附加 TypeScript 类型提示。 + +![示例](../../assets/uni-app-example.png) + +### Script +推荐使用 `@uni-helper/uni-app-types` 导出的 TypeScript 类型为变量标注类型。 + +```vue -``` -也可以直接使用命名空间来为变量标注类型。 - -```vue +``` +也可以直接使用命名空间来为变量标注类型（不推荐，详见 [typescript-eslint - no-namespace](https://typescript-eslint.io/rules/no-namespace/))。 + +```vue -``` -如果你需要传入事件之外的参数，可以参考以下例子。参数顺序参考了 Vue 文档的示例（见 [在内联事件处理器中访问事件参数](https://cn.vuejs.org/guide/essentials/event-handling.html#accessing-event-argument-in-inline-handlers)）。 - -```vue +``` +如果需要传入事件之外的参数，请参考以下例子和 [Vue 官方文档 - 在内联事件处理器中访问事件参数](https://cn.vuejs.org/guide/essentials/event-handling.html#accessing-event-argument-in-inline-handlers)。 + +```vue + + ``` 请查看 [src](./src) 了解所有类型。 +## 其它 + +### Vue 2 支持情况 + +如果你正在使用 Vue 2、需要组件 TypeScript 类型支持，请使用 Volar v2.0.21 和 @uni-helper/uni-app-types v0.5，这是最后已知可用的版本组合。 + +> [👉 点击获取 Volar v2.0.21 VS Code Extension](../../assets/Vue.volar-2.0.21.vsix) + +如果你正在使用 Vue 2、无需组件 TypeScript 类型支持，请使用 [Vetur](https://github.com/vuejs/vetur)。 + +> [!WARNING] +> Volar 和 Vetur 不可共存，请只启用其中一个。 + +### 类型与文档冲突或类型不正确 + +类型与官方文档的冲突之处，请以官方文档为准。如果发现类型冲突或类型不正确等问题，请考虑在 QQ 群内反馈、微信群内反馈、提交 ISSUE 或 PR，我们将尽快处理，非常感谢你的帮助！🙏 + ## 致谢 最初在 [uni-base-components-types](https://github.com/satrong/uni-base-components-types) 得到了灵感。 基于 [这个 PR](https://github.com/satrong/uni-base-components-types/pull/5) 完成。 + +## 赞助 + +如果这个包对你有所帮助，请考虑 [赞助](https://github.com/ModyQyW/sponsors) 支持。 + +

+ + + +

diff --git a/packages/uni-app-types/package.json b/packages/uni-app-types/package.json index 9a538a7..41dfe81 100644 --- a/packages/uni-app-types/package.json +++ b/packages/uni-app-types/package.json @@ -1,7 +1,7 @@ { "name": "@uni-helper/uni-app-types", "version": "0.0.0", - "description": "为 uni-app 内置组件提供 TypeScript 类型支持。", + "description": "为 uni-app 组件提供 TypeScript 类型", "keywords": ["uni-app", "uniapp", "types", "type"], "homepage": "https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types", "bugs": { diff --git a/packages/uni-cloud-types/README.md b/packages/uni-cloud-types/README.md index 842fa2c..2099abf 100644 --- a/packages/uni-cloud-types/README.md +++ b/packages/uni-cloud-types/README.md @@ -1,150 +1,109 @@ # @uni-helper/uni-cloud-types -[![License](https://img.shields.io/github/license/uni-helper/uni-cloud-types)](https://github.com/uni-helper/uni-cloud-types/blob/main/LICENSE) +
-[![npm](https://img.shields.io/npm/v/@uni-helper/uni-cloud-types)](https://www.npmjs.com/package/@uni-helper/uni-cloud-types) +[![License](https://img.shields.io/github/license/uni-helper/uni-types?style=for-the-badge)](https://github.com/uni-helper/uni-types/blob/main/LICENSE) -- [@uni-helper/uni-app-types](https://github.com/uni-helper/uni-app-types) 提供 `uni-app` 组件类型 -- [@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-cloud-types) （当前仓库）提供 `uni-cloud` 组件类型 -- [@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-ui-types) 提供 `uni-ui` 组件类型 +[![npm](https://img.shields.io/npm/v/%40uni-helper%2Funi-cloud-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-cloud-types) -基于 [这个 PR](https://github.com/vuejs/core/pull/3399)，[Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar)（即 Volar） 已经支持。 +[![npm downloads](https://img.shields.io/npm/dm/%40uni-helper%2Funi-cloud-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-cloud-types) -安装之后，请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 配置你的 VS Code。启用或安装后需要重启 VS Code。 +
-维护直到官方类型推出。 +- [@uni-helper/uni-app-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types) 为 Vue v3 uni-app 组件提供 TypeScript 类型。 +- 【当前】[@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-cloud-types) 为 Vue v3 uni-cloud 组件提供 TypeScript 类型。 +- [@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-ui-types) 为 Vue v3 uni-ui 组件提供 TypeScript 类型。 +- [@uni-helper/uni-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-types) 为 Vue v3 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型支持，即以上三者的集合。 -**类型和文档的冲突之处，请以文档为准。** +## 起步 -类型源代码在 [uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-cloud-types)。欢迎提交 ISSUE 和 PR 改进类型。 +### 配置编辑器/IDE + +请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 将 Volar（Vue 语言服务工具）添加到你的编辑器或 IDE，配置完毕后请重启你的编辑器或 IDE 以确保服务启动。 + +> [!WARNING] +> Volar 需要 v2.0.22 或更高版本，对应地，TypeScript 需要 v5.0.0 或更高版本。 + +### 安装依赖 + +```shell +npm i -D @uni-helper/uni-cloud-types +``` + +此外你需要确保项目已经安装 Vue v3.0.0 或更高版本，以及 TypeScript v5 或更高版本。 + +> [!TIP] +> 为了避免幽灵依赖（又称幻影依赖，详见 [这篇文章](https://rushjs.io/zh-cn/pages/advanced/phantom_deps/)），请检查你的包管理器。 +> +> 如果你正在使用 yarn v2 或以上版本，请参考 [文档](https://yarnpkg.com/configuration/yarnrc/#nodeLinker) 设置 `nodeLinker` 为 `node_modules`。 +> +> 如果你正在使用 pnpm，请参考 [文档](https://pnpm.io/npmrc#shamefully-hoist) 设置 `shamefully-hoist` 为 `true`。 + +### 配置 TypeScript + +更新 `tsconfig.json`，确保： + +- `compilerOptions.types` 包含 `@uni-helper/uni-cloud-types` +- `include` 包含 `vue` 相关文件 + +以下是一个 `tsconfig.json` 示例，你可以直接复制它并粘贴到项目内。请注意，你可能需要稍微调整以匹配你的开发需求，相关依赖需要自行安装。 + +> [!WARNING] +> 再次提醒，TypeScript 需要 v5.0.0 或更高版本。 +> +> 截至 2024-07-28，uni-app 官方提供的 Vue3 + Vite + TypeScript 模板版本相对落后，如果你正在使用它，你需要手动升级。 +> +> 你也可以在这里获取 [社区模板](https://github.com/uni-helper/awesome-uni-app#%E6%A8%A1%E6%9D%BF) 以起步。 + +```jsonc +{ + "compilerOptions": { + "lib": ["DOM", "DOM.Iterable", "ESNext"], + "module": "ESNext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "jsx": "preserve", + "jsxImportSource": "vue", + "noImplicitThis": true, + "strict": true, + "verbatimModuleSyntax": true, + "target": "ESNext", + "useDefineForClassFields": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "skipLibCheck": true, + "types": [ + // uni-app + Vue 3 使用 Vite 构建，需要安装 vite + "vite/client", + // uni API 相关的 TypeScript 类型 + "@dcloudio/types", + // my API 相关的 TypeScript 类型 + "@mini-types/alipay", + // wx API 相关的 TypeScript 类型，需要手动安装依赖 + "miniprogram-api-typings", + // 为 uni-cloud 组件提供 TypeScript 类型 + "@uni-helper/uni-cloud-types" + ] + }, + "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue", "*.d.ts"] +} +``` + +再次重启你的编辑器或 IDE 以确保服务启动并正确加载配置。如果一切顺利，你应该可以看到类似的 TypeScript 类型提示。 + +![示例](../../assets/uni-cloud-example.png) ## 使用 -- 安装依赖 - - ```shell - npm i -D @uni-helper/uni-app-types @uni-helper/uni-cloud-types - ``` - -
- yarn v2/v3 -

请参考 文档 设置 nodeLinker 为 node_modules。

-
- -
- pnpm -

请参考 文档 设置 shamefully-hoist 为 true。

-
- -- 配置 `tsconfig.json`，确保 `compilerOptions.types` 中含有 `@dcloudio/types`、`@uni-helper/uni-app-types` 和 `@uni-helper/uni-cloud-types`，且 `include` 包含了对应的 `vue` 文件 - -
- 2.0.14 <= Vue Language Features (Volar) & vue-tsc - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-cloud-types" - ] - }, - "vueCompilerOptions": { - "plugins": ["@uni-helper/uni-app-types/volar-plugin"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.7.12 <= Vue Language Features (Volar) & vue-tsc < 2.0.14 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-cloud-types" - ] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.5.1 <= Vue Language Features (Volar) & vue-tsc < 1.7.12 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-cloud-types" - ] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.0.10 <= Vue Language Features (Volar) & vue-tsc < 1.5.1 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-cloud-types" - ] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 0.34.16 <= Vue Language Features (Volar) & vue-tsc < 1.0.10 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-cloud-types" - ] - }, - "vueCompilerOptions": { - "experimentalRuntimeMode": "runtime-uni-app" - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -- 重启编辑器 / IDE - -### 标注类型 - -推荐使用 `@uni-helper/uni-cloud-types` 导出的类型为变量标注类型。 +### Template + +自动为 Template 内对应组件附加 TypeScript 类型提示。 + +![示例](../../assets/uni-cloud-example.png) + +### Script + +推荐使用 `@uni-helper/uni-cloud-types` 导出的 TypeScript 类型为变量标注类型。 ```vue + + +``` + +也可以直接使用命名空间来为变量标注类型（不推荐，详见 [typescript-eslint - no-namespace](https://typescript-eslint.io/rules/no-namespace/))。 + +```vue + + + +``` + +如果需要传入事件之外的参数，请参考以下例子和 [Vue 官方文档 - 在内联事件处理器中访问事件参数](https://cn.vuejs.org/guide/essentials/event-handling.html#accessing-event-argument-in-inline-handlers)。 + +```vue + + + +``` + +请查看 [src](./src) 了解所有类型。 + +## 其它 + +### Vue 2 支持情况 + +如果你正在使用 Vue 2、需要组件 TypeScript 类型支持，请使用 Volar v2.0.21 和 @uni-helper/uni-app-types、@uni-helper/uni-cloud-types 和 @uni-helper/uni-ui-types v0.5，这是最后已知可用的版本组合。 + +> [👉 点击获取 Volar v2.0.21 VS Code Extension](../../assets/Vue.volar-2.0.21.vsix) + +如果你正在使用 Vue 2、无需组件 TypeScript 类型支持，请使用 [Vetur](https://github.com/vuejs/vetur)。 + +> [!WARNING] +> Volar 和 Vetur 不可共存，请只启用其中一个。 + +### 类型与文档冲突或类型不正确 + +类型与官方文档的冲突之处，请以官方文档为准。如果发现类型冲突或类型不正确等问题，请考虑在 QQ 群内反馈、微信群内反馈、提交 ISSUE 或 PR，我们将尽快处理，非常感谢你的帮助！🙏 + +## 致谢 + +最初在 [uni-base-components-types](https://github.com/satrong/uni-base-components-types) 得到了灵感。 + +基于 [这个 PR](https://github.com/satrong/uni-base-components-types/pull/5) 完成。 + +## 赞助 + +如果这个包对你有所帮助，请考虑 [赞助](https://github.com/ModyQyW/sponsors) 支持。 + +

+ + + +

diff --git a/packages/uni-types/package.json b/packages/uni-types/package.json index fd537b8..5d9c1eb 100644 --- a/packages/uni-types/package.json +++ b/packages/uni-types/package.json @@ -1,7 +1,7 @@ { "name": "@uni-helper/uni-types", "version": "0.0.0", - "description": "为 uni-app 内置组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型支持。", + "description": "为 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型", "keywords": ["uni-app", "uniapp", "types", "type"], "homepage": "https://github.com/uni-helper/uni-types/tree/main/packages/uni-types", "bugs": { diff --git a/packages/uni-ui-types/README.md b/packages/uni-ui-types/README.md index 834b87f..29e9497 100644 --- a/packages/uni-ui-types/README.md +++ b/packages/uni-ui-types/README.md @@ -1,152 +1,109 @@ # @uni-helper/uni-ui-types -[![License](https://img.shields.io/github/license/uni-helper/uni-ui-types)](https://github.com/uni-helper/uni-ui-types/blob/main/LICENSE) +
-[![npm](https://img.shields.io/npm/v/@uni-helper/uni-ui-types)](https://www.npmjs.com/package/@uni-helper/uni-ui-types) +[![License](https://img.shields.io/github/license/uni-helper/uni-types?style=for-the-badge)](https://github.com/uni-helper/uni-types/blob/main/LICENSE) -- [@uni-helper/uni-app-types](https://github.com/uni-helper/uni-app-types) 提供 `uni-app` 组件类型 -- [@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-cloud-types) 提供 `uni-cloud` 组件类型 -- [@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-ui-types) （当前仓库）提供 `uni-ui` 组件类型 +[![npm](https://img.shields.io/npm/v/%40uni-helper%2Funi-ui-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-ui-types) -基于 [这个 PR](https://github.com/vuejs/core/pull/3399)，[Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar)（即 Volar） 已经支持。 +[![npm downloads](https://img.shields.io/npm/dm/%40uni-helper%2Funi-ui-types?style=for-the-badge)](https://www.npmjs.com/package/@uni-helper/uni-ui-types) -安装之后，请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 配置你的 VS Code。启用或安装后需要重启 VS Code。 +
-维护直到官方类型推出。 +- [@uni-helper/uni-app-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-app-types) 为 Vue v3 uni-app 组件提供 TypeScript 类型。 +- [@uni-helper/uni-cloud-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-cloud-types) 为 Vue v3 uni-cloud 组件提供 TypeScript 类型。 +- 【当前】[@uni-helper/uni-ui-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-ui-types) 为 Vue v3 uni-ui 组件提供 TypeScript 类型。 +- [@uni-helper/uni-types](https://github.com/uni-helper/uni-types/tree/main/packages/uni-types) 为 Vue v3 uni-app 组件、uni-ui 组件和 uni-cloud 组件提供 TypeScript 类型支持，即以上三者的集合。 -**类型和文档的冲突之处，请以文档为准。** +## 起步 -类型源代码在 [uni-helper/uni-ui-types](https://github.com/uni-helper/uni-ui-types)。欢迎提交 ISSUE 和 PR 改进类型。 +### 配置编辑器/IDE + +请参考 [这里](https://cn.vuejs.org/guide/typescript/overview.html) 将 Volar（Vue 语言服务工具）添加到你的编辑器或 IDE，配置完毕后请重启你的编辑器或 IDE 以确保服务启动。 + +> [!WARNING] +> Volar 需要 v2.0.22 或更高版本，对应地，TypeScript 需要 v5.0.0 或更高版本。 + +### 安装依赖 + +```shell +npm i -D @uni-helper/uni-ui-types +``` + +此外你需要确保项目已经安装 Vue v3.0.0 或更高版本，以及 TypeScript v5 或更高版本。 + +> [!TIP] +> 为了避免幽灵依赖（又称幻影依赖，详见 [这篇文章](https://rushjs.io/zh-cn/pages/advanced/phantom_deps/)），请检查你的包管理器。 +> +> 如果你正在使用 yarn v2 或以上版本，请参考 [文档](https://yarnpkg.com/configuration/yarnrc/#nodeLinker) 设置 `nodeLinker` 为 `node_modules`。 +> +> 如果你正在使用 pnpm，请参考 [文档](https://pnpm.io/npmrc#shamefully-hoist) 设置 `shamefully-hoist` 为 `true`。 + +### 配置 TypeScript + +更新 `tsconfig.json`，确保： + +- `compilerOptions.types` 包含 `@uni-helper/uni-ui-types` +- `include` 包含 `vue` 相关文件 + +以下是一个 `tsconfig.json` 示例，你可以直接复制它并粘贴到项目内。请注意，你可能需要稍微调整以匹配你的开发需求，相关依赖需要自行安装。 + +> [!WARNING] +> 再次提醒，TypeScript 需要 v5.0.0 或更高版本。 +> +> 截至 2024-07-28，uni-app 官方提供的 Vue3 + Vite + TypeScript 模板版本相对落后，如果你正在使用它，你需要手动升级。 +> +> 你也可以在这里获取 [社区模板](https://github.com/uni-helper/awesome-uni-app#%E6%A8%A1%E6%9D%BF) 以起步。 + +```jsonc +{ + "compilerOptions": { + "lib": ["DOM", "DOM.Iterable", "ESNext"], + "module": "ESNext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "jsx": "preserve", + "jsxImportSource": "vue", + "noImplicitThis": true, + "strict": true, + "verbatimModuleSyntax": true, + "target": "ESNext", + "useDefineForClassFields": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "skipLibCheck": true, + "types": [ + // uni-app + Vue 3 使用 Vite 构建，需要安装 vite + "vite/client", + // uni API 相关的 TypeScript 类型 + "@dcloudio/types", + // my API 相关的 TypeScript 类型 + "@mini-types/alipay", + // wx API 相关的 TypeScript 类型，需要手动安装依赖 + "miniprogram-api-typings", + // 为 uni-ui 组件提供 TypeScript 类型 + "@uni-helper/uni-ui-types" + ] + }, + "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue", "*.d.ts"] +} +``` + +再次重启你的编辑器或 IDE 以确保服务启动并正确加载配置。如果一切顺利，你应该可以看到类似的 TypeScript 类型提示。 + +![示例](../../assets/uni-ui-example.png) ## 使用 -### 配置 - -- 安装依赖 - - ```shell - npm i -D @uni-helper/uni-app-types @uni-helper/uni-ui-types - ``` - -
- yarn v2/v3 -

请参考 文档 设置 nodeLinker 为 node_modules。

-
- -
- pnpm -

请参考 文档 设置 shamefully-hoist 为 true。

-
- -- 配置 `tsconfig.json`，确保 `compilerOptions.types` 中含有 `@dcloudio/types`、`@uni-helper/uni-app-types` 和 `@uni-helper/uni-ui-types`，且 `include` 包含了对应的 `vue` 文件 - -
- 2.0.14 <= Vue Language Features (Volar) & vue-tsc - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-ui-types" - ] - }, - "vueCompilerOptions": { - "plugins": ["@uni-helper/uni-app-types/volar-plugin"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.7.12 <= Vue Language Features (Volar) & vue-tsc < 2.0.14 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-ui-types" - ] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.5.1 <= Vue Language Features (Volar) & vue-tsc < 1.7.12 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-ui-types" - ] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 1.0.10 <= Vue Language Features (Volar) & vue-tsc < 1.5.1 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-ui-types" - ] - }, - "vueCompilerOptions": { - "nativeTags": ["block", "component", "template", "slot"] - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -
- 0.34.16 <= Vue Language Features (Volar) & vue-tsc < 1.0.10 - - ```json - { - "compilerOptions": { - "types": [ - "@dcloudio/types", - "@uni-helper/uni-app-types", - "@uni-helper/uni-ui-types" - ] - }, - "vueCompilerOptions": { - "experimentalRuntimeMode": "runtime-uni-app" - }, - "include": ["src/**/*.vue"] - } - ``` - -
- -- 重启编辑器 / IDE - -### 标注类型 - -推荐使用 `@uni-helper/uni-ui-types` 导出的类型为变量标注类型。 +### Template + +自动为 Template 内对应组件附加 TypeScript 类型提示。 + +![示例](../../assets/uni-ui-example.png) + +### Script + +推荐使用 `@uni-helper/uni-ui-types` 导出的 TypeScript 类型为变量标注类型。 ```vue @@ -164,7 +121,7 @@ const onClick: UniBadgeOnClick = (event) => { ``` -也可以直接使用命名空间来为变量标注类型。 +也可以直接使用命名空间来为变量标注类型（不推荐，详见 [typescript-eslint - no-namespace](https://typescript-eslint.io/rules/no-namespace/))。 ```vue