@worktile/gantt 12.0.0 → 12.0.1

package/docs/guides/basic/usage.md

@@ -0,0 +1,189 @@
+---
+title: 如何使用
+path: usage
+order: 10
+---
+
+## 基本使用
+
+一般情况下最基本的使用我们只需要定义 `items` 数据传入组件中，如需要左侧的表格展示，则还需要定义表格的 column
+
+```html
+<ngx-gantt #gantt [items]="items">
+  <ngx-gantt-table>
+    <ngx-gantt-column name="标题" width="300px">
+      <ng-template #cell let-item="item"> {{ item.title }} </ng-template>
+    </ngx-gantt-column>
+  </ngx-gantt-table>
+</ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197, expandable: true },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597, links: ['000003', '000004', '000000'], expandable: true },
+    { id: '000002', title: 'Task 2', start: 1610536397, end: 1610622797 },
+    { id: '000003', title: 'Task 3', start: 1628507597, end: 1633345997, expandable: true }
+  ];
+}
+```
+
+## 如何设置分组
+
+分组模式下我们还需要传入一个 `groups` 的数组，并且保证我们传入的 `items` 数据中设置了每个数据项的 `group_id`
+
+```html
+<ngx-gantt #gantt [groups]="groups" [items]="items">
+  <ngx-gantt-table>
+    <ngx-gantt-column name="标题" width="300px">
+      <ng-template #cell let-item="item"> {{ item.title }} </ng-template>
+    </ngx-gantt-column>
+  </ngx-gantt-table>
+</ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  groups: GanttGroup[] = [
+    { id: '000000', title: 'Group-0' },
+    { id: '000001', title: 'Group-1' }
+  ];
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197, group_id: '000000' },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597, group_id: '000001' }
+  ];
+}
+```
+
+## 树形结构展示
+
+`GanttItem` 类型包含 `children` 属性，默认情况下只要我们传入了 `children` 属性则就就会展示为树形结构。
+
+```javascript
+export class AppGanttExampleComponent {
+  items: GanttItem[] = [
+    {
+      id: '000000',
+      title: 'Task 0',
+      children: [
+        { id: '000000-01', title: 'Task 0-1' },
+        { id: '000000-02', title: 'Task 0-2' }
+      ]
+    }
+  ];
+}
+```
+
+如果需要异步加载子数据，我们需要设置将组件的 `async` 设置为 `true` 然后设置加载子数据的 Resolve 函数 `childrenResolve`，最后我们还需要指定哪些数据是可展开的。
+
+```html
+<ngx-gantt #gantt [items]="items" [async]="true" [childrenResolve]="childrenResolve"> ... </ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  // 设置 expandable 为true 指定数据是可展开的
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197, expandable: true },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597, expandable: true }
+  ];
+
+  // 设置加载子数据的 Resolve 函数，返回值必须是一个可观察对象 Observable
+  childrenResolve = (item: GanttItem) => {
+    const children = randomItems(random(1, 5), item);
+    return of(children).pipe(delay(1000));
+  };
+}
+```
+
+## 依赖
+
+如果我们需要展示数据项的依赖关系，则需要设置 `GanttItem` 中的 `links` 属性，设置需要关联的 id，如果需要拖拽创建关联关系，则需要设置 `[linkable] = true`，在某些场景下可能我们需要设置某一条数据开启拖拽创建关联，我们也可以通过设置 item 数据的 `linkable` 来实现。
+
+```html
+<ngx-gantt #gantt [items]="items" [linkable]="true" (linkDragEnded)="linkDragEnded($event)"> ... </ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197, links: ['000001', '000002'] },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597, links: ['000003'] },
+    { id: '000002', title: 'Task 2', start: 1617361997, end: 1625483597, linkable: false }
+  ];
+
+  linkDragEnded($event: GanttLinkDragEvent) {
+    this.http
+      .post(`/api/item/deps`, {
+        source: event.source,
+        target: event.target
+      })
+      .subscribe((items) => {});
+  }
+}
+```
+
+## 滚动加载
+
+为了保证组件的性能，默认情况下只会展示一定周期的时间（不同的视图周期不同），所以组件默认开启了滚动加载。如果不需要滚动加载可以通过设置 `[disabledLoadOnScroll]=true` 来禁用。
+
+```html
+<ngx-gantt #gantt [items]="items" (loadOnScroll)="loadOnScroll($event)"> ... </ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197 },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597 },
+    { id: '000002', title: 'Task 2', start: 1617361997, end: 1625483597 }
+  ];
+
+  loadOnScroll(event: GanttLoadOnScrollEvent) {
+    this.http.get(`/api/items?start=${event.start}&end=${event.end}`).subscribe((items) => {
+      this.items = [...this.items, ...items];
+    });
+  }
+}
+```
+
+## 拖拽
+
+通过设置 `[draggable]=true` 来启用拖拽功能，支持 `(dragStarted)`、`(dragEnded)` 事件。
+
+```html
+<ngx-gantt #gantt [items]="items" [draggable]="true" (dragEnded)="dragEnded($event)"> ... </ngx-gantt>
+```
+
+```javascript
+export class AppGanttExampleComponent {
+  dragEnded($event: GanttDragEvent) {
+    this.http
+      .put(`/api/item/${$event.item.id}`, {
+        start: $event.item.start,
+        end: $event.item.end
+      })
+      .subscribe((items) => {});
+  }
+}
+```
+
+## 导出为图片
+
+如需要导出图片功能，我们需要在使用组件时注入图片打印服务 `GanttPrintService`
+
+```javascript
+@Component({
+  selector: 'app-gantt-example',
+  templateUrl: './gantt.component.html',
+  providers: [GanttPrintService]
+})
+export class AppGanttExampleComponent {
+  @ViewChild('gantt') ganttComponent: NgxGanttComponent;
+
+  exportImage() {
+    ganttComponent.print('image name');
+  }
+}
+```

package/docs/guides/index.md

@@ -0,0 +1,5 @@
+---
+title: 指南
+path: 'guides'
+order: 1
+---

package/docs/guides/intro/getting-started.md

@@ -0,0 +1,79 @@
+---
+title: 快速开始
+path: 'getting-started'
+order: 2
+---
+
+# 安装
+
+```bash
+$ npm i @worktile/gantt --save
+# or
+$ yarn add @worktile/gantt
+```
+
+# 使用
+
+### 导入模块
+
+```ts
+import { NgModule } from '@angular/core';
+import { NgxGanttModule } from '@worktile/gantt';
+
+@NgModule({
+  ...
+  imports: [ NgxGanttModule, ... ]
+  ...
+})
+export class AppModule {
+
+}
+```
+
+<br/>
+
+### 引入样式
+在 angular.json 中引入
+```json
+{
+    "styles": [
+        "node_modules/@worktile/gantt/main.bundle.scss"
+    ]
+}
+```
+在style.scss中引入预构建样式文件
+```
+@import "~@worktile/gantt/main.bundle.scss";
+```
+
+### 组件中使用
+
+
+```html
+<!-- component.html -->
+<ngx-gantt #gantt [items]="items">
+  <ngx-gantt-table>
+    <ngx-gantt-column name="标题" width="300px">
+      <ng-template #cell let-item="item"> {{ item.title }} </ng-template>
+    </ngx-gantt-column>
+  </ngx-gantt-table>
+</ngx-gantt>
+```
+
+```javascript
+// component.ts
+@Component({
+  selector: 'app-gantt-example',
+  templateUrl: './gantt.component.html'
+})
+export class AppGanttExampleComponent {
+  items: GanttItem[] = [
+    { id: '000000', title: 'Task 0', start: 1627729997, end: 1628421197, expandable: true },
+    { id: '000001', title: 'Task 1', start: 1617361997, end: 1625483597, links: ['000003', '000004', '000000'], expandable: true },
+    { id: '000002', title: 'Task 2', start: 1610536397, end: 1610622797 },
+    { id: '000003', title: 'Task 3', start: 1628507597, end: 1633345997, expandable: true }
+  ];
+
+  constructor() {}
+}
+```

package/docs/guides/intro/index.md

@@ -0,0 +1,51 @@
+---
+title: 介绍
+path: 'intro'
+order: 1
+---
+
+# 一句话介绍
+
+`ngx-gantt` 是一款基于 Angular 框架的甘特图组件，支持多种视图展示并支持多种高级的特性，能快速的帮助开发者搭建自己的甘特图应用。
+
+# 特性
+
+- 5 种视图（日、周、月、季、年）
+- 任务分组展示
+- 树形结构数据展示并支持异步加载
+- 任务前后置依赖关联及展示
+- 任务拖拽更改时间
+- 表格自定义
+- 滚动加载数据
+- 导出为图片
+- 可定制化开发
+
+# 动机
+
+2020 年，[PingCode](https://pingcode.com) 准备做一款项目集管理的产品 Plan，Plan 这款产品包含多项目路线图管理，进度管理，资源跟踪以及里程碑管理，其中涉及到路线图，里程碑等功能都需要基于甘特图来实现，随后我们开始调研 Github 中开源的一些甘特图的组件，最终都因为不能满足我们的需求而 pass，其中主要的原因有以下几点：
+
+- 不能很好的支持 Angular
+- 有一些功能强大的库依旧依赖 JQuery
+- 不支持多层级展示
+- 默认支持的视图不满足我们的场景
+- 不够灵活
+
+基于上述原因，我们决定自己造轮子，做一款基于 Angular 的甘特图组件。
+
+## 当前版本
+
+[![npm (scoped)](https://img.shields.io/npm/v/@worktile/gantt?style=flat-square)](https://www.npmjs.com/package/@worktile/gantt)
+
+## 支持 Angular 版本
+
+`ngx-gantt` 与 `@angular/core` 保持相同的主版本号，目前支持 Angular ^12.0.0 版本。
+
+## 依赖第三方库
+
+- Components Dev Kit (Angular CDK)
+- date-fns
+- html2canvas
+
+# 参与贡献
+
+Gantt 目前还处于开发中，欢迎一起参与贡献 https://github.com/worktile/ngx-gantt 。

package/example/browserslist

@@ -0,0 +1,12 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+> 0.5%
+last 2 versions
+Firefox ESR
+not dead
+not IE 9-11 # For IE 9-11 support, remove 'not'.

package/example/src/app/app-routing.module.ts

@@ -0,0 +1,26 @@
+import { NgModule } from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+import { AppGanttExampleComponent } from './gantt/gantt.component';
+import { AppGanttAdvancedExampleComponent } from './gantt-advanced/gantt-advanced.component';
+import { AppGanttRangeExampleComponent } from './gantt-range/gantt-range.component';
+import { AppExampleComponentsComponent } from './components/components.component';
+import { AppGanttGroupsExampleComponent } from './gantt-groups/gantt-groups.component';
+
+const routes: Routes = [
+    {
+        path: 'components',
+        component: AppExampleComponentsComponent,
+        children: [
+            { path: '', redirectTo: 'basic', pathMatch: 'full' },
+            { path: 'basic', component: AppGanttExampleComponent },
+            { path: 'groups', component: AppGanttGroupsExampleComponent },
+            { path: 'advanced', component: AppGanttAdvancedExampleComponent }
+        ]
+    }
+];
+
+@NgModule({
+    imports: [RouterModule.forRoot(routes)],
+    exports: [RouterModule]
+})
+export class AppRoutingModule {}

package/example/src/app/app.component.html

@@ -0,0 +1,2 @@
+<dg-navbar></dg-navbar>
+<router-outlet></router-outlet>

package/example/src/app/app.component.ts

@@ -0,0 +1,11 @@
+import { Component, HostBinding } from '@angular/core';
+
+@Component({
+    selector: 'example-root',
+    templateUrl: `./app.component.html`,
+    styles: [],
+})
+export class AppComponent {
+    @HostBinding(`class.dg-main`) isRoot = true;
+    title = 'example';
+}

package/example/src/app/app.module.ts

@@ -0,0 +1,57 @@
+import { ThyLayoutModule } from 'ngx-tethys/layout';
+import { setPrintErrorWhenIconNotFound } from 'ngx-tethys/icon';
+import { ThyNavModule } from 'ngx-tethys/nav';
+import { ThyButtonModule } from 'ngx-tethys/button';
+import { ThyCheckboxModule } from 'ngx-tethys/checkbox';
+import { ThyNotifyModule } from 'ngx-tethys/notify';
+import { NgModule } from '@angular/core';
+import { RouterModule } from '@angular/router';
+import { NgxGanttModule } from 'ngx-gantt';
+import { AppComponent } from './app.component';
+import { AppGanttExampleComponent } from './gantt/gantt.component';
+import { AppRoutingModule } from './app-routing.module';
+import { CommonModule } from '@angular/common';
+import { AppGanttAdvancedExampleComponent } from './gantt-advanced/gantt-advanced.component';
+import { AppGanttRangeExampleComponent } from './gantt-range/gantt-range.component';
+import { DOCGENI_SITE_PROVIDERS } from './content/index';
+import { DocgeniTemplateModule } from '@docgeni/template';
+import { BrowserModule } from '@angular/platform-browser';
+import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
+import { AppGanttFlatComponent } from './gantt-advanced/component/flat.component';
+import { EXAMPLE_MODULES } from './content/example-modules';
+import { AppExampleComponentsComponent } from './components/components.component';
+import { AppGanttGroupsExampleComponent } from './gantt-groups/gantt-groups.component';
+
+@NgModule({
+    declarations: [
+        AppComponent,
+        AppExampleComponentsComponent,
+        AppGanttExampleComponent,
+        AppGanttAdvancedExampleComponent,
+        AppGanttGroupsExampleComponent,
+        AppGanttRangeExampleComponent,
+        AppGanttFlatComponent
+    ],
+    imports: [
+        BrowserModule,
+        BrowserAnimationsModule,
+        CommonModule,
+        DocgeniTemplateModule,
+        NgxGanttModule,
+        AppRoutingModule,
+        RouterModule.forRoot([]),
+        ThyButtonModule,
+        ThyNavModule,
+        ThyLayoutModule,
+        ThyCheckboxModule,
+        ThyNotifyModule,
+        ...EXAMPLE_MODULES
+    ],
+    providers: [...DOCGENI_SITE_PROVIDERS],
+    bootstrap: [AppComponent]
+})
+export class AppModule {
+    constructor() {
+        setPrintErrorWhenIconNotFound(false);
+    }
+}

package/example/src/app/components/components.component.html

@@ -0,0 +1,6 @@
+<div class="dg-layout dg-scroll-container">
+  <dg-sidebar [menus]="menus"></dg-sidebar>
+  <div class="gantt-example-content" style="margin-left: 300px">
+    <router-outlet></router-outlet>
+  </div>
+</div>

package/example/src/app/components/components.component.ts

@@ -0,0 +1,33 @@
+import { Component, OnInit } from '@angular/core';
+import { DocItem } from '@docgeni/template';
+
+@Component({
+    selector: 'app-example-components',
+    templateUrl: './components.component.html'
+})
+export class AppExampleComponentsComponent implements OnInit {
+    menus: DocItem[] = [
+        {
+            id: 'basic',
+            title: '基本使用',
+            subtitle: 'Basic',
+            path: 'basic'
+        },
+        {
+            id: 'groups',
+            title: '分组展示',
+            subtitle: 'Groups',
+            path: 'groups'
+        },
+        {
+            id: 'advanced',
+            title: '高级使用',
+            subtitle: 'Advanced',
+            path: 'advanced'
+        }
+    ];
+
+    constructor() {}
+
+    ngOnInit() {}
+}