Skip to main content

Runtime

svelte/action

Edit this page on GitHub

action は、要素が作成されたときに呼び出される関数です。要素がアンマウントされたときに呼び出される destroy メソッドをもつオブジェクトを返すことができます。

App.svelte
<script>
	/** @type {import('svelte/action').Action}  */
	function foo(node) {
		// the node has been mounted in the DOM

		return {
			destroy() {
				// the node has been removed from the DOM
			}
		};
	}
</script>

<div use:foo />
App.svelte
<script lang="ts">
	import type { Action } from 'svelte/action';
	
	const foo: Action = (node) => {
		// the node has been mounted in the DOM
	
		return {
			destroy() {
				// the node has been removed from the DOM
			},
		};
	};
</script>

<div use:foo />

action はパラメータを取ることができます。戻り値に update メソッドがあると、そのパラメータが変化するときはいつも、Svelte がマークアップに更新を適用した直後にそのメソッドが呼び出されます。

すべてのコンポーネントインスタンスに対して foo 関数を再宣言しているという事実について心配する必要はありません。Svelte は、ローカル状態に依存しない関数をコンポーネント定義から巻き上げます。

App.svelte
<script>
	/** @type {string} */
	export let bar;

	/** @type {import('svelte/action').Action<HTMLElement, string>}  */
	function foo(node, bar) {
		// the node has been mounted in the DOM

		return {
			update(bar) {
				// the value of `bar` has changed
			},

			destroy() {
				// the node has been removed from the DOM
			}
		};
	}
</script>

<div use:foo={bar} />
App.svelte
<script lang="ts">
	import type { Action } from 'svelte/action';
	
	export let bar: string;
	
	const foo: Action<HTMLElement, string> = (node, bar) => {
		// the node has been mounted in the DOM
	
		return {
			update(bar) {
				// the value of `bar` has changed
			},
	
			destroy() {
				// the node has been removed from the DOM
			},
		};
	};
</script>

<div use:foo={bar} />

Attributes

action がカスタムイベントを発行し、適用する要素にカスタム属性を適用することがあります。これをサポートするために、Action 型または ActionReturn 型の action は最後のパラメータとして Attributes を持つことができます:

App.svelte
<script>
	/**
	 * @type {import('svelte/action').Action<HTMLDivElement, { prop: any }, { 'on:emit': (e: CustomEvent<string>) => void }>}
	 */
	function foo(node, { prop }) {
		// the node has been mounted in the DOM

		//...LOGIC
		node.dispatchEvent(new CustomEvent('emit', { detail: 'hello' }));

		return {
			destroy() {
				// the node has been removed from the DOM
			}
		};
	}
</script>

<div on:emit={handleEmit} use:foo={{ prop: 'someValue' }} />
App.svelte
<script lang="ts">
	import type { Action } from 'svelte/action';
	
	const foo: Action<
		HTMLDivElement,
		{ prop: any },
		{ 'on:emit': (e: CustomEvent<string>) => void }
	> = (node, { prop }) => {
		// the node has been mounted in the DOM
	
		//...LOGIC
		node.dispatchEvent(new CustomEvent('emit', { detail: 'hello' }));
	
		return {
			destroy() {
				// the node has been removed from the DOM
			},
		};
	};
</script>

<div on:emit={handleEmit} use:foo={{ prop: 'someValue' }} />

Types

Action

Actions are functions that are called when an element is created. You can use this interface to type such actions. The following example defines an action that only works on <div> elements and optionally accepts a parameter which it has a default value for:

ts
export const myAction: Action<HTMLDivElement, { someProperty: boolean } | undefined> = (node, param = { someProperty: true }) => {
// ...
}

Action<HTMLDivElement> and Action<HTMLDivElement, undefined> both signal that the action accepts no parameters.

You can return an object with methods update and destroy from the function and type which additional attributes and events it has. See interface ActionReturn for more details.

Docs: https://svelte.dev/docs/svelte-action

ts
interface Action<
Element = HTMLElement,
Parameter = undefined,
Attributes extends Record<string, any> = Record<
never,
any
>
> {}
ts
<Node extends Element>(
...args: undefined extends Parameter
? [node: Node, parameter?: Parameter]
: [node: Node, parameter: Parameter]
): void | ActionReturn<Parameter, Attributes>;

ActionReturn

Actions can return an object containing the two properties defined in this interface. Both are optional.

  • update: An action can have a parameter. This method will be called whenever that parameter changes, immediately after Svelte has applied updates to the markup. ActionReturn and ActionReturn<undefined> both mean that the action accepts no parameters.
  • destroy: Method that is called after the element is unmounted

Additionally, you can specify which additional attributes and events the action enables on the applied element. This applies to TypeScript typings only and has no effect at runtime.

Example usage:

ts
interface Attributes {
newprop?: string;
'on:event': (e: CustomEvent<boolean>) => void;
}
export function myAction(node: HTMLElement, parameter: Parameter): ActionReturn<Parameter, Attributes> {
// ...
return {
update: (updatedParameter) => {...},
destroy: () => {...}
};
}

Docs: https://svelte.dev/docs/svelte-action

ts
interface ActionReturn<
Parameter = undefined,
Attributes extends Record<string, any> = Record<
never,
any
>
> {}
ts
update?: (parameter: Parameter) => void;
ts
destroy?: () => void;