@ dedesign.estate/dees-emlement (英语)

扩展 Lit 的强大的自定义元素基础类 LitElement 与集成主题,反应灵敏的 CSS 公用事业,RxJS 驱动指令,和 DOM 工具化——这样你就可以构建一些看起来很棒的网络组件,并保持在框外的反应.

问题报告和安全

关于报告错误、问题或安全弱点,请访问 社区. fos.global/这是所有问题报告的中央社区中心。 签署和遵守我们缴款协议并经过身份验证的开发者也可获得 代码.fos.global/ 账户直接提交 Pull 请求.

安装

npm install @design.estate/dees-element
# or
pnpm install @design.estate/dees-element

本包船作为无害环境管理,并用TypeScript来书写. 请用现代模块解析策略(例如:. NodeNext) (中文(简体) ).

使用量

您需要的都从主入口输出 :

import {
  DeesElement,
  customElement,
  property,
  state,
  html,
  css,
  cssManager,
  directives,
} from '@design.estate/dees-element';

QQ 创建自定义元素

扩展 DeesElement 并应用 @customElement 装饰 :

import { DeesElement, customElement, html, css, cssManager } from '@design.estate/dees-element';

@customElement('my-button')
class MyButton extends DeesElement {
  static styles = [
    cssManager.defaultStyles,
    css`
      .btn {
        padding: 8px 16px;
        border-radius: 4px;
        background: ${cssManager.bdTheme('#0060df', '#3a8fff')};
        color: ${cssManager.bdTheme('#fff', '#fff')};
        border: none;
        cursor: pointer;
      }
    `,
  ];

  render() {
    return html`<button class="btn"><slot></slot></button>`;
  }
}

那个单身 bdTheme() 调用生成一个 CSS 变量, 当用户的主题改变时, 在亮值和暗值之间自动翻转—— 不需要手动拖动 .

* 电子包装设备

组件演示可以导入 demotools 要注册的子路径 <dees-demowrapper>。包装器会制作其分档的演示内容,然后运行 runAfterRender,用于需要设置状态的演示,查询提供了光-DOM子,或者在第一次渲染后模拟用户交互.

import { html } from '@design.estate/dees-element';
import { DeesDemoWrapper } from '@design.estate/dees-element/demotools';

export const demo = () => html`
  <dees-demowrapper
    .runAfterRender=${(wrapper: DeesDemoWrapper) => {
      const button = wrapper.querySelector('button');
      button?.dispatchEvent(new Event('click', { bubbles: true }));
    }}
  >
    <button>Demo action</button>
  </dees-demowrapper>
`;

主题管理 cssManager

单子 cssManager 它是主题和反应性布局的中心枢纽:

示例——应答+主题样式:

@customElement('my-card')
class MyCard extends DeesElement {
  static styles = [
    cssManager.defaultStyles,
    css`
      :host {
        display: block;
        padding: 16px;
        background: ${cssManager.bdTheme('#ffffff', '#1e1e1e')};
        color: ${cssManager.bdTheme('#111', '#eee')};
        border-radius: 8px;
      }
    `,
    cssManager.cssForPhone(css`
      :host { padding: 8px; }
    `),
  ];

  render() {
    return html`<slot></slot>`;
  }
}

集装箱反应组件

对需要应对其 自有宽度 (不是取景口),使用 @containerResponsive() 装饰和通过 this 作为第二个参数 cssManager.cssFor*数字 :

import {
  DeesElement, customElement, html, css, cssManager,
  containerResponsive,
} from '@design.estate/dees-element';

@containerResponsive()
@customElement('my-stats-grid')
class MyStatsGrid extends DeesElement {
  static styles = [
    cssManager.defaultStyles,
    css`.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }`,

    // Component-level: when THIS element is narrower than tablet width
    cssManager.cssForTablet(css`
      .grid { grid-template-columns: repeat(2, 1fr); }
    `, this),

    // Viewport-level: when the browser window is phone-sized
    cssManager.cssForPhone(css`
      .grid { grid-template-columns: 1fr; }
    `),

    // Component-level with custom width constraint
    this.cssForConstraint({ maxWidth: 500 })(css`
      .grid { gap: 8px; }
    `),
  ];

  render() {
    return html`<div class="grid"><slot></slot></div>`;
  }
}

如何运作:

这个 @containerResponsive() 需要装订器来进行组件范围查询——它确定了CSS的封装上下文 :host。 。 。 .

& 状态

使用标准立特装饰器,为方便再出:

import { DeesElement, customElement, property, state, html } from '@design.estate/dees-element';

@customElement('my-counter')
class MyCounter extends DeesElement {
  @property({ type: String })
  accessor label = 'Count';

  @state()
  accessor count = 0;

  render() {
    return html`
      <button @click=${() => this.count++}>
        ${this.label}: ${this.count}
      </button>
    `;
  }
}

说明: 此库使用 TC39 标准装潢器与 accessor 装饰类属性的关键词 .

QQ 主题更改回调

DeesElement 通过 goBright 属性并显示可选 themeChanged 回调 :

@customElement('theme-aware')
class ThemeAware extends DeesElement {
  protected themeChanged(goBright: boolean) {
    console.log(goBright ? 'Switched to bright' : 'Switched to dark');
  }

  render() {
    return html`<p>Current theme: ${this.goBright ? 'bright' : 'dark'}</p>`;
  }
}

goBright 反映为 gobright 属性在主机元素上,所以主题可以在没有 JavaScript 或每值的平面 CSS 中被样式化 bdTheme() 配对 :

public static styles = [
  css`
    :host {
      background: #000;
    }
    :host([gobright]) {
      background: #fff;
    }
  `,
];

主题切换时属性会自动更新 。 一个元素在连接时取出生效的主题,所以它的第一个渲染已经在这个主题中,没有颜色从黑暗的默认中消失. 一个元素创建于 ignoreGlobal 遵循它自己的多姆工具,一旦它被设置,它的主题就会被采纳.

* 生命周期帮助者

DeesElement 在 LitElement 上添加生命周期公用事业:

@customElement('my-widget')
class MyWidget extends DeesElement {
  constructor() {
    super();

    // Runs for each connection, after the previous connection has finished cleanup.
    this.registerStartupFunction(async (signal) => {
      if (signal.aborted) return;
      console.log('Widget connected!');
    });

    // Runs when the element is disconnected — perfect for cleanup
    this.registerGarbageFunction(() => {
      console.log('Widget removed');
    });
  }

  render() {
    return html`<p>Hello World</p>`;
  }
}

此外, this.elementDomReady 一个承诺,在之后解决 firstUpdated,这在等待初始渲染时是有用的:

await this.elementDomReady;
// The element's shadow DOM is now fully rendered

启动钩接受 AbortSignal 在删除时同步中止。 用这个 取消支持取消的工作。 已经运行的虎克可以安顿下来; 垃圾钩在下次连接开始前完成。 登记钩,通常一次 在建筑师。 由起动钩所创造的资源属于这种连接.

指令断开 rxSubscriptions 删除时立即取消订阅. 完成启动后加入的订阅在清理完成前被排出. 每条垃圾钩都尝试过,即使再扔一次;返回的断开承诺 以 AggregateError,以后的连接仍然可以运行。 子类应 立即拨打超阶级的生命周期方法,等待它回归的承诺 开始一个同步的工作.

这个 resolve 指令无视陈旧的承诺,保留有待清除的工作,以及 使当前承诺在重新连接后实现,即使承诺在分离时已经实现.

语言 localize 财务报告和审定财务报表 provideI18n

组件表达其软件包目录中的单词,一个键入 @push.rocks/smarti18n iCU消息目录. 应用程序 通过提供 I18n 实例; 下方的每个组件在变化时重递.

1. 一揽子组成部分界定其目录 (关于消息、翻译和检查,见smarti18n读取器):

import { defineCatalog } from '@push.rocks/smarti18n';

export const messages = defineCatalog({
  namespace: '@my/components',
  source: 'en',
  messages: {
    counter: 'Step {current, number} of {total, number}',
    help: 'Read the <link>guide</link>.',
  },
});
messages.addTranslation('de', () => import('./messages.de.js'));

2. 构成部分的用词是: localize数字 :

import { DeesElement, customElement, html, localize } from '@design.estate/dees-element';
import { messages } from './messages.js';

@customElement('my-stepper')
class MyStepper extends DeesElement {
  private t = localize(this, messages);

  render() {
    return html`
      <span>${this.t('counter', { current: 2, total: 4 })}</span>
      <p>${this.t.rich('help', { link: (chunks) => html`<a href="/guide">${chunks}</a>` })}</p>
      <small>${this.t.format.number(1234.5)}</small>
    `;
  }
}

• 键和参数为: this.t('counter', { current: 2 }) 财务报告和审定财务报表 this.t('countr') 正在编译错误.
• this.t.format 用目录格式写数字、钱、日期、列表和相对时间 写进,所以它总是同意 数字内的信息,和 this.t.i18n 元素为实例 现在说话.

3. 该应用程序提供了其实例打开 <html> 因此,附件中的要点 document.body (模式,菜单)找到它 还有:

import { createI18n } from '@push.rocks/smarti18n';
import { provideI18n } from '@design.estate/dees-element';

const i18n = createI18n({ locale: 'de-DE' });
provideI18n(document.documentElement, i18n, { reflect: true }); // keeps <html lang dir> in step

await i18n.setLocale('en-GB'); // every localized element re-renders in English

它的行为:

• 没有供应商 a 元素表达其目录的源语言(smarti18n's sourceI18n) (中文(简体) ). 提供商 因此设置顺序并不重要.

• 自己的倒计时: localize(this, messages, { fallback }) 说话 fallback 改为 sourceI18n 没有 供应商为要件服务,在供应商被处置时也是如此。 组件库保存自己的格式 这样一来,直到一个主机提供语言,例如没有分组的数字,在消息和 t.format 类似:

  import { createSourceI18n, Formats } from '@push.rocks/smarti18n';
  
  class UngroupedFormats extends Formats {
    public override intlNumberFormat(options: Intl.NumberFormatOptions): Intl.NumberFormat {
      return super.intlNumberFormat({ useGrouping: false, ...options });
    }
  }
  const neutral = createSourceI18n({ createFormats: (settings) => new UngroupedFormats(settings) });
  
  // in the component
  private t = localize(this, messages, { fallback: neutral });
  

• 一个子树可以说另一种语言: provideI18n(previewElement, documentI18n) 为下列要素服务 previewElement (文档预览,并列演示). 在一个 DeesElement 主办供应商与东道方住在一起; reflect 套装 lang 财务报告和审定财务报表 dir 当它连接时. provider.i18n = other 将子树另一只 举个例子. provider.dispose() 停止提供者并恢复其主机 lang 财务报告和审定财务报表 dir;平原上的供货商 元素,例如 <html>住到那时.

• 封面可以说开口语: 提供者服务于主机下方的元素, 绝不是主机本身的 localize() 词. provideI18n(overlay, openerI18n, { includeHost: true }) 也为东道主服务: 它使发言的内容 openerI18n 除页面外,请遵循一个本地端口或 provider.i18n = other,以及 返回页面语言 provider.dispose()。无论主机已经连接还是连接,它都有效 等会.

• 话还没说完. DeesElement.scheduleUpdate() 等待元素使用的目录 为它的语言加载,所以一个懒散定义的目录从不首先显示它的源词. 它只是等待 语言 仍然要加载 : 每个单词加载后, 更新是同步的, 所以一个本地化的孩子, 由父母所制作 电流,一旦父母的 updateComplete 决定。 无法加载的单词拒绝 updateComplete (与 翻译本身的失误,在 AggregateError; 下一次更新再次尝试. 覆盖的子类 scheduleUpdate() 必须呼叫 super.scheduleUpdate()。 。 。 .

• 无有漏出. 一个元素订阅其提供者,并在连接和断开时取消订阅.

• 右为左. i18n.direction 实值 rtl 阿拉伯语、希伯来语、波斯语和假语言 ar-XB; 与 reflect, (中文(简体) ), dir="rtl" 翻出一页. en-XA (单位:千美元)createI18n({ locale: 'en-XA', pseudo: true })显示已剪辑或 未译正文一览.

• 情况是 i18nContext (Web组件上下文协议,通过 @lit/context),按键 Symbol.for('dees.i18n'),所以每一份页面中的这个软件包都共享.

* 指令

这个 directives 命名空间包括强大的模板助手,可通过 directives.*数字 :

resolve ——兑现承诺

import { html, directives } from '@design.estate/dees-element';

render() {
  return html`${directives.resolve(this.fetchData())}`;
}

resolveExec 解决懒惰的合成功能

render() {
  return html`${directives.resolveExec(() => this.loadContent())}`;
}

subscribe - 显示 RxJS 观测器

import { html, directives } from '@design.estate/dees-element';

render() {
  return html`<span>${directives.subscribe(this.count$)}</span>`;
}

subscribeWithTemplate ——可观察+模板转换

render() {
  return html`
    ${directives.subscribeWithTemplate(
      this.items$,
      (items) => html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`
    )}
  `;
}

再出口 诉讼指令

指令命名空间还再出口这些常用的立特指令:

• until ——使占位者,而允诺是解决的
• asyncAppend — 辅助变量
• keyed ——当关键更改时,强制重生成模板
• repeat · 有效地使名单具有身份追踪

++ 完全导出参考

内容4 公众 domtools 命名空间(和 DeesElement.domtools(中文(简体) ) 揭发了"德多斯"5,"Typed Request 9"和"德多斯"2. 消费者升级 要件3必须:

• 替换 domtools.plugins.smartdelay 与 domtools.plugins.smartpromise,并在 替换多姆工具实例 DeesElement.domtools.convenience.smartdelay 与 DeesElement.domtools.convenience.smartpromise (单位:千美元)delayFor, (中文(简体) ), delayForRandom 财务报告和审定财务报表 Timeout 保持他们的签名;
• 导入 DeesElement 构造器选项类型为 domtools.IDomToolsConstructorOptions (密码) IDomToolsContructorOptions 已经消失);
• 将自己的打出的请求路由器和目标与Typed Request 9连接起来,后者 routeAndAddResponse() 决定 T | null 以及他们 IPostMethod 决定 ITypedRequest | null。 。 。 .

许可证和法律资料

这个寄存器包含根据麻省理工学院许可证许可的开源代码. 许可证副本可在 许可证 文档.

请注意: 麻省理工学院许可证不准许使用该项目的商品名、商标、服务标记或产品名称,除非在描述作品来源和复制NOTICE文件内容时需要合理和习惯使用.

商标

这个项目由Task Venture Capital GmbH拥有和维护。 与Task Venture Capital GmbH相关的名称和标志以及任何相关的产品或服务是Task Venture Capital GmbH或第三方的商标,不属于本文授予的麻省理工学院许可证的范围.

使用这些商标必须符合Wasure Venture Capital GmbH的商标准则或各自的第三方所有者的准则,任何使用都必须获得书面批准。 此处使用的第三方商标是其各自所有者的财产并仅以描述方式使用,例如用于实施API或类似的.

企业信息

任务风险资本股份有限公司 在德国不来梅地区法院注册的HRB 35230 HB

如欲了解任何法律查询或进一步情况,请通过电子邮件与我们联系 你好@ task.vc。 。 。 .

通过使用这个寄存器,你承认你读过这个部分,同意遵守它的条款,并且明白代码的许可并不意味着Task Venture Capital GmbH认可任何衍生作品.