跳到主要内容

出码类型选择

在实际生产中，我们会根据不同的业务场景，选择不同的出码类型：

出码类型业务场景说明
完整开发环境适合新业务从零搭建输出一套完整的专题类项目工程文件，采用 Vite 作为构建工具，内部集成了 Typescript、React、Prettier 等常用工具快速上手。
组件形式在已有项目持续集成输出与组件相关的代码文件，可按照 使用教程 灵活的集成到已有的项目中使用。

完整开发环境​

适合新业务从零搭建。提供一套完整的专题类项目工程文件，采用 Vite 作为构建工具，内部集成了 Typescript、React、Prettier 等常用工具，开发者可在此基础上进行二次开发。

系统要求​

  • Node.js 16.14 或更高版本。

  • 支持 macOS、Windows（包括 WSL）和 Linux。

安装依赖​

# 安装依赖
npm install

# 启动开发环境
npm run dev

目录结构​

这是 cube-vite-template 生成的默认目录结构。

├── README.md
├── index.html
├── package.json
├── src
│   ├── App.tsx
│   ├── components
│   ├── cube                    // 魔方主要目录
│   │   ├── card                // 卡片目录
│   │   │   ├── components      // 卡片级组件目录
│   │   │   ├── context         // 卡片共享 Context
│   │   │   ├── hooks           // 卡片自定义 Hooks
│   │   │   └── view            // 卡片源码
│   │   │       └── Card
│   │   ├── index.tsx
│   │   ├── styles              // 卡片公共样式
│   │   ├── types               // 魔方 TS 类型定义目录
│   │   └── utils               // 工具方法目录
│   ├── data.tsx
│   ├── main.tsx
│   └── styles
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── vite.md
└── yarn.lock

组件形式​

在已有项目持续集成。提供与组件相关的代码文件，可灵活的集成到已有的项目中使用。

使用方式​

1. 解压输出包，将 cube 目录完整拷贝到项目根目录下的 src 文件夹内。​

压缩包文件结构

.
├── README.md             // 使用文档
└── cube                  // 组件目录
    ├── Demo.tsx          // 调用示例文件
    ├── card              // 卡片目录
    │   ├── components
    │   ├── context
    │   ├── hooks
    │   └── view
    ├── data.tsx          // 专题数据
    ├── index.tsx
    ├── mergePackage.mjs  // 自动合并 package.json 脚本
    ├── package.json
    ├── styles            // 卡片公共样式
    ├── types
    └── utils

2. 合并 package 依赖，在根目录运行下列命令，并重新安装依赖。​

# 合并 package 依赖
node ./src/cube/mergePackage.mjs

# 重新安装依赖
npm install
提示

合并操作前会备份 package.json 文件到 bak 目录下备用，并会提示当前项目与 cube 组件依赖之间的版本依赖冲突（需按需解决），默认采用 cube 依赖版本。

3. 脚手架配置，这里以 vite 为例，其他脚手架请参考对应文档。​

  • 增加 styled-jsx/babel 插件，用于支持 styled-jsx 语法。

  • 增加 alias 配置，用于支持 cube 组件内部的引用。

  • 增加 define 配置，cube 组件依赖的环境变量。

vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['styled-jsx/babel'],
      },
    }),
  ],
  resolve: {
    alias: {
      '@cube': path.resolve(__dirname, 'src/cube'),
      '~@cube': path.resolve(__dirname, 'src/cube'),
    },
  },
  define: {
    'process.env.IS_FRONT_ENV': JSON.stringify(true),
    'process.env.APP_ENV': JSON.stringify('production'),
  },

});

调整 tsconfig 配置，增加 baseUrl 配置，用于支持 cube 组件内部的引用。

tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@cube/*": [
        "src/cube/*"
      ]
    },
    "moduleResolution": "Node",
    "allowSyntheticDefaultImports": true,
  },
}

4. 在项目中引入 cube 组件。​

src/App.tsx
import Demo from './cube/Demo';

function App() {
  return <Demo />;
}
export default App;

常见问题​

  • 关于 REM 默认配置 16px，如需调整查看 ./src/cube/styles/_mixin.scss 中 px2rem 方法。
  • 卡片中并未包含样式重置功能 reset.css，如需重置参考完整框架中的配置。
  • 关于 build 阶段 ts 类型报错问题，举例 swiper@^8.0.0 在 typescript@^5.0.0 下类型错误，可通过调整 tsconfig.json 中 moduleResolution: "node" 解决。
  • 当模块没有默认导出时允许导出模块，tsconfig.json 中定义 allowSyntheticDefaultImports: true。