mirror of
https://github.com/ialley-workshop-open/uni-halo.git
synced 2026-09-12 16:40:40 +08:00
refactor: 架构升级
This commit is contained in:
小莫唐尼
@@ -0,0 +1,192 @@
|
||||
# uni-app-x 安装指南
|
||||
|
||||
## 官方文档
|
||||
|
||||
参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html
|
||||
|
||||
## 环境要求
|
||||
|
||||
### HBuilderX 版本
|
||||
|
||||
- **最低版本**：HBuilderX 3.93+
|
||||
- **推荐版本**：最新版本
|
||||
|
||||
### Node.js 版本
|
||||
|
||||
- **推荐版本**：Node.js 16.x 或更高版本
|
||||
- **最低版本**：Node.js 14.x
|
||||
|
||||
```bash
|
||||
# 检查 Node.js 版本
|
||||
node --version
|
||||
|
||||
# 检查 npm 版本
|
||||
npm --version
|
||||
```
|
||||
|
||||
### TypeScript
|
||||
|
||||
uni-app-x 使用 TypeScript，需要 TypeScript 支持。
|
||||
|
||||
## 安装方式
|
||||
|
||||
### 方式一：使用 HBuilderX（推荐）
|
||||
|
||||
HBuilderX 是 DCloud 官方提供的 IDE，内置 uni-app-x 开发环境。
|
||||
|
||||
**下载安装**：
|
||||
1. 访问 https://www.dcloud.io/hbuilderx.html
|
||||
2. 下载 HBuilderX（App 开发版，版本 3.93+）
|
||||
3. 安装并启动 HBuilderX
|
||||
|
||||
**创建项目**：
|
||||
1. 文件 → 新建 → 项目
|
||||
2. 选择 **uni-app x**
|
||||
3. 选择模板（默认模板、示例模板等）
|
||||
4. 填写项目名称和路径
|
||||
5. 点击创建
|
||||
|
||||
### 方式二：使用 CLI
|
||||
|
||||
```bash
|
||||
# 使用官方模板创建项目
|
||||
npx degit dcloudio/uni-preset-vue-x my-project
|
||||
|
||||
# 或使用官方脚手架
|
||||
npm create uni-app-x@latest my-project
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
创建后的项目结构：
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── src/ # 源代码目录
|
||||
│ ├── pages/ # 页面目录
|
||||
│ │ ├── index/
|
||||
│ │ │ └── index.vue
|
||||
│ │ └── ...
|
||||
│ ├── components/ # 组件目录
|
||||
│ │ └── ...
|
||||
│ ├── static/ # 静态资源
|
||||
│ │ └── ...
|
||||
│ ├── utils/ # 工具函数
|
||||
│ ├── api/ # API 接口
|
||||
│ ├── store/ # 状态管理
|
||||
│ ├── App.vue # 应用入口
|
||||
│ └── main.ts # 入口文件（TypeScript）
|
||||
├── manifest.json # 应用配置
|
||||
├── pages.json # 页面路由配置
|
||||
├── vite.config.ts # Vite 配置
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
### tsconfig.json
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"module": "ESNext",
|
||||
"lib": ["ES2020", "DOM"],
|
||||
"jsx": "preserve",
|
||||
"moduleResolution": "node",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"types": ["@dcloudio/types"]
|
||||
},
|
||||
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
```
|
||||
|
||||
### vite.config.ts
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from 'vite'
|
||||
import uni from '@dcloudio/vite-plugin-uni'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [uni()],
|
||||
server: {
|
||||
port: 3000,
|
||||
open: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### manifest.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-app-x",
|
||||
"appid": "",
|
||||
"description": "",
|
||||
"versionName": "1.0.0",
|
||||
"versionCode": "100",
|
||||
"uni-app-x": {
|
||||
"compilerVersion": "1.0.0",
|
||||
"vueVersion": "3",
|
||||
"typescript": true
|
||||
},
|
||||
"app-plus": {
|
||||
"usingComponents": true,
|
||||
"compilerVersion": 3
|
||||
},
|
||||
"h5": {
|
||||
"router": {
|
||||
"mode": "hash",
|
||||
"base": "/"
|
||||
}
|
||||
},
|
||||
"mp-weixin": {
|
||||
"appid": "",
|
||||
"setting": {
|
||||
"urlCheck": false
|
||||
},
|
||||
"usingComponents": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 验证安装
|
||||
|
||||
创建项目后，验证安装是否成功：
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
npm install
|
||||
npm run dev:h5
|
||||
```
|
||||
|
||||
如果浏览器自动打开并显示 uni-app-x 欢迎页面，说明安装成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. HBuilderX 版本过低
|
||||
|
||||
确保使用 HBuilderX 3.93 或更高版本。
|
||||
|
||||
### 2. TypeScript 错误
|
||||
|
||||
检查 `tsconfig.json` 配置是否正确，确保安装了 `@dcloudio/types`。
|
||||
|
||||
### 3. 依赖安装失败
|
||||
|
||||
使用国内镜像：
|
||||
|
||||
```bash
|
||||
npm config set registry https://registry.npmmirror.com
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
安装完成后，参考 `quick-start.md` 开始创建第一个项目。
|
||||
@@ -0,0 +1,156 @@
|
||||
# uni-app-x 项目类型
|
||||
|
||||
## 官方文档
|
||||
|
||||
参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html
|
||||
|
||||
## 项目特点
|
||||
|
||||
uni-app-x 项目统一使用：
|
||||
- **Vue 3**：必须使用 Vue 3
|
||||
- **TypeScript**：必须使用 TypeScript
|
||||
- **Vite**：使用 Vite 作为构建工具
|
||||
- **Composition API**：推荐使用 Composition API
|
||||
|
||||
## 项目结构
|
||||
|
||||
所有 uni-app-x 项目都遵循相同的结构：
|
||||
|
||||
```
|
||||
my-uniappx-project/
|
||||
├── src/
|
||||
│ ├── pages/ # 页面目录
|
||||
│ ├── components/ # 组件目录
|
||||
│ ├── static/ # 静态资源
|
||||
│ ├── utils/ # 工具函数
|
||||
│ ├── api/ # API 接口
|
||||
│ ├── store/ # 状态管理
|
||||
│ ├── App.vue # 应用入口
|
||||
│ └── main.ts # TypeScript 入口
|
||||
├── manifest.json # 应用配置
|
||||
├── pages.json # 页面路由配置
|
||||
├── vite.config.ts # Vite 配置
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
### tsconfig.json
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"module": "ESNext",
|
||||
"lib": ["ES2020", "DOM"],
|
||||
"jsx": "preserve",
|
||||
"moduleResolution": "node",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"types": ["@dcloudio/types"]
|
||||
},
|
||||
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
```
|
||||
|
||||
### vite.config.ts
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from 'vite'
|
||||
import uni from '@dcloudio/vite-plugin-uni'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [uni()],
|
||||
server: {
|
||||
port: 3000,
|
||||
open: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### manifest.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-app-x",
|
||||
"appid": "",
|
||||
"description": "",
|
||||
"versionName": "1.0.0",
|
||||
"versionCode": "100",
|
||||
"uni-app-x": {
|
||||
"compilerVersion": "1.0.0",
|
||||
"vueVersion": "3",
|
||||
"typescript": true
|
||||
},
|
||||
"app-plus": {
|
||||
"usingComponents": true,
|
||||
"compilerVersion": 3
|
||||
},
|
||||
"h5": {
|
||||
"router": {
|
||||
"mode": "hash",
|
||||
"base": "/"
|
||||
}
|
||||
},
|
||||
"mp-weixin": {
|
||||
"appid": "",
|
||||
"setting": {
|
||||
"urlCheck": false
|
||||
},
|
||||
"usingComponents": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 创建方式
|
||||
|
||||
### 使用 HBuilderX
|
||||
|
||||
1. 文件 → 新建 → 项目
|
||||
2. 选择 **uni-app x**
|
||||
3. 选择模板（默认模板、示例模板等）
|
||||
4. 填写项目信息
|
||||
5. 点击创建
|
||||
|
||||
### 使用 CLI
|
||||
|
||||
```bash
|
||||
# 使用官方模板
|
||||
npx degit dcloudio/uni-preset-vue-x my-project
|
||||
|
||||
# 或使用官方脚手架
|
||||
npm create uni-app-x@latest my-project
|
||||
```
|
||||
|
||||
## 开发规范
|
||||
|
||||
### 1. TypeScript 使用
|
||||
|
||||
- 为所有组件和函数添加类型定义
|
||||
- 使用接口定义数据结构
|
||||
- 利用类型推断减少冗余代码
|
||||
|
||||
### 2. Composition API
|
||||
|
||||
- 使用 `<script setup>` 语法
|
||||
- 提取可复用的组合式函数
|
||||
- 合理组织代码逻辑
|
||||
|
||||
### 3. 代码规范
|
||||
|
||||
- 遵循 Vue 3 最佳实践
|
||||
- 使用 ESLint 和 Prettier
|
||||
- 统一代码风格
|
||||
|
||||
## 参考资源
|
||||
|
||||
- uni-app-x 文档：https://doc.dcloud.net.cn/uni-app-x/
|
||||
- Vue 3 文档：https://cn.vuejs.org/
|
||||
- TypeScript 文档：https://www.typescriptlang.org/
|
||||
- Vite 文档：https://cn.vitejs.dev/
|
||||
@@ -0,0 +1,250 @@
|
||||
# uni-app-x 快速开始
|
||||
|
||||
## 官方文档
|
||||
|
||||
参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html
|
||||
|
||||
## 创建第一个项目
|
||||
|
||||
### 一句话创建（CLI）
|
||||
|
||||
```bash
|
||||
# 官方脚手架（推荐）
|
||||
npm create uni-app-x@latest my-uniappx
|
||||
|
||||
# 或使用官方模板
|
||||
npx degit dcloudio/uni-preset-vue-x my-uniappx
|
||||
```
|
||||
|
||||
### 使用 HBuilderX
|
||||
|
||||
1. **打开 HBuilderX**（版本 3.93+）
|
||||
2. **文件 → 新建 → 项目**
|
||||
3. **选择项目类型**：uni-app x
|
||||
4. **选择模板**：默认模板或示例模板
|
||||
5. **填写项目信息**：
|
||||
- 项目名称：my-first-uniappx
|
||||
- 项目路径：选择保存位置
|
||||
6. **点击创建**
|
||||
|
||||
### 使用 CLI
|
||||
|
||||
```bash
|
||||
# 创建项目
|
||||
npx degit dcloudio/uni-preset-vue-x my-first-uniappx
|
||||
|
||||
# 进入项目目录
|
||||
cd my-first-uniappx
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 运行到 H5
|
||||
npm run dev:h5
|
||||
|
||||
# 运行到微信小程序
|
||||
npm run dev:mp-weixin
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
创建后的项目结构：
|
||||
|
||||
```
|
||||
my-first-uniappx/
|
||||
├── src/
|
||||
│ ├── pages/
|
||||
│ │ ├── index/
|
||||
│ │ │ └── index.vue
|
||||
│ │ └── ...
|
||||
│ ├── components/
|
||||
│ ├── static/
|
||||
│ ├── App.vue
|
||||
│ └── main.ts # TypeScript 入口
|
||||
├── manifest.json
|
||||
├── pages.json
|
||||
├── vite.config.ts
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## 运行项目
|
||||
|
||||
### H5 平台
|
||||
|
||||
```bash
|
||||
npm run dev:h5
|
||||
```
|
||||
|
||||
浏览器会自动打开 `http://localhost:3000`
|
||||
|
||||
### 微信小程序
|
||||
|
||||
```bash
|
||||
npm run dev:mp-weixin
|
||||
```
|
||||
|
||||
项目会编译到 `dist/dev/mp-weixin`，使用微信开发者工具打开该目录。
|
||||
|
||||
## 创建第一个页面（TypeScript + Composition API）
|
||||
|
||||
1. **在 `src/pages` 目录下创建页面**：
|
||||
|
||||
```
|
||||
src/pages/
|
||||
└── hello/
|
||||
└── hello.vue
|
||||
```
|
||||
|
||||
2. **创建页面文件 `hello.vue`**：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<view class="container">
|
||||
<text class="title">{{ title }}</text>
|
||||
<button @click="handleClick">点击我</button>
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue'
|
||||
import { onLoad } from '@dcloudio/uni-app'
|
||||
|
||||
const title = ref<string>('Hello uni-app-x!')
|
||||
|
||||
const handleClick = () => {
|
||||
uni.showToast({
|
||||
title: '按钮被点击了',
|
||||
icon: 'success'
|
||||
})
|
||||
}
|
||||
|
||||
onLoad((options) => {
|
||||
console.log('页面加载', options)
|
||||
})
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.container {
|
||||
padding: 20px;
|
||||
text-align: center;
|
||||
}
|
||||
.title {
|
||||
font-size: 24px;
|
||||
color: #333;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
3. **在 `pages.json` 中注册页面**：
|
||||
|
||||
```json
|
||||
{
|
||||
"pages": [
|
||||
{
|
||||
"path": "pages/index/index",
|
||||
"style": {
|
||||
"navigationBarTitleText": "首页"
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": "pages/hello/hello",
|
||||
"style": {
|
||||
"navigationBarTitleText": "Hello"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 创建第一个组件（TypeScript）
|
||||
|
||||
1. **在 `src/components` 目录下创建组件**：
|
||||
|
||||
```
|
||||
src/components/
|
||||
└── my-button/
|
||||
└── my-button.vue
|
||||
```
|
||||
|
||||
2. **组件代码**：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<button class="my-button" @click="handleClick">
|
||||
{{ text }}
|
||||
</button>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
interface Props {
|
||||
text?: string
|
||||
}
|
||||
|
||||
const props = withDefaults(defineProps<Props>(), {
|
||||
text: '按钮'
|
||||
})
|
||||
|
||||
const emit = defineEmits<{
|
||||
(e: 'click'): void
|
||||
}>()
|
||||
|
||||
const handleClick = () => {
|
||||
emit('click')
|
||||
}
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.my-button {
|
||||
background-color: #007aff;
|
||||
color: white;
|
||||
border: none;
|
||||
padding: 10px 20px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
3. **在页面中使用**：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<view>
|
||||
<my-button text="点击我" @click="handleButtonClick"></my-button>
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import MyButton from '@/components/my-button/my-button.vue'
|
||||
|
||||
const handleButtonClick = () => {
|
||||
console.log('按钮被点击')
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## 与 uni-app 的区别
|
||||
|
||||
### 1. 技术栈
|
||||
|
||||
- **uni-app**：Vue 2/3 + JavaScript
|
||||
- **uni-app-x**：Vue 3 + TypeScript + Vite
|
||||
|
||||
### 2. 开发体验
|
||||
|
||||
- 更好的 TypeScript 支持
|
||||
- 更快的构建速度（Vite）
|
||||
- 更好的代码提示
|
||||
|
||||
### 3. 性能
|
||||
|
||||
- 更小的包体积
|
||||
- 更快的启动速度
|
||||
- 更好的运行时性能
|
||||
|
||||
## 下一步
|
||||
|
||||
- 学习 uni-app-x 组件：参考 `uniappx-project`
|
||||
- 学习 uni-app-x API：参考 `uniappx-project`
|
||||
- 配置项目：参考 `templates/project-templates.md`
|
||||
Reference in New Issue
Block a user