@adhocteam/component-library 中文文档教程
Ad Hoc Component Library
This is a Web Component library with Storybook 基于 https://github.com/DesignByOnyx/stencil-storybook-starter.git 的集成
Features
- automatic generation of stories for all components
- automatic knobs generation for all
@Propson your components - ability to customize which knobs are used for each prop (though the code does a good job of guessing for strings, numbers, booleans, objects, dates, and colors).
- ability to define multiple states which are rendered on a single page, each with a title, description, and props to use for rendering. A copyable code snippet is also generated for each state (kind of a lightweight chapters implementation)
- ability to define notes for each component (usually you want the generated readme)
- live rebuild/reload of stencil components (it's still a little wonky - sometimes you have to refresh the browser)
- also comes with the viewport add-on
Setup
要让此 repo 在本地运行以便您可以修改现有组件或创建新组件，请安装依赖项：
npm install
要在 Stencil 的本地查看您的组件开发服务器，将其放入 src/index.html 并启动服务器：
npm run start
在本地启动故事书并浏览故事：
npm run storybook
Stencil
Stencil 是一个使用 Web 组件构建快速 Web 应用程序的编译器。
Stencil 将最流行的前端框架的最佳概念结合到编译时而非运行时工具中。 Stencil 采用 TypeScript、JSX、微型虚拟 DOM 层、高效的单向数据绑定、异步渲染管道（类似于 React Fiber）和开箱即用的延迟加载，并生成 100% 基于标准的 Web 组件，这些组件可以运行在任何支持自定义元素 v1 规范的浏览器中。
Stencil 组件只是 Web 组件，因此它们可以在任何主要框架或根本没有框架的情况下工作。
Creating/Modifying a Component
组件位于src/components目录下，每个组件目录下可能有6个文件：
- The component definition
- The component CSS
- The Story for the component
- A generated readme
- End-to-End tests (testing the component from a consumer perspective)
- Unit tests (testing things within the component)
Stencil要求组件用TypeScript编写，所以定义文件必须以.tsx。
对您的新组件/功能进行一些基本测试是个好主意。
您还可以在此处查看有关创建组件的 Stencil 文档。
Naming Components
创建新的组件标签时，我们建议不要在组件名称中使用stencil（例如：
相反，使用适合您公司的前缀或一组相关组件的任何名称。 例如，所有 Ionic 生成的 Web 组件都使用前缀 ion。
Using a Component elsewhere
Publishing
该组件库旨在能够在其他站点上使用。 为此，必须发布对组件的任何更改：
npm run build
npm publish --public
Installing & Importing
首先，必须安装库：
npm install @adhocteam/component-library --save
接下来，将以下代码放入应用程序的 index.js 文件或等效文件中：
import {defineCustomElements} from '@adhocteam/component-library/loader';
defineCustomelements(window);
或者，您可以添加一个
<script src="https://unpkg.com/@adhocteam/component-library/dist/component-library.js"></script>
Using a component
如果库已正确安装和导入，您应该能够在 HTML 或 JSX 中的任何位置使用定义的组件之一。
Ad Hoc Component Library
This is a Web Component library with Storybook integration based on https://github.com/DesignByOnyx/stencil-storybook-starter.git
Features
- automatic generation of stories for all components
- automatic knobs generation for all
@Propson your components - ability to customize which knobs are used for each prop (though the code does a good job of guessing for strings, numbers, booleans, objects, dates, and colors).
- ability to define multiple states which are rendered on a single page, each with a title, description, and props to use for rendering. A copyable code snippet is also generated for each state (kind of a lightweight chapters implementation)
- ability to define notes for each component (usually you want the generated readme)
- live rebuild/reload of stencil components (it's still a little wonky - sometimes you have to refresh the browser)
- also comes with the viewport add-on
Setup
To get this repo running locally so you can modify existing components or create new ones, install the dependencies:
npm install
To see your component in Stencil's local dev server, put it in src/index.html and start the server:
npm run start
To start storybook locally and browse through the stories:
npm run storybook
Stencil
Stencil is a compiler for building fast web apps using Web Components.
Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.
Stencil components are just Web Components, so they work in any major framework or with no framework at all.
Creating/Modifying a Component
Components live in the src/components directory, and each component directory might have 6 files in it:
- The component definition
- The component CSS
- The Story for the component
- A generated readme
- End-to-End tests (testing the component from a consumer perspective)
- Unit tests (testing things within the component)
Stencil requires components to be written in TypeScript, so the definition file must end in .tsx.
It's a good idea to have some basic tests for your new component/feature.
You can also check out the Stencil docs on creating a component here.
Naming Components
When creating new component tags, we recommend not using stencil in the component name (ex: <stencil-datepicker>). This is because the generated component has little to nothing to do with Stencil; it's just a web component!
Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the Ionic generated web components use the prefix ion.
Using a Component elsewhere
Publishing
This component library is meant to be able to be used on other sites. To do so, any changes to the components must be published:
npm run build
npm publish --public
Installing & Importing
First, the library must be installed:
npm install @adhocteam/component-library --save
Next, put the following code into your app's index.js file or equivalent:
import {defineCustomElements} from '@adhocteam/component-library/loader';
defineCustomelements(window);
Alternatively, you can add a <script> tag to your HTML:
<script src="https://unpkg.com/@adhocteam/component-library/dist/component-library.js"></script>
Using a component
If the library has been installed and imported correctly, you should be able to use one of the defined components anywhere in your HTML or JSX.
