入门教程_入门

入门教程

In this post, I want to share my experience and lessons learned contributing to @angular/components and collaborating with the team at Google maintaining it. As an engineer at Infragistics, among other things, I am responsible for developing and maintaining our IgxOverlayService. It allows rendering of an Angular component or an ElementRef overlaying other content in an app. Think dialogs, drop downs, tooltips and so on.

在这篇文章中，我想分享我对@ angular / components的贡献以及与Google团队合作维护它的经验教训。 作为Infragistics的工程师，我负责开发和维护IgxOverlayService 。 它允许渲染Angular组件或ElementRef覆盖应用程序中的其他内容。 考虑对话框，下拉菜单，工具提示等。

Several months ago I looked at Angular Components CDK (Component Dev Kit) — a set of tools that implement common interaction patterns whilst being un-opinionated about their presentation. It represents an abstraction of the core functionalities found in the Angular Material library, without any styling specific to Material Design. Think of the CDK as a blank state of well-tested functionality upon which you can develop your own bespoke components. One of the abstractions that it provides is an overlay service. This service has very similar functionality to the one I am responsible for in our product. Angular Components Overlay service also allows rendering of an Angular component or template overlaying other content in an app. This service looked like a good fit. Instead of implementing our own services I decided that we could use the ones provided by CDK. I started investigating if the CDK overlay is feature complete for our requirements.

几个月前，我研究了Angular Components CDK (组件开发工具包)，这是一组实现通用交互模式而又不妨碍其表示的工具。 它代表了在Angular Material库中找到的核心功能的抽象，而没有任何特定于Material Design的样式。 将CDK视为经过良好测试的功能的空白状态，在此状态下您可以开发自己的定制组件。 它提供的一种抽象方法是覆盖服务 。 这项服务的功能与我在产品中负责的功能非常相似。 Angular Components Overlay服务还允许渲染Angular组件或模板以覆盖应用程序中的其他内容。 这项服务看起来很合适。 我决定不使用自己的服务，而可以使用CDK提供的服务。 我开始调查CDK覆盖是否符合我们的要求。

入门 (Getting Started)

I had a meeting with the management at Infragistics to discuss the possibility of switching from our IgxOverlayService to the Angular Components SDK Overlay. We decided that if we switched to the Angular overlay service we would have less code to maintain and we would be able to contribute to Angular Components open source project. Finally, the decision was made to try to switch to SDK Overlay. To make the switch happen developers at Infragistics were given the possibility to spend several hours a day contributing to Angular Components.

我与Infragistics的管理层开会，讨论了从IgxOverlayService切换到Angular Components SDK叠加层的可能性。 我们决定，如果切换到Angular覆盖服务，我们将需要维护的代码更少，并且我们将能够为Angular Components开源项目做出贡献。 最后，决定尝试切换到SDK叠加层。 为了实现这一转变，Infragistics的开发人员可以每天花几个小时为Angular Components做出贡献。

As a first step, I forked the repository, built the packages, ran the dev-app, and started looking at the contribution process and the standards that the Angular Components team follows. As soon as I felt more comfortable with the code I started looking at the issues in Material Components public repository on GitHub. If you want to contribute this is a nice first step to take along with helping with the documentation. Here’s a strategy for you to get started:

第一步，我分叉了存储库，构建了程序包，运行了dev-app，并开始研究了贡献过程和Angular Components团队遵循的标准。 当我对代码感到更加满意后，便开始查看GitHub上的Material Components公共存储库中的问题。 如果您想做出贡献，那么这是迈向文档帮助的第一步。 这是您入门的策略：

• Look at the issues.
  看问题。
• Grab one.
  抓住一个。
• Try to solve it.
  尝试解决它。

The more issues you go through the more familiar you get with the code and the way components are developed and work. Before contributing it’s important to look at “Contributing to Angular Material” guidelines. They will help you avoid common pitfalls when getting started with open source.

您遇到的问题越多，您对代码以及组件的开发和工作方式就越熟悉。 在进行贡献之前，请务必先阅读“ 对角材料做出贡献 ”指南。 他们将帮助您避免在开始使用开源程序时遇到的常见陷阱。

新功能 (New Features)

After I went through several issues and started to feel comfortable with the library I took a look at the Overlay service and found that some specific features I needed were missing there. For example, the ability to render pure HTML elements, as well as allow the service to attach its final elements hierarchy at a particular place in the DOM. This is where I decided that I can suggest additional features to the Angular Components team and try to implement them myself.

在经历了几个问题并开始对库感到满意之后，我看了一下Overlay服务 ，发现那里缺少我需要的某些特定功能。 例如，呈现纯HTML元素的功能以及允许服务将其最终元素层次结构附加到DOM中特定位置的能力。 在这里，我决定向Angular Components团队推荐其他功能，并尝试自己实现这些功能。

Dictum factum. Together, with my team lead and product owner, we connected with the Angular Components team. After several emails we had a meeting with them to discuss the new features we needed in the overlay service. They were happy about our willingness to contribute to the product. They also explained the process of adding new features to the project. The most important was: do not break existing functionality. As they said, this library is used in many thousands of applications and all of them should work after a change is merged.

Dictum事实。 与我的团队负责人和产品负责人一起，我们与Angular Components团队建立了联系。 在收到几封电子邮件之后，我们与他们开会讨论了叠加服务中所需的新功能。 他们对我们为产品做出贡献的意愿感到高兴。 他们还解释了向项目添加新功能的过程。 最重要的是： 不要破坏现有功能 。 正如他们所说，该库已在成千上万的应用程序中使用，并且所有更改合并后都应该可以使用。

设计文件 (Design Documents)

The first step in adding a new functionality is the creation of a design document. You can find the collection of all design documents of the Angular components team on their wiki page on GitHub. Before writing your design doc it is a good idea to check the existing ones and use the recommended template to start with. After checking the overlay design doc, as well as some more of the existing ones, I wrote a document for each feature I needed in the Angular Components Overlay. The process was hard and demanding for me, but rewarding in the end. Adding a new feature to the framework may look easy, but when you start to write the design document you find how hard it is. You have to see how the feature will work from all points of view as well as how it will integrate with the existing features. Writing all this in the document helped me to clarify my vision of the features I needed. For example, here are a few of the questions I had to answer:

添加新功能的第一步是创建设计文档。 您可以在GitHub的Wiki页面上找到 Angular组件团队的所有设计文档的集合。 在编写设计文档之前，最好检查一下现有文档并使用推荐的模板开始。 在检查了覆盖设计文档以及一些其他现有文档之后，我为Angular Components Overlay中需要的每个功能编写了文档。 这个过程很艰辛，对我来说很苛刻，但最终却很有意义。 向框架添加新功能可能看起来很容易，但是当您开始编写设计文档时，您会发现它有多难。 您必须从各个角度查看功能的工作方式以及如何与现有功能集成。 将所有这些内容写到文档中有助于我阐明我对所需功能的看法。 例如，以下是我必须回答的一些问题：

• Is there another implementation out there to compare it with?
  是否有另一个实现可与之比较？
• How could the feature be implemented?
  该功能如何实现？
• What would the API be?
  API是什么？

Once I finished the design documents, they had to go through a review by the Angular team. The Angular team was really fast and responsive. As soon as I had sent my design doc I had a review the very next day (your timing may vary). All the reviews I’ve got were concise, positive, and constructive. After addressing all the comments I got the green light to implement the features.

一旦我完成了设计文档，它们就必须经过Angular团队的审查。 Angular团队的React速度非常快。 当我发送设计文档后，第二天就进行了审核(您的时间可能会有所不同)。 我收到的所有评论都是简洁，积极和建设性的。 在解决所有评论之后，我获得了实现功能的绿灯。

The first feature I focused on was the ability of an overlay to render a DOM element or an ElementRef. Fortunately, as soon as I completed the design document, and it was accepted by the Angular Components team, they told me this feature is already implemented and was included in a PR. I took a look at the PR and asked for some changes since some of the changes I needed were included in the PR.

我关注的第一个功能是叠加层渲染DOM元素或ElementRef 。 幸运的是，当我完成设计文档并被Angular Components团队接受后，他们告诉我此功能已经实现，并已包含在PR中 。 我查看了PR，并要求进行一些更改，因为我需要的某些更改已包含在PR中。

实作 (Implementation)

The second feature I actually developed was the functionality to close the overlay on an outside click. Imagine a modal dialog where one can click outside the dialog and this should close it. You can find the design document that explains the implementation details and the prior work here. With the design doc approved I start coding. It is not much different from fixing a bug. I implemented the feature and added the necessary tests. I tested in all supported environments. Pushed my changes and created a PR. Then members of the Angular Components team checked my PR and requested some changes. After all the requested changes were made the feature was added to the framework. My merged PR is available here.

我实际上开发的第二个功能是在外部单击时关闭覆盖的功能。 想象一个模态对话框，在该对话框中，您可以在对话框外部单击，然后将其关闭。 您可以在此处找到解释实施细节和先前工作的设计文档。 获得设计文档批准后，我便开始编码。 它与修复错误没有太大的不同。 我实现了该功能并添加了必要的测试。 我在所有受支持的环境中进行了测试。 推送我的更改并创建PR。 然后，Angular Components团队的成员检查了我的PR，并要求进行一些更改。 完成所有请求的更改后，该功能已添加到框架中。 我合并的PR 在这里可用。

The new feature helped the Angular Components team to solve some of the issues logged in the project. For example, MatMenu is using SDK’s overlay. When - user opens a menu it is shown with back drop and this makes the menu modal (issue 6927). As a result, users are not able to interact with the application items while the menu is open. Using the new detachOnOutsideClick feature helps to solve this issue. There are several other issues that could be solved with the help of this new functionality such as 9320; 15899 and 16036.

新功能帮助Angular Components团队解决了项目中记录的一些问题。 例如，MatMenu使用SDK的叠加层。 当-用户打开菜单时，带有返回的菜单显示出来，这使菜单变为模态的(issue 6927 )。 结果，当菜单打开时，用户将无法与应用程序项进行交互。 使用新的detachOnOutsideClick功能有助于解决此问题。 借助9320等新功能，还可以解决其他一些问题。 15899和16036 。

This story shares my experience as an Angular Component contributor. In the beginning it was intimidating. I wasn’t sure where to start and how everything worked together. However, if you start step by step: find the components you need, debug to figure out the flow of execution, and follow the contribution process then everything will come into place naturally. In the end I was really happy with my work. I learned a lot: the way Angular developers are using RxJS, how the tests in the framework are organized and more. Of course the feeling that you are contributing to a project used by tens of thousands of engineers is great. Also finding that the people responsible for the project are open to new ideas and very friendly. If you have some free time, go ahead, check the issues at Angular Components and fix one!

这个故事分享了我作为Angular Component贡献者的经验。 一开始它是令人生畏的。 我不确定从哪里开始以及一切如何协同工作。 但是，如果您一步一步开始：找到所需的组件，进行调试以找出执行流程，然后按照贡献过程进行操作，那么一切自然就会就绪。 最后，我对自己的工作感到非常满意。 我学到了很多东西：Angular开发人员使用RxJS的方式，框架中的测试如何组织等等。 当然，您为成千上万的工程师使用的项目做贡献的感觉很棒。 还发现负责项目的人员乐于接受新想法并且非常友好。 如果您有空闲时间，请继续进行操作，检查Angular Components中的问题并解决！

翻译自: https://blog.angular.io/how-i-contributed-to-angular-components-b3a8830ca268

入门教程