You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
svelte/site/content/guide/98-api-reference.md

156 lines
3.9 KiB

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
title: API reference
---
## TODO MAKE THIS CURRENT, INCLUDE svelte, svelte/store, ETC ETC
As we saw above, you create a component instance with the `new` keyword:
```js
/* { filename: 'main.js' } */
import App from './App.html';
const component = new App({
// `target` is the only required option. This is the
// DOM element your component will be appended to
target: document.querySelector('main'),
// `anchor` is optional.
// The component is inserted immediately before this
// DOM element, which must be a child of `target`
anchor: document.querySelector('main #child'),
// `props` is optional. A component can also have
// default props we'll learn about that later.
props: {
questions: [
'life',
'the universe',
'everything'
],
answer: 42
}
});
```
Normally, you'd interact with a component by getting and setting *props*:
```js
console.log(component.answer); // 42
component.answer = 420;
```
Every Svelte component instance has three built-in methods:
### component.$set(props)
This updates the component's state with the new values provided and causes the DOM to update. `state` must be a plain old JavaScript object (POJO). Any properties *not* included in `state` will remain as they were.
```js
component.set({
questions: [
'why is the sky blue?',
'how do planes fly?',
'where do babies come from?'
],
answer: 'ask your mother'
});
```
### component.get()
Returns the component's current state:
```js
const { questions, answer } = component.get();
console.log(answer); // 'ask your mother'
```
This will also retrieve the value of [computed properties](docs#computed-properties).
> Previous versions of Svelte allowed you to specify a key to retrieve a specific value — this was removed in version 2.
### component.on(eventName, callback)
Allows you to respond to *events*:
```js
const listener = component.on('thingHappened', event => {
console.log(`A thing happened: ${event.thing}`);
});
// some time later...
listener.cancel();
```
Each component has three built-in events, corresponding to their [lifecycle hooks](docs#lifecycle-hooks):
```js
component.on('state', ({ changed, current, previous }) => {
console.log('state changed', current);
});
component.on('update', ({ changed, current, previous }) => {
console.log('DOM updated after state change', current);
});
component.on('destroy', () => {
console.log('this component is being destroyed');
});
```
### component.fire(eventName, event)
The companion to `component.on(...)`:
```js
component.fire('thingHappened', {
thing: 'this event was fired'
});
```
At first glance `component.on(...)` and `component.fire(...)` aren't particularly useful, but it'll become more so when we learn about [nested components](docs#nested-components) and [component events](docs#component-events).
### component.destroy()
Removes the component from the DOM and removes any event listeners that were created. This will also fire a `destroy` event:
```js
component.on('destroy', () => {
alert('goodbye!'); // please don't do this
});
component.destroy();
```
### component.options
The options used to instantiate the component are available in `component.options`.
```html
<!-- { title: 'component.options' } -->
Check the console.
<script>
export default {
oncreate() {
console.log(this.options);
}
};
</script>
```
This gives you access to standard options like `target` and `data`, but can also be used to access any other custom options you may choose to implement for your component.
### component.root
In [nested components](docs#nested-components), each component has a `root` property pointing to the top-level root component that is, the one instantiated with `new MyComponent({...})`.
> Earlier versions of Svelte had a `component.observe(...)` method. This was removed in version 2, in favour of the `onstate` [lifecycle hook](docs#lifecycle-hooks), but is still available via [svelte-extras](https://github.com/sveltejs/svelte-extras).