You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by ov...@apache.org on 2022/09/20 03:29:45 UTC
[echarts-handbook] 01/01: doc: add doc for coarse-pointer
This is an automated email from the ASF dual-hosted git repository.
ovilia pushed a commit to branch doc-coarse-pointer
in repository https://gitbox.apache.org/repos/asf/echarts-handbook.git
commit bd751e7348816ef5e298fc906fb1c03b31dae98c
Author: Ovilia <zw...@gmail.com>
AuthorDate: Tue Sep 20 11:29:03 2022 +0800
doc: add doc for coarse-pointer
---
contents/en/how-to/interaction/coarse-pointer.md | 27 +++++++++++++++++++++++
contents/en/posts.yml | 2 ++
contents/zh/how-to/interaction/coarse-pointer.md | 27 +++++++++++++++++++++++
contents/zh/posts.yml | 2 ++
static/images/how-to/coarse-pointer-en.gif | Bin 0 -> 257654 bytes
static/images/how-to/coarse-pointer-zh.gif | Bin 0 -> 253963 bytes
6 files changed, 58 insertions(+)
diff --git a/contents/en/how-to/interaction/coarse-pointer.md b/contents/en/how-to/interaction/coarse-pointer.md
new file mode 100644
index 0000000..75f4d36
--- /dev/null
+++ b/contents/en/how-to/interaction/coarse-pointer.md
@@ -0,0 +1,27 @@
+# Intelligent Pointer Snapping
+
+Some interactive elements may be relatively small in charts, so sometimes it is difficult for users to click and do other operations accurately, especially on the mobile. Therefore, in Apache ECharts<sup>TM</sup> 5.4.0, we introduced the concept of "smart pointer snapping".
+
+Starting from this version, by default, ECharts enables pointer snapping for mobile charts and disables it for non-mobile charts.
+
+> If it needs to be enabled for all platforms, it can be achieved by setting `opt.useCoarserPointer` to `true` in [init](${mainSitePath}api.html#echarts.init); set to `false` is turned off for all platforms.
+
+## Snapping Algorithm
+
+When a mouse or touch event occurs, ECharts will determine whether it is interacting with an interactable element based on the position of the mouse or touch. If it is, the element is the object to be interacted with, which is the same logic before this optimization. If not, find an element that is closest to the mouse or touch position within a certain range.
+
+> The default range is 44px (see [W3C standard](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)), developers can set this value through `opt.pointerSize` when [init](${mainSitePath}api.html#echarts.init).
+
+More specifically, ECharts will loop through different angles and different radii (within `opt.pointerSize`) around the mouse or touch position until it finds an element that intersects it. If found, the element is considered to be an interactive object.
+
+<img width="100%" height="100%" style="max-width: 441px"
+src="images/how-to/coarse-pointer-en.gif">
+</img>
+
+That is, if an element is within the `opt.pointerSize` radius of the mouse or touch position, the closest interactable element is considered the interactive object.
+
+## Performance
+
+As for the implementation, we first judge the intersection between the mouse or touch position and the AABB bounding box of all interactable elements, so as to quickly eliminate most of the elements that is not interacting. Then, we perform an accurate path intersection judgment on the remaining elements. Therefore, from the perspective of user experience, there is hardly any perceivable performance loss.
+
+For chart series with large-scale data (that is, bar charts, scatter charts, etc. with `large: true` enabled), the snapping will not be enabled.
diff --git a/contents/en/posts.yml b/contents/en/posts.yml
index 4c13fab..aa3c7db 100644
--- a/contents/en/posts.yml
+++ b/contents/en/posts.yml
@@ -134,6 +134,8 @@
- title: Connect
dir: connect
draft: true
+ - title: Intelligent Pointer Snapping
+ dir: coarse-pointer
- title: Best Practices
dir: best-practices
children:
diff --git a/contents/zh/how-to/interaction/coarse-pointer.md b/contents/zh/how-to/interaction/coarse-pointer.md
new file mode 100644
index 0000000..b06993a
--- /dev/null
+++ b/contents/zh/how-to/interaction/coarse-pointer.md
@@ -0,0 +1,27 @@
+# 智能指针吸附
+
+在图表中，部分可交互元素可能比较小，有时候用户不易准确地进行点击等操作，移动端尤其如此。因此，在 Apache ECharts<sup>TM</sup> 5.4.0 中，我们引入了“智能指针吸附”的概念。
+
+从该版本起，在默认情况下，ECharts 对移动端的图表开启指针吸附，对非移动端的图表关闭。
+
+> 如果需要对所有平台都开启，则可以通过在 [init](${mainSitePath}api.html#echarts.init) 的时候将 `opt.useCoarserPointer` 设置为 `true` 来实现；设为 `false` 则对所有平台都关闭。
+
+## 吸附原理
+
+在鼠标或触摸事件发生时，ECharts 会根据鼠标或触摸的位置，判断是否和某个可交互元素相交。如果是，则认为该元素是交互对象（与优化前的逻辑一致）；如果不是，则在一定范围内找到最接近鼠标或触摸位置的一个元素。
+
+> 默认的范围是 44px（参见 [W3C 标准](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)），开发者可在 [init](${mainSitePath}api.html#echarts.init) 的时候，通过 `opt.pointerSize` 设置该值。
+
+更具体地说，ECharts 会在鼠标或触摸位置的周围，依次循环不同角度和不同半径（在 `opt.pointerSize` 范围内），直到找到一个元素与其相交。如果找到了，则认为该元素是交互对象。
+
+<img width="100%" height="100%" style="max-width: 441px"
+src="images/how-to/coarse-pointer-zh.gif">
+</img>
+
+也就是说，如果有元素在鼠标或触摸位置的 `opt.pointerSize` 半径范围内，则最靠近的可交互元素会被认为是交互对象。
+
+## 性能分析
+
+在实际算法实现的时候，我们首先将鼠标或触摸位置与所有可交互元素的 AABB 包围盒判断相交性，从而快速剔除了大部分不相交的元素。然后，我们再对剩余的元素进行精确的路径相交判断。因此，从用户体验角度，不会带来可感知的性能损耗。
+
+对于大规模数据的图表系列（也就是开启了 `large: true` 的柱状图、散点图等），不会开启吸附功能。
diff --git a/contents/zh/posts.yml b/contents/zh/posts.yml
index 0e15bf5..00568e0 100644
--- a/contents/zh/posts.yml
+++ b/contents/zh/posts.yml
@@ -140,6 +140,8 @@
- title: 多图联动
dir: connect
draft: true
+ - title: 智能指针吸附
+ dir: coarse-pointer
- title: 最佳实践
dir: best-practices
children:
diff --git a/static/images/how-to/coarse-pointer-en.gif b/static/images/how-to/coarse-pointer-en.gif
new file mode 100644
index 0000000..5a256a4
Binary files /dev/null and b/static/images/how-to/coarse-pointer-en.gif differ
diff --git a/static/images/how-to/coarse-pointer-zh.gif b/static/images/how-to/coarse-pointer-zh.gif
new file mode 100644
index 0000000..485bf19
Binary files /dev/null and b/static/images/how-to/coarse-pointer-zh.gif differ
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org