{"id":13692014,"url":"https://github.com/uni-helper/vite-plugin-uni-tailwind","last_synced_at":"2025-04-09T22:11:43.651Z","repository":{"id":63279628,"uuid":"566648152","full_name":"uni-helper/vite-plugin-uni-tailwind","owner":"uni-helper","description":"在 uni-app (vue3) 中使用 tailwindcss@3 原有语法开发小程序","archived":false,"fork":false,"pushed_at":"2024-11-07T06:44:18.000Z","size":994,"stargazers_count":45,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T22:11:37.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uni-helper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ModyQyW","KeJunMao","Neil Lee"],"custom":["https://afdian.net/a/kejun","https://github.com/ModyQyW/sponsors","https://afdian.net/a/zguolee"]}},"created_at":"2022-11-16T05:37:55.000Z","updated_at":"2025-03-13T07:24:41.000Z","dependencies_parsed_at":"2023-09-27T16:38:38.858Z","dependency_job_id":"ba3ce4c1-cacc-4e96-98e8-b287acd2ee3d","html_url":"https://github.com/uni-helper/vite-plugin-uni-tailwind","commit_stats":{"total_commits":44,"total_committers":1,"mean_commits":44.0,"dds":0.0,"last_synced_commit":"30af772ff882e480a2ee9c90903b366d95f3fdd0"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-helper%2Fvite-plugin-uni-tailwind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-helper%2Fvite-plugin-uni-tailwind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-helper%2Fvite-plugin-uni-tailwind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-helper%2Fvite-plugin-uni-tailwind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uni-helper","download_url":"https://codeload.github.com/uni-helper/vite-plugin-uni-tailwind/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119294,"owners_count":21050755,"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":"2024-08-02T17:00:52.570Z","updated_at":"2025-04-09T22:11:43.628Z","avatar_url":"https://github.com/uni-helper.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ModyQyW","https://github.com/sponsors/KeJunMao","https://github.com/sponsors/Neil Lee","https://afdian.net/a/kejun","https://github.com/ModyQyW/sponsors","https://afdian.net/a/zguolee"],"categories":["打包器插件"],"sub_categories":[],"readme":"# @uni-helper/vite-plugin-uni-tailwind\n\n\u003cdiv style=\"display: flex; justify-content: center; align-items: center; gap: 8px;\"\u003e\n  \u003ca href=\"https://github.com/uni-helper/vite-plugin-uni-tailwind/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/uni-helper/vite-plugin-uni-tailwind?style=for-the-badge\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@uni-helper/vite-plugin-uni-tailwind\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/%40uni-helper%2Fvite-plugin-uni-tailwind?style=for-the-badge\" alt=\"npm\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@uni-helper/vite-plugin-uni-tailwind\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/%40uni-helper%2Fvite-plugin-uni-tailwind?style=for-the-badge\" alt=\"npm downloads\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n支持在 uni-app 中使用 TailwindCSS v3 原有语法开发小程序。支持 Vite v2 ~ v5，要求 `node\u003e=14.18`。\n\n## 使用\n\n参考 [TailwindCSS 文档](https://tailwindcss.com/) 在 `uni-app` 项目中安装配置 `TailwindCSS`。你无需禁用 `preflight`，也无需调整原有语法（如 `.w-[200.5rpx]` 等），你只需要正常书写类名，该插件会替你处理剩下的事情。\n\n安装依赖。\n\n```shell\nnpm install @uni-helper/vite-plugin-uni-tailwind -D\n```\n\n配置 `vite.config.ts`。\n\n```typescript\nimport { defineConfig } from 'vite';\n// @ts-ignore\nimport nested from 'tailwindcss/nesting';\nimport tailwindcss from 'tailwindcss';\nimport tailwindcssConfig from './tailwind.config.ts'; // 注意匹配实际文件\nimport postcssPresetEnv from 'postcss-preset-env';\nimport uni from '@dcloudio/vite-plugin-uni';\nimport uniTailwind from '@uni-helper/vite-plugin-uni-tailwind';\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n  css: {\n    // 只能在 Vite 配置文件内处理 postcss 配置\n    // https://github.com/dcloudio/uni-app/issues/3367\n    postcss: {\n      plugins: [\n        nested(),\n        tailwindcss({\n          config: tailwindcssConfig,\n        }),\n        postcssPresetEnv({\n          stage: 3,\n          features: { 'nesting-rules': false },\n        }),\n      ],\n    },\n  },\n  plugins: [\n    uni(),\n    uniTailwind({\n      /* options */\n    }),\n  ],\n});\n```\n\n完整示例请查看 [playground](https://github.com/uni-helper/vite-plugin-uni-tailwind/tree/main/playground)。\n\n## 配置项 `Options`\n\n### `shouldApply`\n\n- 类型：`boolean | ((currentPlatform: string) =\u003e boolean)`\n- 默认值：`编译为小程序和快应用时应用`\n\n是否应用该插件。\n\n`APP` 使用 `WebView` 运行，`H5` 使用浏览器运行，基本都支持特殊字符，所以默认编译为小程序和快应用时应用该插件。\n\n### `shouldTransformAttribute`\n\n- 类型：`(attribute: string) =\u003e boolean`\n- 默认值：`转换以 class、Class、classname、className、ClassName、class-name 结尾的 attribute`\n\n是否转换某个 `attribute`。\n\n### `shouldTransformScript`\n\n- 类型：`(fileName: string) =\u003e boolean`\n- 默认值：`转换路径以 pages、components、layouts 开头的脚本文件`\n\n是否转换某个脚本文件。\n\n### `characterMap`\n\n- 类型：`[string, string][]`\n- 默认值如下\n\n```typescript\n[\n  ['[', '-'],\n  [']', '-'],\n  ['(', '-'],\n  [')', '-'],\n  ['$', '-v-'], // css variable\n  ['#', '-h-'], // hash\n  ['!', '-i-'], // important\n  ['/', '-s-'], // slash\n  ['.', '-d-'], // dot\n  [':', '_'], // colon\n  ['%', '-p-'], // percentage\n  [\"'\", '-q-'], // quote\n  ['+', '-a-'], // add\n  ['=', '-e-'], // equal\n  ['\u0026', '-n-'], // and\n  ['?', '-qm-'], // question mark\n  ['@', '-at-'], // at\n  ['*', '-w-'], // wildcard\n  [',\\\\s', '-c-'], // comma\n  [',', '-c-'], // comma\n  ['\\\\2c\\\\s', '-c-'], // comma\n  ['\\\\2c', '-c-'], // comma\n  ['\\\\\\\\2c\\\\s', '-c-'], // comma\n  ['\\\\\\\\2c', '-c-'], // comma\n];\n```\n\n所有生成样式中特殊字符需要替换成什么字符串。\n\n如果不替换，可能会导致无法正常运行。如果确认无需替换，请设置为空数组。\n\n替换顺序：`directChildrenElements` -\u003e `spaceBetweenElements` -\u003e `divideWidthElements` -\u003e `characterMap` -\u003e `elementMap`。\n\n### `spaceBetweenElements`\n\n- 类型：`string[]`\n- 默认值：`['view', 'button', 'text', 'image']`\n\n[Space Between](https://tailwindcss.com/docs/space) 生成样式中，`*` 需要替换成什么元素。\n\n如果不替换，可能会导致无法正常运行。如果确认无需替换，请设置为空数组。\n\n替换顺序：`directChildrenElements` -\u003e `spaceBetweenElements` -\u003e `divideWidthElements` -\u003e `characterMap` -\u003e `elementMap`。\n\n### `divideWidthElements`\n\n- 类型：`string[]`\n- 默认值：`['view', 'button', 'text', 'image']`\n\n[Divide Width](https://tailwindcss.com/docs/divide-width) 生成样式中，`*` 需要替换成什么元素。\n\n如果不替换，可能会导致无法正常运行。如果确认无需替换，请设置为空数组。\n\n替换顺序：`directChildrenElements` -\u003e `spaceBetweenElements` -\u003e `divideWidthElements` -\u003e `characterMap` -\u003e `elementMap`。\n\n### `directChildrenElements`\n\n- 类型：`string[]`\n- 默认值：`['view', 'button', 'text', 'image']`\n\n[Direct Children](https://tailwindcss.com/docs/hover-focus-and-other-states#styling-direct-children) 生成样式中，后一个 `*` 需要替换成什么元素。\n\n如果不替换，可能会导致无法正常运行。如果确认无需替换，请设置为空数组。\n\n替换顺序：`directChildrenElements` -\u003e `spaceBetweenElements` -\u003e `divideWidthElements` -\u003e `characterMap` -\u003e `elementMap`。\n\n### `elementMap`\n\n- 类型：`[string, string[]][]`\n- 默认值如下\n\n```typescript\n[\n  ['html', ['page']],\n  ['body', ['page']],\n  ['img', ['image']],\n  ['a', ['functional-page-navigator', 'navigator']],\n  [\n    '*',\n    [\n      'page',\n      'cover-image',\n      'cover-view',\n      'match-media',\n      'movable-area',\n      'movable-view',\n      'scroll-view',\n      'swiper',\n      'swiper-item',\n      'view',\n      'icon',\n      'progress',\n      'rich-text',\n      'text',\n      'button',\n      'checkbox',\n      'checkbox-group',\n      'editor',\n      'form',\n      'input',\n      'label',\n      'picker',\n      'picker-view',\n      'picker-view-column',\n      'radio',\n      'radio-group',\n      'slider',\n      'switch',\n      'textarea',\n      'functional-page-navigator',\n      'navigator',\n      'audio',\n      'camera',\n      'image',\n      'live-player',\n      'live-pusher',\n      'video',\n      'voip-room',\n      'map',\n      'canvas',\n      'ad',\n      'ad-custom',\n      'official-account',\n      'open-data',\n      'web-view',\n      'navigation-bar',\n      'page-meta',\n    ],\n  ],\n];\n```\n\n所有生成样式中特定元素需要替换成什么元素。\n\n如果不替换，可能会导致无法正常运行。如果确认无需替换，请设置为空数组。\n\n替换顺序：`directChildrenElements` -\u003e `spaceBetweenElements` -\u003e `divideWidthElements` -\u003e `characterMap` -\u003e `elementMap`。\n\n## FAQ\n\n### 可以支持 WindiCSS 吗？\n\n**请注意：请不要在新项目中使用 WindiCSS！详见 [Windi CSS is Sunsetting](https://windicss.org/posts/sunsetting.html)。**\n\n如果你没有使用 WindiCSS 内的高级功能（如 [Attributify Mode](https://windicss.org/features/attributify.html)），这个库可以正常工作。\n\n### 可以支持 UnoCSS 吗？\n\n**建议使用 [unocss-applet](https://github.com/unocss-applet/unocss-applet) 或 [unocss-preset-weapp](https://github.com/MellowCo/unocss-preset-weapp) 以获取更好的支持。**\n\n如果你没有使用 UnoCSS 内的高级功能（如 [Attributify Mode](https://unocss.dev/presets/attributify)、[Tagify Mode](https://unocss.dev/presets/tagify)），这个库可以正常工作。\n\n### 可以支持 rpx 转换吗？\n\n引自 [微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html#%E5%B0%BA%E5%AF%B8%E5%8D%95%E4%BD%8D)：\n\n\u003e rpx（responsive pixel）: 可以根据屏幕宽度进行自适应。规定屏幕宽为750rpx。如在 iPhone6 上，屏幕宽度为375px，共有750个物理像素，则750rpx = 375px = 750物理像素，1rpx = 0.5px = 1物理像素。\n\n简而言之，rpx 是一个跟屏幕宽度挂钩的响应式单位，不应该也不需要把所有用到 px 或者 rem 的地方换成 rpx。\n\n什么时候必须要用 rpx？我个人的经验是侧边栏的宽度需要随屏幕宽度变化、页面主体根据侧边栏宽度变化时，才必须用到 rpx + flexbox 的组合，否则用 flexbox 就已经足够了。\n\n所以，这个插件不支持 rpx 转换。你可以直接 [使用任意值](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values)，如 `.w-[750rpx]`、`.w-[200rpx]`，我相信可以满足绝大部分的需求。\n\n如果你悲伤地发现这没法满足你的需求，可能这个插件不适合你，请看看以下几个项目是否满足你的需求。\n\n- [tailwind-extensions](https://www.npmjs.com/package/tailwind-extensions)\n- [mini-program-tailwind](https://github.com/dcasia/mini-program-tailwind)\n- [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss)\n- [unocss](https://unocss.dev)\n- [unocss-applet](https://github.com/unocss-applet/unocss-applet)\n- [unocss-preset-weapp](https://github.com/MellowCo/unocss-preset-weapp)\n\n### 这个插件的原理是什么？\n\nuni-app + TailwindCSS 不能编译出小程序能正常运行的代码的错误原因有以下几种：\n\n- 样式文件中含有不支持的字符，如 `()[]$#!/.:,%'` 等；\n- 样式文件中含有不支持的元素，如 `html`, `body`、`img`、`a`、`*` 等；\n- 自带组件传参，模板文件中含有不支持的字符，如 `()[]$#!/.:,%'` 等；\n- 自定义组件传参，脚本文件中含有不支持的字符，如 `()[]$#!/.:,%'` 等，导致参数渲染不正常。\n\n那么，我们只需要做到以下几点就可以让 TailwindCSS 跑在小程序中，而不需要调整 TailwindCSS 的语法来增加开发时的心智负担：\n\n- 使用 PostCSS 改写样式文件里面的 `selector`，包括字符和元素；\n- 使用 Babel 改写模板文件里面的 `class`，只包括字符，这是为了和样式文件里面的 `selector` 相匹配；\n- 使用 Babel 改写脚本文件里面的 `class`，这也是为了和样式文件里面的 `selector` 相匹配。\n\n但请注意，这个插件不是万能的。\n\n- 插件无法突破小程序的限制，比如 `bg-[url(xxxx)]` 经过插件处理后可以正常使用，但是小程序平台不支持使用 `background-image`，此时仍然无法正常渲染出图片。\n- 插件不支持特别复杂的情况，如果自定义组件传参过于复杂，仍然可能绕过插件处理。如果你发现这种情况，欢迎提交 Issue 或 PR 协助改进该插件，非常感谢！🙏\n\n## 资源\n\n- [改动日志](https://github.com/uni-helper/vite-plugin-uni-tailwind/tree/main/CHANGELOG.md)\n\n## 致谢\n\n该项目从以下项目汲取了灵感并参考了代码。在此对它们的开发者表示由衷的感谢。\n\n- [mini-program-tailwind](https://github.com/dcasia/mini-program-tailwind)\n- [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss)\n- [unocss-applet](https://github.com/unocss-applet/unocss-applet)\n- [unocss-preset-weapp](https://github.com/MellowCo/unocss-preset-weapp)\n\n也感谢以下项目的开发者，如果没有他们，前端开发比现在更加困难。\n\n- [TailwindCSS](https://tailwindcss.com/)\n- [WindiCSS](https://windicss.org/)\n- [UnoCSS](https://github.com/unocss/unocss)\n\n## 贡献者们\n\n该项目由 [ModyQyW](https://github.com/ModyQyW) 创建。\n\n感谢 [所有贡献者](https://github.com/uni-helper/vite-plugin-uni-tailwind/graphs/contributors) 的付出！\n\n## 赞助\n\n如果这个包对你有所帮助，请考虑 [赞助](https://github.com/ModyQyW/sponsors) 支持，这将有利于项目持续开发和维护。\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://cdn.jsdelivr.net/gh/ModyQyW/sponsors/sponsorkit/sponsors.svg\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/gh/ModyQyW/sponsors/sponsorkit/sponsors.svg\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-helper%2Fvite-plugin-uni-tailwind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funi-helper%2Fvite-plugin-uni-tailwind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-helper%2Fvite-plugin-uni-tailwind/lists"}