@aaronanderson/lwdc 中文文档教程
Workday® 是 Workday, Inc. 的注册商标。此项目不隶属于 Workday, Inc.,Workday, Inc. 不认可此项目。
lwdc
提供 Lit Workday Canvas Kit UI 组件的 Web 组件。
这些组件的目的是:
充分利用现代原生网络平台,包括 Web Components 和 HTML 模板 通过 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
在表单字段级别,并具有用于文本和选择输入的后代选择器。 此问题有三种可能的解决方案:
将 CSS 选择器添加到 ::slotted< 的父元素/a> 和 ::part
将 CSS 选择器添加到 :host-context()
放弃使用 Shadow DOM 并创建Light DOM 中的元素。
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.