Add doc for Mask and Tagging #1335

minorcell · 2025-02-15T11:12:16Z

以下修改来自于：#1331 (comment)

Tagging
- 标注方
- 消费方
- 单例全局唯一
Mask

type Props = {
  visible: boolean; // 是否显示蒙层
  tags: string[]; // 需要高亮组件的查找路径
};

考虑了 tag选择器的形式查找元素，通过传入key数组找到目标组件。

nighca · 2025-02-17T01:58:15Z

docs/develop/guidance/feature_Mask.md

+</script>
+
+<template>
+  <Mask :visible="visible" :tags="currentTags" />


Mask 的使用方除了希望 Mask 遮住界面上几乎所有内容外，一般都还会展示一些别的内容，比如提示文案、箭头、引导用的卡通形象等，这些内容使用方应当如何渲染以确保它们不会被 Mask 遮住？一般这内容会希望相对被高亮显示的组件定位，是可以方便地做到的吗？

好的，这确实也是需要考虑的地方。我们经过讨论决定通过Props的形式传入description字段：

如果传了description，则代表当前是following步骤，除高亮目标组件外还需要展示卡通形象、提示文案(description)和箭头。

如果没传description，则代表当前是coding步骤，不需要额外素材信息展示，仅高亮目标组件即可。

对于卡通形象、提示文案(description)和箭头展示位置的处理，这里需要考虑：

蒙层中高亮元素的位置是需要通过Tagging精准高亮的。

卡通形象、提示文案(description)和箭头的展示位置需要通过高亮目标动态计算的。

对于动态计算的部分，这里可以考虑坐标系的概念，在Mask建立二维坐标系，根据高亮目标组件的位置，分别计算卡通形象、提示文案和箭头的位置，同理这三者之间也有位置关系。比如：

提示文案应在卡通形象上方

箭头指向不可能是卡通形象，只会指向高亮目标组件

除此外还要考虑屏幕边界问题。

我们经过讨论决定通过Props的形式传入description字段：

你的意思是把“卡通形象、提示文案(description)和箭头”这些内容都做到 Mask 里边？

你说的位置计算逻辑不是现在关注的重点，我们现在应该关心的是，哪些逻辑是哪个模块的职责，在我们给定的职责划分下，接口是不是易用的

是的，原来是想在StepPlayer里做。现在发现在Mask里会更方便一点，因为Mask本身调用了Tagging，这样可以减少调用次数。

把某个逻辑对应的职责从一个模块挪到另一个模块，是一个很重的动作，因为这会改变模块本身的定位，进而影响整体的模块拆分的合理性；建议当遇到问题的时候，先去想：

它是不是一个重要的问题，很多时候性能问题都不是问题

能不能通过优化接口（不改变定位）来达到目的

都不行才去考虑调整模块定位

这里如果只是多调用一次 Tagging 模块的接口，这个本身不是问题，又不是什么很重的操作；每个模块是不是关心了不该它关心的事情、干了它不该干的事情才是重要的

我懂了，这个操作和Mask没什么关系，还是放回StepPlayer吧

nighca · 2025-02-17T03:25:30Z

docs/develop/guidance/module_Tagging.md

+```typescript
+/** 节点  */
+export interface TagNode {
+  e: Component;


e 是什么意思？这里可能混淆了几个概念: element / component / component-instance

可以参考 https://vuejs.org/guide/essentials/component-basics 捋清楚

e在接口层面表现为vue中的type Component，在实例层面表现为component-instance

vue中的type Component

type Component 是一个 component 的类型，而不是一个 component instance 的类型

nighca · 2025-02-17T03:26:16Z

docs/develop/guidance/module_Tagging.md

+   * @param component: 被添加的组件
+   * @param keys: 添加到的目标节点，不传时添加到根节点
+   */
+  addTag(key: string, component: Component, keys?: string[]): void;


预期谁会调用这个方法？以及下边的 removeTag

这里考虑的是动态添加或者删除的内容，比如：

removeTag: 移除一个精灵后需要把精灵在tagTree中的标注删除（如果存在子节点也要删除子节点）。

addTag: 新增一个精灵后，需要在tagTree中添加节点信息。

你说的“精灵”是啥？

如果你说的就是 Builder project 中的 sprite，要知道标记的对象是 UI 节点，不是 sprite 这样的业务数据；比如你看一眼 src/components/editor/panels/sprite/SpritesPanel.vue 然后再考虑下标记的代码长什么样呢？以及 removeTag、addTag 是什么样的代码在什么时候调用呢？

好的，这块我也在想想。

nighca · 2025-02-17T03:26:30Z

docs/develop/guidance/module_Tagging.md

+  getElementByKeys(keys: string[]): Component | null;
+
+  /** 清空所有标注 */
+  clearAllTags(): void;


预期谁在什么情况下会调用 clearAllTags？

这里考虑的是销毁App的时候，App组件卸载时调用，不过现在看来好像没有意义，因为App组件卸载时同样回收了AllTags, 后续的提交中我会删除掉。

nighca · 2025-02-17T03:47:13Z

docs/develop/guidance/feature_Tagging.md

+```vue
+<!-- 示例组件1 -->
+<template>
+  <Father data-tag="father">


Tagging 模块跟其他模块相比，还有个特殊的地方是它的实现会强依赖框架的能力。这里确定接口的同时需要同时确定对应的实现机制（否则很可能无法按预期的接口去实现）。

这里看起来是约定向 vue component 或 HTML element 上添加一个自定义的 HTML attribute？它会是如何被收集起来的呢？

约定向 vue component 或 HTML element 上添加一个自定义的 HTML attribute

这种“以某种姿势来和模块交互”的约定其实也是模块对外 API 的一部分，也应当在 module_Tagging 中予以说明

这里看起来是约定向 vue component 或 HTML element 上添加一个自定义的 HTML attribute？

是的，通过在 vue component 或者 HTML element中添加自定义属性data-tag=${key}实现语义化标注

这种“以某种姿势来和模块交互”的约定其实也是模块对外 API 的一部分，也应当在 module_Tagging 中予以说明

我会在后续提交中加上的。

它会是如何被收集起来的呢？

这里考虑的实现是在初始化时，在跟组件中通过vue中getCurrentInstance()方法获取组件实例，并递归调用，查询data-tag的标注，生成tagTree实现对标准和组件的收集。但getCurrentInstance()获取的组件实例处理起来有些复杂处理时要考虑情况也比较多，或许不是唯一的方法。

通过getCurrentInstance()获取的组件实例

在初始化时，在跟组件中通过vue中getCurrentInstance()方法获取组件实例，并递归调用，查询data-tag的标注，生成tagTree实现对标准和组件的收集。但getCurrentInstance()获取的组件实例处理起来有些复杂处理时要考虑情况也比较多，或许不是唯一的方法。

这个问题是，你没法感知“动态”内容中标注的节点；比如某个界面初始状态下不渲染，直到用户点了某个 button 后那个节点才渲染出来，但是你的 tagTree 是不会知道需要去更新的

这确实也是一个问题

nighca · 2025-02-17T03:51:36Z

docs/develop/guidance/feature_Tagging.md

+```vue
+<script lang="ts" setup>
+// 组件内注入
+const tagging = inject("Tagging");


一般来说一个 library 不会需要使用方自己去指定这个 inject key，因为这样使用方就需要自己去保证：

inject 的地方和 provide 的地方 key 相同

这个 key 不会跟其他不相干 provice/inject 逻辑 key 冲突

你可以看下 pinia、i18n、vue-router 的 API，它们应该几乎都依赖了 provide/inject 的能力，但都不会把上述的负担交给使用方

好的，这个确实需要在注入，我会在后续提交中修改。

minorcell · 2025-02-17T09:16:38Z

语义化标注待解决问题

tag 的收集

tag 跨层级

比如爷爷(有 tag) -> 父亲(无 tag) -> 儿子(有 tag)

动态更新 tagTree

考虑比如初始状态下有些带 tag 的组件不会渲染

nighca · 2025-02-17T09:21:00Z

@minorcell 我之前提过 https://github.com/qbox/portal-base/tree/master/common/components/Role 这个，你上面提到的问题那边倒是都解决过，虽然是在 React 下，不过做法搬到 vue 下也是能用的；你可以先了解一下它的做法，作为一个兜底选项，不排除 vue 下可能有更好的做法

minorcell · 2025-02-17T09:25:15Z

@nighca 这个链接我好像没办法访问，是404页面，在组织项目搜索中也搜不到。

minorcell · 2025-02-18T10:03:32Z

基于 https://github.com/qbox/portal-base/tree/master/common/components/Role 思路的Vue实现：

仓库地址：https://github.com/minorcell/tagging-demo
README: https://github.com/minorcell/tagging-demo/blob/main/README.md

nighca · 2025-02-19T03:44:15Z

如晨会提到的，考虑到 Tagging 信息的消费方不止一个，建议考虑这样的思路把收集 tagging 信息的根节点跟消费 tagging 信息的点分开：

<TaggingRoot>
  <!-- 整个应用 -->
</TaggingRoot>

// 消费 Tagging 信息，典型诉求是根据某个 selector string 找到对应的 component-instance / element，
// 这里的函数名(`useTagging`)及其参数仅仅是示意，不一定要按这个来
const result = useTagging(/* ... */)

这样不至于强迫所有的消费逻辑都集中到跟 TaggingRoot 打交道的同一处代码

qiniu-x · 2025-02-19T03:44:50Z

[Git-flow] Hi @minorcell, There are some suggestions for your information:

Rebase suggestions

Following commits have duplicated messages

Update doc for Tagging and Mask

Update doc for Tagging and Mask

Which seems insignificant, recommend to use git rebase command to reorganize your PR.

For other git-flow instructions, recommend refer to these examples.

If you have any questions about this comment, feel free to raise an issue here:

https://github.com/qiniu/reviewbot

minorcell · 2025-02-19T03:52:25Z

@nighca 寒星老师，我们晨会之后又讨论了一下，我提交文档后看到你在前一分钟的这个#1335 (comment) comment。我们讨论的结果和你的描述是类似的，只不过实现上不大一样。

TagConsumer可以嵌套使用，但是它不会向上上报自己存储的tagTree。即它上层的tag或者tagConsumer不知道它的存在。这样就实现了不至于强迫所有的消费逻辑都集中到跟 TaggingRoot 打交道的同一处代码

如下示例内容：

<template>
  <TagConsumer ref="rootConsumerRef">
    <Tag name="infoBox">
      <div class="info-box">
        <!-- contentConsumerRef 不会上报自己的tagTree -->
        <TagConsumer ref="contentConsumerRef">
          <Tag name="content"> ... </Tag>
        </TagConsumer>
        <Tag name="confirm"> ... </Tag>
      </div>
    </Tag>
    <ClickToRender />
  </TagConsumer>
</template>

它保存的信息结构大概如下，不是一棵tagTree，而是两颗独立的tagTree，消费方通过tagConsumer的ref即可调用接口方法：

// rootConsumerRef的tagTree
{
  name: "_root_",
  instance: null,
  children: [
    {
      name: "infoBox",
      instance: ...,
      children: [
        {
          name: "confirm",
          instance: xxx,
          children: []
        }
      ]
    }
  ]
}

// contentConsumerRef的tagTree
{
  name: "_root_",
  instance: null,
  children: [
    {
      name: "content",
      instance: xxx,
      children: []
    }
  ]
}

nighca · 2025-02-19T04:05:09Z

你说的做法是把我提到的 root 跟 consumer 合成一个 API（TagConsumer），是能用的，只是有几个明显的问题：

为了能正确地收集整棵树，所以整个应用的外层是需要有一个 TagConsumer 的，这个节点的存在只是收集，用的 API 却叫 consumer，这个是奇怪的

component 的形式是不方便消费的，对比一下

<template>
	<TagConsumer ref="tagConsumer">
		<!-- ... -->
	</TagConsumer>
</template>
<script setup>
import { ref } from 'vue'
import { TagConsumer } from 'tagging'

const tagConsumer = ref<InstanceType<typeof TagConsumer>>()
// wait for children to be mounted...
if (tagConsumer.value != null) tagConsumer.value.xxx()
</script>

和

<script setup>
import { useTagConsumer } from 'tagging'

const tagConsumer = useTagConsumer()
tagConsumer.xxx()
</script>

minorcell · 2025-02-19T06:44:47Z

@nighca 寒星老师，根据你上面的描述，我的理解是：

全局只有一个<TagConsumer />，它只负责收集子<tag />的节点信息和构建tagTree，不对外暴露方法。
每个<Tag />是tagTree的一个节点，负责收集子<Tag/>的节点信息和上报自身节点信息到父<Tag />。
把消费的逻辑从<TagConsumer />中抽离到useTagConsumer()中，方便消费方可以在随处调用。

对吗？

nighca · 2025-02-19T06:52:54Z

是的

全局只有一个<TagConsumer />，它只负责收集子<tag />的节点信息和构建tagTree，不对外暴露方法。

那样这个“只负责收集子<tag />的节点信息和构建tagTree”的东西就不太适合叫 consumer 了，因为它并不“消费”标注信息

每个<Tag />是tagTree的一个节点，负责收集子<Tag/>的节点信息和上报自身节点信息到父<Tag />。

从实现的角度看是这样的；只是从使用者的角度看，更像是：每个 <Tag /> 都是在把自身的信息上报到根节点；

只是在实现上，为了方便最后组装回一棵树，所以可能会实现成每个 <Tag /> 都上报到父节点，再由父节点向上传

nighca · 2025-02-19T06:55:21Z

它保存的信息结构大概如下，不是一棵tagTree，而是两颗独立的tagTree

#1335 (comment) 我好像没注意到你在这里提到的“两棵独立的树”这个事情；为啥会设计成有两棵（或者说多棵）树？

minorcell · 2025-02-19T06:59:41Z

#1335 (comment) 我好像没注意到你在这里提到的“两棵独立的树”这个事情；为啥会设计成有两棵（或者说多棵）树？

这个是基于之前的设想，可以存在多个<TagConsumer />（现在可能要换个名字，比如<RootTag />），但如果是全局唯一一个tagTree的话，就不需要这个设计了。

nighca · 2025-02-19T07:08:30Z

这个是基于之前的设想，可以存在多个<TagConsumer />（现在可能要换个名字，比如<RootTag />），但如果是全局唯一一个tagTree的话，就不需要这个设计了。

我有点回忆起来为啥 Role 那边是设计成那样了；它的设计考虑的应该是：每个 RoleConsumer 获得到的数据是（可以由其包含的内容）确定的，即使在 RoleConsumer 外部添加更多的内容（包括更多的 RoleConsumer、Role），也不会影响这个 RoleConsumer 能消费到的节点树。

只是它的设计跟你上面提到的“两颗独立的tagTree”的设计有点区别，它预期嵌套的两个 RoleConsumer 对应的 tree 也是父子的关系，即，如果 RoleConsumer A 被 RoleConsumer B 包含，那么 A 所消费的 Role 节点树也是 B 所消费的 Role 节点树的子树；从你举的例子来看，你的设计里边它俩并不会是子树的关系，而是被切割开了，两个独立的树

它的“多根节点”的设计是有道理的，在项目变复杂之后，尤其是局部的代码跟外层的代码由不同的团队在维护、最终组装起来时，让局部的代码行为尽量不被其他的代码影响是有好处的。不过我们这里暂时没有这个诉求，即使将来有这个诉求，让“RootTag”支持嵌套就好了，不会 break 现有的设定

qiniu-ci · 2025-02-19T10:26:58Z

This PR has been deployed to the preview environment. You can explore it using the preview URL.

Warning

Please note that deployments in the preview environment are temporary and will be automatically cleaned up after a certain period. Make sure to explore it before it is removed. For any questions, contact the Go+ Builder team.

Add doc for Mask and Tagging

9bb060f

vercel bot deployed to Preview February 15, 2025 11:15 View deployment

Update doc for Tagging and Mask

8943c93

vercel bot deployed to Preview February 17, 2025 03:16 View deployment

nighca reviewed Feb 17, 2025

View reviewed changes

nighca mentioned this pull request Feb 17, 2025

Add interface and pseudocode docs. #1326

Merged

Update doc for Tagging and Mask

bf20077

vercel bot deployed to Preview February 19, 2025 03:47 View deployment

Refactor docs for Tagging and Mask

1167fde

vercel bot deployed to Preview February 19, 2025 10:26 View deployment

Add doc for Mask and Tagging #1335

Are you sure you want to change the base?

Add doc for Mask and Tagging #1335

Conversation

minorcell commented Feb 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nighca Feb 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nighca Feb 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

minorcell commented Feb 17, 2025 • edited Loading

语义化标注待解决问题

tag 的收集

tag 跨层级

动态更新 tagTree

nighca commented Feb 17, 2025

minorcell commented Feb 17, 2025

minorcell commented Feb 18, 2025

nighca commented Feb 19, 2025 • edited Loading

qiniu-x bot commented Feb 19, 2025

Rebase suggestions

minorcell commented Feb 19, 2025 • edited Loading

nighca commented Feb 19, 2025 • edited Loading

minorcell commented Feb 19, 2025 • edited Loading

nighca commented Feb 19, 2025 • edited Loading

nighca commented Feb 19, 2025

minorcell commented Feb 19, 2025

nighca commented Feb 19, 2025 • edited Loading

qiniu-ci commented Feb 19, 2025

minorcell commented Feb 15, 2025 •

edited

Loading

nighca Feb 17, 2025 •

edited

Loading

nighca Feb 17, 2025 •

edited

Loading

minorcell commented Feb 17, 2025 •

edited

Loading

nighca commented Feb 19, 2025 •

edited

Loading

minorcell commented Feb 19, 2025 •

edited

Loading

nighca commented Feb 19, 2025 •

edited

Loading

minorcell commented Feb 19, 2025 •

edited

Loading

nighca commented Feb 19, 2025 •

edited

Loading

nighca commented Feb 19, 2025 •

edited

Loading