# How the Background Music Component Loads and Plays Audio in Luban H5

> Discover how the Luban H5 background music component loads and plays audio using a Vue plugin, HTML audio element, and reactive state for seamless playback control.

- Repository: [小小鲁班/luban-h5](https://github.com/ly525/luban-h5)
- Tags: internals
- Published: 2026-03-06

---

**The background music component in Luban H5 uses a Vue plugin named `lbp-bg-music` that renders a native HTML `<audio>` element with autoplay and loop attributes, controlling playback through a reactive `isPlaying` state and direct manipulation of the audio element's `play()` and `pause()` methods via Vue refs.**

The `luban-h5` repository provides a visual H5 page builder that includes a background music feature implemented as the `lbp-bg-music` plugin. This Vue component handles audio loading, automatic playback, and user-controlled toggling through a rotating control button, making it essential for creating immersive mobile web experiences.

## Component Architecture and Source Files

The background music functionality resides in the core plugins directory. The primary implementation file is [`front-end/h5/src/components/core/plugins/lbp-bg-music.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/lbp-bg-music.js), which defines the Vue component logic, template rendering, and playback controls.

The plugin registers with the editor through [`front-end/h5/src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/index.js), making it available in the component palette for drag-and-drop placement. Configuration UI elements appear in [`front-end/h5/src/components/core/editor/right-panel/background.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/right-panel/background.js), handling property panel interactions for selecting audio sources.

## Props and Configuration Interface

The component accepts three defined props that control its behavior:

```javascript
export default {
  name: 'lbp-bg-music',
  props: {
    disabled: PropTypes.boolean({ defaultValue: true, label: 'disabled' }),
    autoplay: PropTypes.boolean({ defaultValue: true, label: '自动播放' }),
    src: PropTypes.string({
      label: '音乐URL',
      defaultValue: 'http://go.163.com/2018/0209/mengniu/audio/bgm.mp3',
      props: { type: 'textarea' }
    })
  }
}

```

The **src** prop holds the music URL with a default value pointing to a sample MP3 file, ensuring immediate functionality when added to the canvas. The **autoplay** flag determines whether playback starts immediately, while **disabled** deactivates the component entirely.

## State Management and Lifecycle Hooks

The component maintains reactive state through a single data property:

```javascript
data: () => ({
  isPlaying: true
})

```

This **isPlaying** boolean drives both the CSS animation state of the control button and the logic determining whether the audio element should be playing or paused.

During the **created** lifecycle hook, the component initializes its state from the **autoplay** prop:

```javascript
created () {
  this.isPlaying = this.autoplay
}

```

This synchronization ensures that when **autoplay** is enabled, the component immediately enters a playing state, triggering the audio element's native autoplay behavior when the element renders.

## Rendering the Audio Element and Control Button

The component uses a JSX render function to create the DOM structure:

```javascript
render () {
  const btnStyle = {
    'animation-play-state': this.isPlaying ? 'running' : 'paused'
  }
  return (
    <div class="bg-music-wrapper" style="display: block;">
      <div class="bg-music-btn rotate"
           style={btnStyle}
           onClick={this.toggle}
           disabled={this.disabled}>
        <audio src={this.src}
               autoplay={this.autoplay}
               preload
               loop
               ref='bgAudio'></audio>
      </div>
    </div>
  )
}

```

The **audio** element receives the bound **src**, **autoplay**, **preload**, and **loop** attributes. The `ref='bgAudio'` attribute creates a direct reference to the native **HTMLAudioElement**, enabling imperative control through the Vue instance's **$refs** object.

The surrounding button element toggles playback when clicked and applies a rotating CSS animation that pauses or runs based on the **isPlaying** state through the **btnStyle** binding.

## Playback Control Logic and User Interaction

The component exposes a single **toggle** method that handles play/pause functionality:

```javascript
methods: {
  toggle () {
    const bgAudio = this.$refs.bgAudio
    if (!bgAudio) return

    this.isPlaying ? bgAudio.pause() : bgAudio.play()
    this.isPlaying = !this.isPlaying
  }
}

```

When invoked, the method retrieves the audio element via **this.$refs.bgAudio**. If the component currently reports **isPlaying** as true, it calls the native **pause()** method; otherwise, it calls **play()**. The method then flips the **isPlaying** boolean, which immediately updates the button's CSS animation state through the reactive binding established in the render function.

## Integration with the Luban H5 Editor

The background music component integrates into the visual editor through the core plugins registration system. In [`front-end/h5/src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/index.js), the plugin imports and registers as **LbpBgMusic**, adding it to the editor's component palette for drag-and-drop placement.

The right panel configuration interface, defined in [`front-end/h5/src/components/core/editor/right-panel/background.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/right-panel/background.js), renders property controls for the music URL and autoplay settings. When users modify these properties through the editor UI, the changes propagate to the component's props, immediately affecting the audio source and playback behavior in both the canvas preview and the published H5 page.

## Summary

- The **lbp-bg-music** component in [`front-end/h5/src/components/core/plugins/lbp-bg-music.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/lbp-bg-music.js) implements background music using a native HTML5 `<audio>` element wrapped in a Vue component.
- **Props** (`src`, `autoplay`, `disabled`) control the audio source, automatic playback, and component activation.
- **State management** uses a reactive `isPlaying` boolean synchronized with the `autoplay` prop during the `created` lifecycle hook.
- **Rendering** produces an `<audio>` element with `ref='bgAudio'` for imperative control, alongside a toggle button with CSS animation tied to playback state.
- **Playback control** relies on the native HTMLAudioElement API (`play()` and `pause()`) accessed through Vue refs, toggled via the `toggle()` method.
- **Editor integration** occurs through [`front-end/h5/src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/index.js) registration and right-panel configuration in [`background.js`](https://github.com/ly525/luban-h5/blob/main/background.js).

## Frequently Asked Questions

### How does the background music component handle automatic playback when a page loads?

The component sets its internal `isPlaying` state to the value of the `autoplay` prop during the `created` lifecycle hook. When `autoplay` is true, the native `<audio>` element receives the `autoplay` attribute, causing the browser to start playback immediately when the page loads, provided the user has interacted with the document or the browser's autoplay policies permit it.

### Can I programmatically control the background music from a parent component?

Yes, you can access the background music component's methods by assigning a ref to the component instance in your parent template. Once referenced, call the `toggle()` method to switch between play and pause states. The component directly manipulates the native HTMLAudioElement through `this.$refs.bgAudio`, giving you imperative control over playback.

### What audio formats does the background music component support?

The component relies on the browser's native HTML5 `<audio>` element, so supported formats depend entirely on the user's browser. Typically, MP3 files enjoy universal support across modern mobile and desktop browsers, while formats like OGG or WAV may have limited support on certain devices. The default `src` prop value points to an MP3 file, reflecting the most compatible choice for H5 pages.

### Where is the background music component registered in the Luban H5 editor?

The component registers in the core plugins index file located at [`front-end/h5/src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/plugins/index.js). This registration imports the `LbpBgMusic` component and adds it to the editor's component palette, allowing users to drag and drop background music elements onto the canvas. Configuration options appear in the right panel through [`front-end/h5/src/components/core/editor/right-panel/background.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/right-panel/background.js).