lit笔记

November 20, 2022

Lit

使用 Lit 必须提前了解 WebComponents

Doc https://lit.dev/docs/
API https://lit.dev/docs/api/LitElement/
另见 https://lit.how/

在 Typescript 中可以使用以下方式将自定义元素合并到 HTMLElementTagNameMap

declare global {
    interface HTMLElementTagNameMap {
        "my-element": MyElement;
    }
}

https://lit.dev/docs/templates/expressions/

子节点

html

html`
<h1>Hello ${name}</h1>
<ul>
    ${listItems}
</ul>
`

标签属性

html

html`
<div class="${highlightClass}"></div>
`

布尔值标签属性

html

html`
<div ?hidden="${!show}"></div>
`

对象属性

html

html`<input .value="${value}" />`

事件监听器

html

html`<button @click="${this._clickHandler}">点我</button>`

元素指令（获取 ref）

html

html`<input ${ref(inputRef)} />`

属性 & 状态

属性可以被外部访问（应视为外部输入），属性是响应式的（即，会自动触发重渲染）。
属性的相等性默认通过严格相等比较运算判断，因此非原始类型若要自动触发变更则需修改引用，
但可调用 this.requestUpdate() 手动触发重渲染。重渲染会推迟到下一个微任务进行。

状态是一种特殊的（内部）属性，lit 不为其分配外部接口（标签属性 attr 和对象属性 prop）

lit 默认为我们声明的响应式属性生成 accessor，定义在当前类的 prototype 上
很少需要创建自定义 accessor。避免设置同名实例属性，防止覆盖 accessor。

property 装饰器选项：https://lit.dev/docs/components/properties/#property-options

import { LitElement, html } from "lit";
import { customElement } from "lit/decorators.js";

@customElement("my-element")
export class MyElement extends LitElement {
    // 最简单的属性
    @property()
    name: string;

    // 最简单的状态（往往标记为 private 或 protected）
    @state()
    private _counter = 0;

    // 不生成标签属性
    @property({ attribute: false })
    myData = {};

    // 生成指定名称的标签属性。默认是直接转换成小写（并不会将驼峰转为短横线）
    @property({ attribute: "my-name" })
    myName = "Ogden";

    // 转换器
    // 由于标签属性都是 DOM String，因此需要转换器转换
    // converter 若指定为函数，相当于只指定了 fromAttribute
    @property({
        converter: {
            fromAttribute: (value, type) => {
                // `value` is a string
                // Convert it to a value of type `type` and return it
            },
            toAttribute: (value, type) => {
                // `value` is of type `type`
                // Convert it to a string and return it
            },
        },
    })
    myTime = new Date();

    // 使用内置转换器 string -> number
    // 内置的转换器有；String(默认) Number Boolean Object Array
    @property({ type: Number })
    aNumber: number = 5;

    // reflect选项，是否将属性反映到标签属性attr上
    @property({ type: Boolean, reflect: true })
    active: boolean = false;

    // 自定义相等性比较
    @property({
        hasChanged(newVal: string, oldVal: string) {
            return newVal?.toLowerCase() !== oldVal?.toLowerCase();
        },
    })
    myProp: string | undefined;
}

样式

import { LitElement, html, css, unsafeCSS } from "lit";
import { customElement } from "lit/decorators.js";

@customElement("my-element")
export class MyElement extends SuperElement {
    // css 模板字符串函数
    mainColor: CSSResultGroup = css`red`;
    static styles = css`
        div {
            color: ${mainColor};
        }
    `;

    // unsafeCSS 函数用于渲染字符串 css
    mainColor: CSSResultGroup = "red";
    static styles = css`
        div {
            color: ${unsafeCSS(mainColor)};
        }
    `;

    // styles 其实是一个数组（adoptedStyleSheets）
    // 由于 styles 是静态属性，因此也可以访问父类的 styles
    static styles: CSSResultGroup = [
        SuperElement.styles,
        css`
            div {
                color: red;
            }
        `,
    ];

    // html 模板中也可以使用 style 标签。style 标签对每个实例求值，静态 styles 属性则对每个类求值
    protected render() {
        return html`
            <p>I am green!</p>
            <style>
                :host {
                    color: green;
                }
            </style>
        `;
    }
}

// classMap 和 styleMap 实用函数
import { classMap } from "lit/directives/class-map.js";
import { styleMap } from "lit/directives/style-map.js";

@customElement("my-element")
export class MyElement extends LitElement {
    static styles = css`
        .someclass {
            border: 1px solid red;
            padding: 4px;
        }
        .anotherclass {
            background-color: navy;
        }
    `;
    @property()
    classes = { someclass: true, anotherclass: true };
    @property()
    styles = { color: "lightgreen", fontFamily: "Roboto" };
    protected render() {
        return html` <div class=${classMap(this.classes)} style=${styleMap(this.styles)}>Some content</div> `;
    }
}

生命周期

LitElement 继承了 HTMLElement 的生命周期，即 WebComponents 的生命周期

connectedCallback() {
  super.connectedCallback();
  this._timerInterval = setInterval(() => this.requestUpdate(), 1000);
}

disconnectedCallback() {
  super.disconnectedCallback();
  clearInterval(this._timerInterval);
}

Pre-Update

Update
Update
Post-Update

import {LitElement, html, PropertyValues} from 'lit';
...
  shouldUpdate(changedProperties: PropertyValues<this>) {
    ...
  }

初次渲染的生命周期函数顺序如下（cp=changedProperties）：

requestUpdate（响应式属性为：undefined）
requestUpdate（响应式属性为：初始值）
constructor
requestUpdate（响应式属性为：标签属性值，若不存在则不触发）
attributeChangedCallback（若不存在对应标签属性则不触发）
connectedCallback（此时响应式属性已正确初始化，lit 保证 shadowRoot 已创建，但尚未开始渲染）
shouldUpdate(cp)
willUpdate(cp)（此处修改响应式属性不会触发重渲染）
render（注意第一次渲染发生在此处）
update(cp) （必须调用 super）
firstUpdated(cp)（仅第一次渲染后触发）
updated(cp)

响应式属性变化后：

requestUpdate(name, oldVal, options)
shouldUpdate
attributeChangedCallback（仅当是标签属性改变才触发）
shouldUpdate
willUpdate
render
update
updated

其余生命周期可用于自定义渲染时机，此处略

参见此示例演示代码如下：

import { html, LitElement, PropertyValues } from "lit";
import { customElement, property } from "lit/decorators.js";
import { ref } from "lit/directives/ref.js";

// https://lit.dev/docs/components/lifecycle/
@customElement("life-cycle")
export class LifeCycle extends LitElement {
    // Standard custom element lifecycle
    constructor() {
        super();
        console.log("constructor");
    }
    connectedCallback() {
        super.connectedCallback();
        console.log("connectedCallback");
    }
    disconnectedCallback() {
        super.disconnectedCallback();
        console.log("disconnectedCallback");
    }
    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null) {
        super.attributeChangedCallback(name, oldVal, newVal);
        console.log("attributeChangedCallback", name, oldVal, newVal);
    }
    adoptedCallback() {
        console.log("adoptedCallback");
    }

    // Reactive update cycle
    // note that we call super only when necessary
    shouldUpdate(changedProperties: PropertyValues<this>) {
        console.log("shouldUpdate", changedProperties);
        return true;
    }
    willUpdate(changedProperties: PropertyValues<this>) {
        console.log("willUpdate", changedProperties);
    }
    update(changedProperties: PropertyValues<this>) {
        super.update(changedProperties);
        console.log("update", changedProperties);
    }
    firstUpdated(changedProperties: PropertyValues<this>) {
        console.log("firstUpdated", changedProperties);
    }
    updated(changedProperties: PropertyValues<this>) {
        console.log("updated", changedProperties);
    }

    @property({
        hasChanged(newVal: string, oldVal: string) {
            console.log("hasChanged", newVal, oldVal);
            return newVal !== oldVal;
        },
    })
    msg = "msg";

    render() {
        console.log("render");
        this.updateComplete.then(() => console.log("updateComplete resolved"));
        return html` <p ${ref(() => console.log("ref"))}>${this.msg}</p>
            <input .value=${this.msg} @input=${(e) => (this.msg = e.target.value)} />`;
    }
}

访问 Shadow DOM

在 lit 中，shadowRoot 可以通过组件的 renderRoot 属性访问

// 可以在生命周期中访问
firstUpdated() {
    this.staticNode = this.renderRoot.querySelector('#static-node');
}

// 可以作为getter访问器
get _closeButton() {
    return this.renderRoot.querySelector('#close-button');
}

不过 lit 也提供了装饰器

import { LitElement, html } from "lit";
import { query, queryAll } from "lit/decorators/query.js";

class MyElement extends LitElement {
    @query("#first")
    _first;
    // 相当于
    get _first() {
        return this.renderRoot?.querySelector("#first") ?? null;
    }

    @queryAll("button")
    _buttons!: NodeListOf<HTMLButtonElement>;

    render() {
        return html`
            <div id="first"></div>
            <div id="second"></div>
        `;
    }
}

lit 内置装饰器参见此处

事件

事件监听参数实际上就是传入 addEventListener() 的参数

render() {
  return html`<button @click=${{handleEvent: () => this.onClick(), once: true}}>click</button>`
}

使用组件实例的 dispatchEvent() 方法传入 CustomEvent 调度事件

当自定义事件同时指定 bubbles 和 composed 时，该事件可冒泡至 ShadowDOM 外部

this.dispatchEvent(
    new CustomEvent("my-event", {
        detail: { message: "my-event happened." },
        bubbles: true,
        composed: true,
        cancelable: true,
    }),
);

插槽中的事件根据实际渲染 DOM 节点的位置传递

静态表达式

动态标签和动态标签属性是不支持的

import { LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { html, literal } from "lit/static-html.js";

@customElement("my-button")
class MyButton extends LitElement {
    // tag = "button" 是错误的，必须以下面的方式声明
    tag = literal`button`;
    activeAttribute = literal`active`;
    @property() caption = "Hello static";
    @property({ type: Boolean }) active = false;

    render() {
        return html`
      <${this.tag} ${this.activeAttribute}?=${this.active}>
        <p>${this.caption}</p>
      </${this.tag}>`;
    }
}

@customElement("my-anchor")
class MyAnchor extends MyButton {
    tag = literal`a`;
}

textarea 标签，在渲染动态内容时，一般使用对象属性
渲染静态内容时则无所谓

html

<!--这样会丢失引用-->
<textarea>${content}</textarea>

<!--使用对象属性可保持引用-->
<textarea .value="${content}"></textarea>

条件

when 指令

html`
    ${when(
        this.user, // 转化为布尔值判断
        () => html`User: ${this.user.username}`,
        () => html`Sign In...`,
    )}
`;

choose 指令

html`
    ${choose(
        this.section, // "home" or "about" or OTHER
        [
            ["home", () => html`<h1>Home</h1>`],
            ["about", () => html`<h1>About</h1>`],
        ],
        () => html`<h1>Error</h1>`, // if is OTHER
    )}
`;

ifDefined 指令

@customElement("my-element")
class MyElement extends LitElement {
    @property()
    filename: string | undefined = undefined;

    @property()
    size: string | undefined = undefined;

    render() {
        // src attribute not rendered if either size or filename are undefined
        return html`<img src="/images/${ifDefined(this.size)}/${ifDefined(this.filename)}" />`;
    }
}

cache 指令

html`${cache(this.userName ? html`Welcome ${this.userName}` : html`Please log in <button>Login</button>`)}`;

nothing（Symbol）

html`<user-name>${this.userName ?? nothing}</user-name>`;

html`<button aria-label="${this.ariaLabel || nothing}"></button>`;

循环

repeat 指令

@customElement("my-element")
class MyElement extends LitElement {
    @property()
    items: Array<{ id: number; name: string }> = [];

    render() {
        return html`
            <ul>
                ${repeat(
                    this.items,
                    (item) => item.id,
                    (item, index) => html` <li>${index}: ${item.name}</li>`,
                )}
            </ul>
        `;
    }
}

map 指令

html`<ul>
    ${map(items, (i) => html`<li>${i}</li>`)}
</ul>`;

range 指令

html`${map(range(8), (i) => html`${i + 1}`)}`;

ref

传入 Ref 对象

@customElement("my-element")
class MyElement extends LitElement {
    inputRef: Ref<HTMLInputElement> = createRef();

    render() {
        // 将 Ref 对象传入ref指令后，Ref 对象的 value 属性将是对元素的引用
        return html`<input ${ref(this.inputRef)} />`;
    }

    firstUpdated() {
        const input = this.inputRef.value!;
        input.focus();
    }
}

传入回调函数

@customElement("my-element")
class MyElement extends LitElement {
    render() {
        // 将回调函数传入 ref 指令，将在被引用的元素变更时调用
        return html`<input ${ref(this.inputChanged)} />`;
    }

    inputChanged(input?: HTMLInputElement) {
        input?.focus();
    }
}