贡献

¥Contributing

欢迎对库作出新的贡献，但我们要求你遵循以下准则：

¥New contributions to the library are welcome, but we ask that you please follow these guidelines:

• 在为主要添加或更改打开 PR 之前，请讨论预期的 API 和/或 提交问题 (opens new window) 的实现或在 Chart.js Discord (opens new window) #dev 通道中询问。这将通过提前获得反馈来节省你的开发时间，并通过为维护者提供更多上下文和详细信息来加快审查速度。

  ¥Before opening a PR for major additions or changes, please discuss the expected API and/or implementation by filing an issue (opens new window) or asking about it in the Chart.js Discord (opens new window) #dev channel. This will save you development time by getting feedback upfront and make reviews faster by giving the maintainers more context and details.

• 考虑你的更改是否对所有用户都有用，或者创建一个 Chart.js plugin 是否更合适。

  ¥Consider whether your changes are useful for all users, or if creating a Chart.js plugin would be more appropriate.

• 检查你的代码是否会通过测试和 eslint 代码标准。pnpm test 将为你运行 linter 和测试。

  ¥Check that your code will pass tests and eslint code standards. pnpm test will run both the linter and tests for you.

• 添加单元测试并记录新功能（分别在 test/ 和 docs/ 目录中）。

  ¥Add unit tests and document new functionality (in the test/ and docs/ directories respectively).

• 除非即将发布主要版本，否则避免破坏性更改，这种情况并不常见。我们鼓励人们为最新的高级功能编写插件，并且非常关心向后兼容性。

  ¥Avoid breaking changes unless there is an upcoming major release, which is infrequent. We encourage people to write plugins for the most new advanced features, and care a lot about backward compatibility.

• 我们强烈希望尽可能将新方法添加为私有方法。方法可以通过在类外部创建顶层 function 或在其前面加上 _ 并在类内部添加 @private JSDoc 来使方法私有化。公共 API 需要花费大量时间进行审查，一旦实现就会被锁定，因为我们在不破坏向后兼容性的情况下更改它们的能力有限。私有 API 允许灵活地解决不可预见的情况。

  ¥We strongly prefer new methods to be added as private whenever possible. A method can be made private either by making a top-level function outside of a class or by prefixing it with _ and adding @private JSDoc if inside a class. Public APIs take considerable time to review and become locked once implemented as we have limited ability to change them without breaking backward compatibility. Private APIs allow the flexibility to address unforeseen cases.

加入项目

¥Joining the project

邀请活跃的提交者和贡献者进行自我介绍并请求提交对该项目的访问权限。我们有一个非常活跃的 Discord 社区，你可以加入 此处 (opens new window)。如果你认为可以提供帮助，我们很乐意邀请你！

¥Active committers and contributors are invited to introduce themselves and request commit access to this project. We have a very active Discord community that you can join here (opens new window). If you think you can help, we'd love to have you!

构建和测试

¥Building and Testing

首先，我们需要确保安装了开发依赖。安装 node 和 pnpm 后，将 Chart.js 存储库克隆到本地目录，并在命令行中导航到该目录后，我们可以运行以下命令：

¥Firstly, we need to ensure development dependencies are installed. With node and pnpm installed, after cloning the Chart.js repo to a local directory, and navigating to that directory in the command line, we can run the following:

> pnpm install

这将为 Chart.js 安装本地开发依赖。

¥This will install the local development dependencies for Chart.js.

现在可以从存储库根目录中使用以下命令：

¥The following commands are now available from the repository root:

> pnpm run build             // build dist files in ./dist
> pnpm run autobuild         // build and watch for source changes
> pnpm run dev               // run tests and watch for source and test changes
> pnpm run lint              // perform code linting (ESLint, tsc)
> pnpm test                  // perform code linting and run unit tests with coverage

pnpm run dev 和 pnpm test 可以附加一个用于匹配规范文件名的字符串。例如：pnpm run dev plugins 将在监视模式下为 test/specs/**/*plugin*.js 启动业力。

¥pnpm run dev and pnpm test can be appended with a string that is used to match the spec filenames. For example: pnpm run dev plugins will start karma in watch mode for test/specs/**/*plugin*.js.

文档

¥Documentation

我们使用 Vuepress (opens new window) 来管理 docs 目录中作为 Markdown 文件包含的文档。你可以使用以下命令在本地运行文档服务器：

¥We use Vuepress (opens new window) to manage the docs which are contained as Markdown files in the docs directory. You can run the doc server locally using these commands:

> pnpm run docs:dev

基于图片的测试

¥Image-Based Tests

一些与显示相关的功能很难通过典型的 Jasmine 单元进行测试。出于这个原因，我们引入了基于图片的测试（#3988 (opens new window) 和 #5777 (opens new window)）来断言图表是逐像素绘制的，与预期图片匹配。

¥Some display-related functionality is difficult to test via typical Jasmine units. For this reason, we introduced image-based tests (#3988 (opens new window) and #5777 (opens new window)) to assert that a chart is drawn pixel-for-pixel matching an expected image.

基于图片的测试中生成的图表应尽可能少，并且仅关注测试的功能，以防止其他功能损坏时出现故障（例如，在测试比例时禁用标题和图例）。

¥Generated charts in image-based tests should be as minimal as possible and focus only on the tested feature to prevent failure if another feature breaks (e.g. disable the title and legend when testing scales).

你可以按照以下步骤创建新的基于图片的测试：

¥You can create a new image-based test by following the steps below:

• 创建定义图表配置和生成选项的 JS 文件 (示例 (opens new window)) 或 JSON 文件 (示例 (opens new window))。

  ¥Create a JS file (example (opens new window)) or JSON file (example (opens new window)) that defines chart config and generation options.

• 在 test/fixtures/{spec.name}/{feature-name}.json 中添加此文件。

  ¥Add this file in test/fixtures/{spec.name}/{feature-name}.json.

• 如果 描述行 (opens new window) 尚不存在，则在 test/specs/{spec.name}.tests.js 的开头添加一个 描述行 (opens new window)。

  ¥Add a describe line (opens new window) to the beginning of test/specs/{spec.name}.tests.js if it doesn't exist yet.

• 运行 pnpm run dev。

  ¥Run pnpm run dev.

• 单击 "调试" 按钮（顶部/右侧）：测试应该失败并且关联的画布可见。

  ¥Click the "Debug" button (top/right): a test should fail with the associated canvas visible.

• 右键单击图表和 "将图片另存为..." test/fixtures/{spec.name}/{feature-name}.png 确保不激活工具提示或任何悬停功能

  ¥Right-click on the chart and "Save image as..." test/fixtures/{spec.name}/{feature-name}.png making sure not to activate the tooltip or any hover functionality

• 刷新浏览器页面（CTRL+R）：测试现在应该通过

  ¥Refresh the browser page (CTRL+R): test should now pass

• 通过稍微更改 JSON 文件中的特性值来验证测试相关性。

  ¥Verify test relevancy by changing the feature values slightly in the JSON file.

测试应该在两个浏览器中通过。通常，我们在图片测试中隐藏了所有文本，因为很难让它们在不同浏览器之间传递。因此，建议在基于图片的测试中隐藏所有比例。还建议禁用动画。如果测试仍未通过，请调整 JSON 文件开头的 tolerance 和/或 threshold (opens new window)，使其尽可能低。

¥Tests should pass in both browsers. In general, we've hidden all text in image tests since it's quite difficult to get them to pass between different browsers. As a result, it is recommended to hide all scales in image-based tests. It is also recommended to disable animations. If tests still do not pass, adjust tolerance and/or threshold (opens new window) at the beginning of the JSON file keeping them as low as possible.

当测试失败时，将显示预期图片和实际图片。如果你希望在测试通过后仍能看到图片，请在 JSON 文件中设置 "debug": true。

¥When a test fails, the expected and actual images are shown. If you'd like to see the images even when the tests pass, set "debug": true in the JSON file.

错误和问题

¥Bugs and Issues

请在 GitHub 页面上报告这些内容 - at github.com/chartjs/Chart.js。请不要将问题用于支持请求。如需使用 Chart.js 的帮助，请查看 Stack Overflow 上的 chart.js (opens new window) 标签。

¥Please report these on the GitHub page - at github.com/chartjs/Chart.js. Please do not use issues for support requests. For help using Chart.js, please take a look at the chart.js (opens new window) tag on Stack Overflow.

结构良好、详细的错误报告对于项目来说非常有价值。

¥Well-structured, detailed bug reports are hugely valuable for the project.

错误报告指南：

¥Guidelines for reporting bugs:

• 检查问题搜索以查看它是否已被报告

  ¥Check the issue search to see if it has already been reported

• 将问题隔离为一个简单的测试用例

  ¥Isolate the problem to a simple test case

• 请在 贾斌 (opens new window)、JS 小提琴 (opens new window) 或 Codepen (opens new window) 等网站上包含该错误的演示。(模板 (opens new window))。如果针对 master 提交错误，你可以通过 https://chart.nodejs.cn/dist/master/chart.umd.js (opens new window) 引用最新代码（更改文件名以根据需要指向你需要的文件）。不要依赖这些文件用于生产目的，因为它们可能随时被删除。

  ¥Please include a demonstration of the bug on a website such as JS Bin (opens new window), JS Fiddle (opens new window), or Codepen (opens new window). (Template (opens new window)). If filing a bug against master, you may reference the latest code via https://chart.nodejs.cn/dist/master/chart.umd.js (opens new window) (changing the filename to point at the file you need as appropriate). Do not rely on these files for production purposes as they may be removed at any time.

请提供与错误相关的任何其他详细信息，如果它是特定于浏览器或屏幕密度的，或者仅发生在特定配置或数据上。

¥Please provide any additional details associated with the bug, if it's browser or screen density specific, or only happens with a certain configuration or data.