VTable Engineering Guide Document

This document provides an engineering guide for the VTable project, including how to obtain the source code, install dependencies, run examples, and an overview of the project structure.

1. Obtain the Source Code

Clone the repository from GitHub

# 克隆 VTable 仓库
git clone https://github.com/VisActor/VTable.git

# 进入项目目录
cd VTable

2. Environment Preparation

Prerequisites

Node.js: Requires Node.js installation, version requirements: >=14.15.0 <15.0.0 || >=16.13.0 <17.0.0 || >=18.15.0 <19.0.0
Rush: VTable uses Microsoft Rush for project management

Install Rush

# 全局安装 Rush
npm install -g @microsoft/rush

Install Project Dependencies

# 在 VTable 根目录下执行以下命令，安装所有依赖
rush update

3. Start Demo

VTable provides rich examples for developers to understand and use.

Execute the following command in the root directory to start the vtable package directory example.

# 启动 vtable包目录示例
rushx demo

This will start a local development server, usually running at http://localhost:300*, which you can access in your browser to view all examples.

Methods to start examples under different feature packages:

Start VTable core library example

# 进入 vtable 包目录
cd packages/vtable
# 启动示例
rushx demo

Start React VTable Example

# 进入 react-vtable 包目录
cd packages/react-vtable

# 启动示例
rushx demo

Start Vue VTable Example

# 进入 vue-vtable 包目录
cd packages/vue-vtable

# 启动示例
rushx demo

Start Vue VTable Example

# 进入 vue-vtable 包目录
cd packages/openinula-vtable

# 启动示例
rushx demo

Start Gantt Chart Example

# 进入 vtable-gantt 包目录
cd packages/vtable-gantt

# 启动示例
rushx demo

Start Calendar Component Example

# 进入 vtable-calendar 包目录
cd packages/vtable-calendar

# 启动示例
rushx demo

Start Plugin Example

# 进入 vtable-plugins 包目录
cd packages/vtable-plugins

# 启动示例
rushx demo

Start the Documentation Site

# 在项目根目录执行
rush docs

This will launch the VTable documentation site, which includes detailed tutorials, API documentation, and examples.

4. Command Description

In each package directory, you can execute the following command:

Command	Instructions
`rushx demo`	Start local example service
`rushx build`	Build Library File
`rushx dev`	Development mode build (watch for file changes)
`rushx test`	Run unit tests
`rushx test-cov`	Run test coverage analysis
`rushx eslint`	Execute code style check
`rushx compile`	Only perform TypeScript type checking

In the project root directory, you can use the following Rush commands:

Command	Instructions
`rush start`	Start the demo under the VTable directory of the core package
`rush update`	Install or update all dependencies
`rush build`	Build all projects
`rush rebuild`	Clean and rebuild all projects
`rush test`	Run tests for all projects
`rush change-all`	Update all changelogs after submitting code
`rush docs`	Start the documentation site

## 5. Project Structure Description

The VTable project adopts a Monorepo structure managed by Rush, mainly consisting of the following parts:

Top-level Directory Structure

VTable/
  ├── .github/            # GitHub 相关配置
  ├── .vscode/            # VS Code 配置
  ├── common/             # Rush 配置文件和公共依赖
  ├── docs/               # 文档站点源码
  ├── packages/           # 所有包的源代码
  ├── share/              # 共享配置（ESLint、TypeScript等）
  ├── tools/              # 开发工具和脚本
  ├── types/              # 公共类型定义
  ├── CONTRIBUTING.md     # 贡献指南
  ├── README.md           # 项目说明
  └── rush.json           # Rush 配置文件

packages directory

The packages directory contains all VTable related packages:

packages/
  ├── vtable/             # VTable 核心库
  ├── react-vtable/       # React 集成
  ├── vue-vtable/         # Vue 集成
  ├── openinula-vtable/   # OpenInula 集成
  ├── vtable-gantt/       # 甘特图组件
  ├── vtable-editors/     # 编辑器组件
  ├── vtable-export/      # 导出工具
  ├── vtable-search/      # 搜索工具
  ├── vtable-calendar/    # 日历组件
  └── vtable-plugins/     # 插件集合

vtable Package Structure

The core vtable package structure is as follows:

packages/vtable/
  ├── examples/           # 示例代码
  ├── site-demo/          # 站点示例
  ├── src/                # 源代码
  ├── test/               # 测试代码
  ├── nodejs/             # Node.js 环境相关代码
  ├── package.json        # 包配置
  └── README.md           # 说明文档

6. Development Process

Develop New Features or Fix Bugs

Create a branch: Create a new feature or fix branch from the main branch develop
Development: Make code modifications and development
Test: Run unit tests to ensure code quality
Create demo: Create a new demo in the packages/vtable/examples directory
Compile: Execute rushx compile to ensure the code compiles correctly
Build: Execute rushx build to ensure the code can be built successfully
Submission: Submit code, be sure to follow submission guidelines
Changelog: Run rush change-all to update the changelog
Submit PR: Submit a pull request to the main repository

具体过程可以参考官网教程：贡献者指南

Version Control

VTable uses Rush to manage versions, primarily relying on the version strategy (versionPolicyName) defined in the rush.json file.

7. Frequently Asked Questions and Solutions

Dependency Installation Issues

If you encounter issues during the rush update process, you can try the following methods:

# 清除 Rush 缓存
rush purge

# 重新安装所有依赖
rush update --full

Failed to Start Demo

If there are issues when starting the example, you can check the following points:

Does the Node.js version meet the requirements
Whether all dependencies have been successfully installed
Check console error messages

# 重新构建并启动示例
rush build
cd packages/vtable
rushx demo

Build Failed

If the build process fails, you can try the following methods:

# 清理构建缓存
rush clean

# 重新构建
rush build

8. Contributing

We welcome all forms of contributions, including but not limited to submitting issues, improving documentation, fixing bugs, or adding new features.

参与贡献前，请务必阅读贡献者指南，了解贡献流程和规范。

9. Resource Links

This document was edited by the following people:

玄魂