@aaronanderson/lwdc 中文文档教程

发布于 3年前 浏览 24 项目主页 更新于 3年前

Workday® 是 Workday, Inc. 的注册商标。此项目不隶属于 Workday, Inc.,Workday, Inc. 不认可此项目。

lwdc

提供 Lit Workday Canvas Kit UI 组件的 Web 组件。

这些组件的目的是:

  • 充分利用现代原生网络平台,包括 Web ComponentsHTML 模板 通过 Lit 消除了对复杂和陈旧的 VDOM 框架的需求

  • 包装 Canvas Kit CSS减少样板代码和拼写错误

  • 的组件提供 Canvas Kit React 组件的替代品,这些组件没有 CSS 等效

  • 项提供 Javascript 功能,例如动态样式和选择

  • 插入 HTML 表单验证

React基于 的应用程序将受益于直接使用 Canvas Kit 中包含的 React 组件。 基于 Web 组件的应用程序可以轻松地包含这些组件或使用 PReact 包装 React 组件,如 这里

欢迎新的合作者或贡献者。

Styling

从逻辑上讲,每个 Canvas Kit 组件都应包装为 Lit Web 组件。 然而,一些 Canvas Kit 组件使用无法穿透 Web 组件影子 DOM 的后代 CSS 选择器。 例如,error.scss 定义了 wdc-form-error 在表单字段级别,并具有用于文本和选择输入的后代选择器。 此问题有三种可能的解决方案:

Light DOM 选项用于选择组件。 ::slotted 和 ::part 解决方案需要对 Canvas Kit SCSS 进行上游更改或大量分叉的 SCSS 来复制 SCSS 父级选择器。 同样, :host-context() 解决方案需要对 SCSS 和子组件的目标 CSS 进行高级内省。 FireFox 也不支持复杂的 :host CSS 选择器。 由于 comobox 组件的复杂性,它确实使用 Shadow DOM 并具有 CSS 选择器 专门用于错误突出显示。

表单相关的 Web 组件被添加到 Light DOM 中,它们的样式被单独添加到最近的阴影 DOM 或文档中。 通常,表单组件将由另一个自定义元素或提供的 lwdc-form 元素包装,因此样式将具有一定的隔离性并且不会过度重复。

Browser Support

Lit 组件利用两个实验性浏览器功能:

当前版本的 Chrome 支持这两种功能,无需任何额外配置。 Firefox 支持正在发展:

可以在最新版本的 Firefox 中通过 dom.webcomponents.elementInternals.enabled about:config

中的设置 最小的 pollyfill 用于提供 Firefox 中缺失的表单关联元素功能,以提供完整的表单验证。

Storybook

构建组件:yarn install 然后

yarn build 构建 Storybook:yarn build-storybook

运行 Storybook:yarn start

Usage

yarn add @aaronanderson/lwdc

Development

本地测试可以通过检出这个项目,在检出目录中运行npm link,然后运行npm link @ aaronanderson/lwdc 在目标项目中。

或者在检出目录中运行 yarn pack 然后运行 ​​yarn remove @aaronanderson/lwdc, yarn cache clean, yarn add file :aaronanderson-lwdc-v1.0.0.tgz 在目标项目中安装最新版本。

Workday® is the registered trademark of Workday, Inc. This project is not affiliated with Workday, Inc. and Workday, Inc. does not endorse this project.

lwdc

Provides Lit web components for Workday Canvas Kit UI components.

The purposes of these components are:

  • Fully leverage the modern native web platform including Web Components and HTML Templates via Lit eliminating the need for complicated and archaic VDOM frameworks

  • Wrap the Canvas Kit CSS components to reduce boilerplate code and typos

  • Offer alternatives to Canvas Kit React components that do not have CSS equivalents

  • Provide Javascript functionality such as dynamic styling and selection

  • Plug into HTML form validation

React based applications would benefit from the direct usage of the React components included in Canvas Kit. Web Component based applications can easily include these components or wrap the React components using PReact as demonstrated here.

New collaborators or contributors are welcome.

Styling

Logically each Canvas Kit component should be wrapped as a Lit web component. However some of the Canvas Kit component utilize descendant CSS selectors that are unable to pierce web component shadow DOMs. For example, error.scss defines wdc-form-error at the form field level and has descendant selectors for text and select inputs. There are three potential solutions to this issue:

  • Add CSS selectors to parent elements for ::slotted and ::part

  • Add CSS selectors to child elements for :host-context()

  • Forego the use of the Shadow DOM and create elements in the Light DOM.

The Light DOM option was used for select components. The ::slotted and ::part solution would require upstream changes to Canvas Kit SCSS or a large amount of forked SCSS to replicate SCSS parent selectors. Likewise the :host-context() solution would require advanced introspection of the SCSS and targeted CSS for child components. Also FireFox does not support complex :host CSS selectors. Due to the complex nature of the comobox component it does use the Shadow DOM and has CSS selectors specifically for error highlighting.

The form related web components are added to the Light DOM and their styles are individually added to the closest shadow DOM or document. Typically form components will be wrapped by another custom element or the provided lwdc-form element so the styles will have some isolation and not excessive duplication.

Browser Support

The Lit components utilize two experimental browser features:

The current version of Chrome supports both of these features without any extra configuration. Firefox support is evolving:

Partial form associated custom element support can be activated in the latest version of Firefox via the dom.webcomponents.elementInternals.enabled setting in about:config

A minimal pollyfill is used to provide the missing form associated element features in Firefox in order to provide full form validation.

Storybook

Build the components: yarn install then yarn build

Build the Storybook: yarn build-storybook

Run the Storybook: yarn start

Usage

yarn add @aaronanderson/lwdc

Development

Local testing can be performed by checking this project out, running npm link in the checked out directory, and then running npm link @aaronanderson/lwdc in the target project.

Alternatively run yarn pack in the checked out directory and then run yarn remove @aaronanderson/lwdc, yarn cache clean, yarn add file:aaronanderson-lwdc-v1.0.0.tgz in the target project to install the latest version.

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文