k-soup

一个集"组件 + 工程配置 + 工具函数"于一体的内聚型前端开发套件，专为提升多项目开发效率而设计。

📖 目录

• ✨ 特性
• 🛠 技术栈
• 📦 安装
• 🚀 快速开始
• 📋 组件清单
• 🔧 工具函数
• 🪝 Hooks
• 🛣️ 路由工具
• 🎨 主题定制
• ⚙️ 工程配置
• 📝 CLI 工具
• 💡 按需加载与优化
• 🧰 常见问题排查
• 🤝 参与贡献

✨ 特性

• 🚀 开箱即用 - 提供完整的 React 组件库和工程配置
• 📦 按需加载 - 支持 ES Module + Tree Shaking，完美的摇树优化
• 🎨 主题定制 - 基于 CSS Variables，支持暗黑模式
• ⚡️ TypeScript - 完整的 TypeScript 支持，提供优秀的开发体验
• 🔧 工程化 - 集成 ESLint、Prettier、Tailwind CSS 等开发工具
• 📚 文档完善 - 基于 dumi 构建，提供完整的组件文档和示例
• 🎯 子路径导入 - 支持精细化导入，减少打包体积

🛠 技术栈

• 框架: React 18
• 构建工具: Vite + tsup
• 样式方案: Tailwind CSS + CSS Variables
• 组件库: Ant Design (可选依赖)
• 文档生成: dumi
• 开发语言: TypeScript

📦 安装

npm install k-soup
# 或
pnpm add k-soup
# 或
yarn add k-soup

依赖说明

k-soup 采用 peerDependencies 模式，不会强制安装所有依赖，可以根据实际使用的功能按需安装：

必需依赖（使用任何组件时都需要）：

pnpm add react react-dom vite @vitejs/plugin-react

可选依赖（仅在使用对应组件时需要）：

• 使用 A 系列组件（如 ATable、AForm、AModal 等）：pnpm add antd @ant-design/icons
• 使用 KEcharts 图表组件：pnpm add echarts
• 使用路由相关功能：pnpm add react-router-dom

快速安装所有依赖

推荐使用 k-install-deps 工具一键补齐/校验（默认只预览，不会修改宿主依赖）：

# 1) 预览/校验（默认 dry-run，不会执行安装）
pnpm exec k-install-deps

# 2) 实际执行安装（只补缺失，不覆盖已有版本）
pnpm exec k-install-deps --apply

# 3) 同时补齐可选依赖（antd、echarts 等）
pnpm exec k-install-deps --apply --include-optional

# 查看帮助信息
pnpm exec k-install-deps --help

🚀 快速开始

前置条件

• Node.js >= 16
• React >= 18
• Vite >= 5
• 包管理器：pnpm（推荐）/ npm / yarn

1. 安装依赖

# 安装 k-soup
pnpm add k-soup

# 一键补齐/校验 peer 依赖（推荐）
pnpm exec k-install-deps --apply --include-optional

2. 样式配置

1.1 引入样式（推荐顺序）

在您的项目入口文件（如 src/main.tsx 或 src/index.tsx）中引入样式。 引入组件库 CSS 与宿主样式（Tailwind 输出）。如果你希望宿主能够覆盖库中的默认样式，请将宿主样式放在后面：

// 1) 先引入组件库 CSS（包含：库内基础增强样式 + 少量组件静态 CSS）
import 'k-soup/dist/index.css';

// 2) 再引入宿主 Tailwind 输出（utilities 由宿主生成；也方便宿主覆盖库默认样式）
import './index.css';

1.2 配置 Tailwind（宿主必需）

所有宿主项目都必须接入 Tailwind CSS，并确保 Tailwind 的 content 能够扫描到 k-soup 的构建产物（因为组件内部直接使用 Tailwind className）：

// tailwind.config.cjs
const base = require('k-soup/config/tailwind');

module.exports = base({
  // ✅ 推荐：用 helper 合并宿主扫描路径 + k-soup 扫描路径
  content: base.withKSoupContent([
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}',
  ]),
  
  // ⚠️ 手动配置方式（不推荐，容易遗漏）
  // content: [
  //   './index.html',
  //   './src/**/*.{js,jsx,ts,tsx}',
  //   './node_modules/k-soup/dist/**/*.{js,mjs}',
  // ],
});

你的入口 CSS（如 src/index.css）需要包含 Tailwind 指令：

@tailwind base;
@tailwind components;
@tailwind utilities;

1.3 最小接入模板（可直接复制）

入口文件（推荐引入顺序）

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';

// ✅ 先组件库 CSS（不包含 Tailwind utilities）
import 'k-soup/dist/index.css';

// ✅ 再宿主 Tailwind 输出（也方便宿主覆盖库默认样式）
import './index.css';

import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

入口 CSS（必须）

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

2. 基础使用

import React from 'react';
import { APageLayout, ANavMenu, ATable } from 'k-soup';

const App = () => {
  const navItems = [
    { key: 'dashboard', label: '仪表板', path: '/' },
    { key: 'users', label: '用户管理', path: '/users' }
  ];

  return (
    <APageLayout
      showHeader
      logoText="我的应用"
      navigation={<ANavMenu items={navItems} mode="horizontal" />}
    >
      <div className="p-6">
        <h1>欢迎使用 k-soup</h1>
      </div>
    </APageLayout>
  );
};
export default App;

🧰 常见问题排查

1) 组件里的 Tailwind 类名不生效 / 样式缺失

最高频原因：宿主 Tailwind 没有扫描到 k-soup 的构建产物，导致对应 utilities 根本没生成。

建议直接复制下面这份配置（已用 helper 合并宿主 + k-soup 扫描路径，减少复制出错）：

// tailwind.config.cjs
const base = require('k-soup/config/tailwind');

module.exports = base({
  content: base.withKSoupContent([
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}',
  ]),
});

同时确认宿主入口 CSS 包含 Tailwind 指令：

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

2) 样式优先级不稳定 / 组件样式被覆盖

优先检查入口样式引入顺序是否为（推荐，可复制）：

// src/main.tsx (或入口文件)
// 先组件库 CSS，再宿主样式（便于宿主覆盖库默认样式）
import 'k-soup/dist/index.css';
import './index.css';

📋 组件清单

布局组件

| 组件 | 描述 | 导入方式 | |------|------|----------| | APageLayout | 页面布局容器，支持顶部导航和侧边栏 | import { APageLayout } from 'k-soup' | | APageHeader | 页面头部组件，支持面包屑和操作区域 | import { APageHeader } from 'k-soup' |

导航组件

| 组件 | 描述 | 导入方式 | |------|------|----------| | ANavMenu | 导航菜单，支持水平和垂直模式 | import { ANavMenu } from 'k-soup' |

表单组件

| 组件 | 描述 | 导入方式 | |------|------|----------| | AForm | 表单组件，支持动态表单项依赖 | import { AForm } from 'k-soup' | | AFormPage | 表单页面容器 | import { AFormPage } from 'k-soup' | | ASearch | 搜索组件 | import { ASearch } from 'k-soup' |

数据展示

| 组件 | 描述 | 导入方式 | |------|------|----------| | ATable | 数据表格，基于 Ant Design Table 增强 | import { ATable } from 'k-soup' | | KEcharts | 图表组件，基于 ECharts | import { KEcharts } from 'k-soup' |

反馈组件

| 组件 | 描述 | 导入方式 | |------|------|----------| | AModal | 模态框，支持 Promise 调用 | import { AModal } from 'k-soup' | | ADrawer | 抽屉组件 | import { ADrawer } from 'k-soup' | | AQuestionTooltip | 问号提示组件 | import { AQuestionTooltip } from 'k-soup' |

其他组件

| 组件 | 描述 | 导入方式 | |------|------|----------| | ACopyText | 可复制文本组件 | import { ACopyText } from 'k-soup' | | ATextBtns | 文本按钮组 | import { ATextBtns } from 'k-soup' |

🔧 工具函数

k-soup 提供了一系列开箱即用的工具函数，支持子路径导入以减少打包体积。

存储工具（Storage）

提供类型安全的 localStorage 和 sessionStorage 封装：

import { local, session } from 'k-soup/utils/store';

// ✅ 设置存储（支持任意可序列化类型）
local.set('token', 'abc123');
local.set('user', { id: 1, name: 'Alice' });
session.set('tempData', { count: 42 });

// ✅ 获取存储（支持类型推断）
const token = local.get<string>('token');           // string | null
const user = local.get<{ id: number; name: string }>('user');

// ✅ 删除存储
local.remove('token');
session.remove('tempData');

// ✅ 批量清理（配合 storeMap）
const storeMap = {
  TOKEN: { name: 'TOKEN_MY_APP', clear: true },
  USERINFO: { name: 'USERINFO_MY_APP', clear: true }
};
local.clear(storeMap);  // 清理所有标记为 clear: true 的项

高精度计算（Calc）

基于 mathjs 的高精度数值计算，解决 JavaScript 浮点数精度问题：

import { calc } from 'k-soup/utils/calc';

// ✅ 加法（避免 0.1 + 0.2 = 0.30000000000000004）
const sum = calc('add', '0.1', '0.2');        // '0.3'

// ✅ 减法
const diff = calc('subtract', '1', '0.9');    // '0.1'

// ✅ 乘法
const product = calc('multiply', '0.1', '3'); // '0.3'

// ✅ 除法（保留完整精度）
const quotient = calc('divide', '1', '3');    // '0.333...'

// ✅ 支持多个操作数
const result = calc('add', '0.1', '0.2', '0.3'); // '0.6'

日期处理（Dayjs）

提供两种 dayjs 导出方式，按需选择：

// 方式 1: 基础版本（无副作用，体积最小）
import { dayJs } from 'k-soup/utils/dayjs';

console.log(dayJs().format('YYYY-MM-DD'));
console.log(dayJs('2024-01-01').add(1, 'day').format('YYYY-MM-DD'));

// 方式 2: 中文版本（包含中文 locale 和常用插件）
import dayJsZh from 'k-soup/utils/dayjs-zh';

console.log(dayJsZh().format('YYYY年MM月DD日'));          // 2024年01月25日
console.log(dayJsZh().format('dddd'));                    // 星期四
console.log(dayJsZh().fromNow());                         // 几秒前
console.log(dayJsZh('2024-01-01').isBetween('2023-12-01', '2024-02-01')); // true

中文版本已预装插件：

• relativeTime：相对时间（如 "3 天前"）
• isBetween：判断日期是否在区间内
• customParseFormat：自定义解析格式
• weekday：周几计算
• isSameOrBefore/isSameOrAfter：日期比较

事件总线（Event）

轻量级事件发布/订阅系统：

import { events, EventEmitter } from 'k-soup/utils/event';

// ✅ 使用全局事件总线
events.on('user:login', (data) => console.log('用户登录', data));
events.emit('user:login', { userId: 123 });
events.off('user:login');

// ✅ 创建独立的事件实例
const bus = new EventEmitter();
bus.on('custom:event', (data) => console.log(data));
bus.emit('custom:event', { message: 'Hello' });

🪝 Hooks

DOM 操作 Hooks

import {
  useContainerHeight,
  useElementSize,
  useScrollLock,
  useClickOutside,
  getTableScroll,
} from 'k-soup';

// ✅ 容器高度计算（常用于表格/列表自适应）
const App = () => {
  const { containerRef, tableHeight } = useContainerHeight({
    offset: 200, // 预留空间
    minHeight: 300,
  });
  
  return (
    <div ref={containerRef}>
      <Table scroll={{ y: tableHeight }} />
    </div>
  );
};

// ✅ 元素尺寸监听
const { ref, width, height } = useElementSize<HTMLDivElement>();

// ✅ 滚动锁定（弹窗时禁止背景滚动）
const { lock, unlock } = useScrollLock();

// ✅ 点击外部区域检测
const ref = useClickOutside<HTMLDivElement>(() => {
  console.log('点击了外部区域');
});

// ✅ 表格滚动配置（Ant Design Table）
const scroll = getTableScroll({ offset: 200, minHeight: 300 });

路由 Hooks

import { useRouter } from 'k-soup';

const MyComponent = () => {
  const { query, setQuery, navigate } = useRouter();
  
  // ✅ 获取 URL 查询参数
  console.log(query.id); // ?id=123 => '123'
  
  // ✅ 更新查询参数（保留其他参数）
  setQuery({ page: '2' }); // ?id=123&page=2
  
  // ✅ 编程式导航
  navigate('/users', { state: { from: 'home' } });
  navigate(-1); // 返回上一页
};

🛣️ 路由工具

提供路由配置生成工具，简化路由表定义：

import { createRoutes } from 'k-soup/router';
import { lazy } from 'react';

// ✅ 定义路由配置
const routes = createRoutes([
  {
    path: '/',
    element: <Layout />,
    children: [
      {
        index: true,
        component: lazy(() => import('./pages/Home')),
      },
      {
        path: 'users',
        component: lazy(() => import('./pages/Users')),
      },
    ],
  },
]);

// ✅ 在 React Router 中使用
import { useRoutes } from 'react-router-dom';

function App() {
  const element = useRoutes(routes);
  return element;
}

浏览器路由辅助工具：

import { BrowserRouter } from 'k-soup/router/browser';

// ✅ 简化路由初始化
const App = () => (
  <BrowserRouter routes={routes} basename="/app" />
);

🎨 主题定制

k-soup 基于 CSS Variables 提供主题定制能力：

// 方式 1: 从主题模块导入
import { defaultTheme, darkTheme } from 'k-soup/theme';

// ✅ 应用主题
document.documentElement.dataset.theme = 'dark';

// 方式 2: 自定义 CSS Variables
```css
:root {
  /* 主色调 */
  --k-primary-color: #1890ff;
  --k-success-color: #52c41a;
  --k-warning-color: #faad14;
  --k-error-color: #ff4d4f;
  
  /* 布局 */
  --k-border-radius: 6px;
  --k-box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
  
  /* 字体 */
  --k-font-size-base: 14px;
  --k-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

/* 暗黑模式 */
[data-theme='dark'] {
  --k-primary-color: #177ddc;
  --k-bg-color: #141414;
  --k-text-color: rgba(255, 255, 255, 0.85);
}

⚙️ 工程配置

本库不仅提供组件，还导出多项目可复用的工程配置，帮助快速搭建标准化的前端项目。

配置清单

| 配置类型 | 导入路径 | 用途说明 | |----------|----------|----------| | ESLint 基础 | k-soup/config/eslint | TypeScript + 通用规则 | | ESLint React | k-soup/config/eslint-react | React 项目（包含 hooks + a11y 规则） | | TypeScript 基础 | k-soup/config/tsconfig/base | 基础 TypeScript 编译配置 | | TypeScript React | k-soup/config/tsconfig/react | React 项目 TS 配置（包含 JSX） | | Tailwind CSS | k-soup/config/tailwind | Tailwind 预设配置 + helper 函数 | | PostCSS | k-soup/config/postcss | PostCSS 插件配置（autoprefixer 等） | | Vite 基础 | k-soup/config/vite/base | Vite 通用配置（别名、分包、压缩等） | | Vite 版本注入 | k-soup/config/vite/version | 自动注入版本号和构建时间 |

配置使用示例

ESLint 配置

// .eslintrc.cjs
module.exports = {
  // 注意：这里建议使用 require.resolve(...)，避免 ESLint 将 "k-soup/..." 误按 shareable-config 规则
  // 归一化为 "eslint-config-k-soup/..." 导致找不到配置。
  extends: [require.resolve('k-soup/config/eslint-react')], // React 项目
  // 或 extends: [require.resolve('k-soup/config/eslint')], // 基础配置
};

TypeScript 配置

{
  "extends": "k-soup/config/tsconfig/react",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Vite 配置

// vite.config.ts
import { defineConfig } from 'vite';
import { createKBaseViteConfig } from 'k-soup/config/vite/base';

export default defineConfig(
  createKBaseViteConfig({
    appName: 'my-app',
    overrides: {
      server: { 
        port: 3000,
        proxy: { '/api': 'http://localhost:8000' } 
      }
    }
  })
);

Vite 版本注入（可选）

如果需要在应用中显示版本号和构建时间，可以使用 k-soup/config/vite/version：

// vite.config.ts
import { defineConfig } from 'vite';
import { createKBaseViteConfig } from 'k-soup/config/vite/base';
import { createVersionSupport } from 'k-soup/config/vite/version';

const { htmlPlugin, define } = createVersionSupport({ appName: 'my-app' });

export default defineConfig({
  ...createKBaseViteConfig({ 
    appName: 'my-app',
    define // 注入版本相关的全局变量
  }),
  plugins: [htmlPlugin] // 支持在 HTML 中使用版本变量
});

这会自动注入以下全局变量和 HTML 模板变量：

// 在 TypeScript/JavaScript 代码中使用
console.log(__APP_VERSION__);    // 从 package.json 读取的版本号
console.log(__APP_BUILD_TIME__);  // ISO 格式的构建时间
console.log(__APP_NAME__);        // 应用名称

<!-- 在 index.html 中使用 -->
<title><%= APP_NAME %> v<%= APP_VERSION %></title>
<meta name="version" content="<%= APP_VERSION %>" />
<meta name="build-time" content="<%= APP_BUILD_TIME %>" />

Tailwind 配置

// tailwind.config.js
module.exports = require('k-soup/config/tailwind')();

📝 CLI 工具

k-soup 提供了一套完整的 CLI 工具，帮助标准化项目工作流：

依赖管理

| 命令 | 功能描述 | 使用场景 | |------|----------|----------| | k-install-deps | 检测 peerDependencies（默认仅预览），可用 --apply 补齐缺失项 | 新项目接入或依赖缺失时使用 |

# 预览/校验（默认 dry-run，不会执行安装）
pnpm exec k-install-deps

# 实际安装缺失的必需 peerDependencies
pnpm exec k-install-deps --apply

# 包含可选依赖（如 antd、echarts 等）
pnpm exec k-install-deps --apply --include-optional

# 严格模式（要求宿主依赖 spec 与要求完全一致）
pnpm exec k-install-deps --strict

# 查看帮助
pnpm exec k-install-deps --help

Git 工作流与版本管理

| 命令 | 功能描述 | 使用场景 | |------|----------|----------| | k-commit | 规范化提交（基于 commitizen） | 代替 git commit，生成符合约定式提交的消息 | | k-version | 语义化版本管理（基于 standard-version） | 根据提交历史自动生成版本号和 CHANGELOG | | k-release | 版本发布到 Git（生成版本并推送） | 自动生成版本、更新 CHANGELOG 并推送 tags 到远程仓库 | | k-view-changelog | 预览待发布的变更日志 | 发布前查看将要生成的 CHANGELOG 内容 |

# Git 工作流示例
pnpm exec k-commit           # 交互式规范提交
pnpm exec k-view-changelog   # 预览变更（自上次标签以来）
pnpm exec k-release          # 生成版本并推送到 Git（仅在有规范提交时）

# view-changelog 高级用法
pnpm exec k-view-changelog --all              # 显示全部变更（无行数限制）
pnpm exec k-view-changelog --max-lines 200    # 自定义最大行数
pnpm exec k-view-changelog --since v0.2.6     # 从指定标签开始预览

完整的版本发布流程（维护者）：

# 1. 开发和提交代码
pnpm exec k-commit           # 使用规范化提交

# 2. 预览即将生成的变更日志
pnpm exec k-view-changelog   # 确认变更内容

# 3. 生成版本号、更新 CHANGELOG 并推送到 Git
pnpm exec k-release          # 自动完成版本管理和 Git 推送

# 4. 构建项目
pnpm build                   # 生成 dist/ 和 docs-dist/

# 5. 发布到 npm（需要单独手动执行）
npm publish                  # 或 pnpm publish

注意：k-release 只负责版本管理和 Git 推送，不包含 npm 发布。发布到 npm 需要单独执行 npm publish 命令。

代码质量

| 命令 | 功能描述 | 使用场景 | |------|----------|----------| | k-lint | 代码检查（ESLint） | CI 或提交前检查代码规范 | | k-lint-fix | 代码检查并自动修复 | 批量修复可自动修复的问题 | | k-format | 代码格式化（Prettier） | 统一代码风格 | | k-format-check | 检查代码格式 | CI 中验证代码格式是否符合规范 | | k-check-config | 检查项目是否使用共享配置 | 验证项目配置是否正确引用 k-soup 配置 |

# 代码质量工具使用
pnpm exec k-lint              # 检查代码问题
pnpm exec k-lint-fix          # 修复可自动修复的问题
pnpm exec k-format            # 格式化代码
pnpm exec k-format-check      # 仅检查格式（不修改文件）
pnpm exec k-check-config      # 验证是否使用共享 ESLint 配置

项目维护

| 命令 | 功能描述 | 使用场景 | |------|----------|----------| | k-size-check | 构建产物体积分析 | 优化打包体积，生成可视化分析报告 | | k-sync-ignores | 同步忽略文件规则 | 保持 .gitignore 和 .prettierignore 一致 |

# 项目维护工具
pnpm exec k-size-check        # 分析构建产物体积（生成可视化报告）
pnpm exec k-sync-ignores      # 同步 gitignore 规则到 prettierignore

在项目中集成 CLI 工具

你可以在项目的 package.json 中添加快捷脚本：

{
  "scripts": {
    "commit": "k-commit",
    "release": "k-release",
    "lint": "k-lint",
    "lint:fix": "k-lint-fix",
    "format": "k-format",
    "check:size": "k-size-check"
  }
}

然后直接使用：

pnpm commit        # 等同于 pnpm exec k-commit
pnpm release       # 等同于 pnpm exec k-release
pnpm lint          # 等同于 pnpm exec k-lint

💡 按需加载与优化

k-soup 支持多种导入方式，可根据项目需求选择最优方案。

子路径导入清单

组件（支持单独导入）：

// A 系列组件（基于 Ant Design）
import ATable from 'k-soup/ATable';
import AForm from 'k-soup/AForm';
import AFormPage from 'k-soup/AFormPage';
import AModal from 'k-soup/AModal';
import ADrawer from 'k-soup/ADrawer';
import ASearch from 'k-soup/ASearch';
import ANavMenu from 'k-soup/ANavMenu';
import APageHeader from 'k-soup/APageHeader';
import APageLayout from 'k-soup/APageLayout';
import ATextBtns from 'k-soup/ATextBtns';
import ACopyText from 'k-soup/ACopyText';
import AQuestionTooltip from 'k-soup/AQuestionTooltip';

// K 系列组件（独立组件）
import { KEcharts } from 'k-soup/KEcharts';

工具函数（推荐子路径导入）：

// 存储工具
import { local, session } from 'k-soup/utils/store';

// 计算工具
import { calc } from 'k-soup/utils/calc';

// 日期工具
import { dayJs } from 'k-soup/utils/dayjs';         // 基础版本
import dayJsZh from 'k-soup/utils/dayjs-zh';        // 中文版本

// 事件总线
import { events, EventEmitter } from 'k-soup/utils/event';

路由和 Hooks（支持子路径导入）：

// 路由工具
import { createRoutes } from 'k-soup/router';
import { BrowserRouter } from 'k-soup/router/browser';

// Hooks
import { useContainerHeight, useElementSize } from 'k-soup/hooks/useDom';
import { useRouter } from 'k-soup/hooks/useRouter';

主题和组件索引：

// 主题
import { defaultTheme, darkTheme } from 'k-soup/theme';

// 所有组件的索引（仅用于 re-export）
import * as components from 'k-soup/components';

导入方式对比

// 方式 1: 根入口导入（推荐，支持 Tree Shaking）
import { APageLayout, ANavMenu, calc } from 'k-soup';
// ✅ 优点：写法简洁，IDE 提示友好
// ✅ 优点：支持 Tree Shaking，未使用的代码会被自动移除
// ⚠️ 注意：需要构建工具支持 ES Module

// 方式 2: 子路径导入（体积敏感场景）
import APageLayout from 'k-soup/APageLayout';
import { calc } from 'k-soup/utils/calc';
// ✅ 优点：确保最小化打包体积
// ✅ 优点：更快的编译速度（不需要解析整个入口）
// ⚠️ 注意：写法稍繁琐，需要记住具体路径

// 方式 3: 懒加载（大组件推荐）
import { lazy, Suspense } from 'react';
const KEcharts = lazy(() => import('k-soup/KEcharts'));
// ✅ 优点：按需加载，减少首屏体积
// ✅ 适用场景：图表、编辑器等大组件
// ⚠️ 注意：需要配合 Suspense 使用

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <KEcharts />
    </Suspense>
  );
}

Tree Shaking 支持

k-soup 已完整支持 Tree Shaking：

• ✅ ES Module：整个库使用 ES Module 构建
• ✅ sideEffects：在 package.json 中正确配置了副作用文件（仅 CSS）
• ✅ 按需引入：所有组件和工具函数都支持独立导入
• ✅ 自动优化：未使用的代码会被 Vite/Webpack 等构建工具自动移除

Tree Shaking 效果示例：

// 只导入了 calc 和 ATable
import { calc, ATable } from 'k-soup';

// 构建后，以下模块不会被打包：
// ❌ KEcharts（大型图表库）
// ❌ 其他未使用的组件
// ❌ 未使用的工具函数
// ✅ 仅打包 calc 和 ATable 相关代码

🙋 常见问题

安装与依赖

Q: 安装后提示缺少 peer 依赖怎么办？

A: 使用 k-install-deps 工具自动安装：

# 基础依赖
pnpm exec k-install-deps --apply

# 包含可选依赖（如 antd、echarts 等）
pnpm exec k-install-deps --apply --include-optional

Q: 是否需要安装 antd？

A: 取决于使用的组件：

• 仅使用工具函数、配置、K 系列组件：不需要
• 使用 A 系列组件（ATable、AForm 等）：需要安装 antd 和 @ant-design/icons

Q: 如何减小打包体积？

A: 推荐以下方式：

// ✅ 方式 1：根入口导入 + Tree Shaking（推荐）
import { ATable, calc } from 'k-soup';

// ✅ 方式 2：子路径导入（更细粒度控制）
import ATable from 'k-soup/ATable';
import { calc } from 'k-soup/utils/calc';

// ✅ 方式 3：懒加载大组件
import { lazy } from 'react';
const KEcharts = lazy(() => import('k-soup/KEcharts'));

样式问题

Q: 组件里的 Tailwind 类名不生效/样式缺失？

A: 最常见原因是宿主 Tailwind 没有扫描 k-soup 的构建产物。请使用以下配置：

// tailwind.config.cjs
const base = require('k-soup/config/tailwind');

module.exports = base({
  // ✅ 使用 helper 自动包含 k-soup 路径
  content: base.withKSoupContent([
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}',
  ]),
});

同时确认入口 CSS 包含 Tailwind 指令：

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Q: 样式优先级不稳定/组件样式被覆盖？

A: 检查入口样式引入顺序（推荐）：

// src/main.tsx
// 1. 先引入组件库 CSS
import 'k-soup/dist/index.css';
// 2. 再引入宿主样式（便于覆盖库默认样式）
import './index.css';

Q: 如何自定义主题？

A: 通过 CSS Variables 覆盖默认主题变量：

:root {
  --k-primary-color: #1890ff;
  --k-border-radius: 6px;
  --k-font-size-base: 14px;
}

/* 暗黑模式 */
[data-theme='dark'] {
  --k-primary-color: #177ddc;
  --k-bg-color: #141414;
}

TypeScript 相关

Q: TypeScript 类型提示不完整？

A: 确保项目的 tsconfig.json 配置正确：

{
  "compilerOptions": {
    "moduleResolution": "bundler", // 或 "node"
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

Q: 如何使用 k-soup 的 TypeScript 配置？

A: 扩展预设配置：

{
  "extends": "k-soup/config/tsconfig/react",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

构建与优化

Q: 如何分析打包体积？

A: 使用内置的体积分析工具：

pnpm exec k-size-check

会生成可视化的打包分析报告。

Q: 是否支持服务端渲染（SSR）？

A: 是的，所有组件都支持 SSR。但请注意：

• DOM 操作相关的 Hooks（如 useContainerHeight）需要在客户端环境使用
• 确保浏览器特定的 API 在服务端不会执行

组件设计

Q: 为什么有些组件前缀是 A，有些是 K？

A:

• A 系列：基于 Ant Design 的业务组件封装，提供开箱即用的功能（如 ATable、AForm）
• K 系列：独立开发的轻量级组件，使用 Tailwind CSS 构建（如 KEcharts）

Q: 如何查看完整的组件 API 文档？

A:

# 本地启动文档站点
pnpm dev
# 访问 http://localhost:8000

CLI 工具

Q: CLI 工具命令太长，如何简化？

A: 在项目 package.json 中添加快捷脚本：

{
  "scripts": {
    "commit": "k-commit",
    "lint": "k-lint",
    "format": "k-format"
  }
}

然后使用 pnpm commit 代替 pnpm exec k-commit。

Q: 如何在 CI/CD 中使用这些工具？

A: 示例 GitHub Actions 配置：

- name: 代码检查
  run: pnpm exec k-lint

- name: 格式检查
  run: pnpm exec k-format-check

- name: 体积分析
  run: pnpm exec k-size-check

🔗 相关链接

• React 官方文档
• Vite 官方文档
• Ant Design
• Tailwind CSS
• ECharts

📄 许可证

MIT License

Copyright (c) 2024-present k-soup contributors

本项目采用 MIT 许可证开源。查看项目根目录下的 LICENSE 文件获取完整许可证文本。

Built with ❤️ by the k