diff --git a/.gitignore b/.gitignore index 26d607a..7feb32c 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,9 @@ dist .stylelintcache .eslintcache +docs/.vitepress/dist +docs/.vitepress/cache + # lock 文件还是不要了，我主要的版本写死就好了 # pnpm-lock.yaml # package-lock.json diff --git a/docs/.vitepress/components/BuildInfo.vue b/docs/.vitepress/components/BuildInfo.vue new file mode 100644 index 0000000..380ef56 --- /dev/null +++ b/docs/.vitepress/components/BuildInfo.vue @@ -0,0 +1,23 @@ + + + + + + diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 0000000..e2079e3 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,220 @@ +import dayjs from 'dayjs' +import { defineConfig } from 'vitepress' +import packageJson from '../../package.json' + +const buildTime = dayjs().format('yyyy-MM-dd HH:mm:ss') + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + lang: 'zh-CN', + base: '/unibest-docs/', + // base: '/', + title: 'unibest', + description: '最好用的 uniapp 开发模板', + lastUpdated: true, + cleanUrls: true, + head: [ + [ + 'meta', + { + name: 'keywords', + content: 'unibest, uniapp, uni-app, vue, vue3, vite,template, typescript, ts', + }, + ], + [ + 'meta', + { + name: 'author', + content: '菲鸽, 菲哥, 鸽鸽, feige996, feige996, 1020103647@qq.com', + }, + ], + ['link', { rel: 'icon', href: './favicon.ico' }], // 这里要加上 base 前缀，否则资源访问不到 + [ + 'meta', + { + name: 'twitter:title', + content: '最好用的 uniapp 开发模板', + }, + ], + // 添加 ICP 备案信息 + ['meta', { name: 'icp', content: '粤ICP备2024160998号' }], + ['link', { rel: 'license', href: 'https://beian.miit.gov.cn/' }], + // 其他杂七杂八的 meta 标签 + ['meta', { name: 'twitter:card', content: 'summary_large_image' }], + ['meta', { name: 'twitter:site', content: 'feige996' }], + [ + 'meta', + { + name: 'twitter:image:src', + content: + 'https://opengraph.githubassets.com/1cac1150838995e1f7d1643c00eee51a5d884f2054f995c9d3225b07b0eddb39/feige996/unibest', + }, + ], + [ + 'meta', + { + property: 'og:image', + content: + 'https://opengraph.githubassets.com/1cac1150838995e1f7d1643c00eee51a5d884f2054f995c9d3225b07b0eddb39/feige996/unibest', + }, + ], + [ + 'meta', + { + property: 'og:image:alt', + content: '最好用的 uniapp 开发模板', + }, + ], + ['meta', { property: 'og:image:width', content: '1200' }], + ['meta', { property: 'og:image:height', content: '600' }], + ['meta', { property: 'og:site_name', content: 'GitHub' }], + ['meta', { property: 'og:type', content: 'object' }], + [ + 'meta', + { + property: 'og:title', + content: '最好用的 uniapp 开发模板', + }, + ], + ['meta', { property: 'og:url', content: 'https://github.com/feige996/unibest' }], + [ + 'meta', + { + property: 'og:description', + content: '最好用的 uniapp 开发模板', + }, + ], + // 增加构建信息 + ['meta', { name: 'build-time', content: buildTime }], + ['meta', { name: 'version', content: packageJson.version }], + // 下面是百度统计代码 + ['script', { async: '', src: 'https://hm.baidu.com/hm.js?081c2ec121383d9e7d5a35c5833ab6ff' }], + // 下面是不蒜子统计代码 + ['script', { async: '', src: '//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js' }], + ], + markdown: { + theme: { + light: 'vitesse-light', + dark: 'vitesse-dark', + }, + }, + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + logo: './logo.svg', + siteTitle: 'unibest', + nav: [ + { + text: '快速开始', + link: '/base/2-start', + activeMatch: '/base', + }, + { + text: '🥤 打赏', + link: '/advanced/rewards/rewards', + }, + { + text: '相关链接', + link: '/other/links/links', + activeMatch: '/other', + }, + ], + sidebar: [ + { + text: '基础·必看', + base: '/base/', + items: [ + { text: '介绍', link: '1-introduction' }, + { + text: '快速开始', + link: '2-start', + }, + { text: 'uni 插件', link: '3-plugin' }, + { text: '样式篇', link: '4-style' }, + { text: '图标篇', link: '5-icons' }, + { text: 'SVG篇', link: '6-svg' }, + { text: 'UI库选型篇', link: 'ui/ui' }, + { text: 'UI库替换篇', link: '7-ui' }, + { text: '请求篇', link: '8-request' }, + { text: '状态篇', link: '9-state' }, + { text: '多语言篇', link: '10-i18n' }, + { text: '运行发布', link: '11-build' }, + { text: '环境变量', link: '12-env' }, + { text: 'hbx 模板', link: '13-hbx' }, + { text: '常见问题', link: '14-faq' }, + { text: '常见问题2', link: '15-faq' }, + { text: '最佳实践', link: '20-best' }, + ], + }, + { + text: '社交', + base: '/advanced/', + items: [ + { text: '🥤 打赏', link: 'rewards/rewards' }, + { text: '微信交流群', link: 'wechat/wechat' }, + { text: '赞助榜', link: 'sponsor/sponsor' }, + ], + }, + { + text: '延伸', + base: '/other/', + items: [ + { text: '相关链接', link: 'links/links' }, + { text: '图片占位图', link: 'image/image' }, + { text: 'iconfont详细版', link: 'iconfont/iconfont' }, + { text: 'Git 提交优化', link: 'czg/czg' }, + { text: '文件资源展示优化', link: 'files/files' }, + { text: 'unibest博客', link: 'blog' }, + ], + }, + ], + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright (c) 2024 菲鸽', + }, + socialLinks: [ + { icon: 'github', link: 'https://github.com/feige996/unibest' }, + { + icon: { + svg: ``, + }, + link: 'https://gitee.com/feige996/unibest', + ariaLabel: 'Gitee', + }, + // #1f80ff 是掘金的 logo 的颜色 + { + icon: { + svg: ` + + + + `, + }, + link: 'https://juejin.cn/user/3263006241460792/posts', + ariaLabel: '菲鸽的掘金主页', + }, + ], + search: { + provider: 'local', + options: { + locales: { + zh: { + translations: { + button: { + buttonText: '搜索文档', + buttonAriaLabel: '搜索文档', + }, + modal: { + noResultsText: '无法找到相关结果', + resetButtonTitle: '清除查询条件', + footer: { + selectText: '选择', + navigateText: '切换', + }, + }, + }, + }, + }, + }, + }, + }, +}) diff --git a/docs/.vitepress/layouts/Default.vue b/docs/.vitepress/layouts/Default.vue new file mode 100644 index 0000000..6235948 --- /dev/null +++ b/docs/.vitepress/layouts/Default.vue @@ -0,0 +1,26 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/HomeStar.vue b/docs/.vitepress/theme/components/HomeStar.vue new file mode 100644 index 0000000..f942ded --- /dev/null +++ b/docs/.vitepress/theme/components/HomeStar.vue @@ -0,0 +1,50 @@ + + + diff --git a/docs/.vitepress/theme/components/NavBarTitleAfter.vue b/docs/.vitepress/theme/components/NavBarTitleAfter.vue new file mode 100644 index 0000000..34480b0 --- /dev/null +++ b/docs/.vitepress/theme/components/NavBarTitleAfter.vue @@ -0,0 +1,21 @@ + + + diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css new file mode 100644 index 0000000..064f125 --- /dev/null +++ b/docs/.vitepress/theme/custom.css @@ -0,0 +1,84 @@ +/** + * Colors + * -------------------------------------------------------------------------- */ +:root { + --vp-c-brand-1: hsl(128, 56%, 38%); + --vp-c-brand-2: hsl(128, 56%, 55%); + --vp-c-brand-3: hsl(128, 56%, 45%); + --vp-c-brand-soft: rgba(98, 133, 208, 0.16); +} +/** + * Component: Home + * -------------------------------------------------------------------------- */ + +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient( + 120deg, + hsl(128, 56%, 38%) 30%, + hsl(128, 56%, 60%) + ); + --vp-home-hero-image-background-image: linear-gradient( + 120deg, + hsl(100, 56%, 45%) 30%, + hsl(120, 56%, 38%) + ); + --vp-home-hero-image-filter: blur(40px); +} +@media (min-width: 640px) { + :root { + --vp-home-hero-image-filter: blur(56px); + } +} + +@media (min-width: 960px) { + :root { + --vp-home-hero-image-filter: blur(72px); + } +} + +.md-center > p { + display: flex; + /* justify-content: center; */ + flex-wrap: wrap; + margin-top: -4px; + margin-right: -4px; +} +.md-center img { + display: inline-block; + height: 1.4em; + margin-top: 4px; + margin-right: 4px; + line-height: 1.6; +} +.md-center2 img { + display: inline-block; + margin-top: 4px; + margin-right: 4px; +} + +.busuanzi_container { + display: flex; + justify-content: space-around; + opacity: 0.3; +} + +@media (max-width: 960px) { + .busuanzi_container { + flex-direction: column; + padding-top: 12px; + padding-left: 30px; + } +} +@media (min-width: 961px) { + .busuanzi_container { + height: 60px; + line-height: 60px; + } +} + +.icp_container { + display: flex; + align-items: center; + justify-content: center; +} diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000..20d7ce6 --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,22 @@ +// https://vitepress.dev/guide/custom-theme +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' +import { h } from 'vue' +import './custom.css' + +import HomeStar from './components/HomeStar.vue' +import NavBarTitleAfter from './components/NavBarTitleAfter.vue' + +export default { + extends: DefaultTheme, + Layout: () => { + return h(DefaultTheme.Layout, null, { + // https://vitepress.dev/guide/extending-default-theme#layout-slots + 'home-hero-info-after': () => h(HomeStar), + 'nav-bar-title-after': () => h(NavBarTitleAfter), + }) + }, + enhanceApp({ app, router, siteData }) { + // ... + }, +} satisfies Theme diff --git a/docs/advanced/me/image-2.png b/docs/advanced/me/image-2.png new file mode 100644 index 0000000..b18b7ca Binary files /dev/null and b/docs/advanced/me/image-2.png differ diff --git a/docs/advanced/me/image-3.png b/docs/advanced/me/image-3.png new file mode 100644 index 0000000..02473d5 Binary files /dev/null and b/docs/advanced/me/image-3.png differ diff --git a/docs/advanced/me/me.md b/docs/advanced/me/me.md new file mode 100644 index 0000000..867d601 --- /dev/null +++ b/docs/advanced/me/me.md @@ -0,0 +1,30 @@ +# 关于我 + +我叫 `菲鸽`，江西宋城人。前端工程师，全栈实践者，精通 `vue`、`react`、`uniapp`、`typescript`、`小程序`、`Nodejs` 等。 + +热爱编程，喜欢分享，平时比较宅，喜欢撸代码，偶尔打篮球和玩王者荣耀。 + + + +## 找到我 + +- Github: [feige996](https://github.com/feige996) +- Gitee: [feige996](https://gitee.com/feige996) +- 掘金：[菲鸽](https://juejin.cn/user/3263006241460792/posts) +- 微信：`feige996` = `菲鸽`，大家都叫我 `鸽鸽` +- QQ：`1020103647` +- 邮箱：`1020103647@qq.com` + +## 微信公众号 + +微信公众号：`菲鸽爱编程` + +![微信公众号](./screenshots/wx-gzh.png) + + diff --git a/docs/advanced/me/screenshots/pay-wx.png b/docs/advanced/me/screenshots/pay-wx.png new file mode 100644 index 0000000..8c8c633 Binary files /dev/null and b/docs/advanced/me/screenshots/pay-wx.png differ diff --git a/docs/advanced/me/screenshots/wx-gzh.png b/docs/advanced/me/screenshots/wx-gzh.png new file mode 100644 index 0000000..25fcb5b Binary files /dev/null and b/docs/advanced/me/screenshots/wx-gzh.png differ diff --git a/docs/advanced/me/screenshots/wx-me.png b/docs/advanced/me/screenshots/wx-me.png new file mode 100644 index 0000000..efb91b9 Binary files /dev/null and b/docs/advanced/me/screenshots/wx-me.png differ diff --git a/docs/advanced/rewards/assets/group-qq.jpg b/docs/advanced/rewards/assets/group-qq.jpg new file mode 100644 index 0000000..6f6df26 Binary files /dev/null and b/docs/advanced/rewards/assets/group-qq.jpg differ diff --git a/docs/advanced/rewards/assets/group-wx.jpg b/docs/advanced/rewards/assets/group-wx.jpg new file mode 100644 index 0000000..78f2261 Binary files /dev/null and b/docs/advanced/rewards/assets/group-wx.jpg differ diff --git a/docs/advanced/rewards/assets/pay-1.png b/docs/advanced/rewards/assets/pay-1.png new file mode 100644 index 0000000..92e8019 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-1.png differ diff --git a/docs/advanced/rewards/assets/pay-2.png b/docs/advanced/rewards/assets/pay-2.png new file mode 100644 index 0000000..9004bed Binary files /dev/null and b/docs/advanced/rewards/assets/pay-2.png differ diff --git a/docs/advanced/rewards/assets/pay-ali.png b/docs/advanced/rewards/assets/pay-ali.png new file mode 100644 index 0000000..dce450a Binary files /dev/null and b/docs/advanced/rewards/assets/pay-ali.png differ diff --git a/docs/advanced/rewards/assets/pay-w-5.png b/docs/advanced/rewards/assets/pay-w-5.png new file mode 100644 index 0000000..8de0cf8 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-w-5.png differ diff --git a/docs/advanced/rewards/assets/pay-wx-10.png b/docs/advanced/rewards/assets/pay-wx-10.png new file mode 100644 index 0000000..c035320 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-wx-10.png differ diff --git a/docs/advanced/rewards/assets/pay-wx-2.png b/docs/advanced/rewards/assets/pay-wx-2.png new file mode 100644 index 0000000..9a5f692 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-wx-2.png differ diff --git a/docs/advanced/rewards/assets/pay-wx-5-doc.png b/docs/advanced/rewards/assets/pay-wx-5-doc.png new file mode 100644 index 0000000..e484ed0 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-wx-5-doc.png differ diff --git a/docs/advanced/rewards/assets/pay-wx-5.png b/docs/advanced/rewards/assets/pay-wx-5.png new file mode 100644 index 0000000..909c225 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-wx-5.png differ diff --git a/docs/advanced/rewards/assets/pay-wx.png b/docs/advanced/rewards/assets/pay-wx.png new file mode 100644 index 0000000..8c8c633 Binary files /dev/null and b/docs/advanced/rewards/assets/pay-wx.png differ diff --git a/docs/advanced/rewards/rewards.md b/docs/advanced/rewards/rewards.md new file mode 100644 index 0000000..03576e9 --- /dev/null +++ b/docs/advanced/rewards/rewards.md @@ -0,0 +1,8 @@ +# 🥤 打赏 + +如果本项目对你的工作起到了帮助，加快了您的项目进展，解决了您的问题，欢迎 `打赏` ！ + +

+special sponsor appwrite +special sponsor appwrite +

diff --git a/docs/advanced/sponsor/sponsor.md b/docs/advanced/sponsor/sponsor.md new file mode 100644 index 0000000..81bd500 --- /dev/null +++ b/docs/advanced/sponsor/sponsor.md @@ -0,0 +1,61 @@ +# 赞助榜 + +感谢所有赞助者！ + +如需更改展示信息，或者需要展示更详细的信息，请联系我。 + +如果需要展示产品、博客、友链啥的，也可以联系我，很乐意为您展示。 + +> 金牌赞助者将额外获得首页产品展示位。 + +## 200 元 + +- 麦可 +- 程序员云创 [https://www.codecommitter.com/](https://www.codecommitter.com/) + +## 50 元 + +- \*皮 +- 暗月隐落 [飞鸟快验 - 一个通用网络验证后台](https://www.fnkuaiyan.cn) + +## 20 元 + +- \*捷 +- \*度 +- \*恼 + +## 10-20 元 + +- 薛柳(15) +- 是魔王哒(12) + +## 10 元 + +- \*辛 +- \*y +- \*边 + +## 5-10 元 + +- Leo （9.90） +- \*熙 （6.66） +- 阿森纳 （6.66） +- I am 小萝北 ²º²4 （6.60） +- SUMMER （5） +- \*峰 （5） +- 阿云 （5） +- nuYoah （5） +- 许志成 （5） +- JY_en_ke_hao （5） + +## 2 元及以下 + +有 `15` 人，这里不一一列出。（如果希望展示，请联系我） + +## 红包打赏 + +还有一部分群友是发 `专属红包` 打赏的，这里没有统计，如果需要展示，请联系我。 + +--- + +> 再次感谢所有赞助者、打赏者！ diff --git a/docs/advanced/wechat/image-1.png b/docs/advanced/wechat/image-1.png new file mode 100644 index 0000000..1a3a7da Binary files /dev/null and b/docs/advanced/wechat/image-1.png differ diff --git a/docs/advanced/wechat/image-2.png b/docs/advanced/wechat/image-2.png new file mode 100644 index 0000000..299b00f Binary files /dev/null and b/docs/advanced/wechat/image-2.png differ diff --git a/docs/advanced/wechat/image.png b/docs/advanced/wechat/image.png new file mode 100644 index 0000000..d2c453f Binary files /dev/null and b/docs/advanced/wechat/image.png differ diff --git a/docs/advanced/wechat/wechat.md b/docs/advanced/wechat/wechat.md new file mode 100644 index 0000000..c2b7115 --- /dev/null +++ b/docs/advanced/wechat/wechat.md @@ -0,0 +1,14 @@ +# 微信交流群 + +> 作者最近比较忙，本来想隐藏交流群的，但是还是有人通过加我微信，要去交流群，索性还是放开吧。 + +最近作者在复习，准备面试，群消息关注较少，希望见谅。 + +再次提醒，千万记得 `先看一遍文档`，两个小时就看完了吧。 + +![alt text](https://oss.laf.run/ukw0y1-site/unibest-discussion-group/wechat.jpeg) + +> 如果上面的微信群满了，请使用下面的 QQ 群，QQ 群不会过期，长期有效。 + +① 群已满，下面是 ② 群。 +![alt text](https://oss.laf.run/ukw0y1-site/unibest-discussion-group/qq.jpeg) diff --git a/docs/base/1-introduction.md b/docs/base/1-introduction.md new file mode 100644 index 0000000..79cfdf4 --- /dev/null +++ b/docs/base/1-introduction.md @@ -0,0 +1,196 @@ +# 简介 + +
+ +[![GitHub Repo stars](https://img.shields.io/github/stars/codercup/unibest?style=flat&logo=github)](https://github.com/codercup/unibest) +[![GitHub Repo stars](https://img.shields.io/github/stars/feige996/unibest?style=flat&logo=github)](https://github.com/feige996/unibest) +[![star](https://gitee.com/codercup/unibest/badge/star.svg?theme=dark)](https://gitee.com/codercup/unibest) +![node version](https://img.shields.io/badge/node-%3E%3D18-green) +![pnpm version](https://img.shields.io/badge/pnpm-%3E%3D7.30-green) +![GitHub License](https://img.shields.io/github/license/codercup/unibest) + +
+ +> 上面前 2 个 `star` 分别是旧仓库 `codercup` 和新仓库 `feige996` 的 `star` 数。 + +`unibest` 是最好的 `uniapp` 开发框架，由 `uniapp` + `Vue3` + `Ts` + `Vite5` + `UnoCss` + `VSCode`(可选 `webstorm`) + `uni插件`+ `wot-ui`（可选其他 UI 库）构建，集成了多种工具和技术，使用了最新的前端技术栈，无需依靠 `HBuilderX`，通过命令行方式即可运行 `web`、`小程序` 和 `App`。（注：`App` 还是需要 `HBuilderX`） + +`unibest` 内置了 `约定式路由`、`layout布局`、`请求封装`、`请求拦截`、`登录拦截`、`UnoCSS`、`i18n多语言` 等基础功能，提供了 `代码提示`、`自动格式化`、`统一配置`、`代码片段` 等辅助功能，让你编写 `uniapp` 拥有 `best` 体验 （ `unibest 的由来`）。 + +> `unibest` 目前支持 `H5`、`小程序` 和 `App`。 + +## ⭐ Star History + +Github Star History 实时地址：[https://star-history.com/#codercup/unibest&Date](https://star-history.com/#codercup/unibest&Date) 。 + +[![Star History Chart](https://api.star-history.com/svg?repos=codercup/unibest&type=Date)](https://star-history.com/#codercup/unibest&Date) + +与同类型模板对比，如下图，红色的为 `unibest`，后来居上，遥遥领先。 + +:::details + +[![Star History Chart](https://api.star-history.com/svg?repos=codercup/unibest,Ares-Chang/uni-vitesse,uni-helper/vitesse-uni-app&type=Date)](https://star-history.com/#codercup/unibest&Ares-Chang/uni-vitesse&uni-helper/vitesse-uni-app&Date) + +同类模板对比实时地址：[https://star-history.com/#codercup/unibest&Ares-Chang/uni-vitesse&uni-helper/vitesse-uni-app&Date](https://star-history.com/#codercup/unibest&Ares-Chang/uni-vitesse&uni-helper/vitesse-uni-app&Date) +::: + +## 🗂 生成过程 + +`unibest` 由最初始的官方 cli 脚手架模板生成，执行的命令如下： + +```sh +npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project +``` + +`uniapp` 官方链接：[点击跳转 - quickstart-cli](https://uniapp.dcloud.net.cn/quickstart-cli.html) + +在官方生成的项目基础上，增加了如下内容： + +- 前端基础配置六件套 + - prettier + - eslint + - stylelint + - husky + - lint-staged + - commitlint +- UnoCSS +- UnoCSS Icons +- Uni 插件 + - vite-plugin-uni-pages + - vite-plugin-uni-layouts + - vite-plugin-uni-manifest + - vite-plugin-uni-platform +- UI 库（默认 `wot-ui`，支持替换其他 `UI库`) +- pinia + pinia-plugin-persistedstate +- 通用功能 + - 请求封装 + - 请求拦截 + - 路由拦截 + +## ✨ 特性 + +- ⚡️ [Vue 3](https://github.com/vuejs/core), [Vite](https://github.com/vitejs/vite), [pnpm](https://pnpm.io/), [esbuild](https://github.com/evanw/esbuild) - 就是快！ + +- 🔥 最新语法 - ` +``` + +::: + +## 3. Vue-Office 使用哪个版本？ + +使用 `1.8x`，而不是 `2.x`，否则出现下面这样的问题： + +![alt text](./assets/15-4.png) + +## 4. 为啥不用 `vant-ui`？ + +`vant-ui` 是 `WEB` 端 `UI 库`，不适用于 `uni-app`。 + +`uni-app` 没有 `window`, `document` 等 `WEB API`，所以凡是使用 `WEB API` 的 `框架`、`UI 库` 等都不适用于 `uni-app`。 + +## 4. 控制台报错 `[plugin:uni:mp-using-component] Unexpected token S in JSON at position 208`。 + +控制台报错如下： +![alt text](./assets/15-6.png) + +原因是 `uni-pages` 这个插件最新版本 `0.2.22` 有问题，需要回退到 `0.2.20`。 + +![alt text](./assets/15-5.png) + +执行如下命令即可： + +``` +pnpm add @uni-helper/vite-plugin-uni-pages@0.2.20 +``` + +> 因为 `unibest` 在 `2.3.0（含）` 之前没有把 `pnpm-lock.yaml` 加入到版本管理，导致小版还是有细微差别。 +> +> 在 `2.4.0` 开始已经加入，不会再出现这个问题。 diff --git a/docs/base/2-start.md b/docs/base/2-start.md new file mode 100644 index 0000000..f19584a --- /dev/null +++ b/docs/base/2-start.md @@ -0,0 +1,119 @@ +# 快速开始 + +- 前置依赖 + + - **Node.js** - `>=v18` + - **pnpm** - `>=7.30`（推荐使用 `8.12+`） + - **`VSCode`** - 可选 `WebStrom` + - **`HBuilderX`** - `APP` 的运行和发布还是离不开它 + - **Vue-Office** - `1.8x`，别升到 `2.x` ！ + +## 创建项目 + +通过下面的命令可以快速生成项目模板，`pnpm create unibest <项目名称>` ，如果不写 `<项目名称>` 会进入命令行交互模式。 + +```bash +# 如果没有 pnpm，请先安装: npm i -g pnpm +pnpm create unibest my-project +``` + +npm 创建如下(不推荐) +:::details +如果使用 `npm`，可能有缓存，需要加上 `@latest` 标识，如果创建失败，请使用 `pnpm` 安装。 + +```bash +npm create unibest my-project +# 如果提示报错，或者生成的项目版本太旧，请使用下面的命令，增加 @latest 标识 +npm create unibest@latest my-project +``` + +::: +实际操作截图如下： + +![create project](./assets/2-1.png) + +`create-unibest` 在 `v1.10.0` 开始会有版本号，如下： + +![alt text](./assets/2-2.png) + +![unibest templates](https://oss.laf.run/ukw0y1-site/xmind/unibest模板.png) + +`create unibest` 支持 `-t` 参数选择模板，目前已有两大类 `8` 个模板 + +- `普通` 模板( `4个` ）：分别是 `base`、`tabbar`、`i18n`、`demo`、~~`js`~~ +- `hbx` 模板(`2个` ）：分别是 `hbx-base`、`hbx-demo`。 + +不带 `-t` 参数时会默认生成 `base` 模板。 + +`base` 模板是最基本的模板，更新最及时，推荐使用 `base` 模板创建新项目。其他几个模板也是基于 `base` 模板得到的。 `demo` 模板则作为参考用。 + +`js` 模板不推荐使用，可以使用 `base` 模板替代，里面已经做了兼容配置，可以直接编写 `js`，原本的 `ts` 文件还能提供部分类型，何乐而不为？ + +```sh +# VS Code 模板 +pnpm create unibest my-project # 默认用 base 模板 + +pnpm create unibest my-project -t base # 基础模板 +pnpm create unibest my-project -t tabbar # 自定义 tabbar 模板 +pnpm create unibest my-project -t i18n # 多语言模板 +pnpm create unibest my-project -t demo # 所有demo的模板(包括i18n) +# pnpm create unibest my-project -t js # js 模板 + +# HBuilderX 模板，方便使用 uniCloud 云开发 (未来可以对接 uni-app x) +pnpm create unibest my-project -t hbx-base # hbx的base模板 +pnpm create unibest my-project -t hbx-demo # hbx的demo模板，包含所有的demo +``` + +## 项目仓库地址 + +`github` 和 `gitee` 实时同步，代码一致。 + +### 普通模板： + +- https://github.com/feige996/unibest +- https://gitee.com/feige996/unibest + +> `demo` 模板是在 `hello-unibest` 项目中，仓库地址如下： + +- https://github.com/feige996/hello-unibest +- https://gitee.com/feige996/hello-unibest + +### hbx 模板 + +- https://github.com/feige996/unibest-hbx +- https://gitee.com/feige996/unibest-hbx + +> `hbx` 目前由 `青谷` 大佬维护，微信号：`qingguxixi`，[青谷 github 地址](https://github.com/Xiphin) 。 + +## 安装、运行 + +```bash [pnpm] +pnpm i +pnpm dev +# dev默认运行的是h5，其他平台执行dev:，如: +pnpm dev:mp-weixin +``` + +`pnpm dev` 之后在浏览器打开 `http://localhost:9000/`。 + +> 其他平台构建和发布，查看 [运行发布篇](./11-build)。 + +## 第一次 `commit` + +```bash +git add . +git commit -m "feat: init project" +``` + +## `v3` 代码块 + +在 `vue` 文件中，输入 `v3` 按 `tab` 即可快速生成页面模板，可以大大加快页面生成。 + +> 原理：基于 `VSCode` 代码块生成。 + +![alt text](./assets/2-4.gif) + +## 注意事项 + +- 若代码里面自动引入的 `API` 报错，只需要 `pnpm dev` 即可。 +- 若代码运行后，`H5端` 浏览器界面底部没有 `tabbar`， 刷新浏览器或者再次 `pnpm dev` 即可。 diff --git a/docs/base/20-best.md b/docs/base/20-best.md new file mode 100644 index 0000000..e7075ec --- /dev/null +++ b/docs/base/20-best.md @@ -0,0 +1,25 @@ +# 最佳实践 + +新项目使用 `base` 模板，可选 `tabbar` 模板。如果需要多语言，可以选 `i18n` 模板。 + +同时参考 `demo` 模板，可以直接 `clone` `demo` 项目，用来参考用。 + +> 推荐先全部体验一下 `demo` 的示例 + +```sh +# 新项目创建 +pnpm create unibest my-project -b base +# 参考项目 +git clone https://github.com/feige996/hello-unibest unibest-demo +# 参考项目-gitee (与 github 同步，无梯子用户优先使用 gitee) +git clone https://gitee.com/feige996/hello-unibest unibest-demo +``` + +## 必看章节 + +- [介绍](/base/1-introduction) +- [快速开始](/base/2-start) +- [uni 插件](/base/3-plugin) +- [常见问题](/base/14-faq) +- [常见问题 2](/base/15-faq) +- [运行发布](/base/11-build) diff --git a/docs/base/3-plugin.md b/docs/base/3-plugin.md new file mode 100644 index 0000000..419044d --- /dev/null +++ b/docs/base/3-plugin.md @@ -0,0 +1,158 @@ +# uni 插件 + +## 引言 + +有群友第一次看到 `unibest` 里面 `vue` 文件 `route-block` 这种写法，表示很奇怪，重来没见过！ + +```vue + +{ + layout: 'demo', + style: { + navigationBarTitleText: '标题', + }, +} + + + +``` + +## uni 插件总览 + +哈哈，这个当然是 `uni插件` 的功劳了，具体点是 `@uni-helper/vite-plugin-uni-pages` 插件的功劳，该插件由 `uni-helper` 官方团队开发。 + +本文就来说说 `unibest` 都引入了哪些有用的 `uni插件`。下面这个表格描述了各个插件的主要作用。 + +| 插件名 | 作用 | +| :----------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @dcloudio/vite-plugin-uni | **最核心的 `uni 插件`**，没有它就不能在 vite 项目跑 uniapp，其他所有的 `uni插件` 都需要经通过它的手来编译，所以写法上，都是先写 `UniXXX`，再写 `Uni`，见下文 | +| @uni-helper/vite-plugin-uni-pages | `uni 插件`，也是 `unibest 灵魂插件`，`route-block` 就是它的功劳，让你可以直接在本文件就能设置页面的路元信息，无需跑去 `pages.json` 配置，同时支持 `pages.config.ts` 编写 `pages.json` | +| @uni-helper/vite-plugin-uni-layouts | `uni 插件`，支多种 `layouts` 布局，群友脑洞大开，充分利用这个特性实现平时不容实现的写法 | +| @uni-helper/vite-plugin-uni-manifest | `uni 插件`，支持 `manifest.config.ts` 编写 `manifest.json` | + +`UniXXX()` 插件都需要在 `uni()` 之前引入，因为最终都需要 `Uni` 来处理所有的代码。如下图： +![vite uni plugin](./assets/3-1.png) + +接下来介绍一下 `uni 插件`，其他 `通用插件` 大家都比较熟悉，不再赘述。 + +`unibest` 引入了 `uni-helper` 团队的几个重要插件，少了它们 `unibest` 就缺少了灵魂，感谢 `uni-helper` 团队的贡献。`Uni 插件` 列表如下： + +- `vite-plugin-uni-pages` + + - 介绍：为 `Vite` 下的 `uni-app` 提供基于文件系统的路由 + - 额外：使用 `TypeScript` 来编写 `uni-app` 的 `pages.json` + - 访问地址：[@uni-helper/vite-plugin-uni-pages](https://github.com/uni-helper/vite-plugin-uni-pages) + +- `vite-plugin-uni-layouts` + + - 介绍：为 `Vite` 下的 `uni-app` 提供类 `nuxt` 的 `layouts` 系统 + - 访问地址：[@uni-helper/vite-plugin-uni-layouts](https://github.com/uni-helper/vite-plugin-uni-layouts) + +- `vite-plugin-uni-manifest` + + - 介绍：使用 `TypeScript` 来编写 `uni-app` 的 `manifest.json` + - 访问地址：[@uni-helper/vite-plugin-uni-manifest](https://github.com/uni-helper/vite-plugin-uni-manifest) + +## vite-plugin-uni-pages + +得益于 [@uni-helper/vite-plugin-uni-pages](https://github.com/uni-helper/vite-plugin-uni-pages)，约定式路由（文件路由）的实现轻而易举。 + +`src/pages` 目录下的每个文件都代表着一个路由。要创建新页面，只需要在这个目录里新增 `.vue` 文件，插件会自动生成对应的 `pages.json` 文件。 + +`route` 代码块则可以配置页面相关信息，这些信息会自动同步到 `page.json`，无需切换到 `page.json` 进行配置。 + +> `pages.json` 文件是自动生成的，请不要手动修改，全局的东西请在 `pages.config.ts` 里面配置，页面上的东西请在 `vue` 文件的 `route` 代码块配置，如下图。 + +```vue [src/pages/index.vue] + + + +{ + style: { + navigationStyle: 'custom', + navigationBarTitleText: '首页', + }, +} + + +``` + +```vue [src/pages/about.vue] + +{ + style: { + navigationBarTitleText: '关于', + }, +} + + +``` + +### 设置首页 + +通过在 `route-block` 里面配置 `type="home"` 即可，尽量保证一个项目 `只有一个` 这个配置，如果有多个，会按照字母顺序来排列，最终可能不是您想要的效果。 + +### 设置 pages 过滤和分包 + +- 过滤：默认 `src/pages` 里面的 `vue` 文件都会生成一个页面，如果不需要生成页面可以对 `vite.config.ts` 中的 `UniPages` 进行 `exclude` 配置。 + +- 分包：如果需要设置 `分包` 则可以通过 `subPackages` 进行配置，该配置项是个数组，可以配置多个 `分包`，注意分包的目录不能为 `src/pages` 里面的子目录。 + +```ts [vite.config.ts] +UniPages({ + exclude: ['**/components/**/**.*'], + subPackages: ['src/pages-sub'], // 是个数组，可以配置多个，但不能为 `src/pages` 里面的子目录 +}) +``` + +## vite-plugin-uni-layouts + +得益于 [@uni-helper/vite-plugin-uni-layouts](https://github.com/uni-helper/vite-plugin-uni-layouts)，你可以轻松地切换不同的布局。 + +`src/layouts` 文件夹下的 `vue` 文件都会自动生成一个布局，默认的布局文件名为 `default` ，路径 `src/layouts/default.vue` 。 + +如果需要修改使用的布局，可以通过 `vue` 文件内 `route` 代码块指定需要的布局，如下示例使用 `demo` 布局。 + +```vue [src/pages/demo.vue]{3} + +{ + layout: 'demo', + style: { + navigationBarTitleText: '关于', + }, +} + +``` + +```vue [src/layouts/demo.vue] + +``` + +## vite-plugin-uni-manifest + +得益于 [@uni-helper/vite-plugin-uni-manifest](https://github.com/uni-helper/vite-plugin-uni-manifest)，你可以使用 `TypeScript` 来编写 `manifest.json`。 + +> `manifest.json` 文件是自动生成的，请不要手动修改，需要配置的内容请在 `manifest.config.ts` 里面配置。 + +## 总结 + +本文介绍了 `unibest` 引入的几个重要的 `uni插件`。 + +如果还想了解更多信息，可以去 `uni-helper` [github 仓库](https://github.com/uni-helper) 看看。 diff --git a/docs/base/4-style.md b/docs/base/4-style.md new file mode 100644 index 0000000..ca01613 --- /dev/null +++ b/docs/base/4-style.md @@ -0,0 +1,220 @@ +# 样式篇 + +本篇主要介绍 `UnoCSS` 的使用，以及如何与 `设计稿尺寸` 对应。 + +## UnoCSS + +[UnoCSS](https://unocss.dev/) 是按需使用的原子 CSS 引擎，提供了良好的样式支持。 + +![alt text](./assets/4-1.png) + +在 VSCode 中还可以预览， + +![alt text](./assets/4-2.png) + +![alt text](./assets/4-3.png) + +> 如果原子化 `UnoCSS` 没有预览效果，请安装 `VSCode` 插件 `antfu.unocss`。 + +如果不记得原子类，可以查 `UnoCSS 的原子类`，[UnoCSS Interactive](https://unocss.dev/interactive/)，如下图 +![alt text](./assets/4-4.png) + +也可以查看 `tailwindcss` 的原子类，更加清晰明了，[链接 - tailwindcss](https://tailwindcss.com/)，如下图： + +![alt text](./assets/4-5.png) + +## 常用的原子类 + +- 宽高内外边距： `w-2`, `h-4`, `px-6`, `mt-8`等 +- 前景色背景色：`text-green-400`, `bg-green-500` +- border: `border-2`, `border-solid`, `border-green-600`, `b-r-2` (注意 `border` = `border-1`，就是说边框 `1px` 时，一般简写为 `border` ) +- border-radius: `rounded-full`, `rounded-6`, `rounded-sm` (不是 `br-10`, 也不是 `b-r-10`) +- line-height: `leading-10` (不是 `l-10`, 也不是 `lh-10`) +- hover: `hover:text-green-200`, `hover:bg-green-300`, `hover:border-dashed` +- flex: `flex`, `items-center`, `justify-center`, `flex-1` + +## `UnoCSS` 配置 + +下面内容选读： + +:::details +`unocss.config.ts` 文件内容如下： + +```ts +// uno.config.ts +import { + type Preset, + defineConfig, + presetUno, + presetAttributify, + presetIcons, + transformerDirectives, + transformerVariantGroup, +} from 'unocss' + +import { presetApplet, presetRemRpx, transformerAttributify } from 'unocss-applet' + +// @see https://unocss.dev/presets/legacy-compat +import { presetLegacyCompat } from '@unocss/preset-legacy-compat' + +const isMp = process.env?.UNI_PLATFORM?.startsWith('mp') ?? false + +const presets: Preset[] = [] +if (isMp) { + // 使用小程序预设 + presets.push(presetApplet(), presetRemRpx()) +} else { + presets.push( + // 非小程序用官方预设 + presetUno(), + // 支持css class属性化 + presetAttributify(), + ) +} +export default defineConfig({ + presets: [ + ...presets, + // 支持图标，需要搭配图标库，eg: @iconify-json/carbon, 使用 `