feat: update readme

hellof2e · Oct 27, 2022 · c847874 · c847874
1 parent d3d37de
commit c847874
Show file tree

Hide file tree

Showing 4 changed files with 528 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -9,50 +9,60 @@
 
 <div align="center">
 
-  一套企业级跨框架 UI 设计语言
+  An enterprise-class UI design language and cross-framework UI library, Based on web components.
 
 </div>
 
-## 特性
-
-- 支持 Vue、React、Angular 等各类框架/无框架。
-- 完全覆盖您所需要的各种通用组件。
-- 支持按需引用。
-- 详尽的文档和示例。
-- 单元测试覆盖。
-- 支持 TypeScript。
-- 支持定制主题。
-- 国际化语言支持。
-- 支持服务端渲染（Bate）。
-
-## 兼容环境
+English | [简体中文](./README-zh_CN.md)
+
+## Motivation
+The emergence of the technical framework has improved the development experience and page performance, but the continuous iterative update of the technical framework has brought many challenges to the maintenance of the project, such as:
+
+- Visual components cannot be used across technical frameworks (React, Vue, etc.)
+- Once the technical framework is upgraded, visual components often have to be upgraded iteratively
 
-现代浏览器和 IE11（需要 [polyfills](https://www.webcomponents.org/polyfills)）
+Therefore, we developed this UI framework to isolate it from the technology framework (no technology stack), so that visual components can avoid falling into the vicious circle of technology stack iteration and iteration.
+## Features
+
+- Support Vue, React, Angular, JQ and no framework project
+- 40+ High quality components
+- Support Tree Shaking
+- 90%+ Unit test coverage
+- Written in TypeScript
+- Support TypeScript
+- Support Custom Theme
+- Support i18n, built-in 20+ languages
 
-## 安装
+## Install
+Using `npm` to install:
 
 ```bash
-// Vue/Angular/无框架前端工程
-npm i quarkd --save
+# install for Vue/React/Angular/No framework project
+npm i quarkd
 ```
 
+
 ```bash
-// React 项目
+#  install for React project
 npm i @quarkd/quark-react --save
 ```
 
-## 示例
+## Quickstart
 Vue.x
 ```jsx
+// 1. Import the components you need
 import "quarkd/lib/button"
 
+// 2. Use it
 <quark-button type="primary">Button</quark-button>
 ```
 
 React.x
 ```jsx
+// 1. Import the components you need
 import { Button } from '@quarkd/quark-react';
 
+// 2. Use it
 const App = () => (
   <>
     <Button type="primary">Button</Button>
@@ -61,18 +71,19 @@ const App = () => (
 ```
 
 Angular
-```html
-import { Component } from '@angular/core
+```jsx
+// 1. Import the components you need
 import "quarkd/lib/button"
 
+// 2. Use it
 @Component({
   template: `<quark-button loading="{{loading}}"" (click)="handleClick()">
     Button
   </quark-button>`
 })
 ```
 
-其它 H5 项目
+No framework project
 ```html
 <!DOCTYPE html>
 <html lang="en">
@@ -91,19 +102,66 @@ import "quarkd/lib/button"
 </html>
 ```
 
-## 定制主题
+## Custom theme
+
+See [custom theme](https://quark-design.hellobike.com/#/zh-CN/guide/theme) 。
+
+## Internationalization
+
+Dozens of languages supported in, see [Docs](https://quark-design.hellobike.com/#/en-US/guide/internationalization)。
+
+## Browser Support
 
-参考  [定制主题](https://quark-design.hellobike.com/#/zh-CN/guide/theme) 文档。
+Modern browsers and Internet Explorer 11 (with[polyfills](https://www.webcomponents.org/polyfills))。
 
-## 国际化
+## Contribution Guide
 
-参考 [国际化文档](https://quark-design.hellobike.com/#/zh-CN/guide/internationalization)。
+Please make sure to read the [Contributing Guide](https://github.com/hellof2e/quark-design/blob/main/CONTRIBUTORING.md) before making a pull request. 
 
-## 参与共建
-参考 [本地开发文档](https://github.com/hellof2e/quark-design/blob/main/CONTRIBUTORING.md)
+## Special Note
 
-## 特别说明
-- 由于 `quarkd` 提供的组件均为原生自定义元素（类比div），因此组件派发的事件需要使用addEventLisener接收。
-- Vue 技术栈使用 `@xx` 即可接收原生派发的事件，因此不需要使用addEventLisener接收。
-- 针对 React 技术栈，为了避免开发者手动 addEventLisener 接收事件，我们底层依托 `quarkd` ，上层进行了 Reactify(React 化)！因此 React 项目推荐使用 `@quarkd/quark-react`。
+- Since the components provided by `quarkd` are all native custom elements (analogous to div), the events dispatched by the components need to be received using addEventListener.
+- The Vue stack uses `@xx` to receive natively dispatched events, so there is no need to use addEventListener to receive them.
+- For the React technology stack, in order to avoid developers manually addingEventLisener to receive events, we rely on `quarkd` at the bottom and Reactify (Reactize) the upper layer! Therefore the React project recommends using `@quarkd/quark-react`.
+
+
+## Pay attention
+
+- Unknown custom element in Vue project:
+
+```html
+<!-- vue2: -->
+Unknown custom element: <quark-icon> - did you register the component correctly? For recursive components, make sure to provide the "name" option.
+<!-- vue3 -->
+[Vue warn]: Failed to resolve component: quark-icon 
+```
+
+This is because the syntax part of Vue components refers to custom elements. In order to avoid conflicts with Vue components, custom elements need to be ignored! Please inject the following code into the project:
+
+```tsx
+// VUE2.x
+Vue.config.ignoredElements = [/^quark-/]
+
+// VUE3.x
+// https://v3.cn.vuejs.org/guide/migration/global-api.html#config-productiontip-%E7%A7%BB%E9%99%A4
+const app = createApp({})
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('quark-')
+```
 
+If you are using vite, modify vite.config.js:
+
+```tsx
+import vue from '@vitejs/plugin-vue'
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: tag => tag.startsWith('quark-')
+        }
+      }
+    })
+  ]
+}
+```
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -0,0 +1,164 @@
+<p align="center">
+  <a href="https://ant.design">
+    <img width="200" src="https://user-images.githubusercontent.com/14307551/197440754-08db4379-eb0f-4808-890d-690355e6e8d2.png">
+  </a>
+</p>
+
+
+<h1 align="center">Quark Design</h1>
+
+<div align="center">
+
+  一套企业级跨框架 UI 设计语言，底层基于 Web components
+
+</div>
+
+## 特性
+
+- 支持 Vue、React、Angular 等各类框架/无框架。
+- 完全覆盖您所需要的各种通用组件。
+- 支持按需引用。
+- 详尽的文档和示例。
+- 单元测试覆盖。
+- 支持 TypeScript。
+- 支持定制主题。
+- 国际化语言支持。
+- 支持服务端渲染（Bate）。
+
+[English](./README.md) | 简体中文
+
+## 🤔 动机
+
+技术框架的出现，提升了开发体验以页面性能，但技术框架的不断迭代更新，为项目的维护带来诸多挑战，如：
+
+- 视觉组件无法跨技术框架（React、Vue等）使用
+- 技术框架一旦升级，视觉组件常常必须配合迭代升级
+
+因此，我们开发了这套 UI 框架，旨在与技术框架隔离（技术栈无关），让视觉组件避免落入技术栈迭代而迭代的怪圈。
+
+## 安装
+
+```bash
+# Vue/Angular/JQ/无框架工程
+npm i quarkd
+```
+
+
+```bash
+# React 项目
+npm i @quarkd/quark-react
+```
+
+## 示例
+Vue.x
+```jsx
+import "quarkd/lib/button"
+
+<quark-button type="primary">Button</quark-button>
+```
+
+React.x
+```jsx
+import { Button } from '@quarkd/quark-react';
+
+const App = () => (
+  <>
+    <Button type="primary">Button</Button>
+  </>
+);
+```
+
+Angular
+```jsx
+import { Component } from '@angular/core
+import "quarkd/lib/button"
+
+@Component({
+  template: `<quark-button loading="{{loading}}"" (click)="handleClick()">
+    Button
+  </quark-button>`
+})
+```
+
+其它 H5 项目
+```html
+<!DOCTYPE html>
+<html lang="en">
+<body>
+  <quark-button loading="false" id="btn">Button</quark-button>
+</body>
+
+<script src="./node_modules/quarkd/lib/button/index.js" /> // or cdn
+<script>
+  window.addEventListener(function() {
+    const el = document.getElementById('btn')
+    el.loading = true
+    setTimeout(() => { el.loading = true }, 2000);
+  })
+</script>
+</html>
+```
+
+## 定制主题
+
+参考  [定制主题](https://quark-design.hellobike.com/#/zh-CN/guide/theme) 文档。
+
+## 国际化
+
+参考 [国际化文档](https://quark-design.hellobike.com/#/zh-CN/guide/internationalization)。
+
+## 兼容环境
+
+现代浏览器和 IE11（需要 [polyfills](https://www.webcomponents.org/polyfills)）
+
+## 参与共建
+
+参考 [本地开发文档](https://github.com/hellof2e/quark-design/blob/main/CONTRIBUTORING.md)
+
+## 特别说明
+
+- 由于 `quarkd` 提供的组件均为原生自定义元素（类比div），因此组件派发的事件需要使用addEventLisener接收。
+- Vue 技术栈使用 `@xx` 即可接收原生派发的事件，因此不需要使用addEventLisener接收。
+- 针对 React 技术栈，为了避免开发者手动 addEventLisener 接收事件，我们底层依托 `quarkd` ，上层进行了 Reactify(React 化)！因此 React 项目推荐使用 `@quarkd/quark-react`。
+
+
+##  注意
+
+- Vue 工程中使用组件可能会出现告警：
+
+```html
+<!-- vue2: -->
+Unknown custom element: <quark-icon> - did you register the component correctly? For recursive components, make sure to provide the "name" option.
+<!-- vue3 -->
+[Vue warn]: Failed to resolve component: quark-icon 
+```
+
+这是由于 Vue 组件的语法部分参考了自定义元素，为了避免与 Vue 组件产生冲突，需要将自定义元素忽略！请在工程中注入如下代码即可：
+
+```tsx
+// VUE2.x
+Vue.config.ignoredElements = [/^quark-/]
+
+// VUE3.x
+// https://v3.cn.vuejs.org/guide/migration/global-api.html#config-productiontip-%E7%A7%BB%E9%99%A4
+const app = createApp({})
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('quark-')
+```
+
+如果您使用的是 vite，修改 vite.config.js:
+
+```tsx
+import vue from '@vitejs/plugin-vue'
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: tag => tag.startsWith('quark-')
+        }
+      }
+    })
+  ]
+}
+```