bugfix250107.1
全站通知：

帮助:Tooltip

来自咸鱼之王WIKI_BWIKI_哔哩哔哩
跳到导航 跳到搜索

简单说明

当鼠标指向特定元素时显示一个使用特定模板或模块生成的提示框，支持移动端。

基本使用方法

拥有bili-tt class的元素将成为可以触发提示框的元素，当鼠标进入该元素时，将会根据以下顺序，依次判断是否符合对应模式的触发条件

  • 行内模式
  • 预载模式
  • 模板模式
  • 页面模式（不推荐使用）
  • 代码内处理模式（用于兼容旧版本，需要自行修改代码）

使用最先符合条件的方式调用浮层，如果没有符合条件的配置，则无效果

另外，为了避免逻辑出错，同一时间只能显示一个提示框。所以提示框内如果有其他触发元素，它们会失效。

行内模式

当元素拥有data-tooltip属性，将会使用该属性的内容作为提示框内容。需要注意的是，因为属性中只能存放纯文本，所以这个模式只能使用纯文本，如果需要更复杂的样式或是调用图片等，请使用下面的预载模式。

代码 
<div class="bili-tt" data-tooltip="这是一行测试提示" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里</div>
效果
鼠标指到这里

提示框的样式会使用本零件附带的class bili-tt-style，如有需要可以自行调整该样式的效果，或替换别的样式名称

这是一行测试提示

预载模式

当元素的子元素中存在拥有bili-tt-preload class的元素时，将会使用该子元素的内容作为提示框内容（不包括该元素自己，只有该元素的内容会被作为提示框内容）。当出现多个子元素拥有bili-tt-preload class时，只会使用第一个。

代码 
<div class="bili-tt" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里<div class="bili-tt-preload">点击[[首页]]去往首页</div></div>
效果
鼠标指到这里
点击首页去往首页

如果在bili-tt-preload元素上同时使用bili-tt-style，则可以使用默认样式展示提示框，请根据需要自行选择

代码 
<div class="bili-tt" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">使用默认样式生成提示框<div class="bili-tt-preload bili-tt-style">点击[[首页]]去往首页</div></div>
效果
使用默认样式生成提示框
点击首页去往首页

模板模式

当元素拥有data-template属性，将会使用该属性的值作为模板名，data-params的值作为参数内容（如不存在则为空），解析模板，使用模板解析后的结果作为提示框。

代码 
<div class="bili-tt" data-template="咸将/咸将悬浮" data-params="甄姬" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里</div>
效果
鼠标指到这里

这里是调用模板{{咸将/咸将悬浮}}，并传入参数“甄姬”（相当于使用{{咸将/咸将悬浮|甄姬}}调用了模板），将解析结果作为提示框显示出来。

在等待模板解析结果出来前，将会使用以下占位内容

读取中，请稍后…

零件没有提供可配置的修改方式，如需修改请自行修改源代码createNewTooltipBlock方法

另外可以额外指定data-sep为分隔符，脚本将会把data-params值中的分隔符批量替换成“|”（管道符），以此避免在原始代码中，可能存在的与wikitext冲突的场合。例如下面的情况（下面的表格是使用wikitext生成的）

代码 
<div class="bili-tt" data-template="咸将/咸将悬浮" data-params="吕布|甄姬" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里</div>
效果 甄姬" style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里
说明 代码中的管道符被识别为wikitext的表格分隔符了
修正代码 
<div class="bili-tt" data-template="咸将/咸将悬浮" data-params="吕布,甄姬" data-sep="," style="display:inline-block;padding:3px 5px;border: 1px solid #000;cursor: help;">鼠标指到这里</div>
修正效果
鼠标指到这里
说明 修正后，脚本会将“吕布,甄姬”中的“,”批量替换成管道符再请求API，从而避开了这个问题

页面模式

当元素拥有data-page属性，将会使用该属性的值作为页面名，将该页面的内容引入作为提示框，不推荐使用该模式，所以这里不举例了。

代码内处理模式

类似旧版本的处理方式，添加新的展示需要修改代码

当元素拥有data-type属性时，将会通过getTriggerTypeBySite方法多进行一次额外处理，请将处理的代码编写于此处，具体请参考代码中的注释进行修改。

脚本配置

可以通过修改BiliTooltip.js文件开头的配置内容来调整脚本使用的各类ID、Class等

项目 初期配置 说明
CACHE_TOP_ELEMENT_SELECTOR #bodyContent 脚本会生成一个区域存放所有缓存的提示框，此处需要配置一个选择器，选择这个缓存区的父级。
CACHE_BLOCK_SELECTOR_ID bili-tt-cache-block 上述缓存区自己的ID，如无必要请不要修改
TOOLTIP_DATA_KEY ttid 每个触发元素在首次触发时会进行初始化，初始化成功后为了避免再次初始化，会给予一个索引值，保存在触发元素的属性里，这里配置了该属性的名字，默认下会保存到data-ttid
CLASS_TRIGGER_ITEM bili-tt 会触发显示提示框的元素对应的class
CLASS_TOOLTIP_CACHE_ITEM bili-tt-cache CACHE_BLOCK_SELECTOR_ID配置的缓存区下每个缓存元素的class，有样式设定，如果需要修改请同步修改样式
CLASS_PRELOAD_TOOLTIP bili-tt-preload 上述预载模式中使用的class
CLASS_TOOLTIP_DEFAULT_STYLE bili-tt-style 默认提示框样式，用于行内模式和预载模式。有样式设定，如果需要修改请同步修改样式

提示框配置

提示框有一些可调整的参数，分为三级配置：触发器配置最优先，其次是单页配置，最后是全局默认配置

全局默认配置

BiliTooltip.js文件头部中规范了这些全局默认配置

项目 初期配置 说明
DEFAULT_TOOLTIP_DIRECTION horizontal-top 全局默认提示框显示位置，请参考显示位置段落的说明
DEFAULT_CACHE_TIME 86400 全局默认缓存时间，单位是秒（s）
DEFAULT_TOOLTIP_PADDING 10 全局默认提示框与触发元素之间的间距，单位是像素（px）
DEFAULT_TOOLTIP_SHOW_DELAY 0 全局默认鼠标移入后，提示框显示的延迟，单位是毫秒（ms）
DEFAULT_TOOLTIP_HIDE_DELAY 200 全局默认鼠标移除后，提示框消失的延迟，单位是毫秒（ms）

单页配置

可以通过向页面中添加id为bili-tt-config的元素，来修改当前页面的全局默认值，具体请参考全局配置 

<div id="bili-tt-config" data-direction="horizontal-top" data-cachetime="86400" data-padding="10" data-showdelay="0" data-hidedelay="200"></div>

注：不一定需要新加一个div，可以将已有的元素添加上该id，并进行配置，配置时只保留需要修改的字段即可

触发器配置

在每个触发器中，都可以针对该触发器单独进行提示框配置 

<div class="bili-tt" ... data-direction="horizontal-top" data-cachetime="86400" data-padding="10" data-showdelay="0" data-hidedelay="200"></div>

配置时只保留需要修改的字段即可

显示位置

该属性可以配置提示框与触发元素的位置关系，格式为方向-对齐，例如top-left，对齐如果省略的话会自动设为center

水平方向 可用对齐 说明
horizontal / h top
center
bottom		 如果触发元素的左上角在屏幕的左半侧，则提示框显示在右边，否则显示在左边
left 总是显示在左边，只有当左边的空间不足时，才会显示在右边
right 总是显示在右边，只有当右边的空间不足时，才会显示在左边
垂直方向 可用对齐 说明
vertical / v left
center
right		 如果触发元素的左上角在屏幕的上半侧，则提示框显示在下边，否则显示在上边
top 总是显示在上边，只有当上边的空间不足时，才会显示在下边
bottom 总是显示在下边，只有当下边的空间不足时，才会显示在上边

此外，如果提示框的位置会超出屏幕显示范围，则会自动进行一定程度上的位置调整，来尽量让提示框显示在屏幕范围内

全局函数

interface window{
    closeHuijiTooltip(): void;  // 关闭现有浮层
}

函数 说明
closeBiliTooltip() 用于关闭现有浮层，用于在与其他脚本中手工调用来解决一些可能存在的显示错误。例如浮层元素在浮层显示状态下因为其他脚本被移除，导致浮层无法正常隐藏，其他脚本可在让浮层元素被移除后调用一下该函数来清除当前的浮层显示

引入模板

    // 配置变量
    var GADGET_VERSION = '2.0.6';
    var DEBUG = mw.config.get('debug'); // 当前是否为debug状态
    var INDEX_URL = '/xyzwgame/index.php'; // 首页的url
    var API_URL = '/xyzwgame/api.php'; // API的URL

修改模板

.bili-tt-style {
    position        : relative;
    background-color: rgba(38, 38, 38, 1);
    color           : #fff;
    border-radius   : 3px;
    padding         : 8px 14px;
    font-size       : 14px;
}

取自“https://wiki.biligame.com/xyzwgame/index.php?title=帮助:Tooltip&oldid=13597”