组件与 API

VPT 使用 Taro 4 的组件和 API 规范。

使用组件

组件从 virtual:taro/components 导入：

import { Text, View } from 'virtual:taro/components'

export default function AccountCard() {
    return (
        <View className="rounded-2xl bg-slate-950 p-5">
            <Text className="text-xl font-bold text-white">账户概览</Text>
        </View>
    )
}

create-vite-taro 默认启用 Tailwind CSS v4。更多样式用法参见样式。

JSX 约定

组件名使用 PascalCase，例如 View、ScrollView 和 PageMeta。
属性使用 camelCase，例如 scrollY 和 hoverClass。
样式类使用 className。
事件以 on 开头，例如 onClick、onScroll 和 onChange。
共享页面使用 Taro 组件，不要直接使用 <div>、<span> 等 Web 元素。

支持的组件

以下组件可以从 virtual:taro/components 导入。点击组件名称查看属性、事件和平台支持。

视图容器

CoverImage：显示可覆盖在原生组件上的图片。
CoverView：显示可覆盖在原生组件上的视图。
MatchMedia：仅在媒体查询条件匹配时显示内容。
MovableArea：定义 MovableView 的移动范围。
MovableView：在 MovableArea 内拖动或缩放视图。
PageContainer：显示带进入和退出动画的页面容器。
RootPortal：将子节点渲染到页面根节点。
ScrollView：显示可滚动的内容区域。
Swiper：显示可滑动切换的轮播容器。
SwiperItem：定义 Swiper 中的单个轮播项。
View：通用布局容器。

基础内容

Icon：显示内置图标。
Progress：显示进度条。
RichText：渲染富文本节点。
Text：显示文本内容。

表单

Button：触发操作或微信开放能力。
Checkbox：提供单个多选项。
CheckboxGroup：管理一组多选项及其变更事件。
Editor：提供富文本编辑区域。
Form：收集控件值并触发表单提交或重置。
Input：提供单行文本输入。
KeyboardAccessory：在输入法键盘上方显示工具栏。
Label：为表单控件提供可点击标签。
Picker：显示从底部弹出的选择器。
PickerView：在页面内显示滚动选择器。
PickerViewColumn：定义 PickerView 的一列选项。
Radio：提供单个单选项。
RadioGroup：管理一组单选项及其变更事件。
Slider：通过滑块选择数值。
Switch：切换开关状态。
Textarea：提供多行文本输入。

Skyline 布局

DraggableSheet：显示可拖动的面板。
GridBuilder：在自定义滚动容器中按需构建网格项。
GridView：在自定义滚动容器中排列网格内容。
ListBuilder：在自定义滚动容器中按需构建列表项。
ListView：在自定义滚动容器中排列列表内容。
NestedScrollBody：定义参与嵌套滚动的主体区域。
NestedScrollHeader：定义参与嵌套滚动的头部区域。
OpenContainer：在页面跳转时执行容器转场动画。
ShareElement：在页面之间执行共享元素转场。
Snapshot：将子节点的渲染结果导出为图片。
Span：在 Skyline 文本中显示行内内容。
StickyHeader：在滚动时固定头部内容。
StickySection：对吸顶区块及其内容分组。

Skyline 手势

DoubleTapGestureHandler：识别双击手势。
ForcePressGestureHandler：识别重按手势。
HorizontalDragGestureHandler：识别水平拖动手势。
LongPressGestureHandler：识别长按手势。
PanGestureHandler：识别平移手势。
ScaleGestureHandler：识别双指缩放手势。
TapGestureHandler：识别点击手势。
VerticalDragGestureHandler：识别垂直拖动手势。

导航

FunctionalPageNavigator：跳转到插件提供的功能页。
NavigationBar：在 PageMeta 中配置页面导航栏。
Navigator：以声明式链接跳转页面。

媒体

Audio：播放音频。
Camera：显示系统相机画面。
ChannelLive：显示微信视频号直播。
ChannelVideo：显示微信视频号视频。
Image：显示图片。
LivePlayer：播放实时音视频流。
LivePusher：推送实时音视频流。
Video：播放视频。
VoipRoom：提供多人实时音视频通话。

地图与画布

Map：显示腾讯地图。
Canvas：使用 Canvas 绘制图形。

开放能力

Ad：显示广告。
AdCustom：显示原生模板广告。
OfficialAccount：显示微信公众号关注组件。
OpenData：显示微信开放数据。
WebView：在小程序中承载网页。

配置与插槽

PageMeta：动态配置页面元信息。
CustomWrapper：缩小深层数据更新影响的节点范围。
NativeSlot：为编译后的原生组件声明插槽。
Slot：向自定义组件的指定插槽传入内容。

使用 API

Taro API 包括内置功能和对小程序能力的封装，统一挂载在 Taro 命名空间下。VPT 从 virtual:taro/api 提供这些接口：

import Taro from 'virtual:taro/api'

export async function confirmSave() {
    const result = await Taro.showModal({
        title: '保存修改',
        content: '确定保存当前修改吗？'
    })

    return result.confirm
}

Taro.showModal() 等异步 API 支持 Promise，可以使用 await，也可以传入回调函数。完整接口、参数和平台支持见 API 参考。

API 分类

Hooks

应用与页面生命周期、页面滚动与刷新、分享以及路由参数等 React hooks。

扩展

事件中心、运行环境、当前实例、渲染器信息和 API 拦截器等 Taro 运行时扩展。

框架

获取 App 实例和当前页面栈。

基础

运行环境、系统信息、版本更新、调试日志、性能监控和加密等基础能力。

路由

在应用页面之间跳转、重定向、返回或切换 tab。

跳转

打开其他小程序、半屏小程序或业务功能页，并从外部小程序返回。

转发

配置分享菜单、转发内容、私密消息和分享信息。

界面

控制提示框、导航栏、Tab Bar、下拉刷新、滚动、动画、字体和窗口。

网络

发起 HTTP 请求、上传下载文件，以及使用 WebSocket、TCP、UDP 和 mDNS。

支付

发起微信支付、订单支付和支付身份验证。

数据缓存

同步或异步读写本地缓存，并使用缓存管理器和后台更新。

数据分析

上报分析事件、性能指标和实验配置。

画布

创建 Canvas 上下文、读写像素、导出图片和使用离屏画布。

媒体

处理图片、视频、音频、相机、录音、实时音视频、地图和媒体编辑。

位置

获取和监听位置、选择地点并打开地图位置。

文件

访问文件系统，保存、读取、删除和打开文件。

开放接口

使用登录、用户信息、授权、账号设置、订阅消息、卡券和隐私接口。

设备

访问蓝牙、Wi-Fi、NFC、传感器、剪贴板、键盘、电量、扫码和联系人等设备能力。

AI

使用端侧推理、VisionKit、人体与人脸识别等微信 AI 能力。

Worker

创建和管理小程序 Worker 后台线程。

WXML

查询节点，并观察元素相交、尺寸和媒体查询变化。

第三方平台

读取第三方平台代开发小程序的扩展配置。

广告

创建和控制激励视频广告与插屏广告。

Skyline

操作 Skyline 的可拖拽面板上下文与节点截图能力。

云开发

访问微信云开发和云数据库实例。

平台支持

组件支持见组件参考，API 支持见 API 参考。微信小程序专用接口应使用条件编译与 Web 代码隔离。