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/documentation/docs/04-compiler-and-api/02-client-side-component-ap...

255 lines
6.7 KiB

This file contains invisible Unicode characters!

This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.

---
title: 'Client-side component API'
---
## Creating a component
```ts
// @errors: 2554
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var options: ComponentConstructorOptions<Record<string, any>>;
}
// @filename: index.ts
// @errors: 2554
// ---cut---
const component = new Component(options);
```
A client-side component — that is, a component compiled with `generate: 'dom'` (or the `generate` option left unspecified) is a JavaScript class.
```ts
// @errors: 2554
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare module './App.svelte' {
class Component extends SvelteComponent {}
export default Component;
}
// @filename: index.ts
// @errors: 2554
// ---cut---
import App from './App.svelte';
const app = new App({
target: document.body,
props: {
// assuming App.svelte contains something like
// `export let answer`:
answer: 42
}
});
```
The following initialisation options can be provided:
| option | default | description |
| --------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `target` | **none** | An `HTMLElement` or `ShadowRoot` to render to. This option is required |
| `anchor` | `null` | A child of `target` to render the component immediately before |
| `props` | `{}` | An object of properties to supply to the component |
| `context` | `new Map()` | A `Map` of root-level context key-value pairs to supply to the component |
| `hydrate` | `false` | See below |
| `intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes |
Existing children of `target` are left where they are.
The `hydrate` option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the [`hydratable: true` option](/docs/svelte-compiler#compile). Hydration of `<head>` elements only works properly if the server-side rendering code was also compiled with `hydratable: true`, which adds a marker to each element in the `<head>` so that the component knows which elements it's responsible for removing during hydration.
Whereas children of `target` are normally left alone, `hydrate: true` will cause any children to be removed. For that reason, the `anchor` option cannot be used alongside `hydrate: true`.
The existing DOM doesn't need to match the component — Svelte will 'repair' the DOM as it goes.
```ts
/// file: index.js
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare module './App.svelte' {
class Component extends SvelteComponent {}
export default Component;
}
// @filename: index.ts
// @errors: 2322 2554
// ---cut---
import App from './App.svelte';
const app = new App({
target: document.querySelector('#server-rendered-html'),
hydrate: true
});
```
## `$set`
```ts
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
var props: Record<string, any>;
}
export {};
// @filename: index.ts
// ---cut---
component.$set(props);
```
Programmatically sets props on an instance. `component.$set({ x: 1 })` is equivalent to `x = 1` inside the component's `<script>` block.
Calling this method schedules an update for the next microtask — the DOM is _not_ updated synchronously.
```ts
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
}
export {};
// @filename: index.ts
// ---cut---
component.$set({ answer: 42 });
```
## `$on`
```ts
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
var ev: string;
var callback: (event: CustomEvent) => void;
}
export {};
// @filename: index.ts
// ---cut---
component.$on(ev, callback);
```
Causes the `callback` function to be called whenever the component dispatches an `event`.
A function is returned that will remove the event listener when called.
```ts
/// file: index.js
// @errors: 7006
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
}
export {};
// @filename: index.ts
// ---cut---
const off = component.$on('selected', (event) => {
console.log(event.detail.selection);
});
off();
```
## `$destroy`
```js
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
}
export {}
// @filename: index.ts
// ---cut---
component.$destroy();
```
Removes a component from the DOM and triggers any `onDestroy` handlers.
## Component props
```js
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
}
export {}
// @filename: index.ts
// @errors: 2339
// ---cut---
component.prop;
```
```js
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
var value: unknown;
}
export {}
// @filename: index.ts
// @errors: 2339
// ---cut---
component.prop = value;
```
If a component is compiled with `accessors: true`, each instance will have getters and setters corresponding to each of the component's props. Setting a value will cause a _synchronous_ update, rather than the default async update caused by `component.$set(...)`.
By default, `accessors` is `false`, unless you're compiling as a custom element.
```js
/// file: index.js
// @filename: ambient.d.ts
import { SvelteComponent, ComponentConstructorOptions } from 'svelte';
declare global {
class Component extends SvelteComponent {}
var component: Component;
var props: Record<string, any>;
}
export {}
// @filename: index.ts
// @errors: 2339
// ---cut---
console.log(component.count);
component.count += 1;
```