diff --git a/docs/react/contributing.en-US.md b/docs/react/contributing.en-US.md index 725a7d4955..8ac2909293 100644 --- a/docs/react/contributing.en-US.md +++ b/docs/react/contributing.en-US.md @@ -1,5 +1,5 @@ --- -order: 9 +order: 10 title: Contributing toc: false --- @@ -16,7 +16,7 @@ All work on Ant Design happens directly on [GitHub](https://github.com/ant-desig ## Branch Organization -According to our [release schedule](changelog#Release-Schedule), we'll cut a `feature` branch (e.g. `feature-3.1` for 3.1 release) from `master` every month. If you send a bugfix pull request, please do it against the `master` branch, if it's a feature pull request, please do it against the `feature` branch. +According to our [release schedule](changelog#Release-Schedule), we maintians two branchs `master` and `feature`. If you send a bugfix pull request, please do it against the `master` branch, if it's a feature pull request, please do it against the `feature` branch. ## Bugs diff --git a/docs/react/contributing.zh-CN.md b/docs/react/contributing.zh-CN.md index eb96f97ead..b15238a31d 100644 --- a/docs/react/contributing.zh-CN.md +++ b/docs/react/contributing.zh-CN.md @@ -1,5 +1,5 @@ --- -order: 9 +order: 10 title: 贡献指南 toc: false --- @@ -16,7 +16,7 @@ toc: false ## 分支管理 -基于我们的 [发布周期](/changelog)，我们每个月都会从 `master` 分支切一个 `feature` 分支出来（比如 `features-3.1` 分支用来发布 3.1 版本）。 如果你要修一个 bug，那么请发 pull request 到 `master`；如果你要提一个增加新功能的 pull request，那么请基于 `feature` 分支来做。 +基于我们的 [发布周期](/changelog)，我们长期维护两个分支 `master` 和 `feature`。如果你要修一个 bug，那么请发 pull request 到 `master`；如果你要提一个增加新功能的 pull request，那么请基于 `feature` 分支来做。 ## Bugs diff --git a/docs/react/customize-theme.en-US.md b/docs/react/customize-theme.en-US.md index 6f6434ac7d..f6aa36648e 100644 --- a/docs/react/customize-theme.en-US.md +++ b/docs/react/customize-theme.en-US.md @@ -98,7 +98,7 @@ Another approach to customize theme is creating a `less` file within variables t Note: This way will load the styles of all components, regardless of your demand, which cause `style` option of `babel-plugin-import` not working. -## How to avoid modifying global styles ? +## How to avoid modifying global styles? Currently ant-design is designed as a whole experience and modify global styles (eg `body` etc). If you need to integrate ant-design as a part of an existing website, it's likely you want to prevent ant-design to override global styles. diff --git a/docs/react/faq.en-US.md b/docs/react/faq.en-US.md new file mode 100644 index 0000000000..f8554e6621 --- /dev/null +++ b/docs/react/faq.en-US.md @@ -0,0 +1,158 @@ +--- +order: 9 +title: FAQ +--- + +Search in the questions about React first: https://reactfaq.site . + +### Are you going to provide Vue(etc...) edition? + +No, but [the LICENSE of ant-design](https://github.com/ant-design/ant-design/blob/master/LICENSE) is MIT. So, you can try to implement it with ant-design's [style](https://github.com/ant-design/ant-design/tree/master/style), like: [ant-design-vue](https://github.com/vueComponent/ant-design-vue) [vue-beauty)](https://github.com/FE-Driver/vue-beauty) or [antue](https://github.com/zzuu666/antue). + +### Are you going to provide Sass/Stylus(etc...) style file? + +No, actually, you can convert Less to Sass/Stylus(etc...) with tools (which you can Google). + +### `Select Dropdown DatePicker TimePicker Popover Popconfirm` will disappear when I click another popup component inside it, How to resolve it? + +Use ` trigger.parentNode}>` to render component inside the scroll area. (Or other getXxxxContainer props). + +https://ant.design/components/select/#Select-props + +related issue: [#3487](https://github.com/ant-design/ant-design/issues/3487) [#3438](https://github.com/ant-design/ant-design/issues/3438) + +### How to modify default theme of Ant Design? + +See: https://ant.design/docs/react/customize-theme . + +### Would you supply other themes? + +No, we follow Ant Design specification. https://github.com/ant-design/ant-design/issues/1241 + +### How to modify `Menu`/`Button`(etc...)'s style? + +You can override its style. But we don't recommend to do so. antd is not only a set of React components but also a design specification. + +### I just want to use `Menu`/`Button`(etc...), but it seems that I have to import the whole antd and its style. + +Try [babel-plugin-import](https://github.com/ant-design/babel-plugin-import), or import what you need in this way: + +```jsx +import Menu from 'antd/lib/menu'; +import 'antd/lib/button/style/css'; +``` + +or (ES6 way with tree shaking): + +```jsx +import { Menu, Breadcrumb, Icon } from 'antd'; +``` + +### How to optimize momentjs bundle size with webpack? + +See: https://github.com/jmblog/how-to-optimize-momentjs-with-webpack + +### It doesn't work when I change `defaultValue` dynamically. + +The `defaultXxxx` (like `defaultValue`) of `Input`/`Select`(etc...) only works in first render. It is a specification of React, please read [React's documentation](https://facebook.github.io/react/docs/forms.html#controlled-components). + +### I set the `value` of `Input`/`Select`(etc...), and then, it cannot be changed by user's action. + +Try `defaultValue` or `onChange` to change `value`, and please read [React's documentation](https://facebook.github.io/react/docs/forms.html#controlled-components). + +### antd override my global styles! + +Yes, antd is designed to develop a complete background application, we override some global styles for styling convenience and it can't be removed now. More info trace https://github.com/ant-design/ant-design/issues/4331 . + +Or follow instruction in [How to avoid modifying global styles?](docs/react/customize-theme#How-to-avoid-modifying-global-styles-?) + +### I cannot install `antd` and `antd`'s dependencies(etc...). FYI, I live in C mainland. + +Long live the Girl Friend Wall! And try [cnpm](http://npm.taobao.org/). + +### I set `dependencies.antd` as git repository in package.json, but it doesn't work. + +Yes, please install `antd` with npm. If you want to install the latest version, try `npm install antd@beta`. + +### `message` and `notification` is lower case, but other components are capitalized. Typo? + +No, as `message` is just a function, not a React Component. + +### `antd` doesn't work well in mobile. + +Please check [And Design Mobile](http://mobile.ant.design) for details. `antd` has not been optimized to do so. You may try [react-component](https://github.com/react-component/), those repositories which start with 'm-' 'rn-' are designed for mobile. + +### Does `antd` supply standalone files like 'react' do? + +Yep, you can [import `antd` with script tag](https://ant.design/docs/react/install?locale=en-US#Import-in-Browser). But we recommend use `npm` to import `antd`, it is simple and ease to maintain. + +### I can't visit `icon` in my network environment. + +You should deploy the iconfont files to your network by following this [example](https://github.com/ant-design/antd-init/tree/7c1a33cadb98f2fd8688fe527dd7f98215b9bced/examples/local-iconfont). [#1070](https://github.com/ant-design/ant-design/issues/1070) + +After 3.9.x [we are using svg icon](/components/icon#svg-icons) so you don't need to deploy iconfont locally any more! + +### How to extend antd's components? + +If you need some features which should not be included in antd, try to extend antd's component with [HOC](https://gist.github.com/sebmarkbage/ef0bf1f338a7182b6775). [more](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750#.eeu8q01s1) + +### How to spell Ant Design correctly? + +- ✅ **Ant Design**: Capitalized with space, for the design language +- ✅ **antd**: all lowercase, for the React UI library + +Here are some typical wrong examples: + +- ❌ AntD +- ❌ antD +- ❌ Antd +- ❌ ant design +- ❌ AntDesign +- ❌ antdesign +- ❌ Antdesign + +### Do you guys have any channel for donation? like PayPal or Alipay. + +No yet. + +### Why not? + +Alibaba will pay us. + +--- + +## Errors & Warnings + +Here are some errors & warnings that you may meet while using antd, but most of them are not bugs of antd. + +### Adjacent JSX elements must be wrapped in an enclosing tag + +An [answer from StackOverflow](http://stackoverflow.com/questions/25034994/how-to-correctly-wrap-few-td-tags-for-jsxtransformer), and please read [React's documentation](http://facebook.github.io/react/docs/displaying-data.html#components-are-just-like-functions). + +### React.createElement: type should not be null, undefined, boolean, or number. It should be a string (for DOM elements) or a ReactClass (for composite components) + +Please make sure that you import `antd`'s components correctly. Read the corresponding documentation of the `antd`'s version which you use. And pay attention to typo. + +### rm is not recognized as an internal or external command + +Please read this [issue](https://github.com/ant-design/ant-design/issues/650#issuecomment-164966511), or try Linux/Unix. + +### Failed propType: Invalid prop `AAA` of type `BBB` supplied to `CCC`, expected `DDD`. Check the render method of `EEE`. + +Please read the corresponding documentation of the `antd`'s version which you use, and make sure that you pass value with correct type to `antd`'s components, + +### Unknown option: xxx/package.json.presets + +An [answer from Stack Overflow](http://stackoverflow.com/questions/33685365/unknown-option-babelrc-presets). + +### Invariant Violation: findComponentRoot(...): Unable to find element. + +You may import React twice. Set React & ReactDOM as external, if you are using webpack, See: [#525](https://github.com/ant-design/ant-design/issues/525). If you are using others(browserify, etc...), please read its documentation and find options which can set React & ReactDOM as external. diff --git a/docs/react/faq.zh-CN.md b/docs/react/faq.zh-CN.md new file mode 100644 index 0000000000..f8554e6621 --- /dev/null +++ b/docs/react/faq.zh-CN.md @@ -0,0 +1,158 @@ +--- +order: 9 +title: FAQ +--- + +Search in the questions about React first: https://reactfaq.site . + +### Are you going to provide Vue(etc...) edition? + +No, but [the LICENSE of ant-design](https://github.com/ant-design/ant-design/blob/master/LICENSE) is MIT. So, you can try to implement it with ant-design's [style](https://github.com/ant-design/ant-design/tree/master/style), like: [ant-design-vue](https://github.com/vueComponent/ant-design-vue) [vue-beauty)](https://github.com/FE-Driver/vue-beauty) or [antue](https://github.com/zzuu666/antue). + +### Are you going to provide Sass/Stylus(etc...) style file? + +No, actually, you can convert Less to Sass/Stylus(etc...) with tools (which you can Google). + +### `Select Dropdown DatePicker TimePicker Popover Popconfirm` will disappear when I click another popup component inside it, How to resolve it? + +Use ` trigger.parentNode}>` to render component inside the scroll area. (Or other getXxxxContainer props). + +https://ant.design/components/select/#Select-props + +related issue: [#3487](https://github.com/ant-design/ant-design/issues/3487) [#3438](https://github.com/ant-design/ant-design/issues/3438) + +### How to modify default theme of Ant Design? + +See: https://ant.design/docs/react/customize-theme . + +### Would you supply other themes? + +No, we follow Ant Design specification. https://github.com/ant-design/ant-design/issues/1241 + +### How to modify `Menu`/`Button`(etc...)'s style? + +You can override its style. But we don't recommend to do so. antd is not only a set of React components but also a design specification. + +### I just want to use `Menu`/`Button`(etc...), but it seems that I have to import the whole antd and its style. + +Try [babel-plugin-import](https://github.com/ant-design/babel-plugin-import), or import what you need in this way: + +```jsx +import Menu from 'antd/lib/menu'; +import 'antd/lib/button/style/css'; +``` + +or (ES6 way with tree shaking): + +```jsx +import { Menu, Breadcrumb, Icon } from 'antd'; +``` + +### How to optimize momentjs bundle size with webpack? + +See: https://github.com/jmblog/how-to-optimize-momentjs-with-webpack + +### It doesn't work when I change `defaultValue` dynamically. + +The `defaultXxxx` (like `defaultValue`) of `Input`/`Select`(etc...) only works in first render. It is a specification of React, please read [React's documentation](https://facebook.github.io/react/docs/forms.html#controlled-components). + +### I set the `value` of `Input`/`Select`(etc...), and then, it cannot be changed by user's action. + +Try `defaultValue` or `onChange` to change `value`, and please read [React's documentation](https://facebook.github.io/react/docs/forms.html#controlled-components). + +### antd override my global styles! + +Yes, antd is designed to develop a complete background application, we override some global styles for styling convenience and it can't be removed now. More info trace https://github.com/ant-design/ant-design/issues/4331 . + +Or follow instruction in [How to avoid modifying global styles?](docs/react/customize-theme#How-to-avoid-modifying-global-styles-?) + +### I cannot install `antd` and `antd`'s dependencies(etc...). FYI, I live in C mainland. + +Long live the Girl Friend Wall! And try [cnpm](http://npm.taobao.org/). + +### I set `dependencies.antd` as git repository in package.json, but it doesn't work. + +Yes, please install `antd` with npm. If you want to install the latest version, try `npm install antd@beta`. + +### `message` and `notification` is lower case, but other components are capitalized. Typo? + +No, as `message` is just a function, not a React Component. + +### `antd` doesn't work well in mobile. + +Please check [And Design Mobile](http://mobile.ant.design) for details. `antd` has not been optimized to do so. You may try [react-component](https://github.com/react-component/), those repositories which start with 'm-' 'rn-' are designed for mobile. + +### Does `antd` supply standalone files like 'react' do? + +Yep, you can [import `antd` with script tag](https://ant.design/docs/react/install?locale=en-US#Import-in-Browser). But we recommend use `npm` to import `antd`, it is simple and ease to maintain. + +### I can't visit `icon` in my network environment. + +You should deploy the iconfont files to your network by following this [example](https://github.com/ant-design/antd-init/tree/7c1a33cadb98f2fd8688fe527dd7f98215b9bced/examples/local-iconfont). [#1070](https://github.com/ant-design/ant-design/issues/1070) + +After 3.9.x [we are using svg icon](/components/icon#svg-icons) so you don't need to deploy iconfont locally any more! + +### How to extend antd's components? + +If you need some features which should not be included in antd, try to extend antd's component with [HOC](https://gist.github.com/sebmarkbage/ef0bf1f338a7182b6775). [more](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750#.eeu8q01s1) + +### How to spell Ant Design correctly? + +- ✅ **Ant Design**: Capitalized with space, for the design language +- ✅ **antd**: all lowercase, for the React UI library + +Here are some typical wrong examples: + +- ❌ AntD +- ❌ antD +- ❌ Antd +- ❌ ant design +- ❌ AntDesign +- ❌ antdesign +- ❌ Antdesign + +### Do you guys have any channel for donation? like PayPal or Alipay. + +No yet. + +### Why not? + +Alibaba will pay us. + +--- + +## Errors & Warnings + +Here are some errors & warnings that you may meet while using antd, but most of them are not bugs of antd. + +### Adjacent JSX elements must be wrapped in an enclosing tag + +An [answer from StackOverflow](http://stackoverflow.com/questions/25034994/how-to-correctly-wrap-few-td-tags-for-jsxtransformer), and please read [React's documentation](http://facebook.github.io/react/docs/displaying-data.html#components-are-just-like-functions). + +### React.createElement: type should not be null, undefined, boolean, or number. It should be a string (for DOM elements) or a ReactClass (for composite components) + +Please make sure that you import `antd`'s components correctly. Read the corresponding documentation of the `antd`'s version which you use. And pay attention to typo. + +### rm is not recognized as an internal or external command + +Please read this [issue](https://github.com/ant-design/ant-design/issues/650#issuecomment-164966511), or try Linux/Unix. + +### Failed propType: Invalid prop `AAA` of type `BBB` supplied to `CCC`, expected `DDD`. Check the render method of `EEE`. + +Please read the corresponding documentation of the `antd`'s version which you use, and make sure that you pass value with correct type to `antd`'s components, + +### Unknown option: xxx/package.json.presets + +An [answer from Stack Overflow](http://stackoverflow.com/questions/33685365/unknown-option-babelrc-presets). + +### Invariant Violation: findComponentRoot(...): Unable to find element. + +You may import React twice. Set React & ReactDOM as external, if you are using webpack, See: [#525](https://github.com/ant-design/ant-design/issues/525). If you are using others(browserify, etc...), please read its documentation and find options which can set React & ReactDOM as external.