diff --git a/.eslintrc b/.eslintrc deleted file mode 100644 index 09dcda3..0000000 --- a/.eslintrc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "extends": [ - "@antfu" - ] -} diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 998bcc8..325db29 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -77,7 +77,7 @@ export default defineConfig({ themeConfig: { // https://vitepress.dev/reference/default-theme-config logo: '/logo.svg', - siteTitle: 'Vitesse', + siteTitle: 'Vitesse Uni App', nav: [ { text: '快速开始', link: '/getting-started/installation', activeMatch: '/getting-started' }, { text: '指南', link: '/guide/concepts/auto-imports', activeMatch: '/guide' }, @@ -179,5 +179,29 @@ export default defineConfig({ pattern: 'https://github.com/uni-helper/vitesse-uni-app-docs/edit/main/:path', text: '在 GitHub 上编辑本页', }, + + search: { + provider: 'local', + options: { + locales: { + zh: { + translations: { + button: { + buttonText: '搜索文档', + buttonAriaLabel: '搜索文档' + }, + modal: { + noResultsText: '无法找到相关结果', + resetButtonTitle: '清除查询条件', + footer: { + selectText: '选择', + navigateText: '切换' + } + } + } + } + } + } + }, }, }) diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000..3b614a0 --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,3 @@ +import antfu from '@antfu/eslint-config' + +export default antfu() diff --git a/getting-started/data-fetching.md b/getting-started/data-fetching.md index e2e8538..f2ba928 100644 --- a/getting-started/data-fetching.md +++ b/getting-started/data-fetching.md @@ -1,37 +1,29 @@ # 数据获取 -你可以使用任何你喜欢的第三方请求库来获取数据。默认情况下，直接使用 `uni.request` 即可。 +你可以使用你喜欢的第三方请求库来获取数据。一般情况下，直接使用 `uni-app` 内置方法即可。 -## `uni.request` +## `uni-app` 内置方法 -这是 uni 内置的网络请求方法。 +`uni-app` 提供了 [uni.request](https://uniapp.dcloud.net.cn/api/request/request.html)、[uni.uploadFile](https://uniapp.dcloud.net.cn/api/request/network-file.html#uploadfile)、[uni.downloadFile](https://uniapp.dcloud.net.cn/api/request/network-file.html#downloadfile)、[WebSocket](https://uniapp.dcloud.net.cn/api/request/websocket.html) 等支持。一般情况下，你可以直接使用它们。 -```ts -uni.request({ - url: 'https://www.example.com/request', - data: { - text: 'uni.request' - }, - header: { - 'custom-header': 'hello' // 自定义请求头信息 - }, - success: (res) => { - console.log(res.data) - } -}) -``` +## axios +如果你更喜欢 [axios](https://github.com/axios/axios) 及其相关生态，你可以使用 [@uni-helper/axios-adapter](https://github.com/uni-helper/axios-adapter)。它是专为 `uni-app` 打造的 `axios` 适配器，支持全平台！ + +```ts +import axios from 'axios' +import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter' -::: tip -你可以在[这里](https://uniapp.dcloud.net.cn/api/request/request.html#)阅读文档。 -::: +axios.defaults.adapter = createUniAppAxiosAdapter() +const { data, isFinished } = useAxios('/user?ID=12345') +``` -## uni-network +## @uni-helper/uni-network -这是一个为 `uni-app` 打造的 [基于 Promise](https://javascript.info/promise-basics) 的 HTTP 客户端，灵感和代码绝大部分源于 `axios@0.27.2`。 +[@uni-helper/uni-network](https://github.com/uni-helper/uni-network) 是一个为 `uni-app` 打造的基于 `Promise` 的 HTTP 客户端，灵感和代码绝大部分源于 `axios@0.27.2`。`@uni-helper/uni-network` 在底层做了 `uni-app` 适配，体积更小，TypeScript 类型更贴近 `uni-app`。 ```ts -import un from '@uni-helper/uni-network' +import { un } from '@uni-helper/uni-network' try { const response = await un.get('/user?ID=12345') @@ -41,23 +33,3 @@ catch (error) { console.error(error) } ``` - -::: tip -你可以在[这里](https://github.com/uni-helper/uni-network)阅读文档。 -::: - -## axios - -如果你更喜欢 axios 或者为了享受其相关生态，你还可以使用由 Uni Helper 团队开发的 [axios-adapter](https://github.com/uni-helper/axios-adapter)，它是专为 uni-app 打造的 axios 适配器，支持全平台！ - -```ts -import axios from 'axios' -import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter' - -axios.defaults.adapter = createUniAppAxiosAdapter() -const { data, isFinished } = useAxios('/user?ID=12345') -``` - -::: tip -你可以阅读 [axios 的文档](https://axios-http.com/docs/intro) 和 [axios-adapter 的文档](https://github.com/uni-helper/axios-adapter)了解更多信息。 -::: diff --git a/getting-started/deployment.md b/getting-started/deployment.md index eb51dd3..2bd7fc4 100644 --- a/getting-started/deployment.md +++ b/getting-started/deployment.md @@ -14,24 +14,21 @@ pnpm build:h5 ## 小程序 -使用下面的命令来打包： +以微信小程序为例，使用下面的命令来打包： ```bash -# 微信小程序 pnpm build:mp-weixin ``` 产物位于 `dist/build/mp-weixin`, 使用微信开发者工具上传即可。 ::: tip -如若想自动上传到微信小程序，可查看[这里](https://juejin.cn/post/7272316909051346959) +如果想自动上传到微信小程序，可直接使用 [uni-mini-ci](https://www.npmjs.com/package/uni-mini-ci)，或参考 [这篇文章](https://juejin.cn/post/7272316909051346959) 自行配置。 ::: -::: tip -要发行其他小程序，执行 `pnpm build:mp-`打包，并使用对应开发者工具上传即可，具体可查看 package.json 的 scripts 部分。 -::: +要发行其他小程序，执行 `pnpm build:mp-`打包，并使用对应开发者工具上传即可，具体可查看 `package.json` 的 `scripts` 部分。 -## App +## APP ### 离线打包 @@ -39,5 +36,144 @@ pnpm build:mp-weixin - [ios](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/ios.html) ::: warning -你任然可以使用 HBuilderX 提供的"安心"打包功能，但是由于这种方式强依赖 HBuilderX，故不做推荐 +你仍然可以使用 HBuilderX 提供的“安心”打包功能，但是由于这种方式强依赖 HBuilderX，故不做推荐。 ::: + +## 兼容性 + +默认情况下，你不需要调整兼容性相关的构建配置，这是因为较新的浏览器、手机、小程序运行环境提供了较好的兼容性支持。 + +但理想很丰满，现实很骨感，总有用户不想换掉自己的旧设备、旧浏览器，而你恰好又需要关怀这些用户。这时候，你就需要调整兼容性相关的构建配置了。 + +### VueCLI + +对于部分正在使用 VueCLI 的历史项目，请参考 [文档](https://cli.vuejs.org/zh/config/#transpiledependencies) 设置 `transpileDependencies`，VueCLI 会自动增加 JavaScript 和 CSS 的支持。 + +### Vite + +Vite 底层使用了 [esbuild](https://esbuild.github.io/)，你可以设置 `build.target` 和 `build.cssTarget` 来做兼容。 + +```ts +import { defineConfig } from 'vite' +import uni from '@dcloudio/vite-plugin-uni' + +export default defineConfig({ + build: { + // esbuild 最低支持 es6 + target: 'es6', // JavaScript 语法支持 + cssTarget: 'es6' // CSS 语法支持 + }, + plugins: [uni()] +}) + +``` + +但 esbuild 没有覆盖到所有需要兼容的情况。对于 JavaScript，esbuild 没有注入 [Polyfills](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill)，这也意味着部分 JavaScript API 不可用。遗憾的是，你无法直接使用 `@vitejs/plugin-legacy` 或 `@vitejs/plugin-legacy-swc`，甚至设置 `@dcloudio/vite-plugin-uni` 中的 `viteLegacyOptions` 也 [只会在 H5 中 生效](https://github.com/dcloudio/uni-app/issues/3842)，此时只可以使用 `core-js` 来手动注入。 + +::: code-group + +```ts [src/main.ts] +/** #ifdef MP */ +// 只有构建小程序时手动注入 Polyfills +// 可以按实际情况调整 +import 'core-js/actual/array/at' +// ❌ 不要像下面这样做，会占用大量小程序体积且没有必要 +// import 'core-js/actual' +/** #endif */ +import { createSSRApp } from 'vue' +import { createPinia } from 'pinia' +import App from './App.vue' + +const pinia = createPinia() + +export function createApp() { + const app = createSSRApp(App).use(pinia); + return { + app, + } +} +``` + +```ts [vite.config.ts] +import { defineConfig } from 'vite' +import uni from '@dcloudio/vite-plugin-uni' +import { isH5 } from '@uni-helper/uni-env' +import legacy from 'vite-plugin-legacy' +// 或者使用 vite-plugin-legacy-swc +// import legacy from 'vite-plugin-legacy-swc' + +export default defineConfig({ + build: { + // 最低支持 es6 + target: 'es6', // JavaScript 语法支持 + cssTarget: 'es6' // CSS 语法支持 + }, + plugins: [ + uni(), + // 只有构建 H5 时应用插件自动注入 Polyfills + // 可以按实际情况调整 + isH5 ? legacy() : null + ] +}) + +``` + +::: + +::: tip +你可以使用 [core-js-compat](https://github.com/zloirock/core-js/blob/master/packages/core-js-compat/README.md) 来确定具体的 Polyfills。 +::: + +对于 CSS，可以使用 [PostCSS](https://postcss.org/) 和 [postcss-preset-env](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env)。 + +```bash +pnpm install postcss postcss-preset-env -D +``` + +::: code-group + +```ts [postcss.config.ts] +import postcssPresetEnv from 'postcss-preset-env'; + +const plugins = [] +if (process.env.NODE_ENV === 'production') { + plugins.push( + postcssPresetEnv({ + // 自定义相应目标 + // 微信小程序 2.11.2 开始支持 Vue3，对应 chrome53 和 ios10 + browsers: ['chrome>=53', 'ios>=10'] + }) + ) +} + +export default { + plugins +} +``` + +```ts [vite.config.ts] +import { defineConfig } from 'vite' +import uni from '@dcloudio/vite-plugin-uni' +import postcssConfig from './postcss.config' + +export default defineConfig({ + build: { + cssTarget: 'chrome61' + }, + css: { + postcss: postcssConfig + }, + plugins: [uni()] +}) + +``` + +::: + +::: warning +你可以在 [dcloudio/uni-app#3367](https://github.com/dcloudio/uni-app/issues/3367) 了解为什么要在 Vite 配置文件内设置 PostCSS。 +::: + +### 构建小程序 + +对于小程序，你可以直接设置小程序最低基础库要求，以排除部分过于老旧的设备。 diff --git a/getting-started/installation.md b/getting-started/installation.md index 826eefe..e10560c 100644 --- a/getting-started/installation.md +++ b/getting-started/installation.md @@ -13,14 +13,15 @@ ### 前置依赖 -- **Node.js** - v16.10.0 或者更高 -- **文本编辑器** - 推荐使用 VS Code 并使用 Volar 插件 -- **终端** - 为了运行 `uni` 命令 +- **Node.js** - v18.19.0 或者更高 +- **文本编辑器** - 推荐使用 [VS Code](https://code.visualstudio.com/) 并使用 [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) 插件 +- **终端** - 为了运行 `uni` 命令，Windows 推荐 Git Bash，Linux 和 macOS 推荐 zsh ::: details 最佳实践 -- **Node.js**: 总是使用偶数版本 (例如 18, 20) -- **Volar**: 推荐启用接管模式 (takeover) +- **Node.js**: 总是使用偶数版本 (即 [LTS 版本](https://nodejs.org/en/about/previous-releases)，例如 18, 20) +- **Volar**: 推荐启用 [接管模式 takeover mode](https://cn.vuejs.org/guide/typescript/overview#volar-takeover-mode) + ::: 打开终端，然后使用以下命令： diff --git a/getting-started/introduction.md b/getting-started/introduction.md index a28387e..34dc34e 100644 --- a/getting-started/introduction.md +++ b/getting-started/introduction.md @@ -1,15 +1,16 @@ # 介绍 -vitess-uni-app 是一个开源模板，具有直观且可扩展的方式来使用 `Vue` & `uni-app` 创建类型安全、高性能和生产级的跨端应用。 +vitess-uni-app 是一个基于 `Vue` 和 `uni-app` 的开源模板，采用直观且可扩展的方式创建类型安全、高性能和生产级的跨端应用。你可以直接开始编写 `.vue` 文件，而无需从头开始配置。 -你可以直接开始编写 `.vue` 文件，而无需从头开始配置。 - -vitesse-uni-app 没有绑定编辑器，你可以使用任何方式任何编辑器进行开发。 +vitesse-uni-app 灵感源于 [vitesse](https://github.com/antfu/vitesse)。 ## 为什么 -- 不要 HBuilderX -- 拥抱 npm 生态 +`uni-app` 背后的公司 DCloudio 选择创建自己的生态，比如 HBuilderX、uni_modules 等。这部分工作对部分开发者来说意义非凡，他们可以轻松上手并享受社区提供的一切资源。 + +但是，`uni-app` 社区生态远不如 npm 生态繁荣，我们常常需要求助于 npm 生态来实现部分需求，而 `uni-app` 的黑盒性阻碍了这一点。 + +vitesse-uni-app 充分拥抱开放生态，比如 VS Code 和 npm，希望能带给你更好的体验。 ## 主要依赖 diff --git a/getting-started/state-management.md b/getting-started/state-management.md index 68a76e5..c78b551 100644 --- a/getting-started/state-management.md +++ b/getting-started/state-management.md @@ -1,8 +1,68 @@ # 状态管理 -得益于 Composition API ，在 Vitesse 中做状态管理很容易。 +得益于组合式方法（Composition API），管理状态非常简单。 -## `ref` +## Pinia + +[Pinia](https://pinia.vuejs.org/zh/) 是 `Vue` 官方最新推荐的状态管理库。 + +```shell +pnpm install pinia@2.0.36 +``` + +安装依赖后，需要做基本设置。 + +:::code-group + +```ts [src/main.ts] +import { createSSRApp } from 'vue' +import { createPinia } from 'pinia' +import App from './App.vue' + +const pinia = createPinia() + +export function createApp() { + const app = createSSRApp(App).use(pinia); + return { + app, + } +} +``` + +```ts [src/stores/counter.ts] +import { defineStore } from 'pinia'; + +export const useCounterStore = defineStore('counter', () => { + const count = ref(0) + function increment() { + count.value++ + } + return { count, increment } +}) +``` + +```vue [src/pages/index/index.vue] + +``` + +::: + +::: warning +你可以在 [dcloudio/uni-app#4350](https://github.com/dcloudio/uni-app/issues/4350) 了解为什么要固定 pinia 版本号。 +::: + +## 简单状态管理 + +你可以直接使用 `Vue` 提供的 `ref` 或 `reactive` 方法来做简单状态管理。 + +### ref ::: code-group @@ -40,7 +100,7 @@ const { globalCount, localCount, increment } = useCount() ::: -## `reactive` +### reactive ::: code-group @@ -65,12 +125,12 @@ export const countStore = reactive({ ::: ::: tip -以上关于 `ref` 和 `reactive`的实例修改自 Vue 官方中文文档的[用响应式 API 做简单状态管理](https://cn.vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api) 部分。 +以上例子修改自 Vue 文档的 [用响应式 API 做简单状态管理](https://cn.vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api)。 ::: ## VueUse -你也可以使用 vueUse 提供的 `createGlobalState` 进行状态管理，你还可以配合 `useStorage` 做数据持久。 +你也可以使用 VueUse 提供的 `createGlobalState` 进行状态管理，你还可以配合 `useStorage` 做数据持久。 :::code-group @@ -110,14 +170,6 @@ export const uniStorage = { ::: -## Pinia - -这个官方推荐的一个状态管理库。安装它，然后阅读[文档](https://pinia.vuejs.org/zh/)。 - -```shell -pnpm install pinia@2.0.36 -``` - ::: warning -你可以在 [#4350](https://github.com/dcloudio/uni-app/issues/4350) 了解为什么要固定 pinia 版本号。 +如果你正在使用 VueUse v10 并遇到了问题，请查看 [dcloudio/uni-app#4604](https://github.com/dcloudio/uni-app/issues/4604) 获取解决方案。 ::: diff --git a/getting-started/styling.md b/getting-started/styling.md index 28636e4..342c038 100644 --- a/getting-started/styling.md +++ b/getting-started/styling.md @@ -1,45 +1,34 @@ # 样式 -我们使用 unocss 来作为 css 框架，当然，你可以使用任何 css 预处理器就像在 Vite 项目中一样。 +模板基于 `UnoCSS` 提供主要样式支持。当然，你可以使用 CSS 预处理器、组件库等。 ## UnoCSS -默认情况下，我们使用了由 uni-helper 核心成员创建的 [`unocss-uni`](https://github.com/uni-helper/unocss-uni)。它在底层使用 [`unocss-applet`](https://github.com/unocss-applet/unocss-applet) 来获得兼容性，并提供了按平台编写样式的能力。 +[UnoCSS](https://unocss.dev/) 是按需使用的原子 CSS 引擎，提供了良好的样式支持。 + +模板内置了 [@uni-helper/unocss-preset-uni](https://github.com/uni-helper/unocss-preset-uni)，它在底层使用 [unocss-applet](https://github.com/unocss-applet/unocss-applet) 来兼容不同平台，并提供了按平台编写样式的能力。 ```html + + + + + ``` -::: tip -你可以参考 UnoCSS [文档](https://unocss.dev/)，了解更多有关 UnoCSS 的使用方法。 -::: - -## 预处理器 - -:::code-group - -```bash [Sass & Scss] -pnpm install sass -``` - -```bash [Less] -pnpm install less -``` - -```bash [Stylus] -pnpm install stylus -``` +## CSS 预处理器 -::: +你可以参考 [Vite 文档 CSS 预处理器](https://cn.vitejs.dev/guide/features.html#css-pre-processors)，了解相关使用方法。 -## SFC 样式 +## 单文件组件样式 -你可以参考 Vue [文档](https://vuejs.org/api/sfc-css-features.html)，了解有关 SFC 样式的使用方法。 +你可以参考 [Vue 文档单文件组件 CSS 功能](https://cn.vuejs.org/api/sfc-css-features.html)，了解相关使用方法。 -## 第三方 UI 库 +## 组件库 -查看 Awesome Uni-App 整理的 [UI 组件库](https://github.com/uni-helper/awesome-uni-app?tab=readme-ov-file#ui-%E7%BB%84%E4%BB%B6%E5%BA%93)，选一个你心动的即可~ +查看 [uni-helper/awesome-uni-app] 整理的 [组件库](https://github.com/uni-helper/awesome-uni-app#ui-%E7%BB%84%E4%BB%B6%E5%BA%93)，选一个你心动的即可~ diff --git a/getting-started/views.md b/getting-started/views.md index 782b2a8..d20144a 100644 --- a/getting-started/views.md +++ b/getting-started/views.md @@ -2,17 +2,23 @@ ## App.vue -uni-app 的主组件，所有页面都是在 App.vue 下进行切换的，是应用入口文件。但 `App.vue` 本身不是页面，这里不能编写视图元素，也就是没有 `