Stencil指南

概述

Web component

Web Components 是一套不同的技术，允许您创建可重用的定制元素（它们的功能封装在您的代码之外）并且在您的web应用中使用它们。

—— MDN

• Custom elements（自定义元素）：一组JavaScript API，允许您定义custom elements及其行为，然后可以在您的用户界面中按照需要使用它们。

• Shadow DOM（影子DOM）：一组JavaScript API，用于将封装的“影子”DOM树附加到元素（与主文档DOM分开呈现）并控制其关联的功能。通过这种方式，您可以保持元素的功能私有，这样它们就可以被脚本化和样式化，而不用担心与文档的其他部分发生冲突。

• HTML templates（HTML模板）： <template> 和 <slot> 元素使您可以编写不在呈现页面中显示的标记模板。然后它们可以作为自定义元素结构的基础被多次重用。

Stencil

stencil.js

• @Component() declares a new web component

• @Prop() declares an exposed property/attribute

• @State() declares an internal state of the component

• @Watch() declares a hook that runs when a property or state changes

• @Element() declares a reference to the host element

• @Method() declares an exposed public method

• @Event() declares a DOM event the component might emit

• @Listen() listens for DOM events

JSX

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {
    render(){
        return <div>hello stencil</div>
    }
}

Typescript

装饰器

@Component

export interface ComponentOptions {
  /**
   * Tag name of the web component. Ideally, the tag name must be globally unique,
   * so it's recommended to choose a unique prefix for all your components within the same collection.
   *
   * In addition, tag name must contain a '-'
   */
  tag: string;

  /**
   * If `true`, the component will use scoped stylesheets. Similar to shadow-dom,
   * but without native isolation. Defaults to `false`.
   */
  scoped?: boolean;

  /**
   * If `true`, the component will use native shadow-dom encapsulation, it will fallback to `scoped` if the browser
   * does not support shadow-dom natively. Defaults to `false`.
   *
   * If an object literal containing `delegatesFocus` is provided, the component will use native shadow-dom
   * encapsulation. When `delegatesFocus` is set to `true`, the component will have `delegatesFocus: true` added to its
   * shadow DOM. When `delegatesFocus` is `true` and a non-focusable part of the component is clicked:
   * - the first focusable part of the component is given focus
   * - the component receives any available `focus` styling
   * Setting `delegatesFocus` to `false` will not add the `delegatesFocus` property to the shadow DOM and therefore
   * will have the focusing behavior described for `shadow: true`.
   */
  shadow?: boolean | { delegatesFocus: boolean };

  /**
   * Relative URL to some external stylesheet file. It should be a `.css` file unless some
   * external plugin is installed like `@stencil/sass`.
   */
  styleUrl?: string;

  /**
   * Similar as `styleUrl` but allows to specify different stylesheets for different modes.
   */
  styleUrls?: string[] | d.ModeStyles;

  /**
   * String that contains inlined CSS instead of using an external stylesheet.
   * The performance characteristics of this feature are the same as using an external stylesheet.
   *
   * Notice, you can't use sass, or less, only `css` is allowed using `styles`, use `styleUrl` if you need more advanced features.
   */
  styles?: string;

  /**
   * Array of relative links to folders of assets required by the component.
   */
  assetsDirs?: string[];

  /**
   * @deprecated Use `assetsDirs` instead
   */
  assetsDir?: string;
}

@Method

// my-button
@Component({
  tag: 'my-button',
  shadow: true,
})
export class MyButton {
  @Method() method1() {
    console.log('method1');
  }
  method2() {
    console.log('method2');
  }
  render(){return <div></div>}
}

// my-component
@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {
   componentDidRender() {
    customElements.whenDefined('my-button');
    let test = document.querySelector('my-button');
    console.log(test);  // web component
    test.method1(); // method1
    test.method2(); // 失败
  }
  render(){
      return (<div> <my-button></my-button> </div>)
  }
}

注意： 在尝试调用公共方法之前，开发人员应该确保组件已经使用了注册自定义元素的whenDefined方法。

@Method装饰的公共方法必须是异步的。可以使用async函数或者返回Promise

大多数情况下不建议声明公开的方法，尽可能地使用默认的属性和事件，随着应用地不断扩展，通过@Prop方法来管理和传递数据会更加容易

@Prop

@Component({
    tag: 'todo-list',
})
export class TodoList {
    // Second, we decorate a class member with @Prop()
    @Prop() name: string;

    render() {
        // Within the component's class, its props are
        // accessed via `this`. This allows us to render
        // the value passed to `todo-list`
        return <div>To-Do List Name: {this.name}</div>
    }
}

数据流

@Event

// 子组件
...
export class TodoList {
  @Event() todoCompleted: EventEmitter<Todo>;
  todoCompletedHandler(todo: Todo) {
    this.todoCompleted.emit(todo);
  }
}
// 父组件
...
export class Todo {
    render(){
        return <todo-list onTodoCompletedHandler={()=>{ ... }}></todo-list>
    }
}

export interface EventOptions {
  /**
   * A string custom event name to override the default.
   */
  eventName?: string;
  /**
   * A Boolean indicating whether the event bubbles up through the DOM or not.
   */
  bubbles?: boolean;

  /**
   * A Boolean indicating whether the event is cancelable.
   */
  cancelable?: boolean;

  /**
   * A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM.
   */
  composed?: boolean;
}

@Listen

...
export class Todo {
  @Listen('click')
  clickHandler() {
    console.log('Listen');
  }
  render(){
      return <div>123</div>
  }
}

export interface ListenOptions {
  target?: 'body' | 'document' | 'window';  // 表明事件监听器挂载到哪里，默认是当前组件
  capture?: boolean;
  passive?: boolean;
}

@State()

@Component({
    tag: 'current-time',
})
export class CurrentTime {
    @State() time: number = Date.now();
    render() {
        return (
            <span>{time}</span>
        );
    }
}

并非所有的类成员都需要@State装饰，如果你确定该值不会更改或不需要触发重新呈现，那么就没必要使用@State

// 以下写法不会触发重新渲染
arr.push(1)
arr.pop()
arr[2] = 1
obj['a'] = '1'
// 以下方式可以触发重新渲染
arr = [...arr,1]
arr = arr.concat([1,2,3])
obj = {...obj,a:'1'}

@Watch

export class LoadingIndicator {
  @Prop() activated: boolean;
  @State() busy: boolean;

  @Watch('activated')
  watchPropHandler(newValue: boolean, oldValue: boolean) {
    console.log('The new value of activated is: ', newValue);
  }
  @Watch('busy')
  watchStateHandler(newValue: boolean, oldValue: boolean) {
    console.log('The new value of busy is: ', newValue);
  }
}

组件生命周期

框架集成

原生HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <my-button>click me</my-button>
</body>
<script type="module" src="./dist/first-webcomponent/first-webcomponent.esm.js"></script>

Vuejs

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 将所有包含短横线的标签作为自定义元素处理
          isCustomElement: tag => tag.includes('-')
        }
      }
    })
  ]
}

// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          // 将所有以 ion- 开头的标签作为自定义元素处理
          isCustomElement: tag => tag.startsWith('ion-')
        }
      }))
  }
}

import { defineCustomElements } from "./webcomponents/esm/loader";
defineCustomElements();

踩坑笔记

注意this的指向

<button onClick={() => handleLink}></button>
// 或者
<button onClick={handleLink.bind(this)}></button>

enmu与type

"@stencil/core": "^2.13.0"

// 报错
...
enum Color{
    success = 'success',
    info = 'info'
}
export class MProgress {
  @Prop() color: Color;
}

// 直接在类里面写
...
export class MProgress {
  @Prop() color:  'info' | 'success';
}
// 或者从ts文件中导入
...
import {Color} from "Color.ts"
export class MProgress {
  @Prop() color:  Color;
}