Taro 开发快速入门手册

1. Taro 项目初始化

1.1. 安装Taro

环境要求

在安装 Taro 之前，确保你的开发环境符合以下要求：

Node.js: 推荐使用 LTS 版本 (>= 14.0.0)。
npm: Taro 使用 npm 来管理依赖，通常 npm 会随 Node.js 一起安装。

安装 Taro CLI

打开终端并运行以下命令来全局安装 Taro CLI：

bash 复制代码

npm install -g @tarojs/cli@4.0.7

安装完成后，可以通过以下命令确认 Taro CLI 是否成功安装：

javascript 复制代码

taro --version

如果看到版本号，说明安装成功。

1.2. 项目搭建

创建新项目

使用 Taro CLI 创建一个新的项目。可以通过以下命令来初始化项目：

javascript 复制代码

taro init my-taro-app

将 my-taro-app 替换为你希望的项目名称。运行命令后，系统会提示你选择项目模板。

选择项目模板

Taro 提供了几种模板供选择：

默认模板: 适用于普通项目。
TypeScript 模板: 如果你希望使用 TypeScript 开发，请选择此项。
React Native 模板: 用于开发 React Native 应用。

根据需求选择合适的模板，然后系统将自动创建项目目录。

安装依赖

进入项目目录后，安装项目所需的依赖：

javascript 复制代码

cd my-taro-app
npm install

这将根据 package.json 文件安装所有必要的依赖库。

启动项目

请注意，为了满足多端打包的场景，将构建产物地址修改一下：

javascript 复制代码

// config/index.ts
import { defineConfig, type UserConfigExport } from "@tarojs/cli";
import TsconfigPathsPlugin from "tsconfig-paths-webpack-plugin";
import devConfig from "./dev";
import prodConfig from "./prod";

console.log("⚡ ~ process.env.TARO_ENV:", process.env.TARO_ENV);

// https://taro-docs.jd.com/docs/next/config#defineconfig-辅助函数
export default defineConfig<"vite">(async (merge, { command, mode }) => {
  const baseConfig: UserConfigExport<"vite"> = {
    ...,
    sourceRoot: "src",
    outputRoot: `dist/${process.env.TARO_ENV}`, // 指定多端
  }

  return baseConfig;
});

(1). 网页端

项目搭建完成后，可以通过以下命令启动开发服务器：

javascript 复制代码

pnpm dev:h5

这条命令会启动 H5 端的开发环境，打开浏览器访问 http://localhost:10086，即可看到默认的 Taro 页面。

(2). 小程序

javascript 复制代码

pnpm dev:weapp

然后打开微信开发者工具，找到项目根目录下的 dist/weapp，导入即可。

1.3. 基础内容

项目结构

创建完 Taro 项目后，项目结构大致如下：

javascript 复制代码

my-taro-app/
├── config/            // 配置文件
├── node_modules/     // 项目依赖
├── src/              // 源码文件
│   ├── assets/       // 静态资源
│   ├── components/   // 自定义组件
│   ├── pages/        // 页面文件
│   ├── app.tsx       // 应用入口文件
│   └── index.html    // H5 页面模板
├── package.json      // 项目描述及依赖
└── tsconfig.json     // TypeScript 配置（如使用）

重要文件说明

app.tsx: 应用的入口文件，定义了应用的基本结构和状态管理。
pages/: 包含所有页面，每个页面都有一个对应的目录和文件。
components/: 存放自定义组件的地方，可以复用的 UI 元素都可以放在这里。
config/: 配置文件，包括路由、样式等。

2. Taro 常用组件

Taro 提供了一套跨平台的组件，以下是一些常用组件的详细介绍：

2.1. View

<View> 是 Taro 中最基本的布局组件，类似于 HTML 的 <div>。

javascript 复制代码

import { View } from '@tarojs/components';

const MyComponent = () => {
  return (
    <View style={{ padding: '20px' }}>
      <Text>Hello, Taro!</Text>
    </View>
  );
};

2.2. Text

<Text> 用于显示文本，支持样式设置。

javascript 复制代码

import { Text } from '@tarojs/components';

const MyText = () => {
  return (
    <Text style={{ color: 'blue' }}>这是蓝色文本</Text>
  );
};

2.3. Image

<Image> 用于显示图片，支持本地和网络图片。

javascript 复制代码

import { Image } from '@tarojs/components';

const MyImage = () => {
  return (
    <Image src="https://example.com/image.png" mode="aspectFit" />
  );
};

2.4. Button

<Button> 用于创建按钮，支持多种样式和事件。

javascript 复制代码

import { Button } from '@tarojs/components';

const MyButton = () => {
  return (
    <Button onClick={() => Taro.showToast({ title: '按钮被点击' })}>
      点击我
    </Button>
  );
};

2.5. Input

<Input> 用于获取用户输入，支持多种输入类型。

javascript 复制代码

import { Input } from '@tarojs/components';

const MyInput = () => {
  return (
    <Input placeholder="请输入内容" />
  );
};

2.6. Form

<Form> 用于创建表单，支持多种表单控件。

javascript 复制代码

import { Form, Button } from '@tarojs/components';

const MyForm = () => {
  return (
    <Form onSubmit={(e) => { /* 处理提交 */ }}>
      <Input name="username" placeholder="用户名" />
      <Button formType="submit">提交</Button>
    </Form>
  );
};

3. Taro 常用API

Taro 提供了一系列 API，方便开发者进行数据请求、设备信息获取等操作。

以下是一些常用 API 的介绍：

3.1. 网络请求

使用 Taro.request 进行网络请求，支持 GET 和 POST 等请求方式。

javascript 复制代码

Taro.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  success: (res) => {
    console.log(res.data);
  },
  fail: (error) => {
    console.error(error);
  }
});

3.2. Toast 提示

使用 Taro.showToast 显示提示信息。

javascript 复制代码

Taro.showToast({
  title: '操作成功',
  icon: 'success',
  duration: 2000,
});

3.3. 获取设备信息

使用 Taro.getSystemInfoSync 获取设备信息。

javascript 复制代码

const systemInfo = Taro.getSystemInfoSync();
console.log(systemInfo);

3.4. 路由跳转

使用 Taro.navigateTo 进行页面跳转。

javascript 复制代码

Taro.navigateTo({
  url: '/pages/detail/detail'
});

3.5. 存储

使用 Taro.setStorageSync 和 Taro.getStorageSync 进行本地存储操作。

javascript 复制代码

Taro.setStorageSync('key', 'value');
const value = Taro.getStorageSync('key');
console.log(value);

4. 多端开发方案详解

Taro 的设计初衷就是为了统一跨平台的开发方式，通过运行时框架、组件和 API 来抹平多端差异。尽管如此，由于不同平台之间的差异，Taro 提供了多种方案来实现更好的跨平台开发，具体如下：

4.1. 内置环境变量

Taro 在编译时提供了一些内置环境变量，以帮助开发者进行特定的处理。

process.env.TARO_ENV

这个变量用于判断当前的编译平台类型，其取值包括：

weapp
swan
alipay
tt
qq
jd
h5
rn

通过这个变量，开发者可以在代码中区分不同环境，以使用不同的逻辑。

引用不同资源

javascript 复制代码

if (process.env.TARO_ENV === 'weapp') {
  require('path/to/weapp/name');
} else if (process.env.TARO_ENV === 'h5') {
  require('path/to/h5/name');
}

加载不同组件

javascript 复制代码

<View>
  {process.env.TARO_ENV === 'weapp' && <ScrollViewWeapp />}
  {process.env.TARO_ENV === 'h5' && <ScrollViewH5 />}
</View>

备注: 不要解构 process.env，请直接以完整方式使用 process.env.TARO_ENV。

4.2. 组件文件中的跨平台支持

为了方便编写跨端的组件代码，Taro 在 .vue 文件的 template 中支持条件编译的特性。

指定平台保留样式

javascript 复制代码

/* #ifdef %PLATFORM% */
模板代码
/* #endif */

指定平台剔除样式

javascript 复制代码

/* #ifndef %PLATFORM% */
模板代码
/* #endif */

**示例：**希望某段模板内容只在微信小程序中生效。

javascript 复制代码

/* #ifdef weapp */
模板代码
/* #endif */

多个平台可以用空格隔开。

4.3. 统一接口的多端文件

虽然内置环境变量可以解决大部分跨端问题，但代码中逻辑判断会影响可维护性。为此，Taro 提供了统一接口的多端文件的方式来解决跨端差异。

统一接口文件的命名规则

开发者可以通过将文件命名为原文件名 + 端类型来创建不同端的实现。所有不同端的文件对外保持统一接口，引用时只需用默认文件名。

使用要点

不同端的文件必须保持统一接口和调用方式。
引用文件时，只需使用默认文件名，不需带后缀。
最好有一个平台无关的默认文件，以避免 TypeScript 的报错。

使用场景

多端组件

假设有一个 Test 组件，存在不同版本：

javascript 复制代码

├── test.js        // 默认版本
├── test.weapp.js  // 微信小程序版本
├── test.swan.js   // 百度小程序版本
└── test.h5.js     // H5 版本

引用方式：

javascript 复制代码

import Test from '../../components/test';

<Test argA={1} argB={2} />

多端脚本逻辑

例如在微信小程序上使用 Taro.setNavigationBarTitle 设置页面标题，而 H5 使用 document.title，可以封装一个 setTitle 方法：

javascript 复制代码

// set_title.weapp.js
import Taro from '@tarojs/taro';
export default function setTitle(title) {
  Taro.setNavigationBarTitle({ title });
}

// set_title.h5.js
export default function setTitle(title) {
  document.title = title;
}

// 调用
import setTitle from '../utils/set_title';
setTitle('页面标题');

多端页面路由

根据不同平台设置不同的路由规则：

javascript 复制代码

let pages = [];

if (process.env.TARO_ENV === 'weapp') {
  pages = ['/pages/index/index'];
}

if (process.env.TARO_ENV === 'swan') {
  pages = ['/pages/indexswan/indexswan'];
}

export default {
  pages,
};

4.4. 端平台插件

从 V3.1.0 起，Taro 将每个小程序平台的兼容逻辑抽取为 Taro 插件，以支持对应平台的编译。Web 端平台插件自 V3.6.0 开始支持。

Taro 内置的端平台插件

其它端平台插件

使用方法

配置插件：

javascript 复制代码

// Taro 项目配置
module.exports = {
  plugins: ['@tarojs/plugin-platform-alipay-iot'],
};

编译为支付宝 IOT 端小程序：

bash 复制代码

taro build --type iot
taro build --type iot --watch

4.5. 端平台的插件化设计思想

随着小程序平台的不断发展，Taro 为了适应新兴平台的需求，提出了端平台的插件化设计思想。

这一思想旨在通过插件的形式扩展 Taro 的端平台支持能力，使得开发者能够灵活地添加或修改编译逻辑，而无需直接修改 Taro 核心库。

插件化设计的理念

解耦合：插件化设计使得平台特定的编译逻辑与 Taro 的核心功能解耦。开发者可以根据自己的需求，选择性地加载所需的插件，而不影响 Taro 的其他部分。这种解耦合有助于提高代码的可维护性和可扩展性。
开放性：Taro 的插件系统允许社区和开发者根据不同的平台需求，自由开发和使用插件。这样的开放性不仅促进了插件的快速迭代和更新，也鼓励社区参与到框架的改进中来。
可复用性：通过插件化，开发者可以复用已有的插件，避免重复造轮子。比如，针对不同的小程序平台，开发者可以基于已有的插件进行扩展，只需实现特定的功能，而无需重新实现所有逻辑。

插件的结构

每个插件通常由以下几个部分组成：

插件名称：唯一标识插件。
编译钩子：在编译过程中，Taro 会在特定的阶段调用插件提供的钩子，以允许开发者插入自定义的编译逻辑。
配置选项：插件可以通过配置选项，让用户定制插件的行为。

插件的封装示例

以下是一个简单的自定义端平台插件的示例，用于扩展微信小程序的编译支持。

创建插件目录 @tarojs/plugin-weixin，并在其中添加以下文件：

javascript 复制代码

@tarojs/plugin-weixin/
├── index.js
└── package.json

编写 package.json

javascript 复制代码

{
  "name": "@tarojs/plugin-weixin",
  "version": "1.0.0",
  "main": "index.js",
  "taro": {
    "plugin": true
  }
}

编写 index.js

老版本：

javascript 复制代码

module.exports = (api) => {
  api.on('buildStart', () => {
    console.log('Custom Alipay plugin: Build started');
  });

  api.on('buildComplete', () => {
    console.log('Custom Alipay plugin: Build completed');
  });

  api.modifyWebpackConfig((config) => {
    // 可以对 Webpack 配置进行修改
    config.module.rules.push({
      test: /\.custom$/,
      use: 'custom-loader',
    });
    return config;
  });
};

4.x：

javascript 复制代码

export default (ctx, options) => {
  // plugin 主体
  ctx.onBuildStart(() => {
    console.log('编译开始！')
  })
  ctx.onBuildFinish(() => {
    console.log('Webpack 编译结束！')
  })
  ctx.onBuildComplete(() => {
    console.log('Taro 构建完成！')
  })
}

使用自定义插件

在 Taro 项目的配置文件中引入自定义插件：

javascript 复制代码

// config/index.js
module.exports = {
  plugins: ['@tarojs/plugin-weixin'],
};

5. 多端应用构建与发布

5.1. 微信小程序构建与发布

构建微信小程序

在项目根目录下，使用以下命令构建微信小程序：

javascript 复制代码

pnpm build:weapp

构建成功后，生成的文件将位于 /dist/weapp 目录中。构建过程会将项目代码转换为微信小程序所需的格式，并进行优化。

发布微信小程序

安装微信开发者工具：下载并安装微信开发者工具。
打开微信开发者工具：启动工具，并选择"导入项目"。
选择构建目录：在导入项目时，选择刚才生成的 /dist/weapp 目录。
填写 AppID：如果尚未拥有 AppID，可以选择"无 AppID"进行测试。
上传代码：导入完成后，点击右上角的"上传"按钮，将代码上传至微信服务器。
提交审核：上传后，填写相关信息并提交审核，待审核通过后即可发布。

注意事项

代码检查：在发布前，确保代码符合微信小程序的审核规范，避免因不合规导致审核失败。
AppID 管理：确保正确管理 AppID 和相关配置，避免信息泄露。

5.2. H5 应用构建与发布

构建 H5 应用

在项目根目录下，使用以下命令构建 H5 应用：

bash 复制代码

pnpm build:h5

构建成功后，生成的文件将位于 /dist/h5 目录中。

发布 H5 应用

这部分部署工作跟其他实战项目操作类似，我们不详细展开，我们以 caddy 为例：

(1). 创建 Dockerfile

在 H5 应用的根目录下，创建一个名为 Dockerfile 的文件，内容如下：

bash 复制代码

# 使用 Caddy 官方镜像
FROM caddy:latest

# 将构建的 H5 文件复制到 Caddy 的默认目录
COPY ./dist/h5 /usr/share/caddy

(2). 目录结构示例

你的项目目录结构应该如下所示：

javascript 复制代码

myProject/
├── dist/
│   └── h5/
│       ├── index.html
│       ├── assets/
│       └── ...
└── Dockerfile

(3). 构建 Docker 镜像

在项目根目录下，执行以下命令构建 Docker 镜像：

bash 复制代码

docker build -t my-h5-app .

这里 my-h5-app 是自定义的镜像名称。

(4). 运行 Docker 容器

使用以下命令运行 Docker 容器：

javascript 复制代码

docker run -d -p 80:80 --name my-h5-app-container my-h5-app

参数说明：

-d：以后台模式运行容器。
-p 80:80：将宿主机的 80 端口映射到容器的 80 端口。
--name my-h5-app-container：指定容器的名称。

(5). 访问应用

在浏览器中输入 http://<YOUR_SERVER_IP>，即可访问部署的 H5 应用。

(6). 配置 HTTPS（可选）

Caddy 默认支持自动获取 SSL 证书，但需要你提供域名。在使用 Caddy 时，你可以通过添加一个 Caddyfile 来配置 HTTPS。

创建 Caddyfile

在项目根目录下创建一个名为 Caddyfile 的文件，内容如下：

bash 复制代码

yourdomain.com {
    root * /usr/share/caddy
    file_server
}

将 yourdomain.com 替换为你的实际域名。

使用 Caddyfile 运行 Docker

使用以下命令重新运行 Docker 容器：

bash 复制代码

docker run -d -p 80:80 -p 443:443 --name my-h5-app-container -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile my-h5-app