Qiuwen Gadgets

简介 / Introduction

本代码库为求闻百科的界面样式、界面脚本和小工具代码库。相关样式表及 JavaScript 优化了求闻百科访客及编者的用户体验，并且为求闻百科用户提供了大量执行常见维护任务的方法。

致谢 / Acknowledgement

求闻百科小工具库是基于 Awesome Gadgets 打造的。

Awesome Gadgets 是面向 MediaWiki 网站，用以统一存储、管理并编译全站小工具（Gadget）的工具。小工具开发者只需关心小工具本身的代码实现，无需关心其他方面。工具将自动检查语法、编译并部署到网站。
Awesome Gadgets is a tool designed specifically for MediaWiki websites, with the goal of centralizing the storage, management, and compilation of all site-wide gadgets. Developers of these gadgets can solely focus on implementing the code for their creations without the need to worry about other aspects. The tool will automatically check the syntax, compile, and deploy gadgets to the website.

• 使用 esbuild 编译，babel 转译，支持 TypeScript 和 Less
  It harnesses esbuild for compilation, babel for transpilation, and supports TypeScript and Less
• 部署时将自动部署
  During deployment, it automatically deploys to the following
  • MediaWiki:Gadgets-definition
  • MediaWiki:Gadget-section-*（支持自动转换中文变体）/ (with automatic conversion for Chinese variations)
  • MediaWiki:Gadget-*（支持自动转换中文变体）/ (with automatic conversion for Chinese variations)
  • MediaWiki:Gadget-*.{js, css}
• 部署后将自动从网站内删除曾经部署过但现在不再需要的页面
  After deployment, it automatically deletes pages from the website that have been deployed but are no longer needed

用法

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

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

2. 在src文件夹下以小工具名新建文件夹
   Create a new directory 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}

   1. 当存在入口文件{小工具名, index}.{js, ts, css, less}时
      If there exists an entry file {GadgetName, index}.{js, ts, css, less}:

      1. 只存在小工具名.{js, ts, css, less}，将最终生成小工具名.{js, css}，其他的脚本/样式是否被编译将取决于其是否被小工具名.{js, ts, css, less}导入
         Only exists GadgetName.{js, ts, css, less}, the final generation will be GadgetName.{js, css}. The compilation of other scripts/styles will depend on whether they are imported by GadgetName.{js, ts, css, less}
      2. 只存在index.{js, ts, css, less}，将最终生成小工具名-index.{js, css}，其他的脚本/样式是否被编译将取决于其是否被index.{js, ts, css, less}导入
         Only exists index.{js, ts, css, less}, the final generation will be GadgetName-index.{js, css}. The compilation of other scripts/styles will depend on whether they are imported by index.{js, ts, css, less}
      3. 二者同时存在，将最终生成小工具名-index.{js, css}，小工具名.{js, ts, css, less}和其他的脚本/样式是否被编译将取决于其是否被index.{js, ts, css, less}导入
         Both exist, the final generation will be GadgetName-index.{js, css}, GadgetName.{js, ts, css, less}. The compilation of other scripts/styles will depend on whether they are imported by index.{js, ts, css, less}

   2. 不存在入口文件时，所有的脚本/样式均会被编译，生成小工具名-对应文件名.{js, css}
      If no entry file exists, all scripts/styles will be compiled, generating GadgetName-CorrespondingFileName.{js, css}

4. 目录下可以创建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], // or false
   	"package": false,
   	"peers": ["peers"],
   	"rights": ["rollback"],
   	"skins": ["vector"]
   }
   

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

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

7. 向上游发起 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 (choose one based on your login method. If multiple login credentials are available, OAuth2 takes precedence over OAuth1.0a, which takes precedence over bot password)

   {
   	"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": ""
   }
   

   {
   	"apiUrl": "https://your.wiki/api.php", // 根据实际情况修改 / Modify according to actual needs
   	"OAuth2AccessToken": "" // 填入 OAuth2 访问密钥 / Enter the OAuth2 access token
   }
   

   {
   	"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"
   	}
   }
   

   根据工具需要，你应该授予机器人账号以下额外权限
   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

请网站维护者注意：在 Fork 本仓库后，本仓库的 Actions 将自动同步上游变更。这意味着在一般情况下，不需要改动除了src文件夹和scripts/constant.ts之外的东西，以免发生合并冲突。
Please note that the Actions of this repository will automatically sync upstream changes. This means that in general, there is no need to modify anything except the src directory and scripts/constant.ts to avoid merge conflicts.

建议网站维护者只接受 Pull request，以便 Actions 自动检查并指出代码语法和格式的错误。如果检查未能通过，也不应修改本仓库的相关规则。未通过意味着代码本身存在问题，而不应该将问题归咎于严格的规则。
It is recommended for website maintainers to only accept pull requests, so that the Actions can automatically check and report syntax and formatting errors. If a check fails, it should not result in modifying the relevant rules of this repository. A failure indicates an issue with the code itself and should not be attributed to strict rules.

最佳实践 / Best practices

• QiuwenGadgets (@qiuwenbaike)