README

OOUI 是一个基于组件的 JavaScript UI 库。主要特性

• 常用小部件、布局和对话框
• 类、元素和混入以创建自定义界面
• 国际化本地化，如支持从右到左（RTL）语言
• 可定制主题
• 内置图标
• 无障碍功能

它是维基媒体基金会的 Web 产品的标准库，最初是为 VisualEditor 使用而创建的。

快速入门

该库可在 npm 上找到。要安装

$ npm install oojs-ui

安装后，包含以下脚本和样式以开始使用

<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/oojs/dist/oojs.min.js"></script>

<script src="node_modules/oojs-ui/dist/oojs-ui.min.js"></script>
<script src="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.js"></script>
<link rel="stylesheet" href="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.css">

加载库

虽然分发目录中文件众多，但您通常只需要加载以下三个

• oojs-ui.js，包含完整库；
• 其中之一 oojs-ui-wikimediaui.css 或 oojs-ui-apex.css，包含特定于主题的样式；以及
• 其中之一 oojs-ui-wikimediaui.js 或 oojs-ui-apex.js，包含特定于主题的代码

您还可以从名为 oojs-ui-wikimediaui-icons-*.css 或 oojs-ui-apex-icons-*.css 的文件中加载额外的图标包。

其余文件使您能够仅加载整个库的部分。

此外，每个 CSS 文件都有一个从右到左（RTL）版本，如果您的环境不自动翻转它们，则可用于使用从右到左语言的文章。

问题跟踪器

发现了一个错误或缺失的功能？请在我们的 问题跟踪器 Phabricator 中报告它！

贡献

当人们贡献补丁时，我们总是很高兴。为了设置您的开发环境

1. 克隆仓库：$ git clone https://gerrit.wikimedia.org/r/oojs/ui oojs-ui

2. 移动到库目录
   $ cd oojs-ui

3. 安装 composer 并确保运行 composer 将执行它（例如，在 POSIX 环境中将它添加到 $PATH 中）。

4. 安装开发依赖项
   $ npm install

5. 构建库（如果您不需要重新构建 PNG，则可以交替使用 grunt quick-build）
   $ grunt build

6. 通过执行 $ npm run-script demos 可以在 /demos 中查看一系列演示。
   $ npm run-script demos

7. 您还可以将分发目录中的文件从 dist 目录复制到您的项目中。

8. 您可以通过在根目录中运行 php -S localhost:80 来启动本地 Web 服务器。

9. 您可以通过访问 http://localhost/tests/ 在您的浏览器中本地运行测试。

我们使用 Gerrit 进行代码审查，并使用 Phabricator 跟踪问题。要贡献补丁或加入讨论，您只需要一个 开发者账户。

• 如果您发现了一个错误，或希望请求一个功能，请在 Phabricator 上创建一个工单。
• 要提交您的补丁，请遵循 “入门”快速指南。我们试图在一周内审查补丁。
• 我们自动对JavaScript、PHP、LESS/CSS、Ruby和JSON文件进行代码检查和样式检查。您可以在推送更改之前，通过本地运行npm test和composer test自行测试。在提交之前，应使用SVGO（SVGO）压缩SVG文件，命令如下：svgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs <filename>。

图书馆的新版本每周二发布。

社区

获取更新，提问并与维护者和贡献者加入讨论。

• 加入维基媒体开发者邮件列表：wikitech-l。
• 在irc.libera.chat上的#wikimedia-dev频道与维护者聊天。
• 在StackOverflow上提问。StackOverflow。
• 关注MediaWiki上的文档以保持更新。

版本控制

我们使用语义化版本控制指南。

发布将按照以下格式编号

<主版本>.<次版本>.<修订版本>

发布

先决条件

• 如果您还没有，请创建一个NPM账号。
• 验证您能否登录您的NPM账号。
• 验证您是否被列为oojs-ui包的维护者。如果不是，请要求现有的维护者添加您。
• 确保您已设置了两步验证（2FA）。
• 运行npm login并按照步骤操作。您只需在每个电脑上做一次。如果您不确定是否已经做过，可以运行npm whoami；如果它打印出您的NPM用户名，则表示您已经登录。
• 克隆mediawiki/vendor仓库：[https://gerrit.wikimedia.org/r/admin/repos/mediawiki/vendor,general](https://gerrit.wikimedia.org/r/admin/repos/mediawiki/vendor,general)

准备和提交发布提交

从此仓库的根目录，更新master并检出新的release分支。

$ git remote update
$ git checkout -B release -t origin/master

清除安装npm依赖项，更新Composer依赖项，并确保测试通过。

$ npm ci && composer update && npm test && composer test

生成此发布版本所包含的提交列表。

$ git log --format='* %s (%aN)' --no-merges v$(node -e 'console.log(require("./package").version);')...HEAD | grep -v "Localisation updates from" | sort

在History.md中，为这个版本添加一个新的标题和日期。将提交列表复制到新的部分，并按顺序排序成五个子部分，省略任何没有提交的子部分。

### Breaking changes
### Deprecations
### Features
### Styles
### Code

生成此发布版本的Phabricator任务列表。复制生成的列表并保存以备后用。在后续步骤中，您将将其添加到MediaWiki核心提交的提交消息中。

$ git log --pretty=format:%b v$(node -e 'console.log(require("./package").version);')...HEAD | grep Bug: | sort | uniq

更新版本号（在以下命令中，如果您已进行了破坏性更改，将'patch'更改为'minor'）

$ npm version patch --git-tag-version=false

提交发布并提交到Gerrit。注意，如果与此发布相关联的Phabricator任务，您应在运行git review之前编辑提交以添加错误号。

$ git add -u
$ git commit -m "Tag v$(node -e 'console.log(require("./package").version);')"
$ git review

发布标签并推送到NPM

在标签提交合并到此仓库后，推送标签并将其发布到NPM。

$ git remote update
$ git checkout origin/master
$ git tag "v$(node -e 'console.log(require("./package").version);')"
$ npm run publish-build && git push --tags && npm publish

更新mediawiki/vendor仓库

在您的本地mediawiki/vendor仓库中，将composer指向新版本并拉取更新的供应商文件。

# Replace 1.2.34 with the version number of the new release
$ composer require oojs/oojs-ui 1.2.34 --no-update
$ composer update --no-dev

然后使用以下提交消息提交更改，将1.2.34替换为新的OOUI版本号（示例：[https://gerrit.wikimedia.org/r/c/mediawiki/vendor/+/813629](https://gerrit.wikimedia.org/r/c/mediawiki/vendor/+/813629)）。

$ git add -u
$ git commit

提交信息格式

Update OOUI to v1.2.34

  Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.md

将此推送到gerrit。注意提交信息中的Change-Id。复制它并保存以备后用。您将在更新MediaWiki时需要它。

$ git review
# Show the last commit
$ git show --stat

更新MediaWiki核心仓库

在您的本地 MediaWiki 核心仓库中，打开 composer.json 并将 oojs/oojs-ui 的版本号更新为新版本号。

打开 RELEASE-NOTES-1.NN。如果已经有关于 OOUI 的项目列表项，更新最新的版本号。例如，如果有一个项目列表项说“从 v1.2.0 更新到 v1.2.33”，则更新后者版本号为 v1.2.34。如果没有关于 OOUI 的项目列表项，请在 Changed external libraries（更改外部库）部分添加一个。

打开 resources/lib/foreign-resources.yaml。对于 OOUI 列表，更改 version（版本）、purl 和 src URL 以使用新版本号。计算新的完整性哈希。

$ php maintenance/run.php manageForeignResources make-sri ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-sri ooui

然后更新 OOUI 库文件。

$ php maintenance/run.php manageForeignResources update ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources update ooui

然后运行以下命令来更新 foreign-resources.cdx.json。

$ php maintenance/run.php manageForeignResources make-cdx
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-cdx

然后使用以下提交信息提交更改，将 1.2.34 替换为新的 OOUI 版本号。

$ git add -u
$ git commit

提交信息格式，其中错误列表是在 OOUI 标签步骤期间生成的列表，Depends-On 设置为 mediawiki/vendor 提交的 Change-Id。

Update OOUI to v1.2.34

  Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.md

Bug: T123456
Bug: T234567
Depends-On: I12345678901234567890

然后将该提交推送到 gerrit。

git review

更新 VisualEditor/VisualEditor 仓库。

在您的本地 VisualEditor/VisualEditor 仓库中，运行脚本以创建一个提交，更新本地 OOUI 复制，并将提交推送到 Gerrit。

$ ./bin/update-ooui.sh
$ git review