Merge pull request #757 from VisActor/feat/auto-poptip

feat: add auto text poptip in vrender
VisActor · Dec 20, 2023 · ca7ec18 · ca7ec18
2 parents 4e2b2cf + 8bfbd50
commit ca7ec18
Show file tree

Hide file tree

Showing 23 changed files with 783 additions and 56 deletions.
diff --git a/docs/assets/demo/en/export/table-export.md b/docs/assets/demo/en/export/table-export.md
@@ -4,8 +4,8 @@ group: export
 title: table export
 cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/pivot-table.png
 order: 4-6
-link: '../guide/components/dropdown'
-option: ListTable#menu.contextMenuItems
+link: '../../guide/export/excel'
+# option: ListTable
 ---
 
 # table export

diff --git a/docs/assets/demo/zh/export/table-export.md b/docs/assets/demo/zh/export/table-export.md
@@ -4,8 +4,8 @@ group: export
 title: 表格导出
 cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/pivot-table.png
 order: 4-6
-link: '../guide/components/dropdown'
-option: ListTable#menu.contextMenuItems
+link: '../../guide/export/excel'
+# option: ListTable
 ---
 
 # 表格导出

diff --git a/docs/assets/guide/en/custom_define/custom_component.md b/docs/assets/guide/en/custom_define/custom_component.md
@@ -0,0 +1,174 @@
+# Custom interactive components
+
+Custom primitives in custom rendering and custom layout can use the components provided by `VRender`. Currently, the following components are supported:
+
+## TextAutoPoptip
+
+The `TextAutoPoptip` component is an interactive component provided by `VRender`. Its function is that when the text is too long and is omitted, hover over the text and a poptip will automatically pop up to display the entire content of the text.
+
+``` javascript livedemo  template=vtable
+  const option = {
+    columns:[
+      {
+        field: 'type',
+        title:'',
+        width:170,
+        headerStyle:{
+          bgColor:'#4991e3'
+        },
+        style:{
+          fontFamily:'Arial',
+          fontWeight:600,
+          bgColor:'#4991e3',
+          fontSize:26,
+          padding:20,
+          lineHeight:32,
+          color:'white'
+        },
+      }, 
+      {
+        field: 'urgency',
+        title:'urgency',
+        width:400,
+        headerStyle:{
+          lineHeight:50,
+          fontSize:26,
+          fontWeight:600,
+          bgColor:'#4991e3',
+          color:'white',
+          textAlign:'center'
+        },
+      customLayout(args){
+        const { width, height}= args.rect;
+        const {dataValue,table,row } =args;
+        const elements=[];
+        let top=30;
+        const left=15;
+
+        const container = new VTable.CustomLayout.Group({
+          height,
+          width,
+          display: 'flex',
+          flexDirection: 'row',
+          alignContent: 'center',
+          alignItems: 'center',
+          justifyContent: 'space-around',
+        });
+
+        const text = new VTable.CustomLayout.Text({
+          fill: '#000',
+          fontSize: 20,
+          fontWeight: 500, 
+          textBaseline: 'top',
+          text: row===1? 'important but not urgency':'not important and not urgency',
+
+          maxLineWidth: 200,
+          pickable: true
+        });
+
+        container.add(text);
+
+        return {
+          rootContainer: container,
+        }
+      }
+    },
+    {
+      field: 'not_urgency',
+      title:'not urgency',
+      width:400,
+      headerStyle:{
+          lineHeight:50,
+          bgColor:'#4991e3',
+          color:'white',
+          textAlign:'center',
+          fontSize:26,
+          fontWeight:600,
+      },
+      style:{
+        fontFamily:'Arial',
+        fontSize:12,
+        fontWeight:'bold'
+      },
+      customRender(args){
+        console.log(args);
+        const { width, height}= args.rect;
+        const {dataValue,table,row} =args;
+        const elements=[];
+        let top=30;
+        const left=15;
+        let maxWidth=0;
+
+        elements.push({
+          type: 'text',
+          fill: '#000',
+          fontSize: 20,
+          fontWeight: 500, 
+          textBaseline: 'middle',
+          text: row===1? 'important but not urgency':'not important and not urgency',
+          x: left+50,
+          y: top-5,
+
+          maxLineWidth: 200,
+          pickable: true
+        });
+
+        return {
+          elements,
+          expectedHeight:top+20,
+          expectedWidth: 100,
+        }
+      }
+    }, 
+    ],
+    records:[
+      {
+        'type': 'important',
+        "urgency": ['crisis','urgent problem','tasks that must be completed within a limited time'],
+        "not_urgency": ['preventive measures','development relationship','identify new development opportunities','establish long-term goals'],
+      },
+      {
+        'type': 'Not\nimportant',
+        "urgency": ['Receive visitors','Certain calls, reports, letters, etc','Urgent matters','Public activities'],
+        "not_urgency": ['Trivial busy work','Some letters','Some phone calls','Time-killing activities','Some pleasant activities'],
+      },
+    ],
+    defaultRowHeight:80,
+    heightMode:'autoHeight',
+    widthMode:'standard',
+    autoWrapText:true,
+    theme: VTable.themes.DEFAULT.extends({
+      textPopTipStyle: {
+        // title: 'title'
+      }
+    })
+  };
+
+const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+```
+
+To use the `TextAutoPoptip` component, you need to configure the corresponding `text` primitive with `pickable: true` to enable interaction. At this time, the `TextAutoPoptip` component will automatically start when the `text` primitive is omitted by the `maxLineWidth` attribute. If you want to disable component retention interaction, you need to configure the `disableAutoClipedPoptip` attribute on the `text` primitive to `true`.
+
+The `poptip` style popped up by the `TextAutoPoptip` component can be configured in `theme.textPopTipStyle`. Some common properties are as follows:
+
+| Name | Type | Description |
+| :-----| :---- | :---- |
+|position|'auto' \| 'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br' \| 'left' \| 'lt' \| 'lb ' \| 'right' \| 'rt' \| 'rb'|`poptip` is displayed relative to the position of the primitive|
+|title|string \| string[] \| number \| number[]|The content of `title` in `poptip`|
+|titleStyle|Partial\<ITextGraphicAttribute\>|The style of the `title` content in `poptip`|
+|titleFormatMethod|(t: string \| string[] \| number \| number[]) => string \| string[] \| number \| number[]|format method for `title` content in `poptip`|
+|content|string \| string[] \| number \| number[]|The content of `content` in `poptip`, the default is the complete string|
+|contentStyle|Partial<ITextGraphicAttribute>|The style of the `content` content in `poptip`|
+|contentFormatMethod|(t: string \| string[] \| number \| number[]) => string \| string[] \| number \| number[]|The format method of `content` in `poptip`|
+|space|number|Distance between `title` and `content`|
+|padding|Padding|padding in `poptip`|
+|panel|BackgroundAttributes & ISymbolGraphicAttribute & {space?:number;}|Background style in `poptip`|
+|minWidth|number|Maximum width in `poptip`|
+|maxWidth|number|The minimum width in `poptip`|
+|maxWidthPercent|number|Maximum width percentage in `poptip`|
+|visible|boolean|whether `poptip` is visible|
+|visibleFunc|(graphic: IGraphic) => boolean|whether `poptip` is visible function|
+|dx|number|`poptip`x-direction offset|
+|dy|number|`poptip`y direction offset|
+
+<!-- |state|StateStyle|discription| -->
diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json
@@ -354,6 +354,13 @@
             "zh": "单元格自定义渲染",
             "en": "custom_render"
           }
+        },
+        {
+          "path": "custom_component",
+          "title": {
+            "zh": "自定义交互组件",
+            "en": "custom_interactive_component"
+          }
         }
       ]
     },

diff --git a/docs/assets/guide/zh/custom_define/custom_component.md b/docs/assets/guide/zh/custom_define/custom_component.md
@@ -0,0 +1,174 @@
+# 自定义交互组件
+
+自定义渲染和自定义布局中的自定义图元，可以使用`VRender`提供的组件，目前支持的有以下组件：
+
+## TextAutoPoptip
+
+`TextAutoPoptip`组件是`VRender`提供的一个交互组件，它的功能是在文本过长被省略时，hover到文本上，会自动弹出一个poptip，展示文本的全部内容。
+
+``` javascript livedemo  template=vtable
+  const option = {
+    columns:[
+      {
+        field: 'type',
+        title:'',
+        width:170,
+        headerStyle:{
+          bgColor:'#4991e3'
+        },
+        style:{
+          fontFamily:'Arial',
+          fontWeight:600,
+          bgColor:'#4991e3',
+          fontSize:26,
+          padding:20,
+          lineHeight:32,
+          color:'white'
+        },
+      }, 
+      {
+        field: 'urgency',
+        title:'urgency',
+        width:400,
+        headerStyle:{
+          lineHeight:50,
+          fontSize:26,
+          fontWeight:600,
+          bgColor:'#4991e3',
+          color:'white',
+          textAlign:'center'
+        },
+      customLayout(args){
+        const { width, height}= args.rect;
+        const {dataValue,table,row } =args;
+        const elements=[];
+        let top=30;
+        const left=15;
+
+        const container = new VTable.CustomLayout.Group({
+          height,
+          width,
+          display: 'flex',
+          flexDirection: 'row',
+          alignContent: 'center',
+          alignItems: 'center',
+          justifyContent: 'space-around',
+        });
+
+        const text = new VTable.CustomLayout.Text({
+          fill: '#000',
+          fontSize: 20,
+          fontWeight: 500, 
+          textBaseline: 'top',
+          text: row===1? 'important but not urgency':'not important and not urgency',
+
+          maxLineWidth: 200,
+          pickable: true
+        });
+
+        container.add(text);
+
+        return {
+          rootContainer: container,
+        }
+      }
+    },
+    {
+      field: 'not_urgency',
+      title:'not urgency',
+      width:400,
+      headerStyle:{
+          lineHeight:50,
+          bgColor:'#4991e3',
+          color:'white',
+          textAlign:'center',
+          fontSize:26,
+          fontWeight:600,
+      },
+      style:{
+        fontFamily:'Arial',
+        fontSize:12,
+        fontWeight:'bold'
+      },
+      customRender(args){
+        console.log(args);
+        const { width, height}= args.rect;
+        const {dataValue,table,row} =args;
+        const elements=[];
+        let top=30;
+        const left=15;
+        let maxWidth=0;
+
+        elements.push({
+          type: 'text',
+          fill: '#000',
+          fontSize: 20,
+          fontWeight: 500, 
+          textBaseline: 'middle',
+          text: row===1? 'important but not urgency':'not important and not urgency',
+          x: left+50,
+          y: top-5,
+
+          maxLineWidth: 200,
+          pickable: true
+        });
+
+        return {
+          elements,
+          expectedHeight:top+20,
+          expectedWidth: 100,
+        }
+      }
+    }, 
+    ],
+    records:[
+      {
+        'type': 'important',
+        "urgency": ['crisis','urgent problem','tasks that must be completed within a limited time'],
+        "not_urgency": ['preventive measures','development relationship','identify new development opportunities','establish long-term goals'],
+      },
+      {
+        'type': 'Not\nimportant',
+        "urgency": ['Receive visitors','Certain calls, reports, letters, etc','Urgent matters','Public activities'],
+        "not_urgency": ['Trivial busy work','Some letters','Some phone calls','Time-killing activities','Some pleasant activities'],
+      },
+    ],
+    defaultRowHeight:80,
+    heightMode:'autoHeight',
+    widthMode:'standard',
+    autoWrapText:true,
+    theme: VTable.themes.DEFAULT.extends({
+      textPopTipStyle: {
+        // title: 'title'
+      }
+    })
+  };
+
+const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+```
+
+使用`TextAutoPoptip`组件需要把相应的`text`图元配置`pickable: true`，开启交互，此时`TextAutoPoptip`组件在`text`图元被`maxLineWidth`属性省略时自动启动。如果想禁用组件保留交互，需要在`text`图元上配置`disableAutoClipedPoptip`属性为`true`。
+
+`TextAutoPoptip`组件弹出的`poptip`样式，可以在`theme.textPopTipStyle`中配置，部分常用属性如下：
+
+| Name | Type | Description |
+| :-----| :---- | :---- |
+|position|'auto' \| 'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br' \| 'left' \| 'lt' \| 'lb' \| 'right' \| 'rt' \| 'rb'|`poptip`显示在相对于图元的位置|
+|title|string \| string[] \| number \| number[]|`poptip`中`title`内容|
+|titleStyle|Partial\<ITextGraphicAttribute\>|`poptip`中`title`内容的样式|
+|titleFormatMethod|(t: string \| string[] \| number \| number[]) => string \| string[] \| number \| number[]|`poptip`中`title`内容的format方法|
+|content|string \| string[] \| number \| number[]|`poptip`中`content`内容，默认是完整字符串|
+|contentStyle|Partial<ITextGraphicAttribute>|`poptip`中`content`内容的样式|
+|contentFormatMethod|(t: string \| string[] \| number \| number[]) => string \| string[] \| number \| number[]|`poptip`中`content`内容的format方法|
+|space|number|`title`和`content`距离|
+|padding|Padding|`poptip`中的padding|
+|panel|BackgroundAttributes & ISymbolGraphicAttribute & {space?:number;}|`poptip`中的背景样式|
+|minWidth|number|`poptip`中的最大宽度|
+|maxWidth|number|`poptip`中的最小宽度|
+|maxWidthPercent|number|`poptip`中的最大宽度百分比|
+|visible|boolean|`poptip`是否可见|
+|visibleFunc|(graphic: IGraphic) => boolean|`poptip`是否可见函数|
+|dx|number|`poptip`x方向偏移|
+|dy|number|`poptip`y方向偏移|
+
+<!-- |state|StateStyle|discription| -->
diff --git a/docs/assets/option/en/custom-element/base-custom-element.md b/docs/assets/option/en/custom-element/base-custom-element.md
@@ -24,9 +24,9 @@ ${prefix} dy (number)
 
 The y-offset of the element.
 
-${prefix} clickable (boolean)
+${prefix} pickable (boolean)
 
-Whether the element is clickable.
+Whether the element is interactive, the interactive element will be displayed in the `target` of the interaction event callback parameter when it is interacted.
 
 ${prefix} cursor (string)