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/docs/01-component-format.md

194 lines
4.6 KiB

---
title: Component format
---
---
Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML.
All three sections — script, styles and markup — are optional.
```html
<script>
// logic goes here
</script>
<style>
/* styles go here */
</style>
<!-- markup (zero or more items) goes here -->
```
### &lt;script&gt;
A `<script>` block contains JavaScript that runs when a component instance is created. Variables declared (or imported) at the top level are 'visible' from the component's markup. There are four additional rules:
##### 1. `export` creates a component prop
---
Svelte uses the `export` keyword to mark a variable declaration as a *property* or *prop*, which means it becomes accessible to consumers of the component:
```html
<script>
// these properties can be set externally
export let foo;
export let bar = 'optional default value';
// Values that are passed in as props
// are immediately available
console.log(foo, bar);
// function declarations cannot be set externally,
// but can be accessed from outside
export function instanceMethod() {
alert(foo);
}
</script>
```
##### 2. Assignments are 'reactive'
---
To change component state and trigger a re-render, just assign to a locally declared variable.
Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect.
```html
<script>
let count = 0;
function handleClick () {
// calling this function will trigger a re-render
// if the markup references `count`
count = count + 1;
}
</script>
```
##### 3. `$:` marks a statement as reactive
---
Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` label. Reactive statements run immediately before the component updates, whenever the values that they depend on have changed.
```html
<script>
export let title;
// this will update `document.title` whenever
// the `title` prop changes
$: document.title = title;
$: {
console.log(`multiple statements can be combined`);
console.log(`the current title is ${title}`);
}
</script>
```
---
If a statement consists entirely of an assignment to an undeclared variable, Svelte will inject a `let` declaration on your behalf.
```html
<script>
export let num;
// we don't need to declare `squared` and `cubed`
// — Svelte does it for us
$: squared = num * num;
$: cubed = squared * num;
</script>
```
##### 4. Prefix stores with `$` to access their values
---
Any time you have a reference to a store, you can access its value inside a component by prefixing it with the `$` character. This causes Svelte to declare the prefixed variable, and set up a store subscription that will be unsubscribed when appropriate.
Note that the store must be declared at the top level of the component — not inside an `if` block or a function, for example.
Local variables (that do not represent store values) must *not* have a `$` prefix.
```html
<script>
import { writable } from 'svelte/store';
const count = writable(0);
console.log($count); // logs 0
count.set(1);
console.log($count); // logs 1
</script>
```
### &lt;script context="module"&gt;
---
A `<script>` tag with a `context="module"` attribute runs once when the module first evaluates, rather than for each component instance. Values declared in this block are accessible from a regular `<script>` (and the component markup) but not vice versa.
You can `export` bindings from this block, and they will become exports of the compiled module.
You cannot `export default`, since the default export is the component itself.
```html
<script context="module">
let totalComponents = 0;
// this allows an importer to do e.g.
// `import Example, { alertTotal } from './Example.svelte'`
export function alertTotal() {
alert(totalComponents);
}
</script>
<script>
totalComponents += 1;
console.log(`total number of times this component has been created: ${totalComponents}`);
</script>
```
### &lt;style&gt;
---
CSS inside a `<style>` block will be scoped to that component.
This works by adding a class to affected elements, which is based on a hash of the component styles (e.g. `svelte-123xyz`).
```html
<style>
p {
/* this will only affect <p> elements in this component */
color: burlywood;
}
</style>
```
---
To apply styles to a selector globally, use the `:global(...)` modifier.
```html
<style>
:global(body) {
/* this will apply to <body> */
margin: 0;
}
div :global(strong) {
/* this will apply to all <strong> elements, in any
component, that are inside <div> elements belonging
to this component */
color: goldenrod;
}
</style>
```