Or How I Learned to Stop Worrying and Love Custom Directives
Another in my "stuff I got stuck on" series! The solution to this particular problem ended up being rather straightforward, perhaps to the point of obvious, but arriving at it was a roundabout process for me so here's hoping this is useful for someone anyway.
Vue provides directives to hook your templates to your scripts. For most cases these are sufficient, but controlling a canvas
element requires lower-level DOM access. <canvas>
does not support v-model
, so we need some other way to pass data into the element for rendering in such a way that it can keep itself in sync with our ViewModel.
As luck would have it, they'd thought of that. With custom directives we can make our own v-something
for our template for which we can define our own behavior.
This code is written to fit in a project created by the Vue CLI 3.0 with the "TypeScript" option selected and class-style component syntax. It should be simple to use with other configurations - the meat here is the directive itself. See the doc links for the full syntax.
We'll work with a bare minimum Single-File Class-Based Component:
<template>
<div class="rxcanvas">
<span>{{ size }}</span>
<input type="range" min="1" max="100" step="5" id="size" v-model="size">
<label for="size">- Size</label>
<p><canvas></canvas></p>
</div>
</template>
<script lang="ts">
import { Component, Vue } from "vue-property-decorator";
import Dot from "@/dot"; // defined below
@Component
export default class RxCanvas extends Vue {
private data() {
return {
size: 10
};
}
// computed property
get dot(): Dot {
return new Dot(this.$data.size);
}
}
</script>
<style scoped>
</style>
Our Dot class just knows to draw itself given a Canvas element for a target:
// dot.ts
export default class Dot {
private readonly color: string = "#000";
constructor(private radius: number) { }
public draw(canvas: HTMLCanvasElement): void {
// resize canvas to dot size
const canvasDim = this.radius * 2;
canvas.width = canvasDim;
canvas.height = canvasDim;
// get context for drawing
const ctx = canvas.getContext('2d')!;
// start with a blank slate
ctx.clearRect(0, 0, canvas.width, canvas.height);
// find the centerpoint
const centerX = canvas.width / 2;
const centerY = canvas.height / 2;
// create the shape
ctx.beginPath();
ctx.arc(centerX, centerY, this.radius, 0, 2 * Math.PI, false);
ctx.fillStyle = this.color;
ctx.fill();
ctx.stroke();
}
}
To get the behavior we want, i.e. a properly sized and drawn-to canvas in sync with our slider input, there's a little more logic that we want to fire on each change than simply bumping a number. We've hidden all that logic inside our Dot
class - Dot.draw(el)
knows how to do everything it needs. We just need this method to automatically fire whenever there's a change.
For starters, we can throw the directive right on to the canvas element in our template - we already know what data it's concerned with:
<canvas v-draw="dot"></canvas>
In this example, our custom directive is called draw
. You could name it anything you like. All directives are prefixed v-
. We're passing in "dot"
, which is the computed property defined on our RxCanvas
class. This way whenever size
changes, this computed property will create a new Dot with the correct size.
Custom directives are defined on the Vue component. When using vue-property-decorator
, you can place it in the decorator options:
@Component({
directives: {
"draw": function(canvasElement, binding) {
// casting because custom directives accept an `Element` as the first parameter
binding.value.draw(canvasElement as HTMLCanvasElement);
}
}
})
export default class RxCanvas extends Vue {
// data(), dot(), etc
}
...and that's it! binding.value
contains the actual Dot
we get from our computed property. This syntax takes advantage of a shorthand available for directives allowing us to condense the definition and not spell out each hook we use. Acknowledging that in most cases users of this feature will want the same logic to happen on bind
and update
, we just define a function with our logic for the directive instead of an object containing hook functions and it gets that behavior by default. Without using the shorthand, you'd define this logic as following:
directives: {
draw: {
bind: function(canvasElement: Element, binding: VNodeDirective) {
binding.value.draw(canvasElement as HTMLCanvasElement);
},
update: function(canvasElement, binding) {
binding.value.draw(canvasElement as HTMLCanvasElement);
}
}
}
The bind
rule is fired exactly once on component creation, and the update
rule will happen any time there is a change to the VNode
instance created from the RxCanvas
class - which includes changes to its data
. Spelling it out like this is verbose and repetitive - prefer the shorthand where possible.
This custom directive will only be available on your RxCanvas
component. If you'd like to use it on multiple components, define it globally:
// index.ts
Vue.directive('draw': function(canvasElement, binding) {
binding.value.draw(canvasElement as HTMLCanvasElement);
});
Huzzah!
Top comments (4)
Just one thing to have in mind. It's not
<canvas>
that doesn't support Vue's v-model, it's Vue's v-model that doesn't support<canvas>
.Let's not make it sound like it's the browser's fault.
Fair enough! You're absolutely right, that wording could be clearer. We shouldn't expect to be able to use
v-model
, it doesn't make senseCool example of directive usage. Thanks.
I had the same task the other day. My solution was to use :key in component containing canvas. Whenever I change the key in my vuex store - my canvas gets redrawn.
Interesting, I hadn't thought of that! Thanks for the tip.