{"_id":"@buletu/screen-fit","name":"@buletu/screen-fit","dist-tags":{"latest":"1.2.0"},"versions":{"1.2.0":{"name":"@buletu/screen-fit","version":"1.2.0","description":"轻量级前端屏幕适配库，支持 rem/vw/scale 三种模式，集成 PostCSS/Vite/Webpack/TailwindCSS 插件及开发调试工具","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","repository":{"type":"git","url":"git+ssh://git@github.com/bluetunice/screen-fit.git"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./postcss-plugin":{"types":"./dist/postcss-plugin.d.ts","import":"./dist/postcss-plugin.mjs","require":"./dist/postcss-plugin.js"},"./vite-plugin":{"types":"./dist/vite-plugin.d.ts","import":"./dist/vite-plugin.mjs","require":"./dist/vite-plugin.js"},"./webpack-loader":{"types":"./dist/webpack-loader.d.ts","import":"./dist/webpack-loader.mjs","require":"./dist/webpack-loader.js"},"./tailwind-plugin":{"types":"./dist/tailwind-plugin.d.ts","import":"./dist/tailwind-plugin.mjs","require":"./dist/tailwind-plugin.js"},"./devtools":{"types":"./dist/devtools.d.ts","import":"./dist/devtools.mjs","require":"./dist/devtools.js"},"./runtime":{"types":"./dist/runtime.d.ts","import":"./dist/runtime.mjs","require":"./dist/runtime.js"}},"scripts":{"build":"tsup index.ts postcss-plugin.ts postcss-plugin-v2.ts vite-plugin.ts webpack-loader.ts tailwind-plugin.ts devtools.ts runtime.ts --format cjs,esm --dts --clean","dev":"tsup index.ts --watch","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["responsive","screen-fit","rem","vw","scale","postcss","vite","webpack","tailwindcss","适配","响应式"],"author":{"name":"buletu"},"license":"MIT","peerDependencies":{"postcss":">=8.0.0","tailwindcss":">=3.0.0","vite":">=4.0.0","webpack":">=4.0.0"},"peerDependenciesMeta":{"postcss":{"optional":true},"tailwindcss":{"optional":true},"vite":{"optional":true},"webpack":{"optional":true}},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","vite":"^5.0.0","webpack":"^5.0.0","@types/webpack":"^5.0.0"},"tsup":{"entry":["index.ts","postcss-plugin.ts","postcss-plugin-v2.ts","vite-plugin.ts","webpack-loader.ts","tailwind-plugin.ts","devtools.ts","runtime.ts"],"format":["cjs","esm"],"dts":true,"clean":true,"treeshake":true,"platform":"node"},"publishConfig":{"access":"public"},"gitHead":"a5ea00588d8dd7714e0f496164b3f7c1b4231a4c","_id":"@buletu/screen-fit@1.2.0","bugs":{"url":"https://github.com/bluetunice/screen-fit/issues"},"homepage":"https://github.com/bluetunice/screen-fit#readme","_nodeVersion":"22.18.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-wEc5TYSIUaSbnvsgWMCCaaSLGSLHKKikZMDHVyBA5PuMVkXz5xLDdrE+KRC8J4d3nlhXnhT3cEMTh5NBB8ua8Q==","shasum":"2615e7e290489cda978b6a972266325c1d0533a0","tarball":"https://registry.npmjs.org/@buletu/screen-fit/-/screen-fit-1.2.0.tgz","fileCount":43,"unpackedSize":164641,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAZR+fh3J5+CFDIUeaUwQVDIaPjZktIxb6aOrM3QVjSDAiAFqvDu4+2H3USzrrG1f7q2DMATicKBeByJWANQxsF/zQ=="}]},"_npmUser":{"name":"buletu","email":"949362805@qq.com"},"directories":{},"maintainers":[{"name":"buletu","email":"949362805@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/screen-fit_1.2.0_1775873251268_0.6220038222904547"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T02:07:31.164Z","1.2.0":"2026-04-11T02:07:31.409Z","modified":"2026-04-11T02:07:31.629Z"},"maintainers":[{"name":"buletu","email":"949362805@qq.com"}],"description":"轻量级前端屏幕适配库，支持 rem/vw/scale 三种模式，集成 PostCSS/Vite/Webpack/TailwindCSS 插件及开发调试工具","homepage":"https://github.com/bluetunice/screen-fit#readme","keywords":["responsive","screen-fit","rem","vw","scale","postcss","vite","webpack","tailwindcss","适配","响应式"],"repository":{"type":"git","url":"git+ssh://git@github.com/bluetunice/screen-fit.git"},"author":{"name":"buletu"},"bugs":{"url":"https://github.com/bluetunice/screen-fit/issues"},"license":"MIT","readme":"# @buletu/screen-fit — 前端多屏适配方案\n\n[![version](https://img.shields.io/badge/version-1.2.0-blue)](./package.json)\n[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)\n\n一个轻量级的前端屏幕适配库，核心思路：**CSS 保持设计稿 px 书写，构建时自动转换为 rem/vw，运行时动态调整根字体实现等比缩放**。\n\n## 特性\n\n| | |\n|---|---|\n| 零侵入 | 不改变现有代码结构，保留 px 书写习惯 |\n| 多构建工具 | Vite / Webpack4 / Webpack5 / PostCSS 全支持 |\n| 三种模式 | rem（推荐）/ vw / scale 按需选择 |\n| 开发调试 | 设计稿切换器 + 元素尺寸检测器 |\n| TypeScript | 完整类型定义 |\n\n---\n\n## 安装\n\n```bash\nnpm install @buletu/screen-fit\n# yarn add @buletu/screen-fit\n# pnpm add @buletu/screen-fit\n```\n\n---\n\n## 快速上手\n\n### 第一步：运行时初始化（必须）\n\n在应用入口文件中加入，负责监听窗口尺寸变化并动态调整根字体：\n\n```typescript\n// main.ts / main.tsx / index.js\nimport { screenFit } from '@buletu/screen-fit';\n\nscreenFit({\n designWidth: 1920, // 设计稿宽度\n designHeight: 1080,\n mode: 'rem', // 推荐\n});\n```\n\n### 第二步：选择构建工具插件（二选一即可）\n\n---\n\n## 构建工具集成\n\n### Vite（推荐）\n\n```typescript\n// vite.config.ts\nimport { defineConfig } from 'vite';\nimport screenFit from '@buletu/screen-fit/vite-plugin';\n\nexport default defineConfig({\n plugins: [\n screenFit({\n mode: 'rem',\n designWidth: 1920,\n // precision: 5, // 小数精度，默认 6\n // minValue: 1, // 小于 1px 的值不转换（保留 1px 细线）\n // excludeProperties: ['font-size', 'border'],\n }),\n ],\n});\n```\n\n---\n\n### Webpack 5\n\n**方式 A：使用专属 Loader（推荐，无需 PostCSS）**\n\n```javascript\n// webpack.config.js\nconst {\n screenFitLoader,\n screenFitLoaderOptions,\n} = require('@buletu/screen-fit/webpack-loader');\n\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.(css|less|scss|sass)$/,\n use: [\n 'style-loader',\n 'css-loader',\n {\n loader: screenFitLoader, // loader 文件路径\n options: screenFitLoaderOptions({ // 类型安全的 options 包装\n mode: 'rem',\n designWidth: 1920,\n }),\n },\n // less-loader / sass-loader 放这里（预处理器先跑）\n ],\n },\n ],\n },\n};\n```\n\n或者用 `createWebpackRule` 一键生成规则：\n\n```javascript\nconst { createWebpackRule } = require('@buletu/screen-fit/webpack-loader');\n\nmodule.exports = {\n module: {\n rules: [\n ...createWebpackRule({ mode: 'rem', designWidth: 1920 }),\n // 再追加 style-loader / css-loader 规则\n ],\n },\n};\n```\n\n**方式 B：通过 PostCSS Loader（已有 postcss-loader 的项目）**\n\n```javascript\n// webpack.config.js\n{\n test: /\\.(css|less|scss)$/,\n use: ['style-loader', 'css-loader', 'postcss-loader'],\n}\n\n// postcss.config.js\nconst { pxToUnitPlugin } = require('@buletu/screen-fit/postcss-plugin');\nmodule.exports = {\n plugins: [pxToUnitPlugin({ mode: 'rem', designWidth: 1920 })],\n};\n```\n\n> ⚠️ 两种方式二选一，不要同时使用。\n\n---\n\n### Webpack 4\n\nWebpack 4 配置与 Webpack 5 完全相同，loader 内部已兼容 `this.query`（webpack4）和 `this.getOptions`（webpack5）两种取参方式。\n\n---\n\n### PostCSS（通用）\n\n适用于任何使用 PostCSS 的项目（CRA、Next.js、Nuxt 等）：\n\n```javascript\n// postcss.config.js\nconst { pxToUnitPlugin } = require('@buletu/screen-fit/postcss-plugin');\n\nmodule.exports = {\n plugins: [\n pxToUnitPlugin({\n mode: 'rem',\n designWidth: 1920,\n excludeProperties: ['font-size', 'border'],\n }),\n ],\n};\n```\n\n---\n\n## 三种适配模式\n\n### REM 模式（推荐）\n\n```\n根字体 = 屏幕宽度 / 设计稿宽度 × 100\n1920px 设计稿中 100px → 100 / 1920 * 100 = 5.2083rem\n屏幕缩小到 1440px 时，根字体自动缩小，rem 值不变，视觉尺寸自动缩放\n```\n\n```typescript\nscreenFit({ mode: 'rem', designWidth: 1920 });\n```\n\n### VW 模式\n\n纯 CSS 方案，无需 JS 计算根字体：\n\n```typescript\nscreenFit({ mode: 'vw', designWidth: 1920 });\n// 1920px → 100vw，100px → 5.2083vw\n```\n\n### Scale 模式\n\n整体页面 transform 缩放，适合后台大屏看板：\n\n```typescript\nscreenFit({\n mode: 'scale',\n designWidth: 1920,\n designHeight: 1080,\n adaptiveHeight: true, // 同时适配高度\n});\n```\n\n---\n\n## CSS 书写示例\n\n无论用哪种构建工具插件，CSS 都保持原始 px 写法：\n\n```css\n/* 原始 CSS（设计稿尺寸）*/\n.header {\n width: 1920px;\n height: 80px;\n padding: 0 40px;\n font-size: 16px; /* font-size 默认不转换 */\n border: 1px solid #eee; /* border 默认不转换 */\n}\n\n.card {\n width: 400px;\n height: 300px;\n border-radius: 8px;\n margin: 20px;\n}\n```\n\n构建后输出（rem 模式，designWidth=1920）：\n\n```css\n.header {\n width: 100rem;\n height: 4.16667rem;\n padding: 0 2.08333rem;\n font-size: 16px; /* 保留原值 */\n border: 1px solid #eee; /* 保留原值 */\n}\n\n.card {\n width: 20.8333rem;\n height: 15.625rem;\n border-radius: 0.41667rem;\n margin: 1.04167rem;\n}\n```\n\n---\n\n## TailwindCSS 支持\n\n```javascript\n// tailwind.config.js\nconst { tailwindScreenFit } = require('@buletu/screen-fit/tailwind-plugin');\n\nmodule.exports = {\n plugins: [tailwindScreenFit({ mode: 'rem', designWidth: 1920 })],\n};\n```\n\n在模板中直接使用设计稿尺寸：\n\n```html\n
\n \n
\n```\n\n---\n\n## React 集成\n\n```typescript\n// App.tsx\nimport { useEffect } from 'react';\nimport { screenFit } from '@buletu/screen-fit';\n\nfunction useScreenFit() {\n useEffect(() => {\n const fit = screenFit({ designWidth: 1920 });\n return () => fit.destroy();\n }, []);\n}\n\nexport default function App() {\n useScreenFit();\n return ;\n}\n```\n\n---\n\n## 开发调试工具\n\n```typescript\nimport { DesignSwitcher, SizeInspector } from '@buletu/screen-fit';\n\n// 只在开发环境启用\nif (process.env.NODE_ENV === 'development') {\n // 设计稿快速切换面板\n const switcher = new DesignSwitcher({\n presets: [\n { name: '1920×1080', width: 1920, height: 1080 },\n { name: '1440×900', width: 1440, height: 900 },\n { name: '1366×768', width: 1366, height: 768 },\n { name: '1280×720', width: 1280, height: 720 },\n ],\n });\n switcher.init();\n\n // 元素尺寸检测器\n const inspector = new SizeInspector();\n inspector.init();\n}\n```\n\n快捷键：\n\n- `Ctrl+Shift+1~4` — 切换预设设计稿\n- `Shift+Alt+I` — 开/关元素尺寸检测器\n\n---\n\n## API\n\n### `screenFit(options)`\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| designWidth | number | 1920 | 设计稿宽度 |\n| designHeight | number | 1080 | 设计稿高度 |\n| mode | `'rem' \\| 'vw' \\| 'scale'` | `'rem'` | 适配模式 |\n| minWidth | number | 1024 | 最小宽度（防止过小屏幕字体异常） |\n| maxWidth | number | 2560 | 最大宽度（防止超宽屏字体过大） |\n| adaptiveHeight | boolean | false | scale 模式是否同时适配高度 |\n\n### 构建插件公共选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| mode | `'rem' \\| 'vw'` | `'rem'` | 转换目标单位 |\n| designWidth | number | 1920 | 设计稿宽度 |\n| precision | number | 6 | 输出小数位数 |\n| minValue | number | 1 | 小于此 px 值不转换 |\n| zeroAsUnitless | boolean | true | `0px` 转为 `0` |\n| excludeProperties | string[] | 见下 | 不转换的属性 |\n| includeProperties | string[] | — | 只转换这些属性（白名单） |\n\n**默认不转换的属性**：`font-size`、`border`、`border-*-width`、`outline-width`、`box-shadow`、`text-shadow`\n\n---\n\n## 文件结构\n\n```\n@buletu/screen-fit/\n├── index.ts # 运行时核心库\n├── vite-plugin.ts # Vite 插件（已修复）\n├── webpack-loader.ts # Webpack Loader ⭐ v1.2 新增\n├── postcss-plugin.ts # PostCSS 插件\n├── postcss-plugin-v2.ts # PostCSS 增强版（支持 calc/CSS变量）\n├── tailwind-plugin.ts # TailwindCSS 插件\n├── devtools.ts # 开发调试工具\n├── runtime.ts # 运行时转换器（CDN 场景）\n└── README.md\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-45d06dfeb46c7210bfc5ef11bdf466bf"}