{"id":28447741,"url":"https://github.com/nervjs/taro-vant","last_synced_at":"2025-06-30T13:32:15.069Z","repository":{"id":52397053,"uuid":"359662706","full_name":"NervJS/taro-vant","owner":"NervJS","description":"Taro 兼容 VantUI","archived":false,"fork":false,"pushed_at":"2021-08-12T08:29:25.000Z","size":610,"stargazers_count":44,"open_issues_count":3,"forks_count":10,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-06-06T12:06:55.467Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NervJS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-20T02:44:40.000Z","updated_at":"2025-02-26T08:10:27.000Z","dependencies_parsed_at":"2022-08-17T19:10:17.206Z","dependency_job_id":null,"html_url":"https://github.com/NervJS/taro-vant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NervJS/taro-vant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NervJS%2Ftaro-vant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NervJS%2Ftaro-vant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NervJS%2Ftaro-vant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NervJS%2Ftaro-vant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NervJS","download_url":"https://codeload.github.com/NervJS/taro-vant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NervJS%2Ftaro-vant/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262783278,"owners_count":23363502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T12:06:43.701Z","updated_at":"2025-06-30T13:32:15.026Z","avatar_url":"https://github.com/NervJS.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Taro Vant\n\n\u003e Taro v3.3+\n\n在 Taro 中使用有赞前端团队开源的移动端组件库[Vant](https://vant-contrib.gitee.io/vant/#/zh-CN/home)。\n\n`Vant` 官方示例：https://vant-contrib.gitee.io/vant/mobile.html#/zh-CN。\n\n能直接兼容使用的组件大概为 **70%**，具体适配情况请见下文。\n\n## Getting Start\n\n```bash\n# 安装 CLI\nnpm i @tarojs/cli@alpha -g\n\n# 启动项目\ncd taro-vant\nnpm i\ntaro build --type weapp --watch\n\n# 预览项目时需要以 prod 模式打包\ntaro build --type weapp\n```\n\n## 兼容工作\n\n相对于官方示例的 H5 代码，本项目主要做了以下兼容工作：\n\n### 1. 浏览器默认样式\n\n#### 方式一、开发者可以选择在全局引入浏览器的默认样式\n\nTaro 提供两种内置样式我们可以直接引入生效：\n\n- `@tarojs/taro/html.css`: W3C HTML4 的内置样式，只有 HTML4 标签样式，体积较小，兼容性强，能适应大多数情况。\n- `@tarojs/taro/html5.css`: Chrome(Blink) HTML5 的内置样式，内置样式丰富，包括了大多数 HTML5 标签，体积较大，不一定支持所有小程序容器。\n\n```scss\n// app.css\n// html4\nimport '@tarojs/taro/html.css';\n// html5\nimport '@tarojs/taro/html5.css';\n```\n\n#### 方式二、只摘取部分需要的浏览器默认样式\n\n以往编写 H5 应用时，我们常常会写一些样式去重置浏览器默认样式。所以一般情况不需要引入，或者可以手动挑选必须的样式。\n\n```scss\n// app.css\n// 以下是为了适配 VantUI 项目所需要的默认样式\n.h5-span {\n  display: inline;\n}\n\n.h5-button,\n.h5-input {\n  display: inline-block;\n}\n\n.h5-button::after {\n  border: none;\n}\n\n.van-button--hairline::after {\n  transform-origin: unset;\n  width: unset;\n  height: unset;\n}\n```\n\n### 2. 尺寸单位\n\nTaro 默认会对开发者编写的尺寸进行转换：\n\n- 小程序：px -\u003e rpx\n- H5：px -\u003e rem\n\n但是组件库一般按照 750px 设计稿的 1/2 编写尺寸，Taro 不需要再对组件库的尺寸进行转换。\n\n可以配置 `@tarojs/plugin-html` 的 `pxtransformBlackList` 选项进行过滤：\n\n```js\n// config/index.js\nconfig = {\n  plugins: [\n    ['@tarojs/plugin-html', {\n      // 过滤 vant 组件库的前缀：van-\n      pxtransformBlackList: [/demo-/, /van-/]\n    }]\n  ]\n  // ...\n}\n```\n\n### 3. SVG 图标\n\n小程序不支持 SVG，目前组件库中的 SVG 图标都不能使用。\n\n开发者可以配置的图标尽量使用 `\u003cimg\u003e`，组件内置的 SVG 图标则暂时没有办法处理。\n\n### 4. 获取元素尺寸\n\n因为在小程序中获取元素尺寸的 API（SelectorQuery） 是**异步**的，和 H5 的**同步**获取（如 `elment.offsetHeight`）不一样。所以需要调用 H5 DOM API 获取元素尺寸的组件，如 `Calendar` 等均不能使用。\n\n### 5. 样式选择器\n\n以下选择器不能正常工作：\n\n- 通配符 `*`\n- 媒体查询\n- 属性选择器，当属性不是对应小程序组件的内置属性时\n\n### 6. 兼容 Vue `\u003ctransition\u003e`\n\n`\u003ctransition\u003e` 组件内部使用了 `getComputedStyle`，用于嗅探组件上的动画样式。但是在小程序中没有办法实现 `getComputedStyle`，可以通过以下方法进行 hack：\n\n为元素的 `style` 设置 `transitionDuration` 或 `animationDuration` 指定过渡时间，即可兼容 `\u003ctransition\u003e`。\n\n```jsx\n\u003ctransition\u003e\n  \u003cdiv style=\"animationDuration: 0.5s\" /\u003e\n\u003c/transition\u003e\n```\n\n### 7. 兼容使用了过渡动画的组件\n\n**VantUI** 中使用到过渡效果的组件，都是使用 `\u003ctransition\u003e` 实现的。因此需要对它们进行兼容，可以分为两种情况：\n\n#### 情况一、组件可以设置 `duration` 属性\n\n**VantUI** 中部分组件可以设置 `duration` 属性，它能为组件增加 `animationDuration` 的 style，这时我们直接设置 `duration` 属性即可。\n\n这些组件包括： `Popup`、`ActionSheet`、`Overlay`、`ShareSheet`、`Coupon`\n\n#### 情况二\n\n另外一些带有过渡动画的组件则没有 `duration` 属性，我们要手动为它们加上 `animationDuration` 的 style，例如 `内置样式` 的 demo。\n\n还有一些组件把过渡动画的元素封装在内，又没有对外暴露 `duration` 属性，则只能改写 **VantUI** 的源码，或忍受没有过渡动画了。\n\n这些组件包括： `Dialog`、`NumberKeyboard`\n\n### 8. 兼容 `Tabs`\n\n`Tabs` 在 **line** 风格下，需要调用 `getBoundingClientRect` API，这样是不支持的。\n\n我们可以魔改它的样式来进行兼容：\n\n```scss\n// 魔改 tabs 样式\n.van-tabs__line {\n  display: none;\n}\n.van-tab.van-tab--active::after {\n  content: '';\n  position: absolute;\n  bottom: 0;\n  left: 50%;\n  margin-left: -20px;\n  z-index: 1;\n  width: 40px;\n  height: 3px;\n  background-color: #ee0a24;\n  border-radius: 3px;\n}\n```\n\n另外，复合组件 `Cascader`、 `Coupon` 也使用了 `Tabs` 组件，在使用它们时也需要加上上述兼容样式。\n\n### 9. 兼容 `Form`\n\n`Form`  组件里可以使用 **VantUI** 的 `Field`、`Checkbox`、`Radio`、`Stepper`、`Rate` 组件。\n\n也可以兼容原生的 `Switch` 和 `Slider` 组件，但是增加需要以下兼容代码：\n\n```jsx\n\u003ctemplate\u003e\n  \u003cvan-form @submit=\"onSubmit\"\u003e\n\n    \u003cvan-field name=\"switch\" :label=\"t('switch')\"\u003e\n      \u003ctemplate #input\u003e\n        \u003ccustom :value=\"switchChecked\"\u003e\n          \u003cswitch name=\"switch\" :checked=\"switchChecked\" @change=\"onSwitchChanged\" /\u003e\n        \u003c/custom\u003e\n      \u003c/template\u003e\n    \u003c/van-field\u003e\n\n    \u003cvan-field name=\"slider\" :label=\"t('slider')\"\u003e\n      \u003ctemplate #input\u003e\n        \u003ccustom :value=\"slider\"\u003e\n          \u003cslider class=\"my-slider\" :value=\"slider\" @change=\"onSliderChange\" /\u003e\n        \u003c/custom\u003e\n      \u003c/template\u003e\n    \u003c/van-field\u003e\n\n  \u003c/van-form\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\nimport { FieldMixin } from 'vant/es/mixins/field'\n\n// 开发者可以写一个类似的 Custom 组件去兼容 Switch 和 Slider 组件\n// 详情请看完整 Form Demo\nconst Custom = {\n  props: {\n    value: null\n  },\n  mixins: [FieldMixin],\n  render (h) {\n    return this.$slots.default\n  }\n}\n\u003c/script\u003e\n```\n\n## 组件支持列表\n\n### 基础组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| Button | ✓ | 不能使用 SVG ICON |\n| Cell | ✓ | |\n| Icon | ✓ | |\n| Image | ✓ | 1. 不能使用 `Lazyload`。2. 各种 `object-fit` 样式会失效。 |\n| Row | ✓ | |\n| Col | ✓ | |\n| Popup | ✓ | 必须设置 `duration` 属性 |\n| 内置样式 | ✓ | 动画的元素的 `style` 需要设置 `animationDuration` |\n| Toast | ✗ | 使用 `Taro.showToast` 代替 |\n\n### 表单组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| Calendar | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| Cascader | ✓ | `\u003cvan-tabs\u003e` 的样式需要魔改 |\n| Checkbox | ✓ | |\n| DatetimePicker | - | 使用小程序的 `\u003cPicker\u003e` 代替 |\n| Field | ✓ | 清除按钮失效（`\u003cText\u003e` 不会触发 `touchstart`）；不支持 `audosize` |\n| Form | ✓ | 某些表单组件不能使用；`\u003cSwitch\u003e` 和 `\u003cSlider\u003e` 需要额外兼容 |\n| NumberKeyboard | ✓ | 不能使用 SVG ICON；过渡动画失效 |\n| PasswordInput | ✓ | |\n| Picker | - | 使用小程序的 `\u003cPicker\u003e` 代替 |\n| Radio | ✓ | |\n| Rate | ✓ | 不支持手势滑动评分 |\n| Search | ✓ | |\n| Slider | - | 使用小程序的 `\u003cSlider\u003e` 代替 |\n| Stepper | ✓ | 注意 `\u003cinput\u003e`； `\u003cbutton\u003e` 需要 `display: inline-block` |\n| Switch | - | 使用小程序的 `\u003cSwitch\u003e` 代替 |\n| Uploader | ✗ | H5 与小程序上传文件的方式不同 |\n\n### 反馈组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| ActionSheet | ✓ | 必须设置 `duration` 属性；不能使用 SVG ICON |\n| Dialog | ✓ | 只能以组件形式调用；过渡效果部分丢失；不能使用 SVG ICON |\n| DropdownMenu | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| Loading | ✓ | 不能使用 SVG ICON |\n| Notify | ✗ | 不能在页面组件的 DOM 树之外插入元素 |\n| Overlay | ✓ | 必须设置 `duration` 属性 |\n| PullRefresh | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| ShareSheet | ✓ | 必须设置 `duration` 属性 |\n| SwipeCell | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n\n### 展示组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| Badge | ✓ |  |\n| Circle | ✗ | 小程序不支持 SVG |\n| Collapse | ✓ | 过渡动画效果缺失（不支持以浏览器的同步 API 获取 DOM 尺寸） |\n| CountDown | ✓ |  |\n| Divider | ✓ |  |\n| Empty | ✓ | 不能使用 SVG ICON |\n| ImagePreview | ✗ | 使用 `Taro.previewImage` 代替 |\n| Lazyload | ✗ |  |\n| List | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| NoticeBar | ✓ | 不支持滚动播放（不支持以浏览器的同步 API 获取 DOM 尺寸） |\n| Popover | ✗ | 不能在页面组件的 DOM 树之外插入元素 |\n| Progress | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| Skeleton | ✓ |  |\n| Steps | ✓ |  |\n| Sticky | ✗ | 使用小程序的 `IntersectionObserver` 代替 |\n| Swipe | ✗ | 使用小程序的 `Swiper` 代替 |\n| Tag | ✓ |  |\n\n### 导航组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| Grid  | ✓ | 徽标失效（`\u003ci\u003e` 里不能嵌套 `\u003cdiv\u003e`） |\n| IndexBar  | ✗ | 不支持以浏览器的同步 API 获取 DOM 尺寸 |\n| NavBar  | ✓ |  |\n| Pagination  | ✓ |  |\n| Sidebar  | ✓ |  |\n| Tab  | ✓ | `line` 风格需要对样式进行魔改 |\n| Tabbar  | ✓ |  |\n| TreeSelect  | ✓ |  |\n\n\n### 业务组件\n\n|  组件  | 是否支持 |  备注  |\n| :---- | :------ | :---- |\n| AddressEdit | ✗ |  |\n| AddressList | ✓ |  |\n| Area | - | 使用小程序的 `\u003cPicker\u003e` 代替 |\n| Card | ✓ |  |\n| ContactCard | ✓ |  |\n| ContactEdit | ✗ | 删除按钮失效（不能在页面组件的 DOM 树之外插入元素） |\n| ContactList | ✓ |  |\n| Coupon | ✓ | `\u003cvan-popup\u003e` 必须设置 `duration` 属性；`\u003cvan-tabs\u003e` 的样式需要魔改 |\n| GoodsAction | ✓ |  |\n| SubmitBar | ✓ |  |\n| Sku | ✗ | 按钮提示弹层不显示（不能在页面组件的 DOM 树之外插入元素）；留言区部分表单组件不支持 |\n\n## 共建\n\n**VantUI** 的组件非常丰富且实用，如 `Sku` 等组件目前未能兼容实在非常遗憾。\n\n但其实很多目前没能兼容的组件，只要针对小程序环境做一点兼容工作，是可以使用的。因此，我们十分期待各位同学参与共建～\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnervjs%2Ftaro-vant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnervjs%2Ftaro-vant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnervjs%2Ftaro-vant/lists"}