|
| 1 | +<!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>WebCell</title><meta name="description" content="Documentation for WebCell"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><link rel="stylesheet" href="assets/custom.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">WebCell</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>WebCell</h1></div><div class="tsd-panel tsd-typography"><a id="webcell-从-v2-到-v3-的迁移" class="tsd-anchor"></a><h1 class="tsd-anchor-link">WebCell 从 v2 到 v3 的迁移<a href="#webcell-从-v2-到-v3-的迁移" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><a id="类-react-状态管理已被完全移除" class="tsd-anchor"></a><h2 class="tsd-anchor-link">类 React 状态管理已被完全移除<a href="#类-react-状态管理已被完全移除" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><strong>WebCell v3</strong> 受到了 <a href="https://github.com/mobxjs/mobx/blob/mobx4and5/docs/refguide/observer-component.md#local-observable-state-in-class-based-components"><strong>MobX</strong> 的 <strong>本地可观察状态</strong> 思想</a> 的深刻启发，<a href="https://fcc-cd.dev/article/translation/3-reasons-why-i-stopped-using-react-setstate/">不仅仅是 React</a>，Web Components 可以更轻松地管理 <strong>内部状态和逻辑</strong>，无需任何复杂的操作：</p> |
| 2 | +<ol> |
| 3 | +<li>状态类型声明</li> |
| 4 | +<li><code>this.state</code> 声明及其类型注解/断言</li> |
| 5 | +<li><code>this.setState()</code> 方法的调用及其回调</li> |
| 6 | +<li>令人困惑的 <em>Hooks API</em>...</li> |
| 7 | +</ol> |
| 8 | +<p>只需像管理 <strong>全局状态</strong> 一样声明一个 <strong>状态存储类</strong>，并在 <code>this</code>（即 <strong>Web Component 实例</strong>）上初始化它。然后像 <a href="https://github.com/mobxjs/mobx/tree/mobx4and5/docs">MobX</a> 一样使用并观察这些状态，一切就完成了。</p> |
| 9 | +<pre><code class="diff">import { |
| 10 | + component, |
| 11 | ++ observer, |
| 12 | +- mixin, |
| 13 | +- createCell, |
| 14 | +- Fragment |
| 15 | +} from 'web-cell'; |
| 16 | ++import { observable } from 'mobx'; |
| 17 | + |
| 18 | +-interface State { |
| 19 | ++class State { |
| 20 | ++ @observable |
| 21 | +- key: string; |
| 22 | ++ accessor key = ''; |
| 23 | +} |
| 24 | + |
| 25 | +@component({ |
| 26 | + tagName: 'my-tag' |
| 27 | +}) |
| 28 | ++@observer |
| 29 | +-export class MyTag extends mixin<{}, State>() { |
| 30 | ++export class MyTag extends HTMLElement { |
| 31 | +- state: Readonly<State> = { |
| 32 | +- key: 'value' |
| 33 | +- }; |
| 34 | ++ state = new State(); |
| 35 | + |
| 36 | +- render({}: any, { key }: State) { |
| 37 | ++ render() { |
| 38 | ++ const { key } = this.state; |
| 39 | + |
| 40 | + return <>{value}</>; |
| 41 | + } |
| 42 | +} |
| 43 | +</code><button type="button">Copy</button></pre> |
| 44 | + |
| 45 | +<p>同时，<code>shouldUpdate() {}</code> 生命周期方法已被移除。你只需在 <code>State</code> 类的方法中，在状态改变之前控制逻辑即可。</p> |
| 46 | +<a id="dom-属性变为可观察数据" class="tsd-anchor"></a><h2 class="tsd-anchor-link">DOM 属性变为可观察数据<a href="#dom-属性变为可观察数据" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><strong>DOM 属性</strong> 不同于 React 的 props，它们是 <strong>响应式的</strong>。它们不仅负责 <strong>更新组件视图</strong>，还会与 <strong>HTML 属性同步</strong>。</p> |
| 47 | +<p>MobX 的 <a href="https://github.com/mobxjs/mobx/blob/mobx4and5/docs/refguide/observable-decorator.md"><code>@observable</code></a> 和 <a href="https://github.com/mobxjs/mobx/blob/mobx4and5/docs/refguide/reaction.md"><code>reaction()</code></a> 是实现上述功能的优秀 API，代码也非常清晰，因此我们添加了 <code>mobx</code> 包作为依赖：</p> |
| 48 | +<pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">mobx</span> |
| 49 | +</code><button type="button">Copy</button></pre> |
| 50 | + |
| 51 | +<p>另一方面，<a href="https://github.com/EasyWebApp/WebCell/tree/v2/MobX"><code>mobx-web-cell</code> 适配器</a> 已经合并到了核心包中。</p> |
| 52 | +<pre><code class="diff">+import { JsxProps } from 'dom-renderer'; |
| 53 | +import { |
| 54 | +- WebCellProps, |
| 55 | + component, |
| 56 | + attribute, |
| 57 | +- watch, |
| 58 | ++ observer, |
| 59 | +- mixin, |
| 60 | +- createCell, |
| 61 | +- Fragment |
| 62 | +} from 'web-cell'; |
| 63 | +-import { observer } from 'mobx-web-cell'; |
| 64 | ++import { observable } from 'mobx'; |
| 65 | + |
| 66 | +-export interface MyTagProps extends WebCellProps { |
| 67 | ++export interface MyTagProps extends JsxProps<HTMLElement> { |
| 68 | + count?: number |
| 69 | +} |
| 70 | + |
| 71 | +@component({ |
| 72 | + tagName: 'my-tag' |
| 73 | +}) |
| 74 | +@observer |
| 75 | +-export class MyTag extends mixin<MyTagProps>() { |
| 76 | ++export class MyTag extends HTMLElement { |
| 77 | ++ declare props: MyTagProps; |
| 78 | + |
| 79 | + @attribute |
| 80 | +- @watch |
| 81 | ++ @observable |
| 82 | +- count = 0; |
| 83 | ++ accessor count = 0; |
| 84 | + |
| 85 | +- render({ count }: MyTagProps) { |
| 86 | ++ render() { |
| 87 | ++ const { count } = this; |
| 88 | + |
| 89 | + return <>{count}</>; |
| 90 | + } |
| 91 | +} |
| 92 | +</code><button type="button">Copy</button></pre> |
| 93 | + |
| 94 | +<a id="使用-shadow-dom-的-mode-选项控制渲染目标" class="tsd-anchor"></a><h2 class="tsd-anchor-link">使用 Shadow DOM 的 <code>mode</code> 选项控制渲染目标<a href="#使用-shadow-dom-的-mode-选项控制渲染目标" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="渲染到-children" class="tsd-anchor"></a><h3 class="tsd-anchor-link">渲染到 <code>children</code><a href="#渲染到-children" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="diff">import { |
| 95 | + component, |
| 96 | +- mixin |
| 97 | +} from 'web-cell'; |
| 98 | + |
| 99 | +@component({ |
| 100 | + tagName: 'my-tag', |
| 101 | +- renderTarget: 'children' |
| 102 | +}) |
| 103 | +-export class MyTag extends mixin() { |
| 104 | ++export class MyTag extends HTMLElement { |
| 105 | +} |
| 106 | +</code><button type="button">Copy</button></pre> |
| 107 | + |
| 108 | +<a id="渲染到-shadowroot" class="tsd-anchor"></a><h3 class="tsd-anchor-link">渲染到 <code>shadowRoot</code><a href="#渲染到-shadowroot" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="diff">import { |
| 109 | + component, |
| 110 | +- mixin |
| 111 | +} from 'web-cell'; |
| 112 | + |
| 113 | +@component({ |
| 114 | + tagName: 'my-tag', |
| 115 | +- renderTarget: 'shadowRoot' |
| 116 | ++ mode: 'open' |
| 117 | +}) |
| 118 | +-export class MyTag extends mixin() { |
| 119 | ++export class MyTag extends HTMLElement { |
| 120 | +} |
| 121 | +</code><button type="button">Copy</button></pre> |
| 122 | + |
| 123 | +<a id="将-shadow-css-注入移动到-render" class="tsd-anchor"></a><h2 class="tsd-anchor-link">将 Shadow CSS 注入移动到 <code>render()</code><a href="#将-shadow-css-注入移动到-render" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>这样使得 <strong>Shadow CSS</strong> 可以随着可观察数据的更新而响应。</p> |
| 124 | +<pre><code class="diff">+import { stringifyCSS } from 'web-utility'; |
| 125 | +import { |
| 126 | + component, |
| 127 | +- mixin |
| 128 | +} from 'web-cell'; |
| 129 | + |
| 130 | +@component({ |
| 131 | + tagName: 'my-tag', |
| 132 | +- renderTarget: 'shadowRoot', |
| 133 | ++ mode: 'open', |
| 134 | +- style: { |
| 135 | +- ':host(.active)': { |
| 136 | +- color: 'red' |
| 137 | +- } |
| 138 | +- } |
| 139 | +}) |
| 140 | +-export class MyTag extends mixin() { |
| 141 | ++export class MyTag extends HTMLElement { |
| 142 | + render() { |
| 143 | + return <> |
| 144 | ++ <style> |
| 145 | ++ {stringifyCSS({ |
| 146 | ++ ':host(.active)': { |
| 147 | ++ color: 'red' |
| 148 | ++ } |
| 149 | ++ })} |
| 150 | ++ </style> |
| 151 | + test |
| 152 | + </>; |
| 153 | + } |
| 154 | +} |
| 155 | +</code><button type="button">Copy</button></pre> |
| 156 | + |
| 157 | +<a id="替换部分-api" class="tsd-anchor"></a><h2 class="tsd-anchor-link">替换部分 API<a href="#替换部分-api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ol> |
| 158 | +<li><code>mixin()</code> => <code>HTMLElement</code> 及其子类</li> |
| 159 | +<li><code>mixinForm()</code> => <code>HTMLElement</code> 和 <code>@formField</code></li> |
| 160 | +<li><code>@watch</code> => <code>@observable accessor</code></li> |
| 161 | +</ol> |
| 162 | +<a id="附录：v3-原型" class="tsd-anchor"></a><h2 class="tsd-anchor-link">附录：v3 原型<a href="#附录：v3-原型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ol> |
| 163 | +<li><a href="https://codesandbox.io/s/web-components-jsx-i7u60?file=/index.tsx">旧架构</a></li> |
| 164 | +<li><a href="https://codesandbox.io/s/mobx-web-components-pvn9rf?file=/src/WebComponent.ts">现代架构</a></li> |
| 165 | +<li><a href="https://codesandbox.io/s/mobx-lite-791eg?file=/src/index.ts">MobX 精简版</a></li> |
| 166 | +</ol> |
| 167 | +</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#webcell-从-v2-到-v3-的迁移"><span>Web<wbr/>Cell 从 v2 到 v3 的迁移</span></a><ul><li><a href="#类-react-状态管理已被完全移除"><span>类 <wbr/>React 状态管理已被完全移除</span></a></li><li><a href="#dom-属性变为可观察数据"><span>DOM 属性变为可观察数据</span></a></li><li><a href="#使用-shadow-dom-的-mode-选项控制渲染目标"><span>使用 <wbr/>Shadow DOM 的 mode 选项控制渲染目标</span></a></li><li><ul><li><a href="#渲染到-children"><span>渲染到 children</span></a></li><li><a href="#渲染到-shadowroot"><span>渲染到 shadow<wbr/>Root</span></a></li></ul></li><li><a href="#将-shadow-css-注入移动到-render"><span>将 <wbr/>Shadow CSS 注入移动到 render()</span></a></li><li><a href="#替换部分-api"><span>替换部分 API</span></a></li><li><a href="#附录：v3-原型"><span>附录：v3 原型</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">WebCell</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html> |
0 commit comments