User:屠麟傲血/JavaScript手册
| “ | 你学的是个锤子JavaScript，你学的是jQuery | ” |
| ——一名不愿透露姓名的维护组成员 | ||
学习JavaScript不久，主要精力放在了jQuery上，把自己的一些心得记下来吧，或许有些naive。
常用mediaWiki函数
原文来自：mw:ResourceLoader/Core modules，但并不是直接翻译，有一定的归纳总结。
mediaWiki提供了丰富的函数供使用，以下举出一些常用的函数。在较新版本的mediaWiki上，它们大部分来自于mediawiki.base模块，在mediaWiki上运行的js不需要调取该库即可使用这些函数。对象的完整路径是window.mediaWiki，常用的简写是mw。
mw.config
mediaWiki.config通过调用内部函数mw.Map来查询各类元数据。常用的有如下几种：
mw.config.get('参数名')，获取参数用于后续代码中；mw.config.exists('参数名')判断这个参数是否存在；mw.config.set('参数名')能够设置一个参数的值；
此外，mw.config.log('参数名')可以将获得的参数直接写入浏览器控制台，在“审查元素”中查看。config可以查询的参数有很多，F12打开控制台，使用mw.config.values查询即可获得当前页面的相关信息。
mw.html
mw.html.escape函数提供字符转义功能。mw.html.element函数能够在安全转义的前提下，创建一个html元素。格式为mw.html.element('元素名',{属性},内容)。mw.html.Raw函数适用于mw.html.element编写多层元素，为了让子元素符号不被转义，需要使用new mw.html.Raw()包裹子元素。
还是jQuery建html元素方便直接用Vanilla JS得了
mw.loader
这里的一些函数不在mediawiki.base，不过在User和mediaWiki名字空间直接调用是没问题的。
mw.loader.addStyleTag：生成一个<style>元素，写入网页窗口的<head>中。mw.loader.getScript：1.33+启用，和jQuery.getScript具有相同的效果。但和jQuery.getScript相比默认开启缓存，后续执行的函数用then方法调用。mw.loader.getState：判断一个模块的状态，例如萌娘百科后台没有es6-polyfills，返回null。mw.loader.load：加载其他代码库、js或css，格式如下：mw.loader.load('模块名')，多个模块使用mw.loader.load(['模块1','模块2'])- 加载js：
mw.loader.load('//zh.moegirl.org.cn/w/index.php?title=MediaWiki:Gadget-HotCat.js&action=raw', 'text/javascript') - 加载css：
mw.loader.load('//zh.moegirl.org.cn/w/index.php?title=User:星海子/vector.css&action=raw', 'text/css')
mw.loader.state：更改一个模块的状态。mw.loader.using：基于jQuery的延迟对象加载其他代码库，然后调用库内函数，格式为：mw.loader.using(["模块1","模块2",……,"模块n"],需要使用模块的函数,报错函数)。亦可用then(需要使用模块的函数,报错函数)、done/fail等方法来调用需要使用模块的函数，表明实际的异步操作。
mw.now
mw.now等同于JavaScript中Date对象的getTime()函数，可以用其直接返回1970年1月1日0时0分0秒（UTC）至今的毫秒数。
mw.notify
mw.notify函数是mediawiki.notification.notify的简写，模块名mediawiki.notify在旧版本mw中作为调用它的重定向存在，该重定向自1.35合并入mediawiki.base模块中。该函数可以在网页右上角显示一个通知，如同气泡一般，格式为mw.notify("消息内容",{通知属性})。通知属性可以用的参数如下：
- autoHide和autoHideSeconds：设置通知显示一段时间后隐藏。
- tag：同一时刻同样tag的通知只会显示一个，如果要显示多个通知，就需要给通知设置不同的tag。
- title：设置通知的标题。
- type：快速设置通知的样式，例如'warn'、'error'和'success'。
- id和classes：通过制定通知的id和classes来设置通知样式。
mw.lib
想创建全局变量，又怕命名冲突？可以把变量塞进mw.lib里。
jQuery衍生库
mediaWiki内置了丰富的jQuery衍生代码库。
chosen
chosen是一个jQuery第三方库，可以用它快速生成一个下拉选择菜单，mediaWiki的编辑标签功能使用了这个库。
client
client能够获取客户端浏览器名称、布局、版本和操作系统信息，用于代替jQuery1.9版本中被废弃的默认函数browser，共有2个用法：
$.client.profile：直接获取客户端浏览器和操作系统的信息，用于后续的判断中。$.client.test：给出对浏览器和操作系统的限制信息，判断当前客户端是否符合要求，格式为$.client.test(限制,{配置},exactMatchOnly)，配置不设置时调用$.client.profile，exactMatchOnly指是否在浏览器未找到时返回真值。
colorUtil
colorUtil提供了调色盘（colors）、亮度调整（getColorBrightness(currentColor, mod)）、从CSS中寻找颜色（getRGB）、hsl模式与Rgb模式互转（rgbToHsl、hslToRgb）功能。
jQuery UI
从1.29开始，mediaWiki不推荐使用jQuery UI，建议使用OOjs UI代替，除非：
- 用jQuery UI写的东西配合
2010版wikieditor、gadget2.0、喂鸡友爱、old vector使用，因为这个版本的编辑器使用jQuery UI； - OOjs-ui不能提供的功能，jQuery UI能够提供。
1.34+的mw上提供完整的jQuery UI库，但1.31版本mw的萌娘百科后台只有一个个小模块。你需要这么来调用：
- 根据你需要使用的模块调用
jquery.ui.*(*为模块名，如dialog, widget）； 直接使用小工具提供的完整jquery.ui库（因服务器原因停止使用ext.gadget.jquery.ui）。
OOjs
面向对象（英语：Object-oriented），简写为OO，是当前MediaWiki推荐使用的JavaScript库，可视化编辑器、交互式浏览历史等使用它的UI库作为界面UI。
常用后台模块
mediawiki.api
mediaWiki提供的API模块能够给js提供数据库读写功能，对jQuery.ajax的再次包装使得它更加简单易学。mediawiki还提供了ForeignApi功能，可以用它来在萌娘百科的页面调取萌娘共享的api。
mediawiki.uri
uri用于设置一个外部链接，下面以一链接说明uri的基本参数：
http://username:[email protected]:81/dir/dir.2/index.html?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top
该链接中包含了url的八个参数：协议（http）、用户名（username）、密码（password）、端口（81）、主机（www.example.com）、网页路径（dir/dir.2/index.html）、查询目标（q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2）和章节（top），它们可以直接被读写。
可以使用new mw.Uri来定义一个新的uri，其拥有的方法列出部分如下：
- clone：克隆目标Uri，更加清晰地表现Uri的继承关系；
- extend：以对象的形式向目标Uri添加查询目标；
- toString：将Uri转化为链接字符串输出。
mediawiki.util
mw.util.addCSS在mw.loader.addStyleTag的基础上，将这个样式表定义为变量，通过sheet.disabled = !sheet.disabled这样的语句使用按钮对样式进行开关。mw.util.addPortletLink可以在侧边栏，工具箱等处插入一个链接。语法是addPortletLink( portletId, 链接, 链接内容, 链接id, 链接标题, 键盘快捷键, 链接位置)。- 函数变量顺序是固定的，空缺的值应当为null。
- 同默认的那些快捷键一样，键盘快捷键使用时需要同时按下alt和shift。
- 插入的链接位置在指定位置之前。如果不指定链接位置或该位置不存在，则链接将以append的形式插入。
mw.util.getParamValue用于读取链接中变量的值，格式为mw.util.getParamValue(变量名，链接)mw.util.isIPAddress可以判断输入的值是否为一个IP地址。同样的，还有isIPv4Address和isIPv6Address判断输入的值是否为IPv4/IPv6地址。mw.util.wikiUrlencode按照PHP规范对链接的字符串进行编码。
mediawiki.storage
mediawiki提供了safe storage类来包装localstorage，不过在1.31不提供储存json时与储存时格式——字符串互相转换的功能，也并不提供限时储存数据的功能，这样只要添加一个数据储存时间（单位：s），不需要额外判断时间就能从localstorage移除内容。
所以，这两周还是用User:AnnAngela/js/LocalObjectStorage吧。
Moment
（待补充）
es6-polyfills
在1.36整合的es6-polyfills，提供了Array.prototype.find, Array.prototype.findIndex, Array.prototype.find, Array.prototype.includes和Promise的polyfill，在1.31的萌娘百科可以使用来自阿里云、更全面的MediaWiki:Gadget-libPolyfill.js代替。
Vue
什么嘛，这都2024年了，mediawiki还不支持符合程序员对未来js库幻想的……哦是萌娘百科没有升级到1.35啊，那……还是有事的，这两年升到1.38才有前台能用的vue3。
下面将一个来自vue官网的例子本地化：
(async () => {
await Promise.all([$.ready, mw.loader.using(["vue"])]);
const { defineComponent, createApp } = Vue;
$("body").append('<div id="app"></div>');
const app = defineComponent({
template: `<div id="app">
<button @click="count++">{{ count }}</button>
</div>`,
data() {
return {
count: 0,
};
},
});
createApp(app).mount("#app");
})();
Widget调用js库
从mediawiki1.32开始，ResourceLoader.php中Widget常用的RLQ接口新增了一个方法，来调用需要在代码执行前加载的js库：
/**
* Wrap JavaScript code to run after a required module.
*
* @since 1.32
* @param string|string[] $modules Module name(s)
* @param string $script JavaScript code
* @return string JavaScript code
*/
public static function makeInlineCodeWithModule( $modules, $script ) {
// Adds an array to lazy-created RLQ
return '(RLQ=window.RLQ||[]).push(['
. self::encodeJsonForScript( $modules ) . ','
. 'function(){' . trim( $script ) . '}'
. ']);';
}
对应的Widget代码可以是：
window.RLQ = window.RLQ || [];
window.RLQ.push([module||["module1","module2",……"moduleN"],function(){
……
}]);
从1.34+开始，因为jQuery加载顺序原因，一部分Widget需要这种方法进行调用jQuery（虽然jQuery默认加载），使用mw.loader.using调用的不少模块也可以写入此处。