InterfaceAdmin
/
QiuwenGadgets
1
0
派生 1
代码 工单 合并请求 项目 版本发布 百科 动态
QiuwenGadgets/docs/how-to-build-or-deploy.md

7.7 KiB
原始文件 永久链接 Blame 文件历史

用法 / Usage

对于小工具开发者：
For gadget developers:

  1. Fork 由目标 MediaWiki 网站所维护的仓库
    Fork the repository maintained by the target MediaWiki website

  2. 在src文件夹下以小工具名新建文件夹
    Create a new folder within the src directory, using the name of your gadget

  3. 在目录下新建小工具名.{js, ts, css, less}或index.{js, ts, css, less}
    Within the directory, create either GadgetName.{js, ts, css, less} or index.{js, ts, css, less}

编译时的优先级如下：
The priority of compilation is as follows:

  1. index.* > 小工具名.* / index.* > GadgetName.*
  2. *.{tsx, ts} > *.{jsx, js}
  3. *.{jsx, tsx} > *.{js, ts}
  4. *.less > *.css
  5. .vue仅供被其他脚本导入 / .vue files are only allowed import by other script files

  • 如果小工具包含脚本，且使用单独的样式表，则其所使用到的样式表应在脚本中导入
    If the gadget has script files and style sheets, the style sheets used should be imported in script files

  • 如果小工具仅包含样式表，则不需要在脚本中导入（无需新建一个脚本文件）
    If the gadget only has style sheets, there is no need to import style sheets in any script files. (no need to create a script file)

  1. 目录下可以创建definition.json以手动指定小工具定义（可选）
    In the directory, you have the option to create a definition.json file to manually specify the gadget definition

    {
	// 示例 / Example
	"actions": ["view", "edit"],
	"contentModels": ["wikitext"],
	"dependencies": ["mediawiki.util"],
	"namespaces": [0],
	"peers": ["peers"],
	"rights": ["rollback"],
	"skins": ["vector"],
}

  2. 目录下可以创建LICENSE以标注小工具的版权信息（可选），文件中的内容会在编译后自动添加到对应小工具文件的顶部
    In the directory, you have the option to create a LICENSE file to indicate the copyright information of your gadget. The content of this file will be automatically added to the top of the gadget file when it is compiled

  3. 运行pnpm run build以格式化代码、检查语法、测试编译
    Run pnpm run build to format the code, check syntax, and test the compilation

  4. 向上游发起 Pull Request
    Initiate a Pull Request to the upstream

脚本可以是 ts 或 js，可以使用 ESNext 所支持的语法（如import，支持跨目录导入）；导入的图片将被自动转换成 Data URLs（如data:image/png;base64,...）
The scripts can be in either TypeScript or JavaScript and can utilize the syntax supported by ESNext, such as import, which allows importing across directories. Imported images will be automatically converted to Data URLs, like data:image/png;base64,....

样式可以是 Less 或 CSS，支持@import语法。
The styles can be written in either Less or CSS and support the @import syntax.

对于网站维护者：
For website maintainers:

  1. Fork 本仓库
    Fork this repository

  2. 根据实际情况更改各个小工具的definition.json，可选值及默认值可见于scripts/constant.ts - DEFAULT_DEFINITION
    Modify the definition.json for each gadget according to your specific requirements. Optional values and their default values can be found in scripts/constant.ts - DEFAULT_DEFINITION

  3. 根据实际情况更改scripts/constant.ts中的信息
    Update the information in scripts/constant.ts based on your specific needs

  4. 在script文件夹下新建credentials.json文件（同一站点存在多种登录凭据时，OAuth2 优先于 OAuth1.0a 优先于机器人账号密码）
    Create a credentials.json file in the script directory (If multiple login credentials are available for a site, OAuth2 takes precedence over OAuth1.0a, which takes precedence over bot password)

    {
	// 站点名称 / Site name
	"siteA": {
		"apiUrl": "https://your.wiki/api.php", // 根据实际情况修改 / Modify according to actual needs
		"username": "", // 填入机器人账号和密码（可以在[[Special:BotPasswords]]获取）/ Enter the robot account and password (you can get it from [[Special:BotPasswords]])
		"password": "",
	},
	"siteB": {
		"apiUrl": "https://your.wiki/api.php", // 根据实际情况修改 / Modify according to actual needs
		"OAuth2AccessToken": "", // 填入 OAuth2 访问密钥 / Enter the OAuth2 access token
	},
	"siteC": {
		"apiUrl": "https://your.wiki/api.php", // 根据实际情况修改 / Modify according to actual needs
		"OAuthCredentials": {
			// 填入 OAuth1.0a 相关信息 / Enter the OAuth1.0a related information
			"accessToken": "16_DIGIT_ALPHANUMERIC_KEY",
			"accessSecret": "20_DIGIT_ALPHANUMERIC_KEY",
			"consumerToken": "16_DIGIT_ALPHANUMERIC_KEY",
			"consumerSecret": "20_DIGIT_ALPHANUMERIC_KEY",
		},
	},
}

    也可以将字符串化后的credentials.json文本声明为CREDENTIALS_JSON环境变量。此时，credentials.json文件将被忽略
    You can declare the stringified credentials.json text as the CREDENTIALS_JSON environment variable, in which case the credentials.json file will be ignored.

    根据工具需要，你应该授予机器人账号以下额外权限
    Grant the robot account the following additional permissions:

    • 大量编辑
      High-volume editing
    • 编辑存在的页面
      Edit existing pages
    • 编辑受保护的页面
      Edit protected pages
    • 编辑MediaWiki命名空间和全站/用户的JSON
      Edit the MediaWiki namespace and sitewide/user JSON
    • 编辑全站和用户的CSS/JS
      Edit sitewide and user CSS/JS
    • 创建、编辑和移动页面
      Create, edit, and move pages
    • 删除页面、修订和日志记录
      Delete pages, revisions, and log entries

  5. 运行pnpm run deploy以检查语法、格式化代码、编译源码、并向网站部署
    Run pnpm run deploy to check syntax, format code, compile the source code, and deploy to the website

直接部署 MediaWiki:Common.js 等 MediaWiki 命名空间下的脚本或样式

  1. 在src文件夹下新建global.json文件，如下所示
    Create a global.json file in the src directory, as shown below:

    {
	"siteA": {
		"Commmon.js": {
			"enable": true,
			"sourceCode": "mw.loader.using(['ext.gadget.Common']);", // 此处的代码不会经过编译，仅支持 CSS 或使用 ES5 语法的 JavaScript / The code here will not be compiled, only supports CSS or JavaScript using ES5 syntax
			"licenseText": "", // 可选 / Optional
		},
		"Skin.js": {
			"enable": true,
			"sourceCode": "mw.loader.using(['ext.gadget.Skin']);",
		},
	},
}

  2. 按正常流程部署即可
    Deploy according to the above process