mirror of
https://github.com/VisActor/VTable
synced 2024-11-22 01:52:03 +00:00
docs: add vtable-calendar guide
This commit is contained in:
Rui-Sun
parent
ec6f91d0cd
commit
cebfd9d08b
73
docs/assets/guide/en/calendar/Getting_Started.md
Normal file
73
docs/assets/guide/en/calendar/Getting_Started.md
Normal file
@ -0,0 +1,73 @@
|
||||
# Quick Start
|
||||
|
||||
In this tutorial, we will introduce how to use @visactor/vtable-calendar to draw a simple calendar.
|
||||
|
||||
## Get @visactor/vtable-calendar
|
||||
|
||||
You can get it in the following ways
|
||||
|
||||
### Use NPM package
|
||||
|
||||
First, you need to install it using the following command in the project root directory:
|
||||
|
||||
```sh
|
||||
|
||||
# Install using npm
|
||||
npm install @visactor/vtable-calendar
|
||||
|
||||
# Install using yarn
|
||||
yarn add @visactor/vtable-calendar
|
||||
```
|
||||
|
||||
### Use CDN
|
||||
|
||||
You can also get the built vtable-calendar file through CDN.
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@visactor/vtable-calendar/dist/vtable-calendar.min.js"></script>
|
||||
<script>
|
||||
const calendarInstance = new VTable.Calendar.VTableCalendar(domContainer, option);
|
||||
</script>
|
||||
|
||||
## Import VTableCalendar
|
||||
|
||||
### Import via NPM package
|
||||
|
||||
Use `import` at the top of the JavaScript file to import vtable-calendar:
|
||||
|
||||
```js
|
||||
import {VTableCalendar} from '@visactor/vtable-calendar';
|
||||
|
||||
const calendarInstance = new VTableCalendar(domContainer, option);
|
||||
```
|
||||
|
||||
### Import using script tag
|
||||
|
||||
Introduce the built vtable-calendar file by adding `<script>` tag directly in the HTML file:
|
||||
|
||||
```html
|
||||
<script> src="https://unpkg.com/@visactor/vtable-calendar/dist/vtable-calendar.min.js"></script>
|
||||
<script>
|
||||
const calendarInstance = new VTable.Calendar.VTableCalendar(domContainer, option);
|
||||
</script>
|
||||
```
|
||||
|
||||
## Draw a simple calendar
|
||||
|
||||
Before drawing, we need to prepare a DOM container with height and width for VTableCalendar, and this container can be relatively positioned, that is, position needs to be set to 'absolute' or 'relative'.
|
||||
|
||||
**Please make sure that the width and height of the container are integers. The offsetWidth, offsetHeight, clientWidth, and clientHeight properties of the container will be used in the internal logic of VTable. If the width and height of the container are decimals, it will cause errors in the value, which may cause table jitter problems. **
|
||||
```html
|
||||
<body>
|
||||
<div id="tableContainer" style="position: absolute; width: 600px;height:400px;"></div>
|
||||
</body>
|
||||
```
|
||||
|
||||
Next, we create a `Calendar` instance and pass in the calendar configuration items:
|
||||
|
||||
```javascript livedemo template=vtable
|
||||
const calendarInstance = new VTableCalendar(document.getElementById(CONTAINER_ID));
|
||||
window['calendarInstance'] = calendarInstance;
|
||||
```
|
||||
|
||||
So far, you have successfully drawn a simple calendar!
|
||||
147
docs/assets/guide/en/calendar/introduction.md
Normal file
147
docs/assets/guide/en/calendar/introduction.md
Normal file
@ -0,0 +1,147 @@
|
||||
# Calendar
|
||||
|
||||
A calendar is a common table used to display dates and corresponding schedules. VTable-Calendar is a calendar component developed based on the VTable component. Users can quickly implement a calendar tool or customize related business functions based on the powerful capabilities of VTable. Compared with traditional calendars, VTable-Calendar has the following advantages:
|
||||
|
||||
- Stepless scrolling function, supports scrolling across months and years
|
||||
|
||||
- Users familiar with VTable api can quickly get started with custom functions
|
||||
|
||||
## Basic configuration of calendar
|
||||
|
||||
When creating a calendar, you can pass in the configuration corresponding to the calendar day:
|
||||
|
||||
```js
|
||||
import { VTableCalendar } from '@visactor/vtable-calendar';
|
||||
|
||||
const calendar = new VTableCalendar(domContainer, options);
|
||||
```
|
||||
|
||||
Among them, option supports the following attributes
|
||||
|
||||
| Attribute | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| startDate | Date | Calendar start date |
|
||||
| endDate | Date | Calendar end date |
|
||||
| currentDate | Date | Calendar day displayed |
|
||||
| rangeDays | number | The range of days displayed in the calendar (if startDate&endDate is not configured, the dates of rangeDays before and after currentDate will be taken as startDate&endDate, the default is 90 days) |
|
||||
| dayTitles | string[] | Calendar title (can be replaced with different languages) |
|
||||
| customEventOptions | ICustomEventOptions | Custom schedule configuration |
|
||||
| customEvents | ICustomEvent[] | Array of custom schedules |
|
||||
| tableOptions | ListTableConstructorOptions | Calendar table configuration (the configuration here will be passed to the corresponding VTable instance for deep customization) |
|
||||
|
||||
The properties configured in `tableOptions` can be referred to [VTable configuration](../../option/ListTable) for further configuration of the table. For example, if you want Saturday to be displayed in blue and Sunday in red in the calendar title, you can use the following configuration:
|
||||
|
||||
```javascript livedemo template=vtable
|
||||
const calendarInstance = new VTableCalendar(document.getElementById(CONTAINER_ID), {
|
||||
tableOptions: {
|
||||
theme: {
|
||||
headerStyle: {
|
||||
color: args => {
|
||||
if (args.col === 0) {
|
||||
return 'red';
|
||||
} else if (args.col === 6) {
|
||||
return 'blue';
|
||||
}
|
||||
return '#000';
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
});
|
||||
window['calendarInstance'] = calendarInstance;
|
||||
```
|
||||
|
||||
## Customized calendar
|
||||
|
||||
VTableCalendar supports two ways to customize the calendar, one for a single day and one for a multi-day schedule. The configuration of custom schedule is as follows:
|
||||
|
||||
```ts
|
||||
export interface ICustomEvent {
|
||||
type: 'list' | 'bar'; // Schedule type, list is a schedule within a single day, bar is a schedule across multiple days
|
||||
id: string; // Schedule id, used to distinguish different schedules
|
||||
|
||||
startDate?: Date; // Schedule start date (for schedules across multiple days)
|
||||
endDate?: Date; // Schedule end date (for schedules across multiple days)
|
||||
date?: Date; // Schedule date (for schedules within a single day)
|
||||
|
||||
text: string;
|
||||
color?: string; // text color
|
||||
bgColor?: string; // bar background color
|
||||
|
||||
customInfo?: any; // user custom data
|
||||
}
|
||||
```
|
||||
|
||||
Custom schedules can be configured during initialization, or dynamically added, deleted, and updated through the API.
|
||||
|
||||
Initialization configuration:
|
||||
```ts
|
||||
const calendar = new VTableCalendar(document.getElementById(CONTAINER_ID), {
|
||||
customEvents: [
|
||||
{
|
||||
date: new Date(2024, 9, 23),
|
||||
text: 'Event A',
|
||||
id: 'Event A',
|
||||
type: 'list',
|
||||
color: '#f99'
|
||||
},
|
||||
{
|
||||
id: 'Event B',
|
||||
startDate: new Date(2024, 9, 21),
|
||||
endDate: new Date(2024, 9, 23),
|
||||
text: 'Event B',
|
||||
type: 'bar',
|
||||
bgColor: '#f99',
|
||||
color: '#fff'
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
Dynamic addition, deletion, update:
|
||||
```ts
|
||||
// Add
|
||||
calendar.addCustomEvent({
|
||||
id: 'Event C',
|
||||
startDate: new Date(2024, 9, 22),
|
||||
endDate: new Date(2024, 10, 4),
|
||||
text: 'Event C',
|
||||
type: 'bar',
|
||||
bgColor: '#9f9',
|
||||
color: '#fff'
|
||||
});
|
||||
|
||||
// Delete
|
||||
calendar.removeCustomEvent('Event C');
|
||||
|
||||
// Update
|
||||
calendar.updateCustomEvent({
|
||||
id: 'Event C', // Update by id
|
||||
startDate: new Date(2024, 9, 22),
|
||||
endDate: new Date(2024, 9, 30),
|
||||
});
|
||||
```
|
||||
|
||||
Customized schedule APIs
|
||||
| Methods | Parameters | Description |
|
||||
| --- | --- | --- |
|
||||
| addCustomEvent | ICustomEvent | Add a custom schedule |
|
||||
| addCustomEvents | ICustomEvent[] | Add custom schedules in batches |
|
||||
| removeCustomEvent | string | Delete custom schedules |
|
||||
| removeCustomEvents | string[] | Delete custom schedules in batches |
|
||||
| updateCustomEvent | ICustomEvent | Update custom schedules |
|
||||
| updateCustomEvents | ICustomEvent[] | Update custom schedules in batches |
|
||||
|
||||
## Calendar events
|
||||
|
||||
VTableCalendar supports the following events:
|
||||
|
||||
| Event name | Description |
|
||||
| --- | --- |
|
||||
| calendar_date_click | Triggered when clicking on a calendar date |
|
||||
| selected_date | Triggered when a date is selected |
|
||||
| selected_date_clear | Triggered when a date is unselected |
|
||||
| drag_select_date_end | Triggered when dragging to select a date ends |
|
||||
| calendar_custom_event_click | Triggered when clicking on a custom schedule |
|
||||
|
||||
If further event processing is required, all events of VTable can be monitored through `calendarInstance.table.on()`.
|
||||
@ -179,6 +179,29 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"path": "calendar",
|
||||
"title": {
|
||||
"zh": "日历图",
|
||||
"en": "calendar"
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"path": "Getting_Started",
|
||||
"title": {
|
||||
"zh": "快速上手",
|
||||
"en": "Getting Started"
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": "introduction",
|
||||
"title": {
|
||||
"zh": "日历图介绍",
|
||||
"en": "calendar introduction"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"path": "cell_type",
|
||||
"title": {
|
||||
|
||||
73
docs/assets/guide/zh/calendar/Getting_Started.md
Normal file
73
docs/assets/guide/zh/calendar/Getting_Started.md
Normal file
@ -0,0 +1,73 @@
|
||||
# 快速上手
|
||||
|
||||
在本教程中，我们将介绍如何使用 @visactor/vtable-calendar 绘制一个简单的日历。
|
||||
|
||||
## 获取 @visactor/vtable-calendar
|
||||
|
||||
你可以通过以下几种方式获取
|
||||
|
||||
### 使用 NPM 包
|
||||
|
||||
首先，你需要在项目根目录下使用以下命令安装：
|
||||
|
||||
```sh
|
||||
|
||||
# 使用 npm 安装
|
||||
npm install @visactor/vtable-calendar
|
||||
|
||||
# 使用 yarn 安装
|
||||
yarn add @visactor/vtable-calendar
|
||||
```
|
||||
|
||||
### 使用 CDN
|
||||
|
||||
你还可以通过 CDN 获取构建好的 vtable-calendar 文件。
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@visactor/vtable-calendar/dist/vtable-calendar.min.js"></script>
|
||||
<script>
|
||||
const calendarInstance = new VTable.Calendar.VTableCalendar(domContainer, option);
|
||||
</script>
|
||||
|
||||
## 引入 VTableCalendar
|
||||
|
||||
### 通过 NPM 包引入
|
||||
|
||||
在 JavaScript 文件顶部使用 `import` 引入 vtable-calendar：
|
||||
|
||||
```js
|
||||
import {VTableCalendar} from '@visactor/vtable-calendar';
|
||||
|
||||
const calendarInstance = new VTableCalendar(domContainer, option);
|
||||
```
|
||||
|
||||
### 使用 script 标签引入
|
||||
|
||||
通过直接在 HTML 文件中添加 `<script>` 标签，引入构建好的 vtable-calendar 文件：
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@visactor/vtable-calendar/dist/vtable-calendar.min.js"></script>
|
||||
<script>
|
||||
const calendarInstance = new VTable.Calendar.VTableCalendar(domContainer, option);
|
||||
</script>
|
||||
```
|
||||
|
||||
## 绘制一个简单的日历图
|
||||
|
||||
在绘图前我们需要为 VTableCalendar 准备一个具备高宽的 DOM 容器，且这个容器可以相对定位，即需要设置position为 'absolute' 或者 'relative'。
|
||||
|
||||
**请务必保证容器的宽高值为整数，VTable 内部逻辑中会用到容器的 offsetWidth、offsetHeight、clientWidth、clientHeight 属性，如果容器的 width 和 height 为小数会造成取值有误差，可能产生表格抖动问题。**
|
||||
```html
|
||||
<body>
|
||||
<div id="tableContainer" style="position: absolute; width: 600px;height:400px;"></div>
|
||||
</body>
|
||||
```
|
||||
|
||||
接下来，我们创建一个 `Calendar` 实例，传入日历图配置项：
|
||||
|
||||
```javascript livedemo template=vtable
|
||||
const calendarInstance = new VTableCalendar(document.getElementById(CONTAINER_ID));
|
||||
window['calendarInstance'] = calendarInstance;
|
||||
```
|
||||
|
||||
至此，你已经成功绘制出了一个简单的日历图！
|
||||
146
docs/assets/guide/zh/calendar/introduction.md
Normal file
146
docs/assets/guide/zh/calendar/introduction.md
Normal file
@ -0,0 +1,146 @@
|
||||
# 日历图
|
||||
|
||||
日历图是一种常见的表格，用于展示日期和相应的日程安排。VTable-Calendar 是一款基于 VTable 表格组件开发的日历图组件，用户可以快速实现一个日历工具，也可以基于VTable的强大能力自定义相关的业务功能。相比于传统日历图，VTable-Calendar 具有以下优势：
|
||||
|
||||
- 无级滚动功能，支持跨月、跨年滚动
|
||||
- 熟悉VTable api的用户可以快速上手定制功能
|
||||
|
||||
## 日历图的基础配置
|
||||
|
||||
在创建日历图时，可以传入日历日对应的配置：
|
||||
|
||||
```js
|
||||
import { VTableCalendar } from '@visactor/vtable-calendar';
|
||||
|
||||
const calendar = new VTableCalendar(domContainer, options);
|
||||
```
|
||||
|
||||
其中，option支持下列属性
|
||||
|
||||
| 属性 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| startDate | Date | 日历开始的日期 |
|
||||
| endDate | Date | 日历结束的日期 |
|
||||
| currentDate | Date | 日历当天显示的日期 |
|
||||
| rangeDays | number | 日历显示的天数范围（如果没有配置startDate&endDate，会从currentDate取前后rangeDays的日期作为startDate&endDate，默认90天） |
|
||||
| dayTitles | string[] | 日历的标题（可以替换为不同语言） |
|
||||
| customEventOptions | ICustomEventOptions | 自定义日程的配置 |
|
||||
| customEvents | ICustomEvent[] | 自定义日程的数组 |
|
||||
| tableOptions | ListTableConstructorOptions | 日历表格的配置（这里的配置会被传给对应的VTable实例，用于深度自定义） |
|
||||
|
||||
`tableOptions` 配置的属性可以参考 [VTable的配置](../../option/ListTable)，用于表格的进一步配置。例如，如果希望日历图标题中周六显示为蓝色，周日显示为红色，可以使用以下配置：
|
||||
|
||||
```javascript livedemo template=vtable
|
||||
const calendarInstance = new VTableCalendar(document.getElementById(CONTAINER_ID), {
|
||||
tableOptions: {
|
||||
theme: {
|
||||
headerStyle: {
|
||||
color: args => {
|
||||
if (args.col === 0) {
|
||||
return 'red';
|
||||
} else if (args.col === 6) {
|
||||
return 'blue';
|
||||
}
|
||||
return '#000';
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
});
|
||||
window['calendarInstance'] = calendarInstance;
|
||||
```
|
||||
|
||||
## 日历图的自定义日程
|
||||
|
||||
VTableCalendar支持两种自定义日程的方式，一种为单日内的日程，一种为跨多天的日程。自定义日程的配置如下：
|
||||
|
||||
```ts
|
||||
export interface ICustomEvent {
|
||||
type: 'list' | 'bar'; // 日程类型，list为单日内的日程，bar为跨多天的日程
|
||||
id: string; // 日程的id，用于区分不同的日程
|
||||
|
||||
startDate?: Date; // 日程的开始日期（用于跨多天的日程）
|
||||
endDate?: Date; // 日程的结束日期（用于跨多天的日程）
|
||||
date?: Date; // 日程的日期（用于单日内的日程）
|
||||
|
||||
text: string;
|
||||
color?: string; // text color
|
||||
bgColor?: string; // bar background color
|
||||
|
||||
customInfo?: any; // user custom data
|
||||
}
|
||||
```
|
||||
|
||||
自定义日程可以在初始化时配置，也可以通过API进行动态添加、删除、更新。
|
||||
|
||||
初始化时配置：
|
||||
```ts
|
||||
const calendar = new VTableCalendar(document.getElementById(CONTAINER_ID), {
|
||||
customEvents: [
|
||||
{
|
||||
date: new Date(2024, 9, 23),
|
||||
text: 'Event A',
|
||||
id: 'Event A',
|
||||
type: 'list',
|
||||
color: '#f99'
|
||||
},
|
||||
{
|
||||
id: 'Event B',
|
||||
startDate: new Date(2024, 9, 21),
|
||||
endDate: new Date(2024, 9, 23),
|
||||
text: 'Event B',
|
||||
type: 'bar',
|
||||
bgColor: '#f99',
|
||||
color: '#fff'
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
动态添加、删除、更新：
|
||||
```ts
|
||||
// 添加
|
||||
calendar.addCustomEvent({
|
||||
id: 'Event C',
|
||||
startDate: new Date(2024, 9, 22),
|
||||
endDate: new Date(2024, 10, 4),
|
||||
text: 'Event C',
|
||||
type: 'bar',
|
||||
bgColor: '#9f9',
|
||||
color: '#fff'
|
||||
});
|
||||
|
||||
// 删除
|
||||
calendar.removeCustomEvent('Event C');
|
||||
|
||||
// 更新
|
||||
calendar.updateCustomEvent({
|
||||
id: 'Event C', // 通过id更新
|
||||
startDate: new Date(2024, 9, 22),
|
||||
endDate: new Date(2024, 9, 30),
|
||||
});
|
||||
```
|
||||
|
||||
自定义日程相关API
|
||||
| 方法 | 参数 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| addCustomEvent | ICustomEvent | 添加自定义日程 |
|
||||
| addCustomEvents | ICustomEvent[] | 批量添加自定义日程 |
|
||||
| removeCustomEvent | string | 删除自定义日程 |
|
||||
| removeCustomEvents | string[] | 批量删除自定义日程 |
|
||||
| updateCustomEvent | ICustomEvent | 更新自定义日程 |
|
||||
| updateCustomEvents | ICustomEvent[] | 批量更新自定义日程 |
|
||||
|
||||
## 日历图的事件
|
||||
|
||||
VTableCalendar支持以下事件：
|
||||
|
||||
| 事件名 | 说明 |
|
||||
| --- | --- |
|
||||
| calendar_date_click | 点击日历日时触发 |
|
||||
| selected_date | 选中日期时触发 |
|
||||
| selected_date_clear | 取消选中日期时触发 |
|
||||
| drag_select_date_end | 拖拽选择日期结束时触发 |
|
||||
| calendar_custom_event_click | 点击自定义日程时触发 |
|
||||
|
||||
如果需要进一步的事件处理，可以通过`calendarInstance.table.on()`监听VTable的所有事件。
|
||||
@ -4,6 +4,7 @@ import Inula from 'openinula';
|
||||
import * as VTable from '@visactor/vtable';
|
||||
import * as VRender from '@visactor/vtable/es/vrender';
|
||||
import * as VTableGantt from '@visactor/vtable-gantt';
|
||||
import { VTableCalendar } from '@visactor/vtable-calendar';
|
||||
import * as VChart from '@visactor/vchart';
|
||||
import * as VTableEditors from '@visactor/vtable-editors';
|
||||
import { downloadCsv, exportVTableToCsv, downloadExcel, exportVTableToExcel } from '@visactor/vtable-export';
|
||||
@ -25,6 +26,7 @@ import { createApp, ref, onMounted, h } from 'vue';
|
||||
(window as any).VTable = VTable;
|
||||
(window as any).VRender = VRender;
|
||||
(window as any).VTableGantt = VTableGantt;
|
||||
(window as any).VTableCalendar = VTableCalendar;
|
||||
(window as any).VTable_editors = VTableEditors;
|
||||
(window as any).VChart = VChart.VChart;
|
||||
|
||||
|
||||
@ -20,6 +20,7 @@ export default {
|
||||
'@visactor/vtable/es/vrender': path.resolve('../packages/vtable/src/vrender.ts'),
|
||||
'@visactor/vtable': path.resolve('../packages/vtable/src/index.ts'),
|
||||
'@visactor/vtable-gantt': path.resolve('../packages/vtable-gantt/src/index.ts'),
|
||||
'@visactor/vtable-calendar': path.resolve('../packages/vtable-calendar/src/index.ts'),
|
||||
'@visactor/vtable-editors': path.resolve('../packages/vtable-editors/src/index.ts'),
|
||||
'@visactor/vtable-export': path.resolve('../packages/vtable-export/src/index.ts'),
|
||||
'@visactor/vtable-search': path.resolve('../packages/vtable-search/src/index.ts'),
|
||||
|
||||
Loading…
Reference in New Issue
Block a user