JavaScript和CSS

如果你想知道,请阅读这篇指南

  • 如何在Matomo(以前的Piwik) UI加载JavaScript和CSS文件
  • 插件应该如何创建JavaScript文件
  • 如何使用TypeScript和Vue与Matomo
  • 如何与Matomo核心的JavaScript代码工作

JavaScript库

Matomo使用以下JavaScript库:

只有当新的JS库对你的插件至关重要时,才包含它们,并确保使用TypeScript工作流,这样当同一个库的不同版本被用于其他插件时,就不会发生冲突。如果许多插件决定使用自定义库,UI将变慢。

在UI中加载JS和CSS文件

插件可以告诉Matomo加载JS和CSS资产文件。

这是通过AssetManager.getStylesheetFiles而且AssetManager.getJavaScriptFiles事件。如果你是活动的新手,请查看我们的活动指南.这些事件定义在你的插件文件中(如果你的插件名是YourPluginName然后它们就被定义在$ matomoDir /插件/ YourPluginName / YourPluginName.php).

要在UI中加载一个文件,只需将应该加载的路径附加到给定的文件中美元的文件数组:

//这些方法需要在你的插件php文件中的公共函数registerEvents(){返回数组('AssetManager. php ')getStylesheetFiles' => 'getStylesheetFiles', '资产管理器。getJavaScriptFiles' => 'getJavaScriptFiles',);}公共函数getStylesheetFiles(&$files) {$files[] = "plugins/MyPlugin/stylesheets/ mystylesheetfiles .less";$files[] = "plugins/MyPlugin/stylesheets/myCssStylesheet.css";}公共函数getJavaScriptFiles(&$files) {$files[] = "plugins/MyPlugin/javascripts/myJavaScript.js";}

资产合并和编译

在生产环境中,Matomo会将所有JavaScript文件连接成一个文件并缩小它。文件将被编译成CSS并合并成一个CSS文件。Matomo不会在每个请求上合并和缩小JavaScript和CSS文件,因为这样做需要很长时间。它们只在某些事件上合并,比如启用一个新插件时。

为了确保您的更改将实际可见和执行,您需要启用开发模式,以防您还没有这样做:

/控制台开发:启用

这样JavaScript文件就不会被合并,并且您可以调试原始的JavaScript源代码。

TypeScript和Vue工作流

从4.5.0版本开始,可以使用Vue和TypeScript为UI创建组件(尽管注意,你不必同时使用两者;你可以使用Vue和ESnext (EcmaScript最先进的版本)一起使用,或者不使用Vue只编写普通的TypeScript)。

Vue和TypeScript文件通过webpack使用Vue CLI服务进行处理,该服务在Matomo中全局配置。要利用这一点,就要创造vue而且vue / src插件中的子文件夹。然后将您的代码(TypeScript, ES, Vue)添加到src子文件夹。确保添加一个index.tsindex.js文件到子文件夹,并导出您想要在浏览器中以编程方式访问的所有内容(例如,通过其他插件)。

有关使用Matomo的Vue代码示例,请参见ExampleVue插件源代码。

编写完代码后,必须将其构建到UMD文件中。运行./console vue:构建MyPlugin命令来构建Vue/TypeScript代码。编译后的UMD将在vue / dist文件夹,并且应该与插件的其余部分一起分发(因为我们不希望所有用户都能访问node或有技术能力手动编译我们的JavaScript)。

在开发时,建议使用——看选项vue:构建因此,您不必不断地重新运行命令。

注意:没有必要将生成的UMD文件添加到“AssetManager.getJavaScriptFiles”事件。Matomo将自动检测是否有一个并使用它(如果插件被激活)。

eslint

Vue CLI被配置为在构建umd时在文件上运行ESlint。如果ESlint基于我们配置的规则之一发现了一个样式问题,它将在的输出中打印出来vue:构建.有时,从错误消息中不清楚实际问题或修复方法。

在这种情况下,最简单的方法是在搜索引擎中搜索规则名称。每个规则都有相关的在线文档,描述了错误的含义、规则存在的原因以及如何修复错误。

Eslint在构建Vue umd时会自动运行,但如果你想直接从命令行运行它,可以运行如下命令:

$ NPM运行eslint -- --ext .js,.ts,。vue插件/并且

AngularJS文件

不推荐使用AngularJS,请改用Vue.js 3。

特殊的HTML元素

下面是一个特殊元素的列表,你应该知道当你开发你的插件或贡献:

  • #根:对用户显示和可见的所有内容的根元素。

  • #内容:根元素,包含在主报告菜单下显示的所有内容和“选择器”控件行(即,周期选择器,段选择器等)。

  • .top_controls:包含“selector”控件的元素。这些元素中只有一个。

  • .widgetContent:每个小部件的根元素。事件被发布到这个特定的元素。

由Matomo定义的全局变量

Matomo定义了几个全局变量window.piwik)有关目前的要求。以下是它们的含义以及使用方法:

  • piwik.token_auth:token_auth当前用户的。应该在AJAX请求中使用,但不应该出现在URL中。
  • piwik.piwik_url:这个Matomo实例的URL。
  • piwik.userLogin:当前用户的登录句柄(如果有当前用户)。
  • piwik.idSite:当前选择的网站ID。
  • piwik.siteName:当前选择的网站名称。
  • piwik.siteMainUrl:当前选择网站的URL。
  • piwik.language:当前选择的语言代码(例如,).

代码编写约定

在为你的贡献或插件编写JavaScript时,你最好遵守以下的编码约定。

重要的JavaScript类

Matomo Core定义了许多应该被新插件和贡献重用的类。这些类可以用来改变UI显示的页面,加载弹出窗口,从CSS中获取主题颜色值。

广播

该类被认为已弃用,仅由于历史原因存在,因为一些组件仍在使用它。只要有可能,你应该使用angularjs的组件,比如美元的位置.在不可能的情况下,广播可以使用。

广播对象直接存储在窗口对象,应该用来解析当前URL,在菜单下面的区域加载一个页面,并加载持久弹窗。

注意:虽然对象存储在窗口而不是JS命名空间,它仍然可以使用需要通过调用要求(广播)

解析URL

广播包含几个解析Matomo URL的方法。Matomo的主UI在URL的哈希值中存储二级查询参数集。这是在菜单下面加载的URL。广播的URL解析函数将在散列中查找查询参数值以及主查询字符串,因此使用它们而不是直接访问是很重要的window.location.href

广播提供以下功能:

  • isHashExists ():如果URL存在,则返回该URL的哈希值。否则如果。
  • getHashFromUrl ():返回URL的哈希值。可以是空字符串。
  • getSearchFromUrl ():返回查询字符串。
  • extractKeyValuePairsFromQueryString ():将查询字符串转换为查询参数名称与查询参数值的对象映射。
  • getValuesFromUrl ():返回对象映射查询参数名称和当前URL的查询参数值。
  • getValueFromUrl ():按名称返回当前URL的一个查询参数值。
  • getValueFromHash ():按名称返回当前URL散列中的一个查询参数值。
  • getHash ():返回URL的哈希值。

方法中的方法文档,以了解有关单个函数的更多信息插件/ CoreHome / javascript / broadcast.js文件。

加载新的Matomo页面(普通JavaScript)

要在Matomo主菜单下面加载新页面,请使用propagateNewPage ()函数带有指向控制器方法的URL,其输出应该显示:

(函数(require) {var broadcast = require('broadcast');broadcast.propagateNewPage (' index . php ?模块= MyPlugin&action = mySpecialPage’,真正的);})(需要);

ajaxHelper(普通JavaScript)

AJAX请求在非vue,香草JavaScript应该使用ajaxHelper全球。

ajaxHelper类应该在需要创建AJAX请求时使用。不应该使用插件. ajax美元直接。ajaxHelper做了一些额外的事情,使得编写不安全的代码更加困难。它还跟踪当前正在进行的AJAX请求,这对用户界面测试

使用ajaxHelper,创建一个实例,配置它,然后调用send ()方法。要了解更多信息,请阅读源代码中的文档(位于插件/睡眠/ javascript / ajaxHelper.js).

例如:

(function (require, $) {var ajaxHelper = require('ajaxHelper');var ajax = new ajaxHelper();ajax.setUrl (index . php ?模块= Actions&action = getPageUrls&idSite = 1和日期= today&period =天');ajax。setCallback(function (response) {$('#myReportContainer').html(response);});ajax.setFormat (html);//期望的响应格式ajax.setLoadingElement('#myReportContainerLoading');ajax.send ();})(需要,jQuery);

故障排除

以下是开发过程中可能出现的一些常见问题的解决方案:

  • 如果工作在Vue代码和vue:构建——手表正在运行,但JavaScript没有正确构建,请尝试重新启动该命令。在内部,它会在再次观看之前清除webpack缓存,这可以解决一些问题。
  • 如果在使用Jest的前端单元测试中看到奇怪的错误,清除Jest的缓存有时会有所帮助。要执行此操作,请运行npm test -- --clearCache命令。

了解更多

  • 学习关于创建新的报表可视化阅读我们的报表数据可视化指南。
  • 学习更多关于资产合并系统读到这博客由系统的作者编写。
  • 学习关于主题阅读我们的主题指南。
  • 学习更多关于UI组件和样式的信息阅读我们的的观点指南。
Baidu