组件与 API

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

使用组件

页面可以直接使用 div、span 等 HTML 标签，并与 Taro 组件混用。

Taro 组件从 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 约定

Taro 组件使用 PascalCase，例如 View、ScrollView 和 PageMeta。
属性使用 camelCase，例如 scrollY 和 hoverClass。
样式类使用 className。
事件以 on 开头，例如 onClick、onScroll 和 onChange。

支持的组件

以下组件可以从 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：识别垂直拖动手势。

媒体

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

地图与画布

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

开放能力

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

配置与插槽

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

使用共享工具

从 virtual:taro/shared 导入 @tarojs/shared 的工具函数和类型，适用于 WX、支付宝、抖音和 H5：

import { toCamelCase, type Box } from 'virtual:taro/shared'

const value: Box<string> = { v: toCamelCase('background-color') }

该入口使用 VPT 自带的 @tarojs/shared 依赖，并与 Taro 运行时共享 hooks 等状态。应用无需单独安装该包或配置别名；类型由 vite-plugin-taro/client 提供。

使用 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 参考。

H5 的 Tree Shaking

H5 的默认 Taro 导出是只读的 ESM 命名空间，不需要编译器改写 API 调用。以下写法均可让构建器移除未使用的平台 API 实现：

import Taro, { showToast } from 'virtual:taro/api'

Taro.showToast({ title: '完成' })
Taro['showToast']({ title: '完成' })
showToast({ title: '完成' })

不要给命名空间增加或替换成员，例如 Taro.showToast = replacement。需要封装或 mock 时，在应用自己的模块中提供函数；Taro.options 等导出对象内部的共享状态仍然可用。

动态访问 Taro[key]、枚举命名空间，或把整个 Taro 传给构建器无法分析的代码，可能保留更多 API。当前 Rolldown 对 const { showToast } = Taro 这样的命名空间解构也会保留完整导出；应改为具名导入。优先使用上面的静态成员访问或具名导入。H5 的 canIUse 在运行时判断能力；需要在构建时排除平台专用代码时，使用条件编译。

生命周期 hooks 保留 Taro 原有的统一注册方式，不会按单个 hook 裁剪。小程序端也保留原有的共享 API 对象和批量初始化方式，不提供按单个原生 API 裁剪的保证；上述只读命名空间约定仅适用于 H5。

平台支持

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