diff --git a/docs/assets/guide/en/Developer_Ecology/openinula.md b/docs/assets/guide/en/Developer_Ecology/openinula.md new file mode 100644 index 000000000..1ba36cbec --- /dev/null +++ b/docs/assets/guide/en/Developer_Ecology/openinula.md @@ -0,0 +1,279 @@ +# Openinula-VTable + +The `@visactor/openinula-vtable` package is a Openinula encapsulation to make it easier to use VTable in the Openinula environment. This component mainly encapsulates the VTable table in Openinula component form, and the related configuration items are consistent with the VTable. + +## Quick start + +### Environmental requirements + +Make sure **node**, **npm** and **Openinula** are installed in your environment and meet the following version requirements: + +- node 10.12.0+ +- npm 6.4.0+ +- openinula 0.1.2-SNAPSHOT+ + +### Install + +#### Install using the package manager + +```shell +# use npm +npm install @visactor/openinula-vtable + +# use yarn +yarn add @visactor/openinula-vtable +``` + +### Introducing Openinula-VTable + +It is recommended to use npm package to import + +```js +import { ListTable } from "@visactor/openinula-vtable"; +``` + +## Draw a simple list + +You can use the `ListTable` component imported via `@visactor/openinula-vtable` just like a standard Openinula component. + +Here is a simple list example code: + +```typescript +import Openinula from 'openinula'; +import OpeninulaDOM from 'openinula-dom/client'; +import { ListTable } from "@visactor/openinula-vtable"; + +const option = { + columns: [ + { + field: "0", + caption: "name", + }, + { + field: "1", + caption: "age", + }, + { + field: "2", + caption: "gender", + }, + { + field: "3", + caption: "hobby", + }, + ], + records: new Array(1000).fill(["John", 18, "male", "🏀"]), +}; + +Inula.render( + , + document.getElementById('root') +); +``` + +Refer to [demo](../../demo-openinula/usage/option) + +## Usage + +Openinula-VTable provides two styles of components for developers to use, namely unified tags and syntactic tags. + +### Unified tags + +Unified tags refer to using a Table tag to receive a complete `option` configuration. If VTable is already used in the project, this method can quickly use Openinula-VTable. The above example is a [demo](../../demo-openinula/usage/grammatical-tag) using unified tags. + +Same as VTable Openinula-VTable provides three table types: + +- ListTable: List table, used to display list data [demo](../../demo-openinula/usage/grammatical-tag) +- PivotTable: Pivot table, used to display cross-pivot data [demo](../../demo-openinula/grammatical-tag/pivot-table) +- PivotChart: Pivot chart, used to display cross-pivot data and display it in a chart [demo](../../demo-openinula/grammatical-tag/pivot-chart) + +The props of these three Openinula components are defined as follows: + +```ts +interface VTableProps extends EventsProps { + option: ITableOption; + records?: any; + width?: number; + height?: number; + onReady?: (instance: VTable, isInitial: boolean) => void; +} +``` + +For the definition of EventsProps, refer to the event binding chapter. + +onReady is a built-in callback event that will be triggered when the table is rendered or updated. Its input parameters respectively represent the table instance object and whether it is rendered for the first time. + +The Openinula-VTable unified label is almost the equivalent function of VTable, which can facilitate developers to migrate Openinula versions, and options obtained from the community or sample center can be used directly in this way, with almost no additional learning cost for developers. + +### Grammatical tags + +Grammatical tags mean that Openinula-VTable encapsulates some components in the table as Openinula components and exports them to developers. Developers can define tables in a way that is more semantic and closer to native Openinula declarations. It should be noted that the definition content of grammatical tags can be converted into each other with the table description `option` in most scenarios. + +It should be noted that although the chart is declared in the form of a Openinula component by definition, it is not parsed into a DOM for rendering in the actual implementation. Therefore, if you use the inspection element, you cannot see the DOM corresponding to each chart component. + +#### ListTable + +The props attributes accepted by ListTable are consistent with options. The subcomponents in ListTable are as follows + +- ListColumn: List column, consistent with the definition of columns in option [api](../../option/ListTable-columns-text#cellType) + +```jsx +import { ListTable, ListColumn } from '../../../src'; +function App() { + // ...... + return ( + + + + + + + ); +} +``` + +Grammatical tag demo: [demo](../../demo-openinula/usage/grammatical-tag) + +#### PivotTable&PivotChart + +The props attributes accepted by PivotTable&PivotChart are the same as options. The sub-components are as follows: + +- PivotColumnDimension: The dimension configuration on the column is consistent with the definition of columns in option [api](../../option/PivotTable-columns-text#headerType) +- PivotRowDimension: The dimension configuration on the row is consistent with the definition of rows in option [api](../../option/PivotTable-rows-text#headerType) +- PivotIndicator: indicator configuration, consistent with the definition of indicators in option [api](../../option/PivotTable-indicators-text#cellType) +- PivotColumnHeaderTitle: column header title configuration, consistent with the definition of columnHeaderTitle in option [api](../../option/PivotTable#rowHeaderTitle) +- PivotRowHeaderTitle: row header title configuration, consistent with the definition of rowHeaderTitle in option [api](../../option/PivotTable#columnHeaderTitle) +- PivotCorner: Corner configuration, consistent with the definition of corner in option [api](../../option/PivotTable#corner) + +```jsx + return ( + + + + + + + + + + + ); + +``` +Grammatical label demo: [PivotTable demo](../../demo-openinula/grammatical-tag/pivot-table) [PivotChart demo](../../demo-openinula/grammatical-tag/pivot-chart) + +#### Components outside the table + +External components currently support: + +- Menu: drop-down menu component, consistent with the definition of menu in option [api](../../option/ListTable#menu) +- Tooltip: tooltip component, consistent with the definition of tooltip in option [api](../../option/ListTable#tooltip) + +```jsx + + // ...... + + + +``` + +### Event binding + +The Props of the outermost table component of the unified label or the syntactic table label inherit the event processing callback EventsProps of the table. + +EventsProps are defined as follows: +```ts +interface EventsProps { + onClickCell?: EventCallback; + onDblClickCell?: EventCallback; + onMouseDownCell?: EventCallback; + onMouseUpCell?: EventCallback; + onSelectedCell?: EventCallback; + onKeyDown?: EventCallback; + onMouseEnterTable?: EventCallback; + onMouseLeaveTable?: EventCallback; + onMouseMoveCell?: EventCallback; + onMouseEnterCell?: EventCallback; + onMouseLeaveCell?: EventCallback; + onContextMenuCell?: EventCallback; + onResizeColumn?: EventCallback; + onResizeColumnEnd?: EventCallback; + onChangeHeaderPosition?: EventCallback; + onSortClick?: EventCallback; + onFreezeClick?: EventCallback; + onScroll?: EventCallback; + onDropdownMenuClick?: EventCallback; + onMouseOverChartSymbol?: EventCallback; + onDragSelectEnd?: EventCallback; + + onDropdownIconClick?: EventCallback; + onDropdownMenuClear?: EventCallback; + + onTreeHierarchyStateChange?: EventCallback; + + onShowMenu?: EventCallback; + onHideMenu?: EventCallback; + + onIconClick?: EventCallback; + + onLegendItemClick?: EventCallback; + onLegendItemHover?: EventCallback; + onLegendItemUnHover?: EventCallback; + onLegendChange?: EventCallback; + + onMouseEnterAxis?: EventCallback; + onMouseLeaveAxis?: EventCallback; + + onCheckboxStateChange?: EventCallback; + onAfterRender?: EventCallback; + onInitialized?: EventCallback; + + // pivot table only + onPivotSortClick?: EventCallback; + onDrillMenuClick?: EventCallback; + + // pivot chart only + onVChartEventType?: EventCallback; +} +``` + +Event usage example: +```jsx +function App() { + const option = { + // ...... + }; + return ( + { + console.log('onClickCell', ...arg); + }} + /> + ); +} +``` + +For detailed description of the event, please refer to: [Event Introduction](../../guide/Event/event_list) diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json index 487c44ceb..78efdc627 100644 --- a/docs/assets/guide/menu.json +++ b/docs/assets/guide/menu.json @@ -528,6 +528,13 @@ "en": "React-VTable" } }, + { + "path": "openinula", + "title": { + "zh": "Openinula-VTable", + "en": "Openinula-VTable" + } + }, { "path": "vue", "title": { diff --git a/docs/assets/guide/zh/Developer_Ecology/openinula.md b/docs/assets/guide/zh/Developer_Ecology/openinula.md new file mode 100644 index 000000000..43242c4e6 --- /dev/null +++ b/docs/assets/guide/zh/Developer_Ecology/openinula.md @@ -0,0 +1,279 @@ +# Openinula-VTable + +`@visactor/openinula-vtable`包是为了方便在 Openinula 环境更加方便使用 VTable 所进行的 Openinula 封装。该组件主要对 VTable 表格做 Openinula 组件化的封装，相关的配置项均与 VTable 一致。 + +## 快速开始 + +### 环境要求 + +确保你的环境中安装了**node**，**npm**以及**Openinula**，并且满足以下版本要求： + +- node 10.12.0+ +- npm 6.4.0+ +- openinula 0.1.2-SNAPSHOT+ + +### 安装 + +#### 使用包管理器安装 + +```shell +# 使用 npm 安装 +npm install @visactor/openinula-vtable + +# 使用 yarn 安装 +yarn add @visactor/openinula-vtable +``` + +### 引入 Openinula-VTable + +推荐使用 npm 包引入 + +```js +import { ListTable } from "@visactor/openinula-vtable"; +``` + +## 绘制一个简单的列表 + +你可以像使用标准的 Openinula 组件一样，使用通过`@visactor/openinula-vtable`导入的`ListTable`组件。 + +以下是一个简单列表示例代码： + +```typescript +import Openinula from 'openinula'; +import OpeninulaDOM from 'openinula-dom/client'; +import { ListTable } from "@visactor/openinula-vtable"; + +const option = { + columns: [ + { + field: "0", + caption: "name", + }, + { + field: "1", + caption: "age", + }, + { + field: "2", + caption: "gender", + }, + { + field: "3", + caption: "hobby", + }, + ], + records: new Array(1000).fill(["John", 18, "male", "🏀"]), +}; + +Inula.render( + , + document.getElementById('root') +); +``` + +参考[demo](../../demo-openinula/usage/option) + +## 使用方式 + +Openinula-VTable提供两种风格的组件供开发者使用，分别是统一标签与语法化标签。 + +### 统一标签 + +统一标签是指是使用一个 Table 标签，接收一个完整的`option`配置，如果项目中已经使用了 VTable ，这种方式可以快速使用Openinula-VTable。上面的例子就是一个使用统一标签的[demo](../../demo-openinula/usage/grammatical-tag)。 + +与VTable相同Openinula-VTable提供三种表格类型： + +- ListTable: 列表表格，用于展示列表数据 [demo](../../demo-openinula/usage/grammatical-tag) +- PivotTable: 透视表格，用于展示交叉透视数据 [demo](../../demo-openinula/grammatical-tag/pivot-table) +- PivotChart: 透视图，用于展示交叉透视数据并以图表方式展示 [demo](../../demo-openinula/grammatical-tag/pivot-chart) + +这三种Openinula组件，其props定义如下： + +```ts +interface VTableProps extends EventsProps { + option: ITableOption; + records?: any; + width?: number; + height?: number; + onReady?: (instance: VTable, isInitial: boolean) => void; +} +``` + +EventsProps的定义参考事件绑定章节 + +onReady是一个内置的回调事件，会在表格渲染或更新时触发，其入参分别代表表格实例对象，以及是否初次渲染。 + +Openinula-VTable统一标签几乎是VTable的对等功能，可以方便开发者进行Openinula版本的迁移，并且从社区或示例中心获得的option可以直接通过这种方式使用，开发者几乎没有额外的学习成本。 + +### 语法化标签 + +语法化标签是指Openinula-VTable将表格中的部分组件封装为Openinula组件导出给开发者，开发者可以通过更加语义化、更接近原生Openinula声明的方式来定义表格。需要说明的是语法化标签的定义内容，在多数场景下都是可以和表格描述`option`进行相互转化的。 + +需要注意的是：虽然图表在定义上是通过Openinula组件的形式进行声明的，但实际实现中并不是将其解析为DOM进行渲染，因此假如使用审查元素时并不能看到各个图表组件对应的DOM。 + +#### ListTable + +ListTable接受的props属性与option一致，ListTable中的子组件如下 + +- ListColumn: 列表列，同option中的columns的定义一致 [api](../../option/ListTable-columns-text#cellType) + +```jsx +import { ListTable, ListColumn } from '../../../src'; +function App() { + // ...... + return ( + + + + + + + ); +} +``` + +语法化标签demo：[demo](../../demo-openinula/usage/grammatical-tag) + +#### PivotTable&PivotChart + +PivotTable&PivotChart接受的props属性与option一致，子组件如下： + +- PivotColumnDimension: 列上的维度配置，同option中的columns的定义一致 [api](../../option/PivotTable-columns-text#headerType) +- PivotRowDimension: 行上的维度配置，同option中的rows的定义一致 [api](../../option/PivotTable-rows-text#headerType) +- PivotIndicator: 指标配置，同option中的indicators的定义一致 [api](../../option/PivotTable-indicators-text#cellType) +- PivotColumnHeaderTitle: 列表头标题配置，同option中的columnHeaderTitle的定义一致 [api](../../option/PivotTable#rowHeaderTitle) +- PivotRowHeaderTitle: 行头标题配置，同option中的rowHeaderTitle的定义一致 [api](../../option/PivotTable#columnHeaderTitle) +- PivotCorner: 角头配置，同option中的corner的定义一致 [api](../../option/PivotTable#corner) + +```jsx + return ( + + + + + + + + + + + ); + +``` +语法化标签demo：[PivotTable demo](../../demo-openinula/grammatical-tag/pivot-table) [PivotChart demo](../../demo-openinula/grammatical-tag/pivot-chart) + +#### 表格外组件 + +表格外组件目前支持： + +- Menu: 下拉菜单组件，同option中的menu的定义一致 [api](../../option/ListTable#menu) +- Tooltip: tooltip组件，同option中的tooltip的定义一致 [api](../../option/ListTable#tooltip) + +```jsx + + // ...... + + + +``` + +### 事件绑定 + +统一标签或是语法化表格标签最外层表格组件，其Props上都继承了表格的事件处理回调EventsProps。 + +EventsProps的定义如下： +```ts +interface EventsProps { + onClickCell?: EventCallback; + onDblClickCell?: EventCallback; + onMouseDownCell?: EventCallback; + onMouseUpCell?: EventCallback; + onSelectedCell?: EventCallback; + onKeyDown?: EventCallback; + onMouseEnterTable?: EventCallback; + onMouseLeaveTable?: EventCallback; + onMouseMoveCell?: EventCallback; + onMouseEnterCell?: EventCallback; + onMouseLeaveCell?: EventCallback; + onContextMenuCell?: EventCallback; + onResizeColumn?: EventCallback; + onResizeColumnEnd?: EventCallback; + onChangeHeaderPosition?: EventCallback; + onSortClick?: EventCallback; + onFreezeClick?: EventCallback; + onScroll?: EventCallback; + onDropdownMenuClick?: EventCallback; + onMouseOverChartSymbol?: EventCallback; + onDragSelectEnd?: EventCallback; + + onDropdownIconClick?: EventCallback; + onDropdownMenuClear?: EventCallback; + + onTreeHierarchyStateChange?: EventCallback; + + onShowMenu?: EventCallback; + onHideMenu?: EventCallback; + + onIconClick?: EventCallback; + + onLegendItemClick?: EventCallback; + onLegendItemHover?: EventCallback; + onLegendItemUnHover?: EventCallback; + onLegendChange?: EventCallback; + + onMouseEnterAxis?: EventCallback; + onMouseLeaveAxis?: EventCallback; + + onCheckboxStateChange?: EventCallback; + onAfterRender?: EventCallback; + onInitialized?: EventCallback; + + // pivot table only + onPivotSortClick?: EventCallback; + onDrillMenuClick?: EventCallback; + + // pivot chart only + onVChartEventType?: EventCallback; +} +``` + +事件使用示例： +```jsx +function App() { + const option = { + // ...... + }; + return ( + { + console.log('onClickCell', ...arg); + }} + /> + ); +} +``` + +事件详细描述参考：[事件介绍](../../guide/Event/event_list)