Feat/gantt auto location icon

common/changes/@visactor/vtable/feat-gantt-autoLocationIcon_2026-03-25-03-56.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: gantt add locateIcon for taskbar\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

docs/assets/demo/en/gantt/gantt-locate-taskbar.md

@@ -0,0 +1,77 @@
+---
+category: examples
+group: gantt
+title: Task Bar Locate (Offscreen Indicator)
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/gantt/gantt-locate-taskbar.gif
+link: gantt/Getting_Started
+option: Gantt#taskBar
+---
+
+# Task Bar Locate (Offscreen Indicator)
+
+When the timeline is long, task bars may be outside the current viewport. This demo shows how to enable the locate icon feature: when a task bar is horizontally outside the viewport, an icon is displayed at the left/right edge of the gantt view; hover highlights it, and click scrolls the task bar into view.
+
+## Key Option
+
+- `taskBar.locateIcon: true`
+
+## Live Demo
+
+```javascript livedemo template=vtable
+// import * as VTableGantt from '@visactor/vtable-gantt';
+let ganttInstance;
+
+const records = [
+  { id: 1, title: 'Offscreen on the left', start: '2024-02-05', end: '2024-02-20', progress: 20 },
+  { id: 2, title: 'Offscreen on the left', start: '2024-03-10', end: '2024-03-18', progress: 60 },
+  { id: 5, title: 'Visible in viewport', start: '2024-05-28', end: '2024-06-05', progress: 50 },
+  { id: 3, title: 'Offscreen on the right', start: '2024-10-05', end: '2024-10-20', progress: 40 },
+  { id: 4, title: 'Offscreen on the right', start: '2024-11-10', end: '2024-11-25', progress: 80 }
+];
+
+const columns = [
+  { field: 'title', title: 'title', width: 160, sort: true },
+  { field: 'start', title: 'start', width: 120, sort: true },
+  { field: 'end', title: 'end', width: 120, sort: true },
+  { field: 'progress', title: 'progress', width: 100, sort: true }
+];
+
+const option = {
+  records,
+  taskKeyField: 'id',
+  taskListTable: {
+    columns,
+    tableWidth: 280,
+    minTableWidth: 240,
+    maxTableWidth: 600
+  },
+  taskBar: {
+    startDateField: 'start',
+    endDateField: 'end',
+    progressField: 'progress',
+    locateIcon: true
+  },
+  minDate: '2024-01-01',
+  maxDate: '2024-12-31',
+  timelineHeader: {
+    colWidth: 30,
+    scales: [{ unit: 'day', step: 1 }]
+  },
+  scrollStyle: {
+    visible: 'scrolling'
+  },
+  grid: {
+    verticalLine: { lineWidth: 1, lineColor: '#e1e4e8' },
+    horizontalLine: { lineWidth: 1, lineColor: '#e1e4e8' }
+  }
+};
+
+ganttInstance = new VTableGantt.Gantt(document.getElementById(CONTAINER_ID), option);
+window['ganttInstance'] = ganttInstance;
+
+setTimeout(() => {
+  const x = ganttInstance.getXByTime(new Date('2024-06-01 00:00:00').getTime());
+  ganttInstance.scrollLeft = x;
+}, 0);
+```
+

docs/assets/demo/menu.json

@@ -314,6 +314,13 @@
             "en": "Gantt Basic"
           }
         },
+        {
+          "path": "gantt-locate-taskbar",
+          "title": {
+            "zh": "任务条定位（超出可视区）",
+            "en": "Task Bar Locate"
+          }
+        },
         {
           "path": "gantt-customLayout",
           "title": {

docs/assets/demo/zh/gantt/gantt-locate-taskbar.md

@@ -0,0 +1,77 @@
+---
+category: examples
+group: gantt
+title: 甘特图任务条定位（超出可视区提示）
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/gantt/gantt-locate-taskbar.gif
+link: gantt/Getting_Started
+option: Gantt#taskBar
+---
+
+# 甘特图任务条定位（超出可视区提示）
+
+当时间轴很长时，任务条可能不在当前可视区域内。本示例展示如何开启定位图标能力：当任务条横向超出可视区域时，在甘特图左右边缘显示定位图标；鼠标 hover 会高亮，点击后会自动滚动将任务条带入可视区域。
+
+## 关键配置
+
+- `taskBar.locateIcon: true`
+
+## 代码演示
+
+```javascript livedemo template=vtable
+// import * as VTableGantt from '@visactor/vtable-gantt';
+let ganttInstance;
+
+const records = [
+  { id: 1, title: '任务条在左侧不可见', start: '2024-02-05', end: '2024-02-20', progress: 20 },
+  { id: 2, title: '任务条在左侧不可见', start: '2024-03-10', end: '2024-03-18', progress: 60 },
+  { id: 5, title: '任务条在可见区', start: '2024-05-28', end: '2024-06-05', progress: 50 },
+  { id: 3, title: '任务条在右侧不可见', start: '2024-10-05', end: '2024-10-20', progress: 40 },
+  { id: 4, title: '任务条在右侧不可见', start: '2024-11-10', end: '2024-11-25', progress: 80 }
+];
+
+const columns = [
+  { field: 'title', title: 'title', width: 160, sort: true },
+  { field: 'start', title: 'start', width: 120, sort: true },
+  { field: 'end', title: 'end', width: 120, sort: true },
+  { field: 'progress', title: 'progress', width: 100, sort: true }
+];
+
+const option = {
+  records,
+  taskKeyField: 'id',
+  taskListTable: {
+    columns,
+    tableWidth: 280,
+    minTableWidth: 240,
+    maxTableWidth: 600
+  },
+  taskBar: {
+    startDateField: 'start',
+    endDateField: 'end',
+    progressField: 'progress',
+    locateIcon: true
+  },
+  minDate: '2024-01-01',
+  maxDate: '2024-12-31',
+  timelineHeader: {
+    colWidth: 30,
+    scales: [{ unit: 'day', step: 1 }]
+  },
+  scrollStyle: {
+    visible: 'scrolling'
+  },
+  grid: {
+    verticalLine: { lineWidth: 1, lineColor: '#e1e4e8' },
+    horizontalLine: { lineWidth: 1, lineColor: '#e1e4e8' }
+  }
+};
+
+ganttInstance = new VTableGantt.Gantt(document.getElementById(CONTAINER_ID), option);
+window['ganttInstance'] = ganttInstance;
+
+setTimeout(() => {
+  const x = ganttInstance.getXByTime(new Date('2024-06-01 00:00:00').getTime());
+  ganttInstance.scrollLeft = x;
+}, 0);
+```
+

docs/assets/guide/en/gantt/introduction.md

@@ -133,6 +133,20 @@ You can set whether task bars are resizable through the `taskBar.resizable` conf
 
 You can set whether task bars are adjustable through the `taskBar.progressAdjustable` configuration item.
 
+#### Task Bar Locate
+
+When the timeline is long and the task bar is outside the current viewport, you can enable the “locate icon” feature: an icon is shown on the left/right edge of the gantt view, and clicking it scrolls the task bar into the viewport.
+
+Key option:
+
+```javascript
+const option = {
+  taskBar: {
+    locateIcon: true
+  }
+};
+```
+
 #### Adjusting the Width of the Left Table
 
 You can set the divider line to be draggable by configuring `frame.verticalSplitLineMoveable` to true.

docs/assets/guide/zh/gantt/introduction.md

@@ -133,6 +133,20 @@ links:[
 
 通过 `taskBar.progressAdjustable` 配置项，可以设置任务条是否可调整进度。
 
+####  任务条定位
+
+当时间轴较长、任务条不在当前可视区域内时，可以开启“定位图标”能力：在甘特图左右边缘显示图标，点击后自动滚动到该任务条的可视区域。
+
+关键配置：
+
+```javascript
+const option = {
+  taskBar: {
+    locateIcon: true
+  }
+};
+```
+
 #### 调整左侧表格宽度
 
 通过 `frame.verticalSplitLineMoveable` 配置为 true，可以设置分割线可拖拽。

docs/assets/option/en/common/gantt/task-bar.md

@@ -171,6 +171,12 @@ Whether the service clause is optional, the default is true
 
 Not required
 
+${prefix} locateIcon(boolean) = false
+
+When the task bar is horizontally outside the current viewport, show a “locate icon” at the left/right edge of the gantt view. Hover highlights the icon, and click scrolls the task bar into the viewport.
+
+Optional
+
 ${prefix} scheduleCreatable(boolean | Function) = true
 
 When there is no scheduling data, scheduling can be done by creating a task bar. When `tasksShowMode` is `TasksShowMode.Tasks_Separate` or `TasksShowMode.Sub_Tasks_Separate`, `scheduleCreatable` defaults to `true`, otherwise, when `tasksShowMode` is `TasksShowMode.Sub_Tasks_Inline`, `TasksShowMode.Sub_Tasks_Arrange`, or `TasksShowMode.Sub_Tasks_Compact`, `scheduleCreatable` defaults to `false`.
@@ -267,4 +273,3 @@ Vertical position of the baseline bar relative to the main task bar:
 - `overlap`: baseline overlaps and is centered with the task bar.
 
 Optional
-

docs/assets/option/zh/common/gantt/task-bar.md

@@ -176,6 +176,12 @@ ${prefix} selectable(boolean)
 
 非必填
 
+${prefix} locateIcon(boolean) = false
+
+当任务条在横向上不在当前可视区域内时，在甘特图左右边缘展示“定位图标”；鼠标 hover 会高亮，点击后会一键滚动到任务条可视区域内。
+
+非必填
+
 ${prefix} scheduleCreatable(boolean | Function) = true
 
 数据没有排期时，可通过创建任务条排期。当 tasksShowMode 为 TasksShowMode.Tasks_Separate 或 TasksShowMode.Sub_Tasks_Separate 时 `scheduleCreatable` 默认为 true，其他情况即当 tasksShowMode 为 TasksShowMode.Sub_Tasks_Inline 或 TasksShowMode.Sub_Tasks_Arrange 或 TasksShowMode.Sub_Tasks_Compact 时 `scheduleCreatable` 默认为 false
@@ -273,4 +279,3 @@ ${prefix} baselinePosition('top' | 'bottom' | 'overlap') = 'bottom'
 - `overlap`：基线与主任务条重叠居中。
 
 非必填
-

packages/vtable-gantt/examples/gantt/gantt-locate-taskbar.ts

@@ -0,0 +1,67 @@
+import type { ColumnsDefine } from '@visactor/vtable';
+import type { GanttConstructorOptions } from '../../src/index';
+import { Gantt } from '../../src/index';
+
+const CONTAINER_ID = 'vTable';
+
+export function createTable() {
+  const records = [
+    { id: 1, title: '任务条在左侧不可见', start: '2024-02-05', end: '2024-02-20', progress: 20 },
+    { id: 2, title: '任务条在左侧不可见', start: '2024-03-10', end: '2024-03-18', progress: 60 },
+    { id: 5, title: '任务条在可见区', start: '2024-05-28', end: '2024-06-05', progress: 50 },
+    { id: 3, title: '任务条在右侧不可见', start: '2024-10-05', end: '2024-10-20', progress: 40 },
+    { id: 4, title: '任务条在右侧不可见', start: '2024-11-10', end: '2024-11-25', progress: 80 }
+  ];
+
+  const columns: ColumnsDefine = [
+    { field: 'title', title: 'title', width: 160, sort: true },
+    { field: 'start', title: 'start', width: 120, sort: true },
+    { field: 'end', title: 'end', width: 120, sort: true },
+    { field: 'progress', title: 'progress', width: 100, sort: true }
+  ];
+
+  const option: GanttConstructorOptions = {
+    records,
+    taskListTable: {
+      columns,
+      tableWidth: 280,
+      minTableWidth: 240,
+      maxTableWidth: 600
+    },
+    taskKeyField: 'id',
+    taskBar: {
+      startDateField: 'start',
+      endDateField: 'end',
+      progressField: 'progress',
+      locateIcon: true
+    },
+    minDate: '2024-01-01',
+    maxDate: '2024-12-31',
+    timelineHeader: {
+      colWidth: 30,
+      scales: [{ unit: 'day', step: 1 }]
+    },
+    scrollStyle: {
+      visible: 'scrolling'
+    },
+    grid: {
+      // backgroundColor: 'gray',
+      verticalLine: {
+        lineWidth: 1,
+        lineColor: '#e1e4e8'
+      },
+      horizontalLine: {
+        lineWidth: 1,
+        lineColor: '#e1e4e8'
+      }
+    }
+  };
+
+  const ganttInstance = new Gantt(document.getElementById(CONTAINER_ID)!, option);
+  (window as any).ganttInstance = ganttInstance;
+
+  setTimeout(() => {
+    const x = ganttInstance.getXByTime(new Date('2024-06-01 00:00:00').getTime());
+    ganttInstance.scrollLeft = x;
+  }, 0);
+}

packages/vtable-gantt/examples/menu.ts

@@ -170,6 +170,10 @@ export const menus = [
   {
     path: 'gantt',
     name: 'project-sub-tasks-inline'
+  },
+  {
+    path: 'gantt',
+    name: 'gantt-locate-taskbar'
   }
   //   ]
   // }

packages/vtable-gantt/src/Gantt.ts

@@ -165,6 +165,7 @@ export class Gantt extends EventTarget {
     tasksShowMode: TasksShowMode;
     projectSubTasksExpandable: boolean;
     taskBarClip: boolean;
+    taskBarLocateIcon: boolean;
 
     startDateField: string;
     endDateField: string;