markdown 附上图书馆

Posted 2021-05-05

Libraries can be attached to all pages, a subset of pages, or to elements in a render array. This allows you to have some assets that are global, and others that are only loaded on an as-needed basis.

Note: While the example below covers how to attach a library in a theme, the same steps work for modules. In the case of modules you'll most likely want to use `#attached` as part of a Render Array.

- Attach a library globally to all pages
- Attach a library to a specific page
- Use #attached to add a library conditionally via a preprocess function
- Attach a library from a Twig template

## Attach a library globally

**Note: You can only attach libraries in themes**

In order to attach a library globally, or to every page on your site, you can specify the library in your `THEMENAME.info.yml` file. Since our site is using a custom theme (called Retro), we'll open up `/themes/custom/retro/retro.info.yml`
```
name: retro
type: theme
description: An amazing Retro theme
package: Other
core: 8.x
libraries:
  - retro/global-styling
  - retro/rainbow
  - retro/retro

base theme: bartik
```
Any libraries specified here in the `THEMENAME.info.yml` file will be made available on every page. Because of this you'll want to take extra care with this approach. With an asset library that provides something like an analytics tracking code this global approach might be a good idea. Often, however, you don't actually need an asset library on every single page.

## Attach a library to a specific page
In most cases it's best to restrict the conditions in which your library is attached to a page. So let's remove our library from `retro.info.yml` and figure out how to add it on only the front page.

One method of conditionally restricting when your library is attached is to use the `hook_page_attachments_alter` function in our `retro.theme` file or in a module's `*.module` file.
```
/**
* Implements hook_page_attachments_alter
*/
function retro_page_attachments_alter(array &$page) {
  // Get the current path.
  $path = \Drupal::service('path.current')->getPath();
  // If we're on the node listing page, add our retro library.
  if ($path == '/node') {
    $page['#attached']['library'][] = 'retro/retro';
  }
}
```

By implementing `hook_page_attachments_alter()` we're able to add conditional logic that determines whether or not our asset library will be included on the page. In the example here we're only adding the retro library to the node listing page (the default front page).

## Use `#attached` to add a library conditionally via a preprocess function

Another useful way to conditionally add a library is by using a preprocess function like `hook_preprocess_page()`. Here's another example of restricting our retro asset library to the front page.
```
/**
* Implements hook_preprocess_page() for PAGE document templates.
*/
function retro_preprocess_page(&$variables) {
  if ($variables['is_front'] == TRUE) {
    $variables['#attached']['library'][] = 'retro/retro';
  }
}
```
This method of attaching a library works in preprocess functions, in manipulating form elements, or render arrays.

## Attach a library from a Twig template

Asset libraries can also be attached from within a Twig template using the `attach_library` filter. Anytime that template is used the corresponding library will be attached in accordance with any template-specific conditions.

In order to see this in action, we need to create a template in our Retro theme. Since we're using Bartik as our base theme, we can copy the `node.html.twig` from Bartik into our theme directory. After rebuilding the cache, we can see this new template in action. Let's add a bit of code so that our retro library is only added to the page if we're viewing node 1.
```
{# only attach our retro library if this is node 1 #} 
{% if node.id == 1 %}
  {{ attach_library('retro/retro') }}
{% endif %}
```
With this in place, visiting node 1 we can see our retro library in action. Visiting any other node we can see that our library (nor any of its dependencies) has not been attached to the page.