diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 59717e80c0..01f655e62b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,10 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate + - uses: actions/setup-node@v4 with: @@ -35,7 +38,9 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: @@ -60,7 +65,7 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: corepack disable && npm install -g pnpm@latest - uses: actions/setup-node@v4 with: diff --git a/.github/workflows/cypress.yml b/.github/workflows/cypress.yml index 5ede657dc8..30a162a7b3 100644 --- a/.github/workflows/cypress.yml +++ b/.github/workflows/cypress.yml @@ -16,7 +16,9 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: diff --git a/.github/workflows/realease-tag.yml b/.github/workflows/realease-tag.yml index 0e5c85e553..ee98598e78 100644 --- a/.github/workflows/realease-tag.yml +++ b/.github/workflows/realease-tag.yml @@ -14,7 +14,9 @@ jobs: uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: diff --git a/.github/workflows/sync-h5.yml b/.github/workflows/sync-h5.yml index 31f6dc06a6..14ae6ab026 100644 --- a/.github/workflows/sync-h5.yml +++ b/.github/workflows/sync-h5.yml @@ -17,7 +17,9 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: diff --git a/.github/workflows/sync-migrate.yml b/.github/workflows/sync-migrate.yml index 28a2c4ddb8..82dde38c78 100644 --- a/.github/workflows/sync-migrate.yml +++ b/.github/workflows/sync-migrate.yml @@ -18,7 +18,9 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: diff --git a/.github/workflows/sync-taro.yml b/.github/workflows/sync-taro.yml index 64ca04d724..d135e2ca61 100644 --- a/.github/workflows/sync-taro.yml +++ b/.github/workflows/sync-taro.yml @@ -17,7 +17,9 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - run: corepack enable pnpm + run: | + corepack enable + corepack prepare pnpm@10.0.0 --activate - uses: actions/setup-node@v4 with: diff --git a/.gitignore b/.gitignore index f56e3aa29f..54d4f200c4 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ node_modules .npmrc /dist /dist-demo +/dist-site /libs /jd/upload.js # yarn.lock diff --git a/index.html b/index.html index 47e045264c..738380c63b 100644 --- a/index.html +++ b/index.html @@ -49,7 +49,7 @@ continue.
- + + + + + + +
+ + + +``` + +::: + +## Component usage + +> NutUI React supports Tree Shaking by default, and supports on-demand import of component JS files without any plug-in configuration. However, css style files cannot be implemented in this way, so from the perspective of style, it can be divided into the following two usage methods: + +#### Method 1, Conventional usage: Full import of styles + +:::demo + +```js +import * as React from 'react' +import * as ReactDOM from 'react-dom' +import '@nutui/nutui-react/dist/style.css' +import { Button } from '@nutui/nutui-react' + +ReactDOM.render( +
+ +
, + document.getElementById('app') +) +``` + +::: + +#### Method 2, import styles on demand + +
+vite + +Install the `vite-plugin-imp` plugin and configure it. + +```sh +#pnpm +pnpm add vite-plugin-imp -D +#yarn +yarn add vite-plugin-imp -D +# npm +npm install vite-plugin-imp -D +``` + +:::demo + +```js +// vite.config.js +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' +import vitePluginImp from 'vite-plugin-imp' + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [ + react(), + vitePluginImp({ + libList: [ + { + libName: '@nutui/nutui-react', + style: (name) => { + return `@nutui/nutui-react/dist/esm/${name}/style/css` + }, + replaceOldImport: false, + camel2DashComponentName: false, + }, + ], + }), + ], +}) +``` + +::: + +

+ +
+webpack + +Install the `babel-plugin-import` plugin and configure it. + +```sh +#pnpm +pnpm add babel-plugin-import -D +#yarn +yarn add babel-plugin-import -D +# npm +npm install babel-plugin-import -D +``` + +Babel configuration: + +:::demo + +```js +{ + //... + plugins: [ + [ + 'import', + { + libraryName: '@nutui/nutui-react', + libraryDirectory: 'dist/esm', + style: 'css', + camel2DashComponentName: false, + }, + 'nutui-react', + ], + ] +} +``` + +::: + +

+ +## Precautions for use + +- NutUI-React is built on [react@^18.0.0](https://www.npmjs.com/package/react) +- The component CSS unit uses **px**, if you need **rem** unit in your project, you can convert it with some tools, such as [px2rem-loader](https://www.npmjs.com/package/px2rem-loader) of [webpack](https://www.webpackjs.com/), [postcss] of [postcss](https://github.com/postcss/postcss) -plugin-px2rem](https://www.npmjs.com/package/postcss-plugin-px2rem) plugin etc. + +## Examples + +Source code for all the examples can be found in the [packages/templates](https://github.com/jdf2e/nutui-react/tree/next/packages/nutui-templates) directory. + + diff --git a/src/sites/sites-react/doc/docs/react/start-react.md b/src/sites/sites-react/doc/docs/react/start-react.md new file mode 100644 index 0000000000..deb0328ec8 --- /dev/null +++ b/src/sites/sites-react/doc/docs/react/start-react.md @@ -0,0 +1,190 @@ +# 快速上手 + +## 介绍 + +通过本文你可以掌握 NutUI React 的安装和使用方法，操作简单易上手，开发简洁快速。 + +## 安装 + +#### 1. 通过 NPM 安装 + +```sh +# pnpm +pnpm add @nutui/nutui-react +# yarn +yarn add @nutui/nutui-react +# npm +npm install @nutui/nutui-react +``` + +#### 2. 通过 CDN 安装及使用 + +> 可以在 **jsdelivr** 和 **unpkg** 等公共 CDN 上获取到 NutUI。 +> 不推荐在生产环境使用组件库 CDN，如果需要这种使用方式，建议将特定版本的 CDN 文件下载至本地项目目录中使用。 + +:::demo + +```html + + + + + + + + + + + + + + +
+ + + +``` + +::: + +## 组件使用 + +> NutUI React 默认支持 Tree Shaking，在无任何插件配置的情况下支持组件 JS 文件的按需引入。但 css 样式文件无法通过这种方式实现，因此从样式的角度可以分为以下两种使用方法： + +#### 方法一、常规用法：全量引入样式 + +:::demo + +```js +import * as React from 'react' +import * as ReactDOM from 'react-dom' +import '@nutui/nutui-react/dist/style.css' +import { Button } from '@nutui/nutui-react' + +ReactDOM.render( +
+ +
, + document.getElementById('app') +) +``` + +::: + +#### 方法二、按需引入样式 + +
+vite + +安装 `vite-plugin-imp` 插件并配置。 + +```sh +# pnpm +pnpm add vite-plugin-imp -D +# yarn +yarn add vite-plugin-imp -D +# npm +npm install vite-plugin-imp -D +``` + +:::demo + +```js +// vite.config.js +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' +import vitePluginImp from 'vite-plugin-imp' + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [ + react(), + vitePluginImp({ + libList: [ + { + libName: '@nutui/nutui-react', + style: (name) => { + return `@nutui/nutui-react/dist/esm/${name}/style/css` + }, + replaceOldImport: false, + camel2DashComponentName: false, + }, + ], + }), + ], +}) +``` + +::: + +

+ +
+webpack + +安装 `babel-plugin-import` 插件并配置。 + +```sh +# pnpm +pnpm add babel-plugin-import -D +# yarn +yarn add babel-plugin-import -D +# npm +npm install babel-plugin-import -D +``` + +babel 配置： + +:::demo + +```js +{ + // ... + plugins: [ + [ + 'import', + { + libraryName: '@nutui/nutui-react', + libraryDirectory: 'dist/esm', + style: 'css', + camel2DashComponentName: false, + }, + 'nutui-react', + ], + ] +} +``` + +::: + +

+ +## 使用注意事项 + +- NutUI-React 基于 [react@^18.0.0](https://www.npmjs.com/package/react) 构建 +- 组件 CSS 单位使用的是 **px**，如果你的项目中需要 **rem** 单位，可借助一些工具进行转换，比如 [webpack](https://www.webpackjs.com/) 的 [px2rem-loader](https://www.npmjs.com/package/px2rem-loader)、[postcss](https://github.com/postcss/postcss) 的 [postcss-plugin-px2rem](https://www.npmjs.com/package/postcss-plugin-px2rem) 插件等 + +## 示例 + +示例代码可以再 [packages/templates](https://github.com/jdf2e/nutui-react/tree/next/packages/nutui-templates) 下查看 + + diff --git a/src/sites/sites-react/doc/docs/react/theme-react.en-US.md b/src/sites/sites-react/doc/docs/react/theme-react.en-US.md new file mode 100644 index 0000000000..062a297deb --- /dev/null +++ b/src/sites/sites-react/doc/docs/react/theme-react.en-US.md @@ -0,0 +1,68 @@ +# Customize Theme + +## Introduce + +NutUI-React supports flexible style customization to meet multiple visual business and brand needs, including but not limited to support for global master tone and component-specific visual customization. +
+
+In NutUI-React version 2.0, the Sass theme customization function of 1.x can still be used. We added CSS variables to the original theme customization function, so that the new theme customization function can be used without introducing additional SCSS style files. + +## Method 1: Use CSS Variables to configure topics + +`NutUI - React` can [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) to organize the pattern, By overwriting these 'CSS' variables, you can achieve custom theme, dynamic switching theme and other functions. +
+
+You can play with the [ConfigProvider](#/zh-CN/component/configprovider) component. +
+
+We recommend replacing [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) for the theme of personalized configuration. + +## Method 2: Use Sass variable for topic configuration + +#### Step 1: Create a custom variable SCSS file + +Create a new 'SCSS' file 'custom_theme.scss' in your local project. + +```scss +// Dominant tone +$color-primary: #fa2c19; +$color-primary-end: #fa6419; +... +``` + +#### Step 2: Modify the configuration file of the local project webpack or vite + +Modify the ** ass-loader** configuration in the 'vite' or 'webpack' configuration file. The following example + +#### vite + +```javascript +// https://vitejs.dev/config/ +export default defineConfig({ + //... + css: { + preprocessorOptions: { + scss: { + additionalData: `@import "@nutui/nutui-react/dist/styles/variables.scss";@import "./your/custom_theme.scss";`, + }, + }, + }, +}) +``` + +#### webpack + +```javascript +{ + test: /\.(sa|sc)ss$/, + use: [ + { + loader: 'sass-loader', + options: { + // Note: The option name is different for different versions of ass-loader. For details, see the corresponding version document of ass-loader + data: `@import "./assets/custom_theme.scss";@import "@nutui/nutui/dist/styles/variables.scss";`, + } + } + ] +} +``` diff --git a/src/sites/sites-react/doc/docs/react/theme-react.md b/src/sites/sites-react/doc/docs/react/theme-react.md new file mode 100644 index 0000000000..cc180538e2 --- /dev/null +++ b/src/sites/sites-react/doc/docs/react/theme-react.md @@ -0,0 +1,65 @@ +# 主题定制 + +## 介绍 + +NutUI-React 支持灵活的样式定制，满足多种视觉业务和品牌需求，包括但不限于全局主色调和特定组件视觉定制的支持。 +
+
+在 NutUI-React 的 2.0 版本中，依然可以使用 1.x 的 Sass 定制主题功能，我们在原有的主题定制功能上新增了 CSS 变量， 无需引入额外的 SCSS 样式文件，就可以使用到新的主题定制功能。 + +## 方式一 使用 CSS Variables 进行主题配置 + +`NutUI-React` 组件可以通过 [CSS Vars](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 `CSS` 变量，可以实现定制主题、动态切换主题等功能。 +
+
+您可在 [ConfigProvider 组件](#/zh-CN/component/configprovider) 进行体验。我们更推荐使用替换 [CSS Vars](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 的方式来进行个性化的主题配置。 + +## 方式二 使用 Sass 变量 进行主题配置 + +### 第一步 新建自定义变量 SCSS 文件 + +在本地项目中新建一个 `SCSS` 文件 `custom_theme.scss` 进行自定义。 + +```scss +// 主色调 +$color-primary: #fa2c19; +$color-primary-end: #fa6419; +... +``` + +### 第二步 修改本地项目 Webpack 或者 Vite 的配置文件 + +修改 `vite` 或者 `webpack` 配置文件中 **sass-loader** 的配置。如下示例： + +#### Vite 方式 + +```javascript +// https://vitejs.dev/config/ +export default defineConfig({ + //... + css: { + preprocessorOptions: { + scss: { + additionalData: `@import "@nutui/nutui-react/dist/styles/variables.scss";@import "./your/custom_theme.scss";`, + }, + }, + }, +}) +``` + +#### Webpack 方式 + +```javascript +{ + test: /\.(sa|sc)ss$/, + use: [ + { + loader: 'sass-loader', + options: { + // 注意：在 sass-loader 不同版本，这个选项名是 是不一样的，具体可参考 sass-loader对应的版本文档 + data: `@import "./assets/custom_theme.scss";@import "@nutui/nutui/dist/styles/variables.scss";`, + } + } + ] +} +``` diff --git a/src/sites/sites-react/doc/docs/taro/contributing-react.en-US.md b/src/sites/sites-react/doc/docs/taro/contributing-react.en-US.md new file mode 100644 index 0000000000..2d201daa60 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/contributing-react.en-US.md @@ -0,0 +1,127 @@ +# Contribution Guidelines + +You can contribute to the NutUI community according to the co-construction direction in 《[NutUI invites you to build, Hello Contributor](https://jelly.jd.com/article/6320528b92d94a0068685525)》. + +  + +This guide will guide you on how to contribute to NutUI. Please take a few minutes to read this guide before you file an issue or pull request to ensure that the contribution is compliant and can help the community. + +## code of conduct + +In order to ensure a good network environment and create a comfortable development atmosphere, I hope all contributors can abide by this [Code of Conduct](https://www.contributor-covenant.org/zh-cn/version/2/1/code_of_conduct/), and please take the time to read the full text to clarify what is prohibited and what is allowed. + +## Branch management + +The main branch is currently maintained on github. If you want to fix a bug or add a feature, send a pull request to the main branch. + +  + +The official website will update [NutUI - React release cycle] (https://github.com/jdf2e/nutui-react/releases), at the same time every day developers review submitted code in the making. The release cycle is once a week, usually incorporating new code or features in advance and releasing formal packages; In case of emergency, beta versions can be released based on the specified branch. + +## Issue + +If submit Bug reports, please be sure to comply with the [` Bug report `] (https://github.com/jdf2e/nutui/blob/next/.github/ISSUE_TEMPLATE/bug_report.md) template. + +## Bugs + +We use [issue - helper] (https://nutui.jd.com/nutui-issue-helper/?repo=jdf2e/nutui-react) for bug tracking. We hope you can submit feedback through the issue assistant we provide, and provide all the development information as much as possible, because the more comprehensive the information, the faster the development response, and the bugs you find will be solved quickly. + +  + +Before you commit a bug, Please ensure that the search had existing [issue] (https://github.com/jdf2e/nutui-react/issues) and read our [FAQ] (https://nutui.jd.com/#/zh-CN/notice). + +## new features + +If you have a better idea of an existing component function or API, We also recommend that you use our provided [issue - helper] (https://nutui.jd.com/nutui-issue-helper/?repo=jdf2e/nutui-react) to submit a issue of adding new features. + +  + +If you want to help develop new features and components, Can scan [qr code] (HTTP: / / https://img13.360buyimg.com/imagetools/s300x300_jfs/t1/187308/9/29678/349561/634fa983E93012590/a641089fdfed5911 .png) join our community co-building group. + +## Participate in contribution + +If you are not familiar with the PR process of github, you can read the following two articles to learn: + +  + +[NutUI Contribution Guidelines](https://github.com/jdf2e/nutui-react/discussions/348) + +[github repository code synchronization](https://github.com/jdf2e/nutui/discussions/687) + +## Pull Request Specification + +1. Each PR addresses a single issue or adds a single feature + +2. When adding components or modifying existing components, synchronously change the corresponding unit tests and documents to ensure the stability of the code + +3. Please follow the [Angular Style Commit Message Conventions](https://gist.github.com/stephenparish/9941e89d80e2bc58a153) specification for the commit message + +4. The PR information should include which component has been modified, which problem has been solved, and associated the corresponding issue link on github + +## Pull Request Process + +1. Fork the main repository and synchronize the latest code of the main repository + +  + +2. Download the project locally, run npm install in the project root directory, and access it locally + +``` +git clone https://github.com/{github username}/nutui-react.git +npm install +npm run dev +``` + +3. Create a new branch or develop on the corresponding branch + +``` +git checkout -b username/xxxx +git checkout {current branch} +``` + +4. If the development involves new components or new features of components, it is necessary to improve the Chinese and English documentation of the components, the unit testing of the components, and use [nutui-demo](https://github.com/jdf2e/nutui-demo) to Component testing is used. + +  + +5、Ensure that the compilation function is used normally + +``` +npm run test +// node v17 +// @nutui/nutui-react +npm run build +// @nutui/nutui-react-taro +npm run build:taro +``` + +6、After the development is completed, submit it to the corresponding branch of the warehouse. After the review is passed, the PR will be merged into the main warehouse, and then wait for NutUI-React to release a new version（Once a week）。 + +  + +### Knowledge sharing + +1. Project Use Cases + +     Share the [use case](https://nutui.jd.com/#/zh-CN/case) of NutUI, we will recommend it on the official website, prepare the name of the project, Project entry (QR code\link), logo, sample image, delivery platform (H5\mini program\APP, etc.), nutui version and other information should be submitted to **nutui@jd.com** by email. + +  + +2. Article video submission + +     Share your experiences (tutorials, articles, videos, etc.) by contributing to **nutui@jd.com**. After passing the review, collect it in the [official website resource](https://nutui.jd.com/#/zh-CN/resource), and pass your knowledge and ideas to NutUI friends. + +  + +3. Co-construction and sharing + +     Based on NutUI, design or develop new tools, such as adapting to uni-app, developing plug-ins to improve efficiency, etc. If you are interested, welcome to join our [Community Development Group](https://img13.360buyimg.com/imagetools/s300x300_jfs/t1/187308/9/29678/349561/634fa983E93012590/a641089fdfed5911.png) to communicate and discuss. + +  + +### Credits + +Thanks to all the developers below who have contributed code to NutUI. + + + contributors + diff --git a/src/sites/sites-react/doc/docs/taro/contributing-react.md b/src/sites/sites-react/doc/docs/taro/contributing-react.md new file mode 100644 index 0000000000..cc161ad9f8 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/contributing-react.md @@ -0,0 +1,121 @@ +# 贡献指南 + +您可根据《[NutUI 邀您共建，Contributor 您好](https://jelly.jd.com/article/6320528b92d94a0068685525)》中的共建方向为 NutUI 社区做出贡献。 + +  + +本篇指南会指导你如何为 NutUI 贡献一份自己的力量，请在您要提 issue 或者 pull request 之前花几分钟来阅读一遍这篇指南，保证贡献是符合规范并且能帮助到社区。 + +## 行为准则 + +为保证良好的网络环境，营造舒适的开发氛围，希望所有的贡献者都能遵守这份[行为准则](https://www.contributor-covenant.org/zh-cn/version/2/1/code_of_conduct/)，也请花时间阅读一遍全文明确哪些行为是禁止的，哪些行为是可行的。 + +## 分支管理 + +目前 github 上长期维护分支 main。如果您要修一个 bug 或新增功能，请发 pull request 到 main 分支。 + +  + +官网会同步更新 [NutUI-React 的发布周期](https://github.com/jdf2e/nutui-react/releases)，同时每天都会有开发者 review github 中提交的代码。发版周期是每 1 周/次，通常会提前合并新的代码或功能，发布正式包；期间如遇紧急需求，可基于指定分支发布 beta 版本。 + +## Issue 报告指南 + +如果提交的是 Bug 报告，请务必遵守 [Bug report](https://github.com/jdf2e/nutui/blob/next/.github/ISSUE_TEMPLATE/bug_report.md) 模板。 + +## Bugs + +我们使用 [issue-helper](https://nutui.jd.com/nutui-issue-helper/?repo=jdf2e/nutui-react) 来做 bug 追踪。希望大家通过我们提供的 issue 小助手来提交反馈，并尽可能提供一切开发信息，因为信息越全面，开发响应速度越快，您发现的 bug 会被快速解决。 + +  + +提交 bug 之前，请先确保搜索过已有的 [issue](https://github.com/jdf2e/nutui-react/issues) 和阅读了我们的[常见问题](https://nutui.jd.com/#/zh-CN/notice)。 + +## 功能新增 + +如果您对现有的组件功能或者 API 有更好的想法，我们同样推荐你使用我们提供的 [issue-helper](https://nutui.jd.com/nutui-issue-helper/?repo=jdf2e/nutui-react) 提交一个添加新功能的 issue。 + +  + +如果你希望协助开发新功能新组件，可扫描[二维码](https://img13.360buyimg.com/imagetools/s300x300_jfs/t1/187308/9/29678/349561/634fa983E93012590/a641089fdfed5911.png)加入我们的社区共建群。 + +## 参与贡献 + +如果你对 github 的 PR 流程还不熟悉，可以阅读下面这 2 篇文章来学习： + +  + +[NutUI 贡献指南](https://github.com/jdf2e/nutui-react/discussions/348) + +[github 仓库代码同步](https://github.com/jdf2e/nutui/discussions/687) + +## Pull Request 规范 + +1. 每个 PR 只解决单个问题或者新增单个功能 + +2. 当新增组件或修改原有组件时，同步更改对应的单元测试和文档，保证代码的稳定 + +3. commit message 请遵循 [Angular Style Commit Message Conventions](https://gist.github.com/stephenparish/9941e89d80e2bc58a153) 规范 + +4. PR 信息中最好包括修改了哪个组件，解决了哪个问题，并关联 github 上对应的 issue 链接 + +## Pull Request 流程 + +1、fork 主仓库，并同步主仓库的最新代码 + +2、将项目下载到本地，在项目根目录下运行 npm install，并在本地能正常访问 + +``` +git clone https://github.com/{github username}/nutui-react.git +npm install +npm run dev +``` + +3、创建一个新的分支或在对应分支上进行开发 + +``` +git checkout -b username/xxxx +git checkout {现有分支名称} +``` + +4、如开发涉及新组件或组件的新特性，需要完善组件的中英文文档、组件的单元测试，同时要使用 [nutui-demo](https://github.com/jdf2e/nutui-demo) 对组件测试使用。 + +5、保证编译功能正常使用 + +``` +npm run test +// build 使用 node 17 版本 +// 构建 @nutui/nutui-react +npm run build +// 构建 @nutui/nutui-react-taro +npm run build:taro +``` + +6、开发完成后提交到仓库的对应分支上，PR 会在 Review 通过后被合并到主仓库，然后等待 NutUI-React 发布新版本（每周一次）。 + +### 知识分享 + +1. 项目使用案例 + +     分享 NutUI 的[使用案例](https://nutui.jd.com/next/#/case)，我们会在官网进行推荐展示，准备项目的名称、项目入口（二维码\链接）、logo、示例图、投放平台（H5\小程序\APP等）、nutui 版本等信息，以邮箱的形式提交到 **nutui@jd.com**。 + +  + +2. 文章视频投稿 + +     分享你的经验（教程、文章、视频等），可以给 **nutui@jd.com** 投稿。在审核通过后，收藏到[官网资源](https://nutui.jd.com/next/#/resource)中，将你的知识与思想传递给 NutUI 的小伙伴们。 + +  + +3. 共建分享征集 + +     以 NutUI-React 为基础，设计或开发新的工具，开发提效的插件等。有兴趣欢迎加入我们的[社区开发群](https://img13.360buyimg.com/imagetools/s300x300_jfs/t1/187308/9/29678/349561/634fa983E93012590/a641089fdfed5911.png)交流讨论。 + +  + +### Credits + +感谢以下所有给 NutUI 贡献过代码的开发者。 +  + +contributors + diff --git a/src/sites/sites-react/doc/docs/taro/international-react.en-US.md b/src/sites/sites-react/doc/docs/taro/international-react.en-US.md new file mode 100644 index 0000000000..a0bbe071cb --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/international-react.en-US.md @@ -0,0 +1,42 @@ +# Internationalization + +NutUI-React support multiple languages. NutUI uses Chinese as the default language. Use as follows: + +## Usage + +### Switch languages + +:::demo + +```javascript +import { ConfigProvider } from '@nutui/nutui-react-taro' +import en from '@nutui/nutui-react-taro/dist/locales/en-US' + +ReactDOM.render( + + + , + document.querySelector('#root') +) +``` + +::: + +## Current supported languages: + +| Language | Filename | Version | +| --- | --- | --- | +| English | en-US | `v1.0.0` | +| Chinese | zh-CN | `v1.0.0` | +| Uygur | zh-UG | `v1.3.15` | +| Traditional Chinese | zh-TW | `v1.0.0` | +| Indonesian | id-ID | `v1.3.2` | +| Thai | th-TH | PR | + +> View all language configs [Here](https://github.com/jdf2e/nutui-react/tree/main/src/locales). + +## Common Questions + +### Missing language pack? + +Welcome to commit PR If you need new language pack. Changes refer to [language pack](https://github.com/jdf2e/nutui-react/tree/main/src/locales). diff --git a/src/sites/sites-react/doc/docs/taro/international-react.md b/src/sites/sites-react/doc/docs/taro/international-react.md new file mode 100644 index 0000000000..19f3c6b717 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/international-react.md @@ -0,0 +1,43 @@ +# 国际化 + +NutUI-React 1.0 以上版本支持多语言。组件默认使用中文。 + +## 使用方法 + +### 多语言切换 + +:::demo + +```javascript +// 多语言版本 +import { ConfigProvider } from '@nutui/nutui-react-taro' +import en from '@nutui/nutui-react-taro/dist/locales/en-US' + +ReactDOM.render( + + + , + document.querySelector('#root') +) +``` + +::: + +## 目前支持的语言: + +| 语言 | 文件名 | 版本 | +| --- | --- | --- | +| 英语 | en-US | `v1.0.0` | +| 简体中文 | zh-CN | `v1.0.0` | +| 维吾尔语 | zh-UG | `v1.3.15` | +| 繁體中文 | zh-TW | `v1.0.0` | +| 印度尼西亚语 | id-ID | `v1.3.2` | +| 泰语 | th-TH | 等待 PR | + +> 在 [这里](https://github.com/jdf2e/nutui-react/tree/main/src/locales) 查看所有的语言包源文件。 + +## 常见问题 + +### 找不到所需的语言包？ + +如果上方列表中没有你需要的语言，欢迎给我们提 Pull Request 来增加新的语言包。改动内容可以参考 [语言包](https://github.com/jdf2e/nutui-react/tree/main/src/locales) 的 PR diff --git a/src/sites/sites-react/doc/docs/taro/intro-react.en-US.md b/src/sites/sites-react/doc/docs/taro/intro-react.en-US.md new file mode 100644 index 0000000000..adfc592745 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/intro-react.en-US.md @@ -0,0 +1,39 @@ +# NutUI-React + +NutUI-React component library, based on Taro, uses React technology stack to develop applet applications, out of the box, helps R&D to quickly develop user interface, improve development efficiency, and improve development experience. + +## Features + +- 🚀 70+ high-quality components covering mainstream mobile scenarios +- 💪 Supports a set of code to develop multi-terminal Mini Programs +H5 at the same time +- 📖 Based on JD APP 10.0 visual specification +- 🍭 Support on-demand reference +- 📖 Detailed documentation and examples +- 💪 Supports TypeScript +- 💪 Support for server-side rendering (test phase) +- 🍭 Support custom themes +- 🌍 Internationalization support +- 🍭 Unit test coverage exceeds 80% to ensure stability +- 📖 Sketch design resources are available + +## Examples + +NutUI-React + +## Version + +| Version | Supported Frameworks | Visual Specifications | Compatibility | +| --- | --- | --- | --- | +| @nutui/nutui-react-taro | React 17\18 | Jingdong [APP 10.0](/next#/resource) | Modern browsers start with Chrome >= 51、iOS >= 10.0、Android >= 6 | + +## All Contributors + +Thanks to the following friends for their contributions to NutUI-React: + + + contributors + + +## LICENSE + +[MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89) diff --git a/src/sites/sites-react/doc/docs/taro/intro-react.md b/src/sites/sites-react/doc/docs/taro/intro-react.md new file mode 100644 index 0000000000..a1caceb7b9 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/intro-react.md @@ -0,0 +1,39 @@ +# NutUI-React + +NutUI-React 组件库，基于 Taro，使用 React 技术栈开发小程序应用，开箱即用，帮助研发快速开发用户界面，提升开发效率，改善开发体验。 + +## 特性 + +- 🚀 80+ 高质量组件，覆盖移动端主流场景 +- 💪 支持一套代码同时开发多端小程序+H5 +- 📖 基于京东APP 10.0 视觉规范 +- 🍭 支持按需引用 +- 📖 详尽的文档和示例 +- 💪 支持 TypeScript +- 💪 支持服务端渲染（测试阶段） +- 🍭 支持定制主题 +- 🌍 国际化支持 +- 🍭 单元测试覆盖率超过 80%，保障稳定性 +- 📖 提供 Sketch 设计资源 + +## 扫码体验 + +NutUI-React + +## 版本说明 + +| 版本 | 支持的框架 | 视觉规范 | 兼容 | +| --- | --- | --- | --- | +| @nutui/nutui-react | React 17\18 | 京东 [APP 10.0](/next#/resource) 规范 | 现代浏览器以 Chrome >= 51、iOS >= 10.0、Android >= 6 | + +## 贡献者们 + +感谢以下小伙伴们为 NutUI-React 发展做出的贡献： + + + contributors + + +## 开源协议 + +本项目基于 [MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89) 协议 diff --git a/src/sites/sites-react/doc/docs/taro/migrate-from-v1.md b/src/sites/sites-react/doc/docs/taro/migrate-from-v1.md new file mode 100644 index 0000000000..97ec2f56e0 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/migrate-from-v1.md @@ -0,0 +1,888 @@ +# 从 v1 升级到 v2 + +本文档将帮助您从 NutUI React `1.x` 升级到 NutUI React `2.x` 版本。 + +## 升级步骤 + +1. H5 安装 NutUI React 2.x 版本 + +```shell +npm install @nutui/nutui-react +``` + +2. Taro 安装 NutUI React 2.x 版本 + +```shell +npm install @nutui/nutui-react-taro +``` + +3. 处理不兼容更新 + +从 NutUI React 1.x 到 NutUI React 2.x 存在一些不兼容更新，需要仔细阅读不兼容更新内容，并依次处理。 + +你可以手动对照下面的列表逐条检查代码进行修改，另外，我们也提供了一个 codemod cli 工具 @nutui/nutui-react-codemod 以帮助你快速升级到 v2 版本。在运行 codemod cli 前，请先提交你的本地代码修改。 + +4. 主题变量更名： + 如，primary-color 更名为 color-primary；注意在使用自定义主题，特别是使用 ConfigProvider 组件的情况下，有没有使用 `nutuiBrandColor`，这时记得更名为 `nutuiColorPrimary` + +## 兼容更新 + +1. 组件样式处理 + +新增了按需引入 css 文件的支持，同时保留了按需引入 scss 文件的能力。可通过 babel-import-plugin 插件实现按需引入 css： + +H5配置如下： + +```json +// Webpack .babelrc 或 babel.config.js中配置 +plugins: [ + [ + "import", + { + libraryName: "@nutui/nutui-react", + libraryDirectory: "dist/esm", + style: 'css', + camel2DashComponentName: false, + }, + "nutui-react", + ] +] +``` + +Taro配置如下： + +```json +// Webpack .babelrc 或 babel.config.js中配置 +plugins: [ + [ + "import", + { + libraryName: "@nutui/nutui-react-taro", + libraryDirectory: "dist/esm", + style: 'css', + camel2DashComponentName: false, + }, + "nutui-react-taro", + ] +] +``` + +2. 更完善的类型导出以及对类型增加 `JSDoc` 注释 +3. 组件分类的调整 + 在组件分类上，我们从交互维度上，和交互设计侧共同对 1.x 分类进行了基于信息结构的评审，并进行了子类梳理，完成重新分类，目标是更贴合交互场景的分布，易于查找组件。主要分布在： + +- 基础组件，将 `Popup` 组件移除，将 `Popup` 细分到操作反馈-引导提示部分； +- 布局组件，保持不变； +- 导航组件：将分页相关组件 `Pagination`、`Indicator` 移动到展示组件（考虑移动端的分页轻操作）；`Menu` 菜单移动到数据录入类-选择器子类（考虑 `Menu` 主要是作为筛选器）；将 `BackTop` 移至导航组件，作为锚点组件的一部分； +- 展示组件：将 `Badge`、`NoticeBar`、`Popover` 移至操作反馈-引导提示类，`Empty`、`Skeleton` 移至操作反馈-加载状态结果反馈中；`WaterMark`、`TrendArrow` 作为特性增强类组件放在特色组件中，待由该类组件的使用场景和范围确认是否变更分类；同时新增 `Audio`，将其同 `Video`、`ImagePreview`、`Swiper` 一同归为展示-多媒体类； +- 操作反馈类，新增 `Skeleton`、`Empty`（加载结果反馈类），`Popover`、`Notify`、`NoticeBar`、`Popup` （引导提示类）6个组件；同时去除 `BackTop`（导航组件-锚点类）、`Switch`（数据录入-选择器）、`Audio``（展示-多媒体）；在此基础上，未来会考虑增加 ResultPage`，整合错误状态、空状态等反馈状态，该组件在考虑中；同时考虑增加加载状态 `Loading` 组件。版本待定。 +- 数据录入类，主要分为两大类-输入及选择器。在输入中增加 `Signature`，该组件在 `Form` 表单中的应用范围日渐广泛，从特色组件中移入到数据录入部分；选择器中增加 `Switch`、`Menu`，及 `Address`。其中 `Signature` 和 `Address` 都是考虑其常用性，从特色中迁移到数据录入部分。 +- 特色组件，保留 `Barrage`、`Card`、`TimeSelect`，新增 `WaterMark`、`TrendArrow`。 + +## 不兼容更新 + +## NutUI Icons 调整 + +1.x 版本我们在实际开发过程中会发现 `Button` 只是引用了一个很小的 Loading Icon，但是全量引用了 IconFont 字体 ，会导致开发者的项目文件增大。我们在 NutUI React 2.x 中为解决此问题，重新定义了 Icon 组件，将所有的 Icons 抽离成单独的图标组件库 @nutui/icons-react（Taro 适配下为 @nutui/icons-react-taro） ，使其可以进行按需加载使用。 因此一些组件之前关于 Icon 的相关 Props 将被移除，需要使用插槽或者传递一个 Component 组件的 Props 进行使用。 受影响的组件如下： + +- Avatar +- Button +- ImagePreview +- Collapse +- InfiniteLoading +- Popup +- Steps +- Switch +- Toast +- Progress +- NoticeBar +- SearchBar +- Navbar +- Menu +- Tabbar +- Checkbox +- InputNumber +- Input +- Radio +- Rate +- Uploader +- Popover +- Grid +- TrendArrow + +如果你的项目中使用了这些组件，请仔细阅读文档并进行升级。 + +## 组件名称调整 + +- GridItem -> Grid.Item +- TabbarItem -> Tabbar.Item +- CollapseItem -> Collapse.Item +- SwiperItem -> Swiper.Item +- CellGroup -> Cell.Group +- MenuItem -> Menu.Item +- Infiniteloading -> InfiniteLoading + +## 组件 API 调整 + +在 2.0 版本中，我们重点对组件 API 进行了评审和修订，使属性和方法命名更贴合常用的命名习惯及 React 语言规范，目标希望开发者在使用组件时得心应手。我们的思路大体如下： + +### 属性定义 + +本次升级重点关注属性的命名方面，从 1.x 的 610 个属性精简为 410 个，更精简、更规范；同时增强属性的类型范围，提升自定义能力。 + +- 对同一属性进行统一描述，比如： + - 缩写类会改为全拼，如 `desc`、`descSlot`、`description` 统一为 `description` + - 能使用名词或形容词的优先使用该类词性，一个词能说明白的不用两个词。 + - 如 `wrap`、`wrapable` 统一为 `wrap` + - 如将 `isXxx` 统一为 `xxx`，如 `isVisible`、`isDeletable` 等，可直接使用 `visible`、`deletable` 等，形容词化 + - 如`showXxx` 尽量统一为 `xxx`，名词化。【部分属性待优化。】 + - 如 `roundRadius` 改为 `radius` ，`columnNum` 改为 `columns`等 + - `onClickXxx` 统一为 `onXxxClick` + - `modelValue` 统一为 `value`，并增加支持 `defaultValue`，支持受控与非受控模式 + - 对于标识位置、对齐等类的属性，将属性名变更为其上一层的属性定义，如 `center`会改为 `align`、`vertical`，改为 `direction`，像标记距离的，如 `top`、`bottom`、`distance` 等，会改为 `threshold` + - 不规范的定义如 `okBtn`、`okText` 这种，会改为 `confirmXxx` +- 扩充属性的类型。如 `title` 的类型从 `string` 扩充为 `React.ReactNode`，增强自定义内容；其中有涉及合并属性的，统一用最简命名来定义属性；如 `title`、`titleSlot` 合并为 `title`，再扩充属性类型。 +- 对于 `xxClass`、`xxStyle`类的属性，移除，可使用 `className` 、`style` 来实现。 +- 移除与样式有关的属性，除基础组件的样式属性及部分实现起来较为复杂的样式属性外，大多数样式属性被移除，可通过样式变量来实现。 +- 将普遍认同可内置的属性或不怎么使用的属性，直接内置，去掉属性设置。 + +### 组件实现 + +### 基础组件 + +#### Button + +- 移除 `plain`，通过 `fill="outline"` 实现 +- 增加 `ref`，对外暴露组件内 `button` 元素 +- CSS 变量中，对 `type` 类型对应的色值的定义，不在暴露到文档中，建议使用默认值，或修改主题变量 +- 增加 `fill` 模式类型，`dashed`，修改 `fill` 默认值为 `outline`。 +- 增加 `rightIcon`，可满足同时设置左右两个icon的情况。 +- 修改 `size` 为 `large` 时的默认 `width` 为 `100%` 的值，如果使用通栏的 `button`，可搭配 `block` 来使用。 + +#### Cell + +- `subTitle` 重命名为 `description`，类型修改为 `React.Node` +- `desc` 重命名为 `extra`，类型修改为 `React.Node` +- `roundRadius` 重命名为 `radius` +- `center` 重命名为 `align`，默认值修改为`flex-start`，可选值为 `flex-start`、`center`、`flex-end` +- 移除 `icon`、 `isLink`、`url`、`linkSlot`、`replace`、`descTextAlign`，通过用户自定义节点实现，参考文档demo示例 + +#### CellGroup + +- 新增 `divider`，单元格之间是否有分割线 +- `desc` 重命名为 `description` +- `title`、`description` 类型修改为 `React.Node` +- 移除 `titleSlot` 和 `descSlot`，通过 `title`、`description` 实现 +- + +#### ConfigProvider + +#### Icon + +#### Image + +- 移除 `round`，通过 `radius` 实现圆或圆角 +- 移除 `loadingImg` 和 `slotLoading`，通过 `loading` 属性实现，当 `loading` 属性设置为 `ReactNode` 或 `true` 时，表示展示 `loading` 状态 +- 移除 `showError` 和 `slotError`，通过 `error` 属性实现，当 `error` 属性设置为 `ReactNode` 或 `true` 时，表示展示 `error` 状态 +- 移除 `loadingImg`，可通过 `loading` 设置 `ReactNode` +- 移除 `errorImg`，可通过 `error` 设置 `ReactNode` +- `showError` 重命名为 `error`，类型修改为 `boolean｜ReactNode` +- `showLoading` 重命名为 `loading`，类型修改为 `boolean｜ReactNode` + +#### Overlay + +- `overlayClass` 重命名为 `className` +- `overlayStyle` 重命名为 `style` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- 更改 `lockScroll` 默认值为 `true` +- 新增 `afterClose` 和 `afterShow`，用于完全关闭后触发的回调和完全展示后触发的回调 + +#### Popup + +- `popClass` 重命名为 `className`，统一将组件的样式类名使用 `className`，不再指定特殊名字，减轻用户使用的记忆成本 +- `overlayClass` 重命名为 `overlayClassName`，继承自`Overlay` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- `onOpened` 和 `onClosed` 重命名为 `afterShow` 和 `afterClose`，继承自`Overlay`，用于完全关闭后触发的回调和完全展示后触发的回调 +- `destroyOnClose` 的描述进行了修订，改为：“组件不可见时，卸载内容”，并把其默认值改为了`false` +- `onClickCloseIcon` 和 `onClickOverlay` 两个方法，增加布尔判断，如返回false 或 未定义返回值时，将不再关闭 Popup；默认值为 `true`；在demo中已增加相应示例；同时，两者的名字变更为 `onCloseIconClick`、`onOverlayClick` +- `closeIcon` 类型从 `string` 改为 `ReactNode`，以前的 `closeIcon='mask-close'` 需改为 `closeIcon={}` +- `onOverlayClick` 和 `onCloseIconClick` 不会自动触发 `onClose` 了，如需触发关闭事件，需主动调用 `onClose` 回调函数 +- 新增 `description` 属性，支持标题下展示描述内容。 +- 调整 `position` 为 `bottom` 时的默认样式，默认支持圆角，此刻不需要再设置 `round` 属性。 + +### 布局组件 + +#### Divider + +- 移除 `dashed`, 通过 `style` 属性实现 +- 移除 `hairline`, 默认为 `true` +- CSS 变量调整：`$divider-before-margin-right`、`$divider-after-margin-left` 统一为 `$divider-spacing`，`$divider-vertical-border-left` 变更为 `$divider-border-color`，增加 `$divider-side-width`。 + +#### Grid + +- 移除 `fontSize`，可自行控制传入的组件字体大小 +- 移除 `border`，作为默认样式 +- `columnNum` 重命名为 `columns` +- `GridItem` 使用方式修改为 `Grid.Item` + +#### Layout + +#### Sticky + +- 移除 `top` 和 `bottom`， 重命名为 `threshold` + +### 导航组件 + +#### Elevator + +- `acceptKey` 重命名为 `floorKey` +- `indexList` 重命名为 `list` +- `isSticky` 重命名为 `sticky` +- `onClickIndex` 重命名为 `onIndexClick` +- `onClickItem` 重命名为 `onItemClick` +- 新增`showKeys`，是否展示右侧导航 +- CSS 变量部分，对命名做了简化。 + +#### FixedNav + +- `unActiveText` 重命名为 `inactiveText` +- `navList` 重命名为 `list` +- `slotBtn` 重命名为 `content` +- `onSelected` 重命名为 `onSelect` +- 移除 `fixednavClass`，通过 `className` 实现 +- 移除 `slotList`，通过 `children` 实现 +- 该组件已废弃 `BEM` 规范，记得把 `__` 改为 `-` + +#### Indicator + +- 移除 `block`，暴露自定义节点 +- 移除 `align`，暴露自定义节点 +- `vertical` 重命名为`direction`，默认值为 `horizontal`，可选 `vertical` +- 移除 `fillZero`，暴露自定义节点 +- `size` 重命名为 `total` +- 增加非数字展示，并设置为默认状态 + +#### Menu + +- 移除 `fontClassName` +- 移除 `iconClassPrefix` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- `titleIcon` 重命名为 `icon` +- `optionsIcon` 重命名为 `icon` +- 增加 `closeOnClickAway` + +#### NavBar + +- `desc` 重命名为 `right`，类型修改为 `React.Node` +- 新增 `left`，左侧内容，渲染在返回区域的右侧 +- 新增 `back`，返回区域内容 +- `onClickBack` 重命名为 `onBackClick` +- 移除 `title`，通过 `children` 实现 +- 移除 `leftText` `leftShow`，通过 `back`、`left`实现 +- `safeAreaInsetTop` 重命名为 `safeArea` +- `border` 废弃 +- 移除 `onClickTitle` `onClickRight` `onClickIcon`，通过在`left`、`title`、`right`自定义事件实现，参考文档demo示例 +- + +#### Pagination + +- 新增 `lite` 模式，只展示页码，不支持事件交互 +- 新增 `defaultValue` 非受控值 +- `modelValue` 重命名为 `value`，受控值 +- `prevText` 重命名为 `prev`，类型修改为 `ReactNode` +- `nextText` 重命名为 `next`，类型修改为 `ReactNode` +- `forceEllipses` 重命令为 `ellipse` +- `showPageSize` 重命名为 `itemSize` +- `itemsPerpage` 重命名为 `pageSize` +- `totalitems` 重命名为 `total` +- `pageNodeRender` 重命名为 `itemRender` +- 移除 `pageCount`，通过 `total` 与 `pageSize` 组合实现 + +#### SideNavBar + +- `offset` 重命名为 `indent` + +#### Tabbar + +- `unactiveColor` 重命名为 `inactiveColor` +- `tabTitle` 重命名为 `title`，类型修改为 `ReactNode` +- `bottom` 重命名为 `fixed` +- `safeAreaInsetBottom` 重命名为 `safeArea` +- `visible` 重命名为 `defaultValue`，非受控 +- `activeVisible` 重命名为 `value`，受控 + +#### TabbarItem + +- 使用方式修改为 `Tabbar.Item` +- `icon` 类型改为 `ReactNode`，移除其他 `icon` 关联属性 +- 移除 `href`，通过 `onSwitch` 事件控制链接与路由跳转 +- 移除 `num`，支持传入所有 `Badge` Props +- 移除 `color`，使用父元素的 `activeColor`，保持同样的 `active` 状态 + +#### Tabs + +- 增加 `lite`、`card`、`button`、`divider` 模式。 +- 移除 `background`，通过 `className` 或 `style` 控制 +- 移除 `titleScroll`, 默认支持滚动 +- 移除 `ellipsis`，默认 `flex：1` +- 移除 `size`，通过 css 变量 `--nutui-tabs-titles-item-font-size` 实现 +- `animatedTime` 重命名为 `duration` +- `titleGutter` 重命名为 css 样式变量实现 +- `titleNode` 重命名为 `title` +- `color` 重命名为 `activeColor` +- `type` 重命名为 `activeType` +- `leftAlign` 重命名为 `align` +- `onClick` 类型改为 `(index: string | number) => void` +- `onChange` 类型改为 `(index: string | number) => void` +- 增加 defaultValue +- 增加 `activeType` 类型 `simple`，实现选项卡的简约选择，只修改字号和字重，不处理字色。 + +#### Tabs.Tabpane + +- `paneKey` 重命名为 `value` + +### 数据录入 + +#### Calendar + +- `poppable` 重命名为 `popup` +- `isAutoBackFill` 重命名为 `autoBackfill` +- `toDateAnimation` 重命名为 `scrollAnimation` +- `startText` 类型改为 `ReactNode` +- `endText` 类型改为 `ReactNode` +- `confirmText` 类型改为 `ReactNode` +- `onBtn` 重命名为 `renderHeaderButtons` +- `onDay` 重命名为 `renderDay` +- `onTopInfo` 重命名为 `renderDayTop` +- `onBottomInfo` 重命名为 `renderDayBottom` +- `onSelected` 重命名为 `onDayClick` +- `onChoose` 重命名为 `onConfirm` +- `onYearMonthChange` 重命名为 `onPageChange` +- 新增 `firstDayOfWeek`，支持按照周进行选择，指定周起止日，如0-6 + +#### Cascader + +- 新增 `defaultValue`，其中 `defaultValue` 用于非受控，原 `value` 用于受控。两者的类型都改为 `(number | string | undefined)[]` +- `checkedIcon` 重命名为 `activeIcon` +- `poppable` 重命名为 `popup` +- `lazyLoad` 重命名为 `onLoad`，当启动懒加载 `lazy` 时，动态加载数据 +- `convertConfig` 重命名为 `format`，配置转换规则 +- 合并 `textKey` `valueKey` `childrenKey` 三个属性为对象属性 `optionKey` +- 移除 `tabsColor`， 该属性为设置 `Tabs` 当前选中的 `tab` 的下划线色值，但该值最好与文字部分搭配使用，统一处理 CSS 变量。 + +#### Checkbox + +- 新增 `defaultChecked`，用于非受控，`checked` 用于受控 +- 新增 `value`，用于 group 模式 +- `textPosition` 重命名为 `labelPosition` +- `iconName` 重命名为 `icon`，类型为 `ReactNode` +- `iconAcitveName` 重命名为 `activeIcon` +- `iconIndeterminateName` 重命名为 `iconIndeterminateIcon` +- 移除 `iconSize` +- 部分 className 命名变更，废弃 `nutui-checkbox__xx` 命名方式，直接使用 `nutui-checkbox-xx`，并对选中状态命名修订为 `nutui-checkbox-icon-checked` +- 增加半选的禁用状态 + +#### Checkbox.Group + +- 新增 `defaultValue`，用于非受控，`value` 用于受控 +- `textPosition` 重命名为 `labelPosition` +- `toggleAll` 重命名为 `toggle` +- `toggleReverse` 重命名为 `reverse` +- 部分 className 命名变更，废弃 `nutui-checkbox__xx` 命名方式，直接使用 `nutui-checkbox-xx`，并对选中状态命名修订为 `nutui-checkbox-icon-checked` + +#### DatePicker + +- `modelValue` 重命名为 `value`，并增加 `defaultValue` +- `isShowChinese` 重命名为 `showChinese` +- `minDate` 重命名为 `startDate` +- `maxDate` 重命名为 `endDate` +- `onConfirmDatePicker` 重命名为 `onConfirm` +- `onCloseDatePicker` 重命名为 `onClose` +- 因为依赖组件`Picker`的变更，方法 `onConfirmDatePicker`、`onChange`的参数进行了调整，从`(selectedValue, selectedOptions)` 改为 `(selectedOptions, selectedValue)`。 + +#### Form + +- 增加 `footer`，类型为 `ReactNode`，用于表单底部区域，通常用于设置提交、重置按钮 +- 增加 `initialValues`，用于设置表单初始值，同时用于表单的重置 +- 增加 `name` 属性 + +#### Form.Item + +- 移除 `labelWidth`, 通过 `--nutui-form-item-label-width` 控制宽度 +- 增加 `required`，用于必选样式控制 +- 增加 `trigger`，用于设置数据更新的时机 +- 增加 `valuePropName`，用于收集子组件受控的属性映射 +- 增加 `getValueFromEvent`，用于在收集数据中进行数据转换 +- 增加 `onclick` 用于收集子组件的 `ref` + +#### Input + +#### InputNumber + +- 增加 `allowEmpty`, 用于允许内容是否为空 +- 新增 `defaultValue`，用于非受控，`value` 用于受控 +- `decimalPlaces` 重命名为 `digits` +- `isAsync` 重命名为 `async` +- 移除 `inputWidth`, 通过`--nutui-inputnumber-input-width`控制输入框的宽度 +- 移除 `buttonSize`, 通过`–nutui-inputnumber-button-width` 和 `–nutui-inputnumber-button-height`控制按钮的宽度和高度 +- taro 新增 `formatter` 属性, 用于指定输入框展示值的格式 +- 移除 `errorMessage` +- 移除 `showWordLimit` +- `autofocus` 重命名为 `autoFocus` +- `type="textarea"` 建议改为使用 `TextArea` 组件实现 + +#### NumberKeyboard + +- `randomKeys` 重命名为 `random` +- `customKey` 重命名为 `custom` +- `title` 类型变更为 `ReactNode` +- 新增 `onConfirm` 事件 +- 移除 `popClass` 定义，默认支持透传 `Popup` 属性 + +#### Picker + +- `isVisible` 重命名为 `visible` +- `listData` 重命名为 `options` +- `defaultValueData` 重命名为 `defaultValue` +- 增加受控 `value` +- `swipeDuration` 重命名为 `duration` +- `onCloseUpdate` 重命名为 `afterClose` +- 方法 `onConfirm`、`onClose`、`afterClose`、`onChange`的参数进行了调整，从`(selectedValue, selectedOptions)` 改为 `(selectedOptions, selectedValue)`。 + +#### Radio + +- 移除 `iconSize`，可通过 Icon 的 css 变量设置 +- `iconName` 重命名为 `icon`，类型修改为 `ReactNode` +- 增加 `labelPosition`，用于设置 `label` 的位置 +- 增加 `checked` 和 `defaultChecked` ，用于受控和非受控 +- `onChange` 类型修改为 `(checked: boolean) => void` +- 部分 className 命名变更，废弃 `nutui-radio__xx` 命名方式，直接使用 `nutui-radio-xx`，并对选中状态命名修订为 `nutui-radio-icon-checked` + +### Radio.Group + +- `textPosition` 重命名为 `labelPosition` +- 增加 `defaultValue` ，用于非受控 +- `onChange` 类型修改为 `(value: string| number) => void` +- 部分 className 命名变更，废弃 `nutui-radio__xx` 命名方式，直接使用 `nutui-radio-xx`，并对选中状态命名修订为 `nutui-radio-icon-checked` + +#### Range + +- `maxDesc` 重命名为 `maxDescription`，类型改为 `ReactNode` +- `minDesc` 重命名为 `minDescription`，类型改为 `ReactNode` +- `curValueDesc` 重命名为 `currentDescription`，类型改为 `(value) => ReactNode` +- 移除 `hiddenRange`，通过 `max/minDescription` 传 `null` 实现 +- 移除 `hiddenTag`，通过 `currentDescription` 传 `null` 实现 +- 移除 `activeColor`、`inactiveColor`、`buttonColor`，通过 `css` 变量实现 +- `onDragStart` 重命名为 `onStart` +- `onDragEnd` 重命名为 `onEnd` +- `modelValue` 重命为 `value`，增加 `defaultValue` 非受控方式 + +#### Rate + +- `minimizeValue` 重命名为 `min` +- `readonly` 重命名为 `readOnly` +- 移除 `spacing`，通过 css 样式变量实现 +- 移除 `activeColor`、`voidColor`、`iconSize`，通过 `checkedIcon`、`uncheckedIcon` 实现 +- 增加受控 `value` 与非受控 `defaultValue`，移除 `modelValue` + +#### SearchBar + +- `onClickInput` 重命名为 `onInputClick` +- 移除 `clearSize`，样式默认 +- 移除 `background`，使用 CSS 变量 `--nutui-searchbar-background` 实现 +- 移除 `inputBackground`，使用 CSS 变量 `--nutui-searchbar-input-background` 实现 +- 移除 `align`，使用 CSS 变量 `--nutui-searchbar-input-text-align` +- 新增 `left` 和 `right`，为 `ReactNode` 节点，可自定义内容 +- 移除 `leftoutIcon` 和 `label`，使用 `left` 实现 +- 移除 `rightoutIcon` 和 `actionText`，使用 `right` 实现 +- 移除 `leftinIcon`，使用 `leftIn` 实现 +- 移除 `rightinIcon`，使用 `rightIn` 实现，同时兼顾和 clearIcon 的交互，当设置rightIn时，默认展示 rightIn，当触发输入后，展示 clearIcon。同时增加 `backable` 来标记是否展示左侧返回Icon +- 移除 `onCancel`，使用 `right` 来实现事件处理 +- 移除 `onClickLeftinIcon`，用户可使用 `left` 来实现事件处理 +- 移除 `onClickLeftoutIcon`，用户可使用 `left` 来实现事件处理 +- 移除 `onClickRightinIcon`，用户可使用 `right` 来实现事件处理 +- 移除 `onClickRightoutIcon`，用户可使用 `right` 来实现事件处理 + +#### ShortPassword + +- `desc` 重命名为 `description` +- `noButton` 重命名为 `hideFooter` +- `onOk` 重命名为 `onConfirm` +- `errorMsg` 重命名为 `error` +- 移除 `closeOnClickOverlay`，默认支持透传 Popup 属性 +- `title`、`description`、`tips`、`error` 类型修改为 `ReactNode` +- `modelValue` 重命名为 `value`，受控模式 +- 新增 `onFoucs` 事件 + +#### TextArea + +- `maxlength` 重命名为 `maxLength` +- `readonly` 重命名为 `readOnly` +- `limitShow` 重命名为 `showCount` +- `autosize` 重命名为 `autoSize` +- 移除 `textAlign`，可通过 `style` 传入 +- `defaultValue` 改为非受控，增加受控值 `value` + +#### Uploader + +- `maximize` 重命名为 `maxFileSize` +- `maximum` 重命名为 `maxCount` +- `listType ` 重命名为 `previewType` +- `isDeletable ` 重命名为 `deletable` +- `isPreview` 重命名为 ` preview` +- `defaultImg` 重命名为 ` previewUrl` +- `defaultFileList` 重命名为 ` defaultValue` +- `uploadIconTip` 重命名为 `uploadLabel`，类型变更为 `ReactNode` +- `onBeforeUpload` 重命名为 `beforeUpload` +- `onBeforeXhrUpload` 重命名为 `beforeXhrUpload` +- `onBeforeDelete` 重命名为 `beforeDelete` +- `onRemove` 重命名为 `onDelete` +- 增加 `fit`，用于图片填充模式 +- 增加 `value`，用于受控传值 +- 移除 `uploadIconSize`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 +- `uploadIcon` 类型从 `string` 调整为 `ReactNode` +- `onChange` 参数类型从 `{fileList: FileItem[], event: any}` 调整为 `FileItem[]` + +### 操作反馈 + +#### ActionSheet + +- `title`，类型变更为 `ReactNode` +- `description`，类型变更为 `ReactNode` +- `cancelTxt`，重命名为 `cancelText`，类型变更为 `ReactNode` +- `menuItems` 重命名为 `options` +- `chooseTagValue` 重命名为 `value` +- `onChoose` 重命名为 `onSelect` +- 增加 `options` 的定义 + - `color` 重命名为 `danger` + - `name`，列表项的标题key + - `description`，列表项的描述key + - `danger`，列表项中提醒用户重点关注的操作 + - `disabled`，列表项中禁用项 + +#### BackTop + +- `elId` 重命名为 `target` +- 移除 `right`、`bottom`，通过 style 传入，增加支持 `left`、`top` +- `distance` 重命名为 `threshold` +- 移除 `isAnimation`，通过 `duration` 设置 0 实现无动画效果 + +#### Dialog + +- `okText` 重命名为 `confirmText`，规范命名。 +- `mask` 重命名为 `overlay`，组件库中统一使用 Overlay 组件作为遮罩层，并使用 overlay 作为是否展示遮罩层的属性值。 +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick`，组件库统一到该属性。 +- `noOkBtn` 重命名为 `hideConfirmButton`，初始值不变，依然表示是否隐藏确认按钮，主要是为了语义化更强。 +- `noCancelBtn` 重命名为 `hideCancelButton`，初始值不变，依然表示是否隐藏取消按钮，主要是为了语义化更强。 +- `okBtnDisabled` 重命名为 `disableConfirmButton`，初始值不变，依然表示是否禁用确认按钮，主要是为了语义化更强。 +- 移除 `noFooter`，使用 footer 统一处理，当 footer 为空时，及可替代该值。目前 noFooter 也需要手动声明是否为 noFooter；修改后需手动指出 footer={null} +- 移除 `textAlign`，改用样式变量 `--nutui-dialog-content-text-align` 或 SCSS 变量 `$dialog-content-text-align` 控制，默认值为 center。 +- 移除 `cancelAutoClose`，改为 `beforeCancel` 和 `beforeClose` 来实现，在点击关闭或取消时，可先触发这两个方法，以确定是否要关闭弹框，如返回true，则关闭；否则不关闭。 +- `onOk` 重命名为 `onConfirm`，规范命名。 +- `onClosed` 重命名为 `onClose`，规范命名，关闭时触发。 +- `onClickSelf` 重命名为 `onClick`，语义不变，仍表示点击弹框自身时触发事件。 +- 增加 `overlayStyle` 和 `overlayClassName`，用来配置 Overlay 组件样式。 +- 增加 `onOverlayClick`，支持点击overlay时，触发事件。 +- `onCancel` 回调不会自动关闭弹层，需主动调用 `Dialog.close(xx)` + +#### Drag + +#### InfiniteLoading + +- `useCapture` 重命名为 `capture` +- `onScrollChange` 重命名为 `onScroll` +- `isOpenRefresh` 重命名为 `pullRefresh` +- `pullTxt` 重命名为 `pullingText`，类型变更为 `ReactNode` +- `loadTxt` 重命名为 `loadingText`，类型变更为 `ReactNode` +- `containerId` 重命名为 `target` +- 修订类名如 `top-box`、`bottom-box` 为 `nut-infinite-top-tips`、`nut-infinite-bottom-tips` + +#### Notify + +- 移除 `color` ，通过css变量`--nutui-notify-text-color`实现 +- 移除`background`，通过css变量`--nutui-notify-base-background-color`实现 +- `onClosed` 重命名为 `onClose` + +#### PullToRefresh + +#### Swipe + +- 移除 `leftWidth` ，通过 `leftAction` 实现 +- 移除 `rightWidth` ，通过 `rightAction` 实现 + +#### Switch + +- 新增 `defaultChecked`，用于非受控，`checked` 用于受控 +- 移除 `isAsync`，通过 `checked`实现 +- 移除 `activeColor` ，通过css变量`--nutui-switch-open-background-color`实现 +- 移除 `inactiveColor`，通过css变量`--nutui-switch-close-background-color`实现 + +#### Toast + +- 移除H5版本 `id` +- 移除 `center`和 `bottom`，通过 `position` 实现 +- 移除 `bgColor`，通过 css 变量实现 +- 移除 `customClass`，通过 `className` 实现 +- 移除 `cover` 和 `coverColor` ，通过css变量实现 +- 移除 `loadingRotate`，旋转状态通过 `iconFont`实现 +- 移除 `textAlignCenter`，通过css变量实现 +- 修改 `closeOnClickOverlay` 为 `closeOnOverlayClick` ，语义不变，是否在点击遮罩层后关闭提示 +- 新增 `lockScroll` ，用于背景是否锁定，默认值为 `false` + +### 展示组件 + +#### Animate + +- `type` 属性类型更改为 `AnimateType` ，具体值详见文档 +- `action` 属性类型更改为 `initial \| click` + +#### AnimatingNumbers + +- `maxLen` 重命名为 `length` +- `endNumber` 重命名为 `value`，类型修改为 `string|number` +- `delaySpeed` 重命名为 `delay` +- `easeSpeed` 重命名为 `duration` + +#### Audio + +- `url` 重命名为 `src` +- `autoplay` 重命名为 `autoPlay` +- `onFastBack` 重命名为 `onBack` +- `onPlayEnd` 重命名为 `onEnd` + +#### Avatar + +- `url` 重命名为 `src` +- `onActiveAvatar` 重命名为 `onClick` +- 新增 `fit` 属性，用于图片填充模式 +- 移除 `iconSize`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 + +#### AvatarGroup + +- AvatarGroup `maxCount` 重命名为 `max` +- AvatarGroup `span` 重命名为 `gap` +- AvatarGroup `zIndex` 重命名为 `level` + +#### Badge + +- 移除 `zIndex`，目前没有用到，也不生效，直接去掉。 +- 移除 `icon`，自定义 `icon` 可放在 `value` 中实现，扩充了 `value` 的类型。 +- 修改 `max` 的最大值为99（之前为10000），比较贴合实际场景。 +- 主题定制的 `css` 变量中，去掉和 `dot` 有关的其他值，只保留 `width`。其他值由 `width` 计算而来. +- 主题定制，增加包含 icon 情况下的样式变量。 + +#### CircleProgress + +- `progress` 重命名为 `percent` +- `circleColor` 重命名为 `color` +- `pathColor` 重命名为 `background` + +#### Collapse + +- 新增 `defaultActiveName` 非受控 +- `activeName` 改为受控方式 +- `icon` 重命名为 `expandIcon`，类型修改为 `ReactNode` +- `onChange` 参数变更为 `activeName, name, status` +- 新增一种样式，尝试修改 `--nutui-collapse-item-border-bottom` 和 `-nutui-collapse-item-header-border-bottom`，可查看 + +#### CollapseItem + +- 使用方式调整为 `Collapse.Item` +- subTitle 重命名为 extra，类型修改为 `ReactNode` +- 新增 `expnandIcon`，优先级高于父组件对应值 +- 新增 `rotate`，优先级高于父组件对应值 + +#### CountDown + +- 新增 `remainingTime`，支持剩余毫秒时间倒计时。 + +#### Ellipsis + +- 新增 `className` 和 `style` 属性的支持 +- 优化 H5 的代码，去掉 `useEffect` 渲染改用 `useLayoutEffect` + +#### Empty + +- 新增 `status` 属性，用于默认图片错误类型 +- 新增 `size` 属性，用于区分全屏与半屏状态下图片的不同大小 +- 新增 `title` 属性，用于展示提示的标题部分 +- 新增 `actions` 属性，用于展示提示的操作部分，支持1个或2个操作 +- `image` 属性类型更改为 `ReactNode` +- 新增 `title`、`size`、`actions` 属性，支持标题的设置、图片大小的设置、可能的操作设置，操作设置默认以`Button`实现。 + +#### ImagePreview + +- `show` 重命名为 `visible` +- `autoplay` 重命名为 `autoPlay` +- `initNo` 重命名为 `defaultValue`，同时增加 `value`，为受控 +- `paginationVisible` 重命名为 `indicator` +- `paginationColor` 重命名为 `indicatorColor` +- `contentClose` 重命名为 `closeOnContentClick` +- 在 `Taro` 下支持视频 + +#### NoticeBar + +- `direction` 的可选值从 `across` 重命名为 `horizontal` +- `text` 重命名为 `content` +- `closeMode` 重命名为 `closeable` +- `leftIcon` 类型扩充，支持 `ReactNode` +- `rightIcon` 类型扩充，支持 `ReactNode` +- `color` 移除，使用 CSS 变量，之前已支持 +- `background` 移除，使用 CSS 变量，之前已支持 +- `wrapable` 重命名为 `wrap` +- `standTime` 重命名为 `duration` +- `onClickItem` 重命名为 `onItemClick` +- `complexAm` 废弃 + +#### Popover + +- 移除 `theme` 属性，可以通过css变量 `--nutui-brand-color` 控制暗黑模式 +- 新增 `showArrow` 属性，用于是否显示小箭头 +- 新增 `closeOnActionClick` 属性，用于是否在点击选项后关闭 +- 新增 `closeOnOutsideClick` 属性，用于是否在点击外部元素后关闭菜单 +- 新增 `targetId` 属性，用于自定义目标元素 id +- 新增 `onOpen` 属性，用于点击菜单时触发 +- 新增 `onClose` 属性，用于关闭菜单时触发 +- 新增 `action` 属性，用于为对应的选项添加方法 +- `onChoose` 重命名为 `onSelect` +- 继承Popup组件的 `overlayStyle` 、`overlayClassName` 、`overlay` 、`closeOnOverlayClick` 属性。 + +#### Price + +- `decimalDigits` 重命名为 `digits` +- 移除 `needSymbol`，通过 `symbol` 判断是否需要加上 symbol 符号 +- 新增 `line`，是否展示划线价 + +#### Progress + +- `percentage` 重命名为 `percent`，受控 +- 移除 `isShowPercentage`，可以自定义传入文案 +- 移除 `textWidth`，可以自定义传入内容的宽度 +- `strokeColor` 重命名为 `color` +- `fillColor` 重命名为 `background` +- 移除 `size`，通过 `strokeWidth`、`progress-height` css 变量实现尺寸自定义 +- `status` 重命名为 `animated`，表示是否展示动画效果 +- 移除 `textBackground`，通过 css 实现 +- 移除 `textColor`，通过 css 实现 +- 移除 `textInside`，仅保留内显功能 +- 移除 `textType、icon`，通过 `children` 传入自定义 `ReactNode`，不再区分类型 +- 新增 `lazy` 属性，支持每次进入可视区时展示进度条动画 +- 新增 `delay` 属性，表示延迟数据加载时长 + +#### Skeleton + +- `loading` 重命名为 `visible` +- `row` 重命名为 `rows` +- 移除 `width`，通过 css 变量 `skeleton-line-width` 实现 +- 移除 `height`，通过 css 变量 `skeleton-line-height` 实现 +- 移除 `round`，通过 css 变量 `skeleton-line-border-radius` 实现 + +#### Steps + +- `current` 重命名为 `value` +- `onClickStep` 重命名为 `onStepClick` +- `progressDot` 重命名为 `dot` + +#### Step + +- 移除 `iconColor`，可通过 `icon` 属性传入自定义 icon 或借助 CSS Variables 修改 icon 颜色 +- 移除 `size`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 +- 移除 `renderContent` ，可通过 `description` 实现 +- `title` 类型修改为 `ReactNode` +- `content` 重命名为 `description`，类型改为 `ReactNode` +- `icon` 类型修改为 `ReactNode` +- `activeIndex` 重命名为 `value` + +#### Swiper + +- h5 + - 移除 `paginationColor`，通过 `indicator` 的 CSS 变量控制 + - 移除 `paginationBgColor`，通过 `indicator` 的 CSS 变量控制 + - 移除 `pageContent`，通过 indicator 实现 + - `autoplay` 重命名为 `autoplay` + - `initPage` 重命名为 `defaultValue` + - `paginationVisible` 重命名为 `indicator`，类型改为` ReactNode` + - `isPreventDefault` 重命名为 `preventDefault` + - `isStopPropagation` 重命名为 `stopPropagation` + - `isCenter` 重命名为 `center` +- taro + - 通过封装 Taro 的 `Swiper` 和 `SwiperItem` 实现，支持的属性可参考 Taro Swiper 文档。 + +#### Table + +- `onSorter` 重命名为 `onSort` +- 合并 `summary` 与 `noData` 的样式处理 + +#### Tag + +- `color` 重命名为 `background` +- `textColor` 重命名为 `color` + +#### TrendArrow + +- `rate` 重命名为 `value` +- `showSign` 重命名为 `symbol` +- `showZero` 重命名为 `zero` +- `arrowLeft` 重命名为 `left` +- `syncTextColor` 重命名为 `sync` +- `textColor` 重命名为 `color` +- `upIconName` 重命名为 `riseIcon`，类型修改为 `React.Node` +- `downIconName` 重命名为 `dropIcon`，类型修改为 `React.Node` +- 移除 `iconSize`，通过`riseIcon`、`dropIcon`自定义传入icon大小 + +#### Video + +- 在 `Taro` 下新增video的适配 + +#### VirtualList + +- `sourceData` 重命名为 `list` +- `conatinerSize` 重命名为 `containerHeight` +- `itemSize` 重命名为 `itemHeight` +- `itemEqualSize` 重命名为 `itemEqual` +- `horizontal` 修改为 `direction`，默认值 `vertical`，可选值 `horizontal` + +#### WaterMark + +- `fontColor` 重命名为 `color` + +### 特色组件 + +#### Address + +- 该组件的 `custom` 改用 `Cascader` 组件重写；`custom2`也将使用 `Cascader` 完成，在 `Cascader` 中支持 `Elevator`，开发中。所以会废弃 `province`、`city`、`country`、`town` 这些属性，同时支持 `Cascader` 的属性。 +- `modelValue` 重命名为 `visible` +- `modelSelect` 重命名为 `defaultValue` +- `onSelected` 重命名为 `onSelect` +- `existAddress` 重命名为 `existList` +- `selectedIcon` 重命名为 `selectIcon` +- `closeBtnIcon` 重命名为 `closeIcon` +- `backBtnIcon` 重命名为 `backIcon` +- `isShowCustomAddress` 重命名为 `custom`，用于已有地址列表与自定义列表的切换，修改默认为值 `false` +- `customAndExistTitle` 废弃，与 `custom` 合并，当 `custom` 为 true 时，为默认文案，设置为某字符串时，展示字符串。 +- `customAddressTitle`、`existAddressTitle` 重命名为 `title`，不再区分状态，可通过onSwitch修改title +- 精简布局和样式 + +#### Barrage + +- `barrageList` 重命名为 `list` +- `frequency` 重命名为 `interval` +- `speeds` 重命名为 `duration` +- `top` 重命名为 `gapY` + +#### Card + +#### Signature + +- `type` 类型修改为 `png｜jpg` +- `unSupportTpl` 重命名为 `unsupported`，类型修改为 `ReactNode` +- 新增 `confirm`和`clear` ref 的方法，移除组件内部 `button`元素，通过自定义按钮元素，设置元素点击事件结合ref实现，参考文档demo示例 + +#### TimeSelect + +- 移除 `height`，通过 `style` 设置高度 +- `title` 类型修改为 `ReactNode` +- `onPannelChange` 重命名为 `onDateChange` +- 移除 `dates`、`times`，合并为 `options`，重新设计了数据结构 +- 增加 `optionKey` 用于自定义数据中的关键字 +- 移除 `currentKey`，新增 `defaultValue` 用于设置默认选项，支持时间选择 diff --git a/src/sites/sites-react/doc/docs/taro/migrate-from-v2.md b/src/sites/sites-react/doc/docs/taro/migrate-from-v2.md new file mode 100644 index 0000000000..5bd3f8ec5e --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/migrate-from-v2.md @@ -0,0 +1,888 @@ +# 从 v2 升级到 v3 + +本文档将帮助您从 NutUI React `2.x` 升级到 NutUI React `3.x` 版本。 + +## 升级步骤 + +1. H5 安装 NutUI React 3.x 版本 + +```shell +npm install @nutui/nutui-react +``` + +2. Taro 安装 NutUI React 3.x 版本 + +```shell +npm install @nutui/nutui-react-taro +``` + +3. 处理不兼容更新 + +从 NutUI React 1.x 到 NutUI React 2.x 存在一些不兼容更新，需要仔细阅读不兼容更新内容，并依次处理。 + +你可以手动对照下面的列表逐条检查代码进行修改，另外，我们也提供了一个 codemod cli 工具 @nutui/nutui-react-codemod 以帮助你快速升级到 v2 版本。在运行 codemod cli 前，请先提交你的本地代码修改。 + +4. 主题变量更名： + 如，primary-color 更名为 color-primary；注意在使用自定义主题，特别是使用 ConfigProvider 组件的情况下，有没有使用 `nutuiBrandColor`，这时记得更名为 `nutuiColorPrimary` + +## 兼容更新 + +1. 组件样式处理 + +新增了按需引入 css 文件的支持，同时保留了按需引入 scss 文件的能力。可通过 babel-import-plugin 插件实现按需引入 css： + +H5配置如下： + +```json +// Webpack .babelrc 或 babel.config.js中配置 +plugins: [ + [ + "import", + { + libraryName: "@nutui/nutui-react", + libraryDirectory: "dist/esm", + style: 'css', + camel2DashComponentName: false, + }, + "nutui-react", + ] +] +``` + +Taro配置如下： + +```json +// Webpack .babelrc 或 babel.config.js中配置 +plugins: [ + [ + "import", + { + libraryName: "@nutui/nutui-react-taro", + libraryDirectory: "dist/esm", + style: 'css', + camel2DashComponentName: false, + }, + "nutui-react-taro", + ] +] +``` + +2. 更完善的类型导出以及对类型增加 `JSDoc` 注释 +3. 组件分类的调整 + 在组件分类上，我们从交互维度上，和交互设计侧共同对 1.x 分类进行了基于信息结构的评审，并进行了子类梳理，完成重新分类，目标是更贴合交互场景的分布，易于查找组件。主要分布在： + +- 基础组件，将 `Popup` 组件移除，将 `Popup` 细分到操作反馈-引导提示部分； +- 布局组件，保持不变； +- 导航组件：将分页相关组件 `Pagination`、`Indicator` 移动到展示组件（考虑移动端的分页轻操作）；`Menu` 菜单移动到数据录入类-选择器子类（考虑 `Menu` 主要是作为筛选器）；将 `BackTop` 移至导航组件，作为锚点组件的一部分； +- 展示组件：将 `Badge`、`NoticeBar`、`Popover` 移至操作反馈-引导提示类，`Empty`、`Skeleton` 移至操作反馈-加载状态结果反馈中；`WaterMark`、`TrendArrow` 作为特性增强类组件放在特色组件中，待由该类组件的使用场景和范围确认是否变更分类；同时新增 `Audio`，将其同 `Video`、`ImagePreview`、`Swiper` 一同归为展示-多媒体类； +- 操作反馈类，新增 `Skeleton`、`Empty`（加载结果反馈类），`Popover`、`Notify`、`NoticeBar`、`Popup` （引导提示类）6个组件；同时去除 `BackTop`（导航组件-锚点类）、`Switch`（数据录入-选择器）、`Audio``（展示-多媒体）；在此基础上，未来会考虑增加 ResultPage`，整合错误状态、空状态等反馈状态，该组件在考虑中；同时考虑增加加载状态 `Loading` 组件。版本待定。 +- 数据录入类，主要分为两大类-输入及选择器。在输入中增加 `Signature`，该组件在 `Form` 表单中的应用范围日渐广泛，从特色组件中移入到数据录入部分；选择器中增加 `Switch`、`Menu`，及 `Address`。其中 `Signature` 和 `Address` 都是考虑其常用性，从特色中迁移到数据录入部分。 +- 特色组件，保留 `Barrage`、`Card`、`TimeSelect`，新增 `WaterMark`、`TrendArrow`。 + +## 不兼容更新 + +## NutUI Icons 调整 + +1.x 版本我们在实际开发过程中会发现 `Button` 只是引用了一个很小的 Loading Icon，但是全量引用了 IconFont 字体 ，会导致开发者的项目文件增大。我们在 NutUI React 2.x 中为解决此问题，重新定义了 Icon 组件，将所有的 Icons 抽离成单独的图标组件库 @nutui/icons-react（Taro 适配下为 @nutui/icons-react-taro） ，使其可以进行按需加载使用。 因此一些组件之前关于 Icon 的相关 Props 将被移除，需要使用插槽或者传递一个 Component 组件的 Props 进行使用。 受影响的组件如下： + +- Avatar +- Button +- ImagePreview +- Collapse +- InfiniteLoading +- Popup +- Steps +- Switch +- Toast +- Progress +- NoticeBar +- SearchBar +- Navbar +- Menu +- Tabbar +- Checkbox +- InputNumber +- Input +- Radio +- Rate +- Uploader +- Popover +- Grid +- TrendArrow + +如果你的项目中使用了这些组件，请仔细阅读文档并进行升级。 + +## 组件名称调整 + +- GridItem -> Grid.Item +- TabbarItem -> Tabbar.Item +- CollapseItem -> Collapse.Item +- SwiperItem -> Swiper.Item +- CellGroup -> Cell.Group +- MenuItem -> Menu.Item +- Infiniteloading -> InfiniteLoading + +## 组件 API 调整 + +在 2.0 版本中，我们重点对组件 API 进行了评审和修订，使属性和方法命名更贴合常用的命名习惯及 React 语言规范，目标希望开发者在使用组件时得心应手。我们的思路大体如下： + +### 属性定义 + +本次升级重点关注属性的命名方面，从 1.x 的 610 个属性精简为 410 个，更精简、更规范；同时增强属性的类型范围，提升自定义能力。 + +- 对同一属性进行统一描述，比如： + - 缩写类会改为全拼，如 `desc`、`descSlot`、`description` 统一为 `description` + - 能使用名词或形容词的优先使用该类词性，一个词能说明白的不用两个词。 + - 如 `wrap`、`wrapable` 统一为 `wrap` + - 如将 `isXxx` 统一为 `xxx`，如 `isVisible`、`isDeletable` 等，可直接使用 `visible`、`deletable` 等，形容词化 + - 如`showXxx` 尽量统一为 `xxx`，名词化。【部分属性待优化。】 + - 如 `roundRadius` 改为 `radius` ，`columnNum` 改为 `columns`等 + - `onClickXxx` 统一为 `onXxxClick` + - `modelValue` 统一为 `value`，并增加支持 `defaultValue`，支持受控与非受控模式 + - 对于标识位置、对齐等类的属性，将属性名变更为其上一层的属性定义，如 `center`会改为 `align`、`vertical`，改为 `direction`，像标记距离的，如 `top`、`bottom`、`distance` 等，会改为 `threshold` + - 不规范的定义如 `okBtn`、`okText` 这种，会改为 `confirmXxx` +- 扩充属性的类型。如 `title` 的类型从 `string` 扩充为 `React.ReactNode`，增强自定义内容；其中有涉及合并属性的，统一用最简命名来定义属性；如 `title`、`titleSlot` 合并为 `title`，再扩充属性类型。 +- 对于 `xxClass`、`xxStyle`类的属性，移除，可使用 `className` 、`style` 来实现。 +- 移除与样式有关的属性，除基础组件的样式属性及部分实现起来较为复杂的样式属性外，大多数样式属性被移除，可通过样式变量来实现。 +- 将普遍认同可内置的属性或不怎么使用的属性，直接内置，去掉属性设置。 + +### 组件实现 + +### 基础组件 + +#### Button + +- 移除 `plain`，通过 `fill="outline"` 实现 +- 增加 `ref`，对外暴露组件内 `button` 元素 +- CSS 变量中，对 `type` 类型对应的色值的定义，不在暴露到文档中，建议使用默认值，或修改主题变量 +- 增加 `fill` 模式类型，`dashed`，修改 `fill` 默认值为 `outline`。 +- 增加 `rightIcon`，可满足同时设置左右两个icon的情况。 +- 修改 `size` 为 `large` 时的默认 `width` 为 `100%` 的值，如果使用通栏的 `button`，可搭配 `block` 来使用。 + +#### Cell + +- `subTitle` 重命名为 `description`，类型修改为 `React.Node` +- `desc` 重命名为 `extra`，类型修改为 `React.Node` +- `roundRadius` 重命名为 `radius` +- `center` 重命名为 `align`，默认值修改为`flex-start`，可选值为 `flex-start`、`center`、`flex-end` +- 移除 `icon`、 `isLink`、`url`、`linkSlot`、`replace`、`descTextAlign`，通过用户自定义节点实现，参考文档demo示例 + +#### CellGroup + +- 新增 `divider`，单元格之间是否有分割线 +- `desc` 重命名为 `description` +- `title`、`description` 类型修改为 `React.Node` +- 移除 `titleSlot` 和 `descSlot`，通过 `title`、`description` 实现 +- + +#### ConfigProvider + +#### Icon + +#### Image + +- 移除 `round`，通过 `radius` 实现圆或圆角 +- 移除 `loadingImg` 和 `slotLoading`，通过 `loading` 属性实现，当 `loading` 属性设置为 `ReactNode` 或 `true` 时，表示展示 `loading` 状态 +- 移除 `showError` 和 `slotError`，通过 `error` 属性实现，当 `error` 属性设置为 `ReactNode` 或 `true` 时，表示展示 `error` 状态 +- 移除 `loadingImg`，可通过 `loading` 设置 `ReactNode` +- 移除 `errorImg`，可通过 `error` 设置 `ReactNode` +- `showError` 重命名为 `error`，类型修改为 `boolean｜ReactNode` +- `showLoading` 重命名为 `loading`，类型修改为 `boolean｜ReactNode` + +#### Overlay + +- `overlayClass` 重命名为 `className` +- `overlayStyle` 重命名为 `style` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- 更改 `lockScroll` 默认值为 `true` +- 新增 `afterClose` 和 `afterShow`，用于完全关闭后触发的回调和完全展示后触发的回调 + +#### Popup + +- `popClass` 重命名为 `className`，统一将组件的样式类名使用 `className`，不再指定特殊名字，减轻用户使用的记忆成本 +- `overlayClass` 重命名为 `overlayClassName`，继承自`Overlay` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- `onOpened` 和 `onClosed` 重命名为 `afterShow` 和 `afterClose`，继承自`Overlay`，用于完全关闭后触发的回调和完全展示后触发的回调 +- `destroyOnClose` 的描述进行了修订，改为：“组件不可见时，卸载内容”，并把其默认值改为了`false` +- `onClickCloseIcon` 和 `onClickOverlay` 两个方法，增加布尔判断，如返回false 或 未定义返回值时，将不再关闭 Popup；默认值为 `true`；在demo中已增加相应示例；同时，两者的名字变更为 `onCloseIconClick`、`onOverlayClick` +- `closeIcon` 类型从 `string` 改为 `ReactNode`，以前的 `closeIcon='mask-close'` 需改为 `closeIcon={}` +- `onOverlayClick` 和 `onCloseIconClick` 不会自动触发 `onClose` 了，如需触发关闭事件，需主动调用 `onClose` 回调函数 +- 新增 `description` 属性，支持标题下展示描述内容。 +- 调整 `position` 为 `bottom` 时的默认样式，默认支持圆角，此刻不需要再设置 `round` 属性。 + +### 布局组件 + +#### Divider + +- 移除 `dashed`, 通过 `style` 属性实现 +- 移除 `hairline`, 默认为 `true` +- CSS 变量调整：`$divider-before-margin-right`、`$divider-after-margin-left` 统一为 `$divider-spacing`，`$divider-vertical-border-left` 变更为 `$divider-border-color`，增加 `$divider-side-width`。 + +#### Grid + +- 移除 `fontSize`，可自行控制传入的组件字体大小 +- 移除 `border`，作为默认样式 +- `columnNum` 重命名为 `columns` +- `GridItem` 使用方式修改为 `Grid.Item` + +#### Layout + +#### Sticky + +- 移除 `top` 和 `bottom`， 重命名为 `threshold` + +### 导航组件 + +#### Elevator + +- `acceptKey` 重命名为 `floorKey` +- `indexList` 重命名为 `list` +- `isSticky` 重命名为 `sticky` +- `onClickIndex` 重命名为 `onIndexClick` +- `onClickItem` 重命名为 `onItemClick` +- 新增`showKeys`，是否展示右侧导航 +- CSS 变量部分，对命名做了简化。 + +#### FixedNav + +- `unActiveText` 重命名为 `inactiveText` +- `navList` 重命名为 `list` +- `slotBtn` 重命名为 `content` +- `onSelected` 重命名为 `onSelect` +- 移除 `fixednavClass`，通过 `className` 实现 +- 移除 `slotList`，通过 `children` 实现 +- 该组件已废弃 `BEM` 规范，记得把 `__` 改为 `-` + +#### Indicator + +- 移除 `block`，暴露自定义节点 +- 移除 `align`，暴露自定义节点 +- `vertical` 重命名为`direction`，默认值为 `horizontal`，可选 `vertical` +- 移除 `fillZero`，暴露自定义节点 +- `size` 重命名为 `total` +- 增加非数字展示，并设置为默认状态 + +#### Menu + +- 移除 `fontClassName` +- 移除 `iconClassPrefix` +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick` +- `titleIcon` 重命名为 `icon` +- `optionsIcon` 重命名为 `icon` +- 增加 `closeOnClickAway` + +#### NavBar + +- `desc` 重命名为 `right`，类型修改为 `React.Node` +- 新增 `left`，左侧内容，渲染在返回区域的右侧 +- 新增 `back`，返回区域内容 +- `onClickBack` 重命名为 `onBackClick` +- 移除 `title`，通过 `children` 实现 +- 移除 `leftText` `leftShow`，通过 `back`、`left`实现 +- `safeAreaInsetTop` 重命名为 `safeArea` +- `border` 废弃 +- 移除 `onClickTitle` `onClickRight` `onClickIcon`，通过在`left`、`title`、`right`自定义事件实现，参考文档demo示例 +- + +#### Pagination + +- 新增 `lite` 模式，只展示页码，不支持事件交互 +- 新增 `defaultValue` 非受控值 +- `modelValue` 重命名为 `value`，受控值 +- `prevText` 重命名为 `prev`，类型修改为 `ReactNode` +- `nextText` 重命名为 `next`，类型修改为 `ReactNode` +- `forceEllipses` 重命令为 `ellipse` +- `showPageSize` 重命名为 `itemSize` +- `itemsPerpage` 重命名为 `pageSize` +- `totalitems` 重命名为 `total` +- `pageNodeRender` 重命名为 `itemRender` +- 移除 `pageCount`，通过 `total` 与 `pageSize` 组合实现 + +#### SideNavBar + +- `offset` 重命名为 `indent` + +#### Tabbar + +- `unactiveColor` 重命名为 `inactiveColor` +- `tabTitle` 重命名为 `title`，类型修改为 `ReactNode` +- `bottom` 重命名为 `fixed` +- `safeAreaInsetBottom` 重命名为 `safeArea` +- `visible` 重命名为 `defaultValue`，非受控 +- `activeVisible` 重命名为 `value`，受控 + +#### TabbarItem + +- 使用方式修改为 `Tabbar.Item` +- `icon` 类型改为 `ReactNode`，移除其他 `icon` 关联属性 +- 移除 `href`，通过 `onSwitch` 事件控制链接与路由跳转 +- 移除 `num`，支持传入所有 `Badge` Props +- 移除 `color`，使用父元素的 `activeColor`，保持同样的 `active` 状态 + +#### Tabs + +- 增加 `lite`、`card`、`button`、`divider` 模式。 +- 移除 `background`，通过 `className` 或 `style` 控制 +- 移除 `titleScroll`, 默认支持滚动 +- 移除 `ellipsis`，默认 `flex：1` +- 移除 `size`，通过 css 变量 `--nutui-tabs-titles-item-font-size` 实现 +- `animatedTime` 重命名为 `duration` +- `titleGutter` 重命名为 css 样式变量实现 +- `titleNode` 重命名为 `title` +- `color` 重命名为 `activeColor` +- `type` 重命名为 `activeType` +- `leftAlign` 重命名为 `align` +- `onClick` 类型改为 `(index: string | number) => void` +- `onChange` 类型改为 `(index: string | number) => void` +- 增加 defaultValue +- 增加 `activeType` 类型 `simple`，实现选项卡的简约选择，只修改字号和字重，不处理字色。 + +#### Tabs.Tabpane + +- `paneKey` 重命名为 `value` + +### 数据录入 + +#### Calendar + +- `poppable` 重命名为 `popup` +- `isAutoBackFill` 重命名为 `autoBackfill` +- `toDateAnimation` 重命名为 `scrollAnimation` +- `startText` 类型改为 `ReactNode` +- `endText` 类型改为 `ReactNode` +- `confirmText` 类型改为 `ReactNode` +- `onBtn` 重命名为 `renderHeaderButtons` +- `onDay` 重命名为 `renderDay` +- `onTopInfo` 重命名为 `renderDayTop` +- `onBottomInfo` 重命名为 `renderDayBottom` +- `onSelected` 重命名为 `onDayClick` +- `onChoose` 重命名为 `onConfirm` +- `onYearMonthChange` 重命名为 `onPageChange` +- 新增 `firstDayOfWeek`，支持按照周进行选择，指定周起止日，如0-6 + +#### Cascader + +- 新增 `defaultValue`，其中 `defaultValue` 用于非受控，原 `value` 用于受控。两者的类型都改为 `(number | string | undefined)[]` +- `checkedIcon` 重命名为 `activeIcon` +- `poppable` 重命名为 `popup` +- `lazyLoad` 重命名为 `onLoad`，当启动懒加载 `lazy` 时，动态加载数据 +- `convertConfig` 重命名为 `format`，配置转换规则 +- 合并 `textKey` `valueKey` `childrenKey` 三个属性为对象属性 `optionKey` +- 移除 `tabsColor`， 该属性为设置 `Tabs` 当前选中的 `tab` 的下划线色值，但该值最好与文字部分搭配使用，统一处理 CSS 变量。 + +#### Checkbox + +- 新增 `defaultChecked`，用于非受控，`checked` 用于受控 +- 新增 `value`，用于 group 模式 +- `textPosition` 重命名为 `labelPosition` +- `iconName` 重命名为 `icon`，类型为 `ReactNode` +- `iconAcitveName` 重命名为 `activeIcon` +- `iconIndeterminateName` 重命名为 `iconIndeterminateIcon` +- 移除 `iconSize` +- 部分 className 命名变更，废弃 `nutui-checkbox__xx` 命名方式，直接使用 `nutui-checkbox-xx`，并对选中状态命名修订为 `nutui-checkbox-icon-checked` +- 增加半选的禁用状态 + +#### Checkbox.Group + +- 新增 `defaultValue`，用于非受控，`value` 用于受控 +- `textPosition` 重命名为 `labelPosition` +- `toggleAll` 重命名为 `toggle` +- `toggleReverse` 重命名为 `reverse` +- 部分 className 命名变更，废弃 `nutui-checkbox__xx` 命名方式，直接使用 `nutui-checkbox-xx`，并对选中状态命名修订为 `nutui-checkbox-icon-checked` + +#### DatePicker + +- `modelValue` 重命名为 `value`，并增加 `defaultValue` +- `isShowChinese` 重命名为 `showChinese` +- `minDate` 重命名为 `startDate` +- `maxDate` 重命名为 `endDate` +- `onConfirmDatePicker` 重命名为 `onConfirm` +- `onCloseDatePicker` 重命名为 `onClose` +- 因为依赖组件`Picker`的变更，方法 `onConfirmDatePicker`、`onChange`的参数进行了调整，从`(selectedValue, selectedOptions)` 改为 `(selectedOptions, selectedValue)`。 + +#### Form + +- 增加 `footer`，类型为 `ReactNode`，用于表单底部区域，通常用于设置提交、重置按钮 +- 增加 `initialValues`，用于设置表单初始值，同时用于表单的重置 +- 增加 `name` 属性 + +#### Form.Item + +- 移除 `labelWidth`, 通过 `--nutui-form-item-label-width` 控制宽度 +- 增加 `required`，用于必选样式控制 +- 增加 `trigger`，用于设置数据更新的时机 +- 增加 `valuePropName`，用于收集子组件受控的属性映射 +- 增加 `getValueFromEvent`，用于在收集数据中进行数据转换 +- 增加 `onclick` 用于收集子组件的 `ref` + +#### Input + +#### InputNumber + +- 增加 `allowEmpty`, 用于允许内容是否为空 +- 新增 `defaultValue`，用于非受控，`value` 用于受控 +- `decimalPlaces` 重命名为 `digits` +- `isAsync` 重命名为 `async` +- 移除 `inputWidth`, 通过`--nutui-inputnumber-input-width`控制输入框的宽度 +- 移除 `buttonSize`, 通过`–nutui-inputnumber-button-width` 和 `–nutui-inputnumber-button-height`控制按钮的宽度和高度 +- taro 新增 `formatter` 属性, 用于指定输入框展示值的格式 +- 移除 `errorMessage` +- 移除 `showWordLimit` +- `autofocus` 重命名为 `autoFocus` +- `type="textarea"` 建议改为使用 `TextArea` 组件实现 + +#### NumberKeyboard + +- `randomKeys` 重命名为 `random` +- `customKey` 重命名为 `custom` +- `title` 类型变更为 `ReactNode` +- 新增 `onConfirm` 事件 +- 移除 `popClass` 定义，默认支持透传 `Popup` 属性 + +#### Picker + +- `isVisible` 重命名为 `visible` +- `listData` 重命名为 `options` +- `defaultValueData` 重命名为 `defaultValue` +- 增加受控 `value` +- `swipeDuration` 重命名为 `duration` +- `onCloseUpdate` 重命名为 `afterClose` +- 方法 `onConfirm`、`onClose`、`afterClose`、`onChange`的参数进行了调整，从`(selectedValue, selectedOptions)` 改为 `(selectedOptions, selectedValue)`。 + +#### Radio + +- 移除 `iconSize`，可通过 Icon 的 css 变量设置 +- `iconName` 重命名为 `icon`，类型修改为 `ReactNode` +- 增加 `labelPosition`，用于设置 `label` 的位置 +- 增加 `checked` 和 `defaultChecked` ，用于受控和非受控 +- `onChange` 类型修改为 `(checked: boolean) => void` +- 部分 className 命名变更，废弃 `nutui-radio__xx` 命名方式，直接使用 `nutui-radio-xx`，并对选中状态命名修订为 `nutui-radio-icon-checked` + +### Radio.Group + +- `textPosition` 重命名为 `labelPosition` +- 增加 `defaultValue` ，用于非受控 +- `onChange` 类型修改为 `(value: string| number) => void` +- 部分 className 命名变更，废弃 `nutui-radio__xx` 命名方式，直接使用 `nutui-radio-xx`，并对选中状态命名修订为 `nutui-radio-icon-checked` + +#### Range + +- `maxDesc` 重命名为 `maxDescription`，类型改为 `ReactNode` +- `minDesc` 重命名为 `minDescription`，类型改为 `ReactNode` +- `curValueDesc` 重命名为 `currentDescription`，类型改为 `(value) => ReactNode` +- 移除 `hiddenRange`，通过 `max/minDescription` 传 `null` 实现 +- 移除 `hiddenTag`，通过 `currentDescription` 传 `null` 实现 +- 移除 `activeColor`、`inactiveColor`、`buttonColor`，通过 `css` 变量实现 +- `onDragStart` 重命名为 `onStart` +- `onDragEnd` 重命名为 `onEnd` +- `modelValue` 重命为 `value`，增加 `defaultValue` 非受控方式 + +#### Rate + +- `minimizeValue` 重命名为 `min` +- `readonly` 重命名为 `readOnly` +- 移除 `spacing`，通过 css 样式变量实现 +- 移除 `activeColor`、`voidColor`、`iconSize`，通过 `checkedIcon`、`uncheckedIcon` 实现 +- 增加受控 `value` 与非受控 `defaultValue`，移除 `modelValue` + +#### SearchBar + +- `onClickInput` 重命名为 `onInputClick` +- 移除 `clearSize`，样式默认 +- 移除 `background`，使用 CSS 变量 `--nutui-searchbar-background` 实现 +- 移除 `inputBackground`，使用 CSS 变量 `--nutui-searchbar-input-background` 实现 +- 移除 `align`，使用 CSS 变量 `--nutui-searchbar-input-text-align` +- 新增 `left` 和 `right`，为 `ReactNode` 节点，可自定义内容 +- 移除 `leftoutIcon` 和 `label`，使用 `left` 实现 +- 移除 `rightoutIcon` 和 `actionText`，使用 `right` 实现 +- 移除 `leftinIcon`，使用 `leftIn` 实现 +- 移除 `rightinIcon`，使用 `rightIn` 实现，同时兼顾和 clearIcon 的交互，当设置rightIn时，默认展示 rightIn，当触发输入后，展示 clearIcon。同时增加 `backable` 来标记是否展示左侧返回Icon +- 移除 `onCancel`，使用 `right` 来实现事件处理 +- 移除 `onClickLeftinIcon`，用户可使用 `left` 来实现事件处理 +- 移除 `onClickLeftoutIcon`，用户可使用 `left` 来实现事件处理 +- 移除 `onClickRightinIcon`，用户可使用 `right` 来实现事件处理 +- 移除 `onClickRightoutIcon`，用户可使用 `right` 来实现事件处理 + +#### ShortPassword + +- `desc` 重命名为 `description` +- `noButton` 重命名为 `hideFooter` +- `onOk` 重命名为 `onConfirm` +- `errorMsg` 重命名为 `error` +- 移除 `closeOnClickOverlay`，默认支持透传 Popup 属性 +- `title`、`description`、`tips`、`error` 类型修改为 `ReactNode` +- `modelValue` 重命名为 `value`，受控模式 +- 新增 `onFoucs` 事件 + +#### TextArea + +- `maxlength` 重命名为 `maxLength` +- `readonly` 重命名为 `readOnly` +- `limitShow` 重命名为 `showCount` +- `autosize` 重命名为 `autoSize` +- 移除 `textAlign`，可通过 `style` 传入 +- `defaultValue` 改为非受控，增加受控值 `value` + +#### Uploader + +- `maximize` 重命名为 `maxFileSize` +- `maximum` 重命名为 `maxCount` +- `listType ` 重命名为 `previewType` +- `isDeletable ` 重命名为 `deletable` +- `isPreview` 重命名为 ` preview` +- `defaultImg` 重命名为 ` previewUrl` +- `defaultFileList` 重命名为 ` defaultValue` +- `uploadIconTip` 重命名为 `uploadLabel`，类型变更为 `ReactNode` +- `onBeforeUpload` 重命名为 `beforeUpload` +- `onBeforeXhrUpload` 重命名为 `beforeXhrUpload` +- `onBeforeDelete` 重命名为 `beforeDelete` +- `onRemove` 重命名为 `onDelete` +- 增加 `fit`，用于图片填充模式 +- 增加 `value`，用于受控传值 +- 移除 `uploadIconSize`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 +- `uploadIcon` 类型从 `string` 调整为 `ReactNode` +- `onChange` 参数类型从 `{fileList: FileItem[], event: any}` 调整为 `FileItem[]` + +### 操作反馈 + +#### ActionSheet + +- `title`，类型变更为 `ReactNode` +- `description`，类型变更为 `ReactNode` +- `cancelTxt`，重命名为 `cancelText`，类型变更为 `ReactNode` +- `menuItems` 重命名为 `options` +- `chooseTagValue` 重命名为 `value` +- `onChoose` 重命名为 `onSelect` +- 增加 `options` 的定义 + - `color` 重命名为 `danger` + - `name`，列表项的标题key + - `description`，列表项的描述key + - `danger`，列表项中提醒用户重点关注的操作 + - `disabled`，列表项中禁用项 + +#### BackTop + +- `elId` 重命名为 `target` +- 移除 `right`、`bottom`，通过 style 传入，增加支持 `left`、`top` +- `distance` 重命名为 `threshold` +- 移除 `isAnimation`，通过 `duration` 设置 0 实现无动画效果 + +#### Dialog + +- `okText` 重命名为 `confirmText`，规范命名。 +- `mask` 重命名为 `overlay`，组件库中统一使用 Overlay 组件作为遮罩层，并使用 overlay 作为是否展示遮罩层的属性值。 +- `closeOnClickOverlay` 重命名为 `closeOnOverlayClick`，组件库统一到该属性。 +- `noOkBtn` 重命名为 `hideConfirmButton`，初始值不变，依然表示是否隐藏确认按钮，主要是为了语义化更强。 +- `noCancelBtn` 重命名为 `hideCancelButton`，初始值不变，依然表示是否隐藏取消按钮，主要是为了语义化更强。 +- `okBtnDisabled` 重命名为 `disableConfirmButton`，初始值不变，依然表示是否禁用确认按钮，主要是为了语义化更强。 +- 移除 `noFooter`，使用 footer 统一处理，当 footer 为空时，及可替代该值。目前 noFooter 也需要手动声明是否为 noFooter；修改后需手动指出 footer={null} +- 移除 `textAlign`，改用样式变量 `--nutui-dialog-content-text-align` 或 SCSS 变量 `$dialog-content-text-align` 控制，默认值为 center。 +- 移除 `cancelAutoClose`，改为 `beforeCancel` 和 `beforeClose` 来实现，在点击关闭或取消时，可先触发这两个方法，以确定是否要关闭弹框，如返回true，则关闭；否则不关闭。 +- `onOk` 重命名为 `onConfirm`，规范命名。 +- `onClosed` 重命名为 `onClose`，规范命名，关闭时触发。 +- `onClickSelf` 重命名为 `onClick`，语义不变，仍表示点击弹框自身时触发事件。 +- 增加 `overlayStyle` 和 `overlayClassName`，用来配置 Overlay 组件样式。 +- 增加 `onOverlayClick`，支持点击overlay时，触发事件。 +- `onCancel` 回调不会自动关闭弹层，需主动调用 `Dialog.close(xx)` + +#### Drag + +#### InfiniteLoading + +- `useCapture` 重命名为 `capture` +- `onScrollChange` 重命名为 `onScroll` +- `isOpenRefresh` 重命名为 `pullRefresh` +- `pullTxt` 重命名为 `pullingText`，类型变更为 `ReactNode` +- `loadTxt` 重命名为 `loadingText`，类型变更为 `ReactNode` +- `containerId` 重命名为 `target` +- 修订类名如 `top-box`、`bottom-box` 为 `nut-infinite-top-tips`、`nut-infinite-bottom-tips` + +#### Notify + +- 移除 `color` ，通过css变量`--nutui-notify-text-color`实现 +- 移除`background`，通过css变量`--nutui-notify-base-background-color`实现 +- `onClosed` 重命名为 `onClose` + +#### PullToRefresh + +#### Swipe + +- 移除 `leftWidth` ，通过 `leftAction` 实现 +- 移除 `rightWidth` ，通过 `rightAction` 实现 + +#### Switch + +- 新增 `defaultChecked`，用于非受控，`checked` 用于受控 +- 移除 `isAsync`，通过 `checked`实现 +- 移除 `activeColor` ，通过css变量`--nutui-switch-open-background-color`实现 +- 移除 `inactiveColor`，通过css变量`--nutui-switch-close-background-color`实现 + +#### Toast + +- 移除H5版本 `id` +- 移除 `center`和 `bottom`，通过 `position` 实现 +- 移除 `bgColor`，通过 css 变量实现 +- 移除 `customClass`，通过 `className` 实现 +- 移除 `cover` 和 `coverColor` ，通过css变量实现 +- 移除 `loadingRotate`，旋转状态通过 `iconFont`实现 +- 移除 `textAlignCenter`，通过css变量实现 +- 修改 `closeOnClickOverlay` 为 `closeOnOverlayClick` ，语义不变，是否在点击遮罩层后关闭提示 +- 新增 `lockScroll` ，用于背景是否锁定，默认值为 `false` + +### 展示组件 + +#### Animate + +- `type` 属性类型更改为 `AnimateType` ，具体值详见文档 +- `action` 属性类型更改为 `initial \| click` + +#### AnimatingNumbers + +- `maxLen` 重命名为 `length` +- `endNumber` 重命名为 `value`，类型修改为 `string|number` +- `delaySpeed` 重命名为 `delay` +- `easeSpeed` 重命名为 `duration` + +#### Audio + +- `url` 重命名为 `src` +- `autoplay` 重命名为 `autoPlay` +- `onFastBack` 重命名为 `onBack` +- `onPlayEnd` 重命名为 `onEnd` + +#### Avatar + +- `url` 重命名为 `src` +- `onActiveAvatar` 重命名为 `onClick` +- 新增 `fit` 属性，用于图片填充模式 +- 移除 `iconSize`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 + +#### AvatarGroup + +- AvatarGroup `maxCount` 重命名为 `max` +- AvatarGroup `span` 重命名为 `gap` +- AvatarGroup `zIndex` 重命名为 `level` + +#### Badge + +- 移除 `zIndex`，目前没有用到，也不生效，直接去掉。 +- 移除 `icon`，自定义 `icon` 可放在 `value` 中实现，扩充了 `value` 的类型。 +- 修改 `max` 的最大值为99（之前为10000），比较贴合实际场景。 +- 主题定制的 `css` 变量中，去掉和 `dot` 有关的其他值，只保留 `width`。其他值由 `width` 计算而来. +- 主题定制，增加包含 icon 情况下的样式变量。 + +#### CircleProgress + +- `progress` 重命名为 `percent` +- `circleColor` 重命名为 `color` +- `pathColor` 重命名为 `background` + +#### Collapse + +- 新增 `defaultActiveName` 非受控 +- `activeName` 改为受控方式 +- `icon` 重命名为 `expandIcon`，类型修改为 `ReactNode` +- `onChange` 参数变更为 `activeName, name, status` +- 新增一种样式，尝试修改 `--nutui-collapse-item-border-bottom` 和 `-nutui-collapse-item-header-border-bottom`，可查看 + +#### CollapseItem + +- 使用方式调整为 `Collapse.Item` +- subTitle 重命名为 extra，类型修改为 `ReactNode` +- 新增 `expnandIcon`，优先级高于父组件对应值 +- 新增 `rotate`，优先级高于父组件对应值 + +#### CountDown + +- 新增 `remainingTime`，支持剩余毫秒时间倒计时。 + +#### Ellipsis + +- 新增 `className` 和 `style` 属性的支持 +- 优化 H5 的代码，去掉 `useEffect` 渲染改用 `useLayoutEffect` + +#### Empty + +- 新增 `status` 属性，用于默认图片错误类型 +- 新增 `size` 属性，用于区分全屏与半屏状态下图片的不同大小 +- 新增 `title` 属性，用于展示提示的标题部分 +- 新增 `actions` 属性，用于展示提示的操作部分，支持1个或2个操作 +- `image` 属性类型更改为 `ReactNode` +- 新增 `title`、`size`、`actions` 属性，支持标题的设置、图片大小的设置、可能的操作设置，操作设置默认以`Button`实现。 + +#### ImagePreview + +- `show` 重命名为 `visible` +- `autoplay` 重命名为 `autoPlay` +- `initNo` 重命名为 `defaultValue`，同时增加 `value`，为受控 +- `paginationVisible` 重命名为 `indicator` +- `paginationColor` 重命名为 `indicatorColor` +- `contentClose` 重命名为 `closeOnContentClick` +- 在 `Taro` 下支持视频 + +#### NoticeBar + +- `direction` 的可选值从 `across` 重命名为 `horizontal` +- `text` 重命名为 `content` +- `closeMode` 重命名为 `closeable` +- `leftIcon` 类型扩充，支持 `ReactNode` +- `rightIcon` 类型扩充，支持 `ReactNode` +- `color` 移除，使用 CSS 变量，之前已支持 +- `background` 移除，使用 CSS 变量，之前已支持 +- `wrapable` 重命名为 `wrap` +- `standTime` 重命名为 `duration` +- `onClickItem` 重命名为 `onItemClick` +- `complexAm` 废弃 + +#### Popover + +- 移除 `theme` 属性，可以通过css变量 `--nutui-brand-color` 控制暗黑模式 +- 新增 `showArrow` 属性，用于是否显示小箭头 +- 新增 `closeOnActionClick` 属性，用于是否在点击选项后关闭 +- 新增 `closeOnOutsideClick` 属性，用于是否在点击外部元素后关闭菜单 +- 新增 `targetId` 属性，用于自定义目标元素 id +- 新增 `onOpen` 属性，用于点击菜单时触发 +- 新增 `onClose` 属性，用于关闭菜单时触发 +- 新增 `action` 属性，用于为对应的选项添加方法 +- `onChoose` 重命名为 `onSelect` +- 继承Popup组件的 `overlayStyle` 、`overlayClassName` 、`overlay` 、`closeOnOverlayClick` 属性。 + +#### Price + +- `decimalDigits` 重命名为 `digits` +- 移除 `needSymbol`，通过 `symbol` 判断是否需要加上 symbol 符号 +- 新增 `line`，是否展示划线价 + +#### Progress + +- `percentage` 重命名为 `percent`，受控 +- 移除 `isShowPercentage`，可以自定义传入文案 +- 移除 `textWidth`，可以自定义传入内容的宽度 +- `strokeColor` 重命名为 `color` +- `fillColor` 重命名为 `background` +- 移除 `size`，通过 `strokeWidth`、`progress-height` css 变量实现尺寸自定义 +- `status` 重命名为 `animated`，表示是否展示动画效果 +- 移除 `textBackground`，通过 css 实现 +- 移除 `textColor`，通过 css 实现 +- 移除 `textInside`，仅保留内显功能 +- 移除 `textType、icon`，通过 `children` 传入自定义 `ReactNode`，不再区分类型 +- 新增 `lazy` 属性，支持每次进入可视区时展示进度条动画 +- 新增 `delay` 属性，表示延迟数据加载时长 + +#### Skeleton + +- `loading` 重命名为 `visible` +- `row` 重命名为 `rows` +- 移除 `width`，通过 css 变量 `skeleton-line-width` 实现 +- 移除 `height`，通过 css 变量 `skeleton-line-height` 实现 +- 移除 `round`，通过 css 变量 `skeleton-line-border-radius` 实现 + +#### Steps + +- `current` 重命名为 `value` +- `onClickStep` 重命名为 `onStepClick` +- `progressDot` 重命名为 `dot` + +#### Step + +- 移除 `iconColor`，可通过 `icon` 属性传入自定义 icon 或借助 CSS Variables 修改 icon 颜色 +- 移除 `size`，可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小 +- 移除 `renderContent` ，可通过 `description` 实现 +- `title` 类型修改为 `ReactNode` +- `content` 重命名为 `description`，类型改为 `ReactNode` +- `icon` 类型修改为 `ReactNode` +- `activeIndex` 重命名为 `value` + +#### Swiper + +- h5 + - 移除 `paginationColor`，通过 `indicator` 的 CSS 变量控制 + - 移除 `paginationBgColor`，通过 `indicator` 的 CSS 变量控制 + - 移除 `pageContent`，通过 indicator 实现 + - `autoplay` 重命名为 `autoplay` + - `initPage` 重命名为 `defaultValue` + - `paginationVisible` 重命名为 `indicator`，类型改为` ReactNode` + - `isPreventDefault` 重命名为 `preventDefault` + - `isStopPropagation` 重命名为 `stopPropagation` + - `isCenter` 重命名为 `center` +- taro + - 通过封装 Taro 的 `Swiper` 和 `SwiperItem` 实现，支持的属性可参考 Taro Swiper 文档。 + +#### Table + +- `onSorter` 重命名为 `onSort` +- 合并 `summary` 与 `noData` 的样式处理 + +#### Tag + +- `color` 重命名为 `background` +- `textColor` 重命名为 `color` + +#### TrendArrow + +- `rate` 重命名为 `value` +- `showSign` 重命名为 `symbol` +- `showZero` 重命名为 `zero` +- `arrowLeft` 重命名为 `left` +- `syncTextColor` 重命名为 `sync` +- `textColor` 重命名为 `color` +- `upIconName` 重命名为 `riseIcon`，类型修改为 `React.Node` +- `downIconName` 重命名为 `dropIcon`，类型修改为 `React.Node` +- 移除 `iconSize`，通过`riseIcon`、`dropIcon`自定义传入icon大小 + +#### Video + +- 在 `Taro` 下新增video的适配 + +#### VirtualList + +- `sourceData` 重命名为 `list` +- `conatinerSize` 重命名为 `containerHeight` +- `itemSize` 重命名为 `itemHeight` +- `itemEqualSize` 重命名为 `itemEqual` +- `horizontal` 修改为 `direction`，默认值 `vertical`，可选值 `horizontal` + +#### WaterMark + +- `fontColor` 重命名为 `color` + +### 特色组件 + +#### Address + +- 该组件的 `custom` 改用 `Cascader` 组件重写；`custom2`也将使用 `Cascader` 完成，在 `Cascader` 中支持 `Elevator`，开发中。所以会废弃 `province`、`city`、`country`、`town` 这些属性，同时支持 `Cascader` 的属性。 +- `modelValue` 重命名为 `visible` +- `modelSelect` 重命名为 `defaultValue` +- `onSelected` 重命名为 `onSelect` +- `existAddress` 重命名为 `existList` +- `selectedIcon` 重命名为 `selectIcon` +- `closeBtnIcon` 重命名为 `closeIcon` +- `backBtnIcon` 重命名为 `backIcon` +- `isShowCustomAddress` 重命名为 `custom`，用于已有地址列表与自定义列表的切换，修改默认为值 `false` +- `customAndExistTitle` 废弃，与 `custom` 合并，当 `custom` 为 true 时，为默认文案，设置为某字符串时，展示字符串。 +- `customAddressTitle`、`existAddressTitle` 重命名为 `title`，不再区分状态，可通过onSwitch修改title +- 精简布局和样式 + +#### Barrage + +- `barrageList` 重命名为 `list` +- `frequency` 重命名为 `interval` +- `speeds` 重命名为 `duration` +- `top` 重命名为 `gapY` + +#### Card + +#### Signature + +- `type` 类型修改为 `png｜jpg` +- `unSupportTpl` 重命名为 `unsupported`，类型修改为 `ReactNode` +- 新增 `confirm`和`clear` ref 的方法，移除组件内部 `button`元素，通过自定义按钮元素，设置元素点击事件结合ref实现，参考文档demo示例 + +#### TimeSelect + +- 移除 `height`，通过 `style` 设置高度 +- `title` 类型修改为 `ReactNode` +- `onPannelChange` 重命名为 `onDateChange` +- 移除 `dates`、`times`，合并为 `options`，重新设计了数据结构 +- 增加 `optionKey` 用于自定义数据中的关键字 +- 移除 `currentKey`，新增 `defaultValue` 用于设置默认选项，支持时间选择 diff --git a/src/sites/sites-react/doc/docs/taro/official-theme-react.en-US.md b/src/sites/sites-react/doc/docs/taro/official-theme-react.en-US.md new file mode 100644 index 0000000000..931c122da2 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/official-theme-react.en-US.md @@ -0,0 +1,65 @@ +# Official theme + +## introduce + +NutUI provides multiple sets of official `UI` themes by default, while allowing new themes to be customized to a certain extent to meet the diverse visual needs of the business. + +#### + +| theme description | scss file name | +| --- | --- | +| Jingdong APP theme (default) | `variables.scss` | +| Jingdong B Mall Theme Preview | `variables-jdb.scss ` | + +NutUI theme customization + +## How to use + +### Modify the configuration file of the local project vite or webpack + +Modify the **sass-loader** configuration in the vite or webpack configuration file. The following example + +#### vite configuration example + +:::demo + +```javascript +// https://vitejs.dev/config/ +export default defineConfig({ + //... + css: { + preprocessorOptions: { + scss: { + // Default Jingdong APP 10.0 theme > @import "@nutui/nutui-react/dist/styles/variables.scss"; + // Jingdong B Mall theme > @import "@nutui/nutui-react/dist/styles/variables-jdb.scss"; + additionalData: `@import "@nutui/nutui-react/dist/styles/variables.scss";`, + }, + }, + }, +}) +``` + +::: + +#### webpack configuration example + +:::demo + +```javascript +{ + test: /\.(sa|sc)ss$/, + use: [ + { + loader: 'sass-loader', + options: { + // Default Jingdong APP 10.0 theme > @import "@nutui/nutui-react/dist/styles/variables.scss"; + // Jingdong B Mall theme > @import "@nutui/nutui-react/dist/styles/variables-jdb.scss"; + // Note: In different versions of sass-loader, the name of this option is different. For details, please refer to the version documentation corresponding to sass-loader + data: `@import "@nutui/nutui-react/dist/styles/variables.scss";`, + } + } + ] +} +``` + +::: diff --git a/src/sites/sites-react/doc/docs/taro/official-theme-react.md b/src/sites/sites-react/doc/docs/taro/official-theme-react.md new file mode 100644 index 0000000000..b183ada3bd --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/official-theme-react.md @@ -0,0 +1,86 @@ +# 官方主题 + +## 介绍 + +NutUI 默认提供多套官方`UI`主题，同时允许在一定程度上定制新主题，以满足业务的多样化视觉需求。 + +#### + +| 主题说明 | scss 文件名称 | +| --- | --- | +| 京东 APP 主题（默认） | `variables.scss` | +| 京东B商城主题预览 | `variables-jdb.scss` | + +NutUI 主题定制 + +## 使用方式 + +### 修改本地项目 vite 或者 webpack 的配置文件 + +修改 vite 或者 webpack 配置文件中 **sass-loader** 的配置。如下示例 + +#### vite 配置示例 + +:::demo + +```javascript +// https://vitejs.dev/config/ +export default defineConfig({ + //... + css: { + preprocessorOptions: { + scss: { + // 默认京东 APP 主题 > @import "@nutui/nutui-react/dist/styles/variables.scss"; + // 京东B商城主题 > @import "@nutui/nutui-react/dist/styles/variables-jdb.scss"; + additionalData: `@import "@nutui/nutui-react/dist/styles/variables.scss";`, + }, + }, + }, +}) +``` + +::: + +#### webpack 配置示例 + +:::demo + +```javascript +{ + test: /\.(sa|sc)ss$/, + use: [ + { + loader: 'sass-loader', + options: { + // 默认京东 APP 主题 > @import "@nutui/nutui-react/dist/styles/variables.scss"; + // 京东B商城主题 > @import "@nutui/nutui-react/dist/styles/variables-jdb.scss"; + // 注意：在 sass-loader 不同版本，这个选项名是 是不一样的，具体可参考 sass-loader对应的版本文档 + data: `@import "@nutui/nutui-react/dist/styles/variables.scss";`, + } + } + ] +} +``` + +::: + +#### vue/cli 3 以上版本修改 **vue.config.js** 进行配置 + +:::demo + +```javascript +module.exports = { + css: { + loaderOptions: { + // 给 sass-loader 传递选项 + scss: { + // @/ 是 src/ 的别名 + // 注意：在 sass-loader v7 中，这个选项名是 "data" + prependData: `@import "@nutui/nutui-react/dist/styles/variables.scss";`, + }, + }, + }, +} +``` + +::: diff --git a/src/sites/sites-react/doc/docs/taro/start-react.en-US.md b/src/sites/sites-react/doc/docs/taro/start-react.en-US.md new file mode 100644 index 0000000000..b8d48574ff --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/start-react.en-US.md @@ -0,0 +1,185 @@ +# Quick Start + +## Intro + +Through this article, you can master the installation and use of NutUI-React Taro. The operation is simple and easy to use, and the development is simple and fast. + +## Install Taro CLI + +```sh +# pnpm +pnpm install -g @tarojs/cli +# npm +npm install -g @tarojs/cli +# yarn +yarn global add @tarojs/cli +``` + +## Method 1: Use the NutUI template to quickly create a project + +#### 1. Use the command to create a Taro project: + +```sh +taro init +``` + +#### 2、Refer to the operation below to select the NutUI React template + +```sh +👽 Taro + +Taro 即将创建一个新项目! +Need help? Go and open issue: https://tls.jd.com/taro-issue-helper + +? 请输入项目名称！ MyProject +? 请输入项目介绍 +? 请选择框架 React +? 是否需要使用 TypeScript ？ Yes +? 请选择 CSS 预处理器（Sass/Less/Stylus） Sass +? 请选择编译工具 Webpack5 +? 请选择包管理工具 pnpm +? 请选择模板源 Github（最新） +✔ 拉取远程模板仓库成功！ + 默认模板 + harmony + mobx + pwa +❯ react-NutUI（使用 NutUI React 的模板） + react-native + ...... +``` + +## Method 2: Introduce NutUI React into the existing Taro project + +#### 1. Install NutUI React + +```sh +# pnpm +pnpm add @nutui/nutui-react-taro +# npm +npm i @nutui/nutui-react-taro +# yarn +yarn add @nutui/nutui-react-taro +``` + +#### 2、Taro + +Install [@tarojs/plugin-html](https://taro-docs.jd.com/docs/use-h5/) + +```sh +# pnpm +pnpm add @tarojs/plugin-html@version +# yarn +yarn add @tarojs/plugin-html@version +# npm +npm i @tarojs/plugin-html@version +``` + +config + +:::demo + +```js +// config/index.js +config = { + plugins: ['@tarojs/plugin-html'], + designWidth(input) { + if (input?.file?.replace(/\\+/g, '/').indexOf('@nutui') > -1) { + return 375 + } + return 750 + }, + deviceRatio: { + 640: 2.34 / 2, + 750: 1, + 828: 1.81 / 2, + 375: 2 / 1, + }, +} +``` + +::: + +#### 3、Component usage and on-demand import + +You can choose to import style files in full: + +```js +import '@nutui/nutui-react-taro/dist/style.css' +``` + +You can also implement on-demand import of styles in the following ways: + +Install `babel-plugin-import`. + +```sh +# pnpm +pnpm add babel-plugin-import +# npm +npm i babel-plugin-import +# yarn +yarn add babel-plugin-import +``` + +babel config + +:::demo + +```js +// babel.config.js +plugins: [ + [ + 'import', + { + libraryName: '@nutui/nutui-react-taro', + libraryDirectory: 'dist/esm', + style: 'css', + camel2DashComponentName: false, + }, + 'nutui-react-taro', + ], +] +``` + +::: + +## Precautions + +#### 1. Check if Taro is successfully installed + +```sh +taro -v +``` + +The Taro version number appears to indicate a successful installation. + +#### 2. Saas-related errors occurred during the installation of Taro + +You may consider installing `mirror-config-china` and try again. + +```sh +npm install -g mirror-config-china +``` + +#### 3. When the applet project is running, the error message "can't find the template" appears + +Solution: Turn off prebundle and cache in Taro configuration file + +:::demo + +```js +// config/index.js +config = { + compiler: { + type: 'webpack5', + prebundle: { + exclude: ['@nutui/nutui-react-taro', '@nutui/icons-react-taro'], + }, + }, + cache: { + enable: false, + }, +} +``` + +::: diff --git a/src/sites/sites-react/doc/docs/taro/start-react.md b/src/sites/sites-react/doc/docs/taro/start-react.md new file mode 100644 index 0000000000..89ac3ff900 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/start-react.md @@ -0,0 +1,191 @@ +# 快速上手 + +## 介绍 + +通过本文你可以掌握 NutUI-React Taro 的安装和使用方法，操作简单易上手，开发简洁快速。 + +## 安装 Taro 脚手架 + +```sh +# pnpm +pnpm install -g @tarojs/cli +# npm +npm install -g @tarojs/cli +# yarn +yarn global add @tarojs/cli +``` + +## 方式一：使用 Taro 内置的 NutUI 模板快速创建项目 + +#### 1、使用命令创建 Taro 项目： + +```sh +taro init +``` + +#### 2、参考下方操作，选择 NutUI React 模板 + +```sh +👽 Taro + +Taro 即将创建一个新项目! +Need help? Go and open issue: https://tls.jd.com/taro-issue-helper + +? 请输入项目名称！ MyProject +? 请输入项目介绍 +? 请选择框架 React +? 是否需要使用 TypeScript ？ Yes +? 请选择 CSS 预处理器（Sass/Less/Stylus） Sass +? 请选择编译工具 Webpack5 +? 请选择包管理工具 pnpm +? 请选择模板源 Github（最新） +✔ 拉取远程模板仓库成功！ + 默认模板 + harmony + mobx + pwa +❯ react-NutUI（使用 NutUI React 的模板） + react-native + ...... +``` + +## 方式二：在已有 Taro 项目中引入 NutUI React + +#### 1、安装 NutUI React + +```sh +# pnpm +pnpm add @nutui/nutui-react-taro +# npm +npm i @nutui/nutui-react-taro +# yarn +yarn add @nutui/nutui-react-taro +``` + +#### 2、Taro 相关配置 + +安装 [@tarojs/plugin-html](https://taro-docs.jd.com/docs/use-h5/) + +> 注意，这里安装的版本 version 必须与项目中 Taro 版本保持一致！ + +```bash +# pnpm +pnpm add @tarojs/plugin-html@version +# yarn +yarn add @tarojs/plugin-html@version +# npm +npm i @tarojs/plugin-html@version +``` + +在项目中配置 + +:::demo + +```js +// config/index.js +config = { + // 开启 HTML 插件 + plugins: ['@tarojs/plugin-html'], + designWidth(input) { + // 配置 NutUI 375 尺寸 + if (input?.file?.replace(/\\+/g, '/').indexOf('@nutui') > -1) { + return 375 + } + // 全局使用 Taro 默认的 750 尺寸 + return 750 + }, + deviceRatio: { + 640: 2.34 / 2, + 750: 1, + 828: 1.81 / 2, + 375: 2 / 1, + }, +} +``` + +::: + +#### 3、组件使用与按需引入 + +您可以选择全量引入样式文件： + +```js +import '@nutui/nutui-react-taro/dist/style.css' +``` + +也可以通过下面的方式实现样式的按需引入： + +首先安装 `babel-plugin-import` 插件 + +```sh +# pnpm +pnpm add babel-plugin-import +# npm +npm i babel-plugin-import +# yarn +yarn add babel-plugin-import +``` + +安装后在项目中设置 babel 相关配置： + +```js +// babel.config.js +module.exports = { + presets: [ + // ... + ], + plugins: [ + [ + 'import', + { + libraryName: '@nutui/nutui-react-taro', + libraryDirectory: 'dist/esm', + style: 'css', + camel2DashComponentName: false, + }, + 'nutui-react-taro', + ], + ], +} +``` + +## 注意事项 + +#### 1、检查 Taro 是否安装成功 + +```sh +taro -v +``` + +出现 Taro 版本号说明安装成功。 + +#### 2、安装 Taro 过程中出现 Saas 相关错误 + +可以考虑安装 `mirror-config-china` 后重试。 + +```sh +npm install -g mirror-config-china +``` + +#### 3、小程序项目运行时出现「找不到模板」的错误提示 + +解决方案：在 Taro 配置文件中关闭 prebundle 及 cache + +:::demo + +```js +// config/index.js +config = { + compiler: { + type: 'webpack5', + prebundle: { + exclude: ['@nutui/nutui-react-taro', '@nutui/icons-react-taro'], + }, + }, + cache: { + enable: false, + }, +} +``` + +::: diff --git a/src/sites/sites-react/doc/docs/taro/theme-react.en-US.md b/src/sites/sites-react/doc/docs/taro/theme-react.en-US.md new file mode 100644 index 0000000000..30cfcb128c --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/theme-react.en-US.md @@ -0,0 +1,58 @@ +# Customize Theme + +## Introduce + +NutUI-React supports flexible style customization to meet multiple visual business and brand needs, including but not limited to support for global master tone and component-specific visual customization. +
+
+In NutUI-React version 1.4.0, the Sass theme customization function of 1.x can still be used. We added CSS variables to the original theme customization function, so that the new theme customization function can be used without introducing additional SCSS style files. + +## Method 1: Use CSS Variables to configure topics + +`NutUI - React` can [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) to organize the pattern, By overwriting these 'CSS' variables, you can achieve custom theme, dynamic switching theme and other functions. +
+
+You can play with the [ConfigProvider](#/zh-CN/component/configprovider) component. +
+
+We recommend replacing [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) for the theme of personalized configuration. + +## Method 2: Use Sass variable for topic configuration + +#### Step 1: Create a custom variable SCSS file + +Create a new 'SCSS' file 'custom_theme.scss' in your local project. + +```scss +// Dominant tone +$color-primary: #fa2c19; +$color-primary-end: #fa6419; +... +``` + +#### Step 2: Modify the configuration file of the local project webpack or vite + +Modify the ** ass-loader** configuration in the 'vite' or 'webpack' configuration file. The following example + +#### taro + +Configure `scss` file global cover in `config/index.js`: + +```javascript +const path = require('path'); +const config = { + deviceRatio: { + 640: 2.34 / 2, + 750: 1, + 828: 1.81 / 2, + 375: 2 / 1 + }, + sass: { + resource: [ + path.resolve(__dirname, '..', 'src/assets/styles/custom_theme.scss') + ], + // 默认京东 APP 10.0主题 > @import "@nutui/nutui-react-taro/dist/styles/variables.scss"; + data: `@import "@nutui/nutui-react-taro/dist/styles/variables.scss";` + }, + // ... +``` diff --git a/src/sites/sites-react/doc/docs/taro/theme-react.md b/src/sites/sites-react/doc/docs/taro/theme-react.md new file mode 100644 index 0000000000..f1aec212d5 --- /dev/null +++ b/src/sites/sites-react/doc/docs/taro/theme-react.md @@ -0,0 +1,53 @@ +# 主题定制 + +## 介绍 + +NutUI-React 支持灵活的样式定制，满足多种视觉业务和品牌需求，包括但不限于全局主色调和特定组件视觉定制的支持。 +
+在 NutUI-React 的 1.4.0 版本中，依然可以使用 1.x 的 Sass 定制主题功能，我们在原有的主题定制功能上新增了 CSS 变量， 无需引入额外的 SCSS 样式文件，就可以使用到新的主题定制功能。 + +## 方式一 使用 CSS Variables 进行主题配置 + +`NutUI-React` 组件可以通过 [CSS Vars](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 `CSS` 变量，可以实现定制主题、动态切换主题等功能。 +
+您可在 [ConfigProvider 组件](#/zh-CN/component/configprovider) 进行体验。 +
+我们更推荐使用替换 [CSS Vars](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 的方式来进行个性化的主题配置。 + +## 方式二 使用 Sass 变量 进行主题配置 + +### 第一步 新建自定义变量 SCSS 文件 + +在本地项目中新建一个 `SCSS` 文件 `custom_theme.scss` 进行自定义。 + +```scss +// 主色调 +$color-primary: #fa2c19; +$color-primary-end: #fa6419; +... +``` + +### 第二步 修改本地项目 webpack 或者 vite 的配置文件 + +#### Taro 小程序使用示例 + +修改 `config/index.js` 文件中配置 `scss` 文件，全局覆盖如： + +```javascript +const path = require('path'); +const config = { + deviceRatio: { + 640: 2.34 / 2, + 750: 1, + 828: 1.81 / 2, + 375: 2 / 1 + }, + sass: { + resource: [ + path.resolve(__dirname, '..', 'src/assets/styles/custom_theme.scss') + ], + // 默认京东 APP 10.0主题 > @import "@nutui/nutui-react-taro/dist/styles/variables.scss"; + data: `@import "@nutui/nutui-react-taro/dist/styles/variables.scss";` + }, + // ... +``` diff --git a/src/sites/doc/main.tsx b/src/sites/sites-react/doc/main.tsx similarity index 89% rename from src/sites/doc/main.tsx rename to src/sites/sites-react/doc/main.tsx index 2345d6fed1..edbb32b1d5 100644 --- a/src/sites/doc/main.tsx +++ b/src/sites/sites-react/doc/main.tsx @@ -1,6 +1,6 @@ import React from 'react' import * as ReactDOM from 'react-dom/client' -import { isMobile } from '@/sites/assets/util' +import { isMobile } from '../../assets/util' import '@/sites/assets/styles/reset.scss' import '@/sites/assets/styles/md-style.scss' import App from './App' diff --git a/src/sites/sites-react/doc/router.ts b/src/sites/sites-react/doc/router.ts new file mode 100644 index 0000000000..3f99c2a5b3 --- /dev/null +++ b/src/sites/sites-react/doc/router.ts @@ -0,0 +1,87 @@ +// const modulesPage = import.meta.globEager('/src/packages/**/doc.md', { +// as: 'raw', +// }) +const modulesPage = import.meta.glob('/src/packages/**/doc.md') +const routes: any[] = [] +const guideRoutes: any[] = [] +const guideEnRoutes: any[] = [] +const guideTaroRoutes: any[] = [] +const guideEnTaroRoutes: any[] = [] +for (const path in modulesPage) { + let name = (/packages\/(.*)\/doc\.md/.exec(path) as any[])[1] + routes.push({ + path: '/zh-CN/component/' + name, + component: modulesPage[path], + name, + }) +} + +// const modulesENPage = import.meta.glob('/src/packages/**/doc.en-US.md', { +// as: 'raw', +// eager: true, +// }) +const modulesENPage = import.meta.glob('/src/packages/**/doc.en-US.md') +// console.log('modulesENPage', modulesENPage) +for (const path in modulesENPage) { + let name = (/packages\/(.*)\/doc\.en-US\.md/.exec(path) as any[])[1] + routes.push({ + path: '/en-US/component/' + name, + component: modulesENPage[path], + name, + }) +} + +const modulesTaroPage = import.meta.glob('/src/packages/**/doc.taro.md') +// console.log('modulesTaroPage', modulesTaroPage) +for (const path in modulesTaroPage) { + let name = (/packages\/(.*)\/doc\.taro\.md/.exec(path) as any[])[1] + routes.push({ + path: '/en-US/component/' + name + '-taro', + component: modulesTaroPage[path], + name: name + '-taro', + }) + routes.push({ + path: '/zh-CN/component/' + name + '-taro', + component: modulesTaroPage[path], + name: name + '-taro', + }) +} + +const modulesDocs = import.meta.glob('/src/sites/sites-react/doc/docs/react/*.md'); +for (const path in modulesDocs) { + let name = (/docs\/react\/(.*).md/.exec(path) as any[])[1]; + guideRoutes.push({ + path: `/zh-CN/guide/${name}`, + component: modulesDocs[path], + name + }); +} + +const modulesEnDocs = import.meta.glob('/src/sites/sites-react/doc/docs/react/*.en-US.md'); +for (const path in modulesEnDocs) { + let name = (/docs\/react\/(.*).en-US.md/.exec(path) as any[])[1]; + guideEnRoutes.push({ + path: `/en-US/guide/${name}`, + component: modulesEnDocs[path], + name: `en-${name}` + }); +} +const modulesTaroDocs = import.meta.glob('/src/sites/doc/docs/taro/*.md'); +for (const path in modulesTaroDocs) { + let name = (/docs\/taro\/(.*).md/.exec(path) as any[])[1]; + guideTaroRoutes.push({ + path: `/zh-CN/guide/${name}-taro`, + component: modulesTaroDocs[path], + name + }); +} +const modulesEnTaroDocs = import.meta.glob('/src/sites/doc/docs/taro/*.en-US.md'); +for (const path in modulesEnTaroDocs) { + let name = (/docs\/taro\/(.*).en-US.md/.exec(path) as any[])[1]; + guideEnTaroRoutes.push({ + path: `/en-US/guide/${name}-taro`, + component: modulesEnTaroDocs[path], + name + }); +} +export {routes, guideRoutes, guideEnRoutes, guideTaroRoutes, guideEnTaroRoutes} diff --git a/src/sites/theme/components/header/header.scss b/src/sites/theme/components/header/header.scss index a090f32d67..b1ae250808 100644 --- a/src/sites/theme/components/header/header.scss +++ b/src/sites/theme/components/header/header.scss @@ -209,12 +209,12 @@ &-box { &.select-down { .header-select-hd { - background-image: url('../../assets/images/icon-select-white-down.png'); + background-image: url('../../../assets/images/icon-select-white-down.png'); } } &.select-up { .header-select-hd { - background-image: url('../../assets/images/icon-select-white-up.png'); + background-image: url('../../../assets/images/icon-select-white-up.png'); } } } @@ -367,12 +367,12 @@ &-box { &.select-down { .header-select-hd { - background-image: url('../../assets/images/icon-select-white-down.png'); + background-image: url('../../../assets/images/icon-select-white-down.png'); } } &.select-up { .header-select-hd { - background-image: url('../../assets/images/icon-select-white-up.png'); + background-image: url('../../../assets/images/icon-select-white-up.png'); } } } diff --git a/vite.config.demo.ts b/vite.config.demo.ts new file mode 100644 index 0000000000..f89b305d4d --- /dev/null +++ b/vite.config.demo.ts @@ -0,0 +1,126 @@ +/// +import { defineConfig, UserConfig } from 'vite' +import { resolve, join } from 'path' +// @ts-ignore +import atImport from 'postcss-import' +import autoprefixer from 'autoprefixer' +import config from './package.json' + +const projectID = process.env.VITE_APP_PROJECT_ID || '' + +let fileStr = `@import "@/styles/variables.scss";@import "@/sites/assets/styles/variables.scss";@import '@/styles/theme-default.scss';\n` +if (projectID) { + fileStr = `@import '@/styles/variables-${projectID}.scss';\n@import "@/sites/assets/styles/variables.scss";\n@import '@/styles/font-${projectID}/iconfont.css';\n@import '@/styles/theme-${projectID}.scss';\n` +} + +// https://vitejs.dev/config/ +export default defineConfig(async (): Promise => { + return { + mode: 'production', + base: `/h5/react/${projectID === 'jmapp' ? 'jdesign' : '3x'}`, + resolve: { + alias: [ + { + find: '@nutui/nutui-react/dist/es/lottie/animation/light/loading.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/light/loading.json' + ), + }, + { + find: '@nutui/nutui-react/dist/es/lottie/animation/light/global.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/light/global.json' + ), + }, + { + find: '@nutui/nutui-react/dist/es/lottie/animation/light/pulltorefresh.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/light/pulltorefresh.json' + ), + }, + { + find: '@nutui/nutui-react/dist/es/lottie/animation/dark/loading.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/dark/loading.json' + ), + }, + { + find: '@nutui/nutui-react/dist/es/lottie/animation/dark/global.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/dark/global.json' + ), + }, + { + find: '@nutui/nutui-react/dist/es/lottie/animation/dark/pulltorefresh.json', + replacement: resolve( + __dirname, + './src/packages/lottie/animation/dark/pulltorefresh.json' + ), + }, + { + find: '@nutui/nutui-react/dist/locale/en-US', + replacement: resolve(__dirname, './src/locales/en-US.ts'), + }, + { + find: '@nutui/nutui-react-taro/dist/locales/en-US', + replacement: resolve(__dirname, './src/locales/en-US.ts'), + }, + { find: '@', replacement: resolve(__dirname, './src') }, + { + find: '@nutui/nutui-react', + replacement: resolve(__dirname, './src/packages/nutui.react.ts'), + }, + { + find: '@nutui/nutui-react-taro', + replacement: resolve(__dirname, './src/packages/nutui.react.taro.ts'), + }, + ], + }, + css: { + preprocessorOptions: { + scss: { + // example : additionalData: `@import "./src/dclearesign/styles/variables";` + // dont need include file extend .scss + api: 'modern-compiler', + additionalData: fileStr, + // 这里查看可选值：https://github.com/sass/sass/blob/1c9ec00/js-api-doc/deprecations.d.ts#L180 + silenceDeprecations: ['import', 'global-builtin'], + }, + postcss: { + plugins: [ + atImport({ path: join(__dirname, 'src`') }), + autoprefixer({ + overrideBrowserslist: [ + '> 0.5%', + 'last 2 versions', + 'ie > 11', + 'iOS >= 10', + 'Android >= 5', + ], + }), + ], + }, + }, + }, + build: { + target: 'es2015', + outDir: `./dist-demo/${projectID === 'jmapp' ? 'jdesign' : '3x'}/`, + cssCodeSplit: true, + rollupOptions: { + input: { + mobile: resolve(__dirname, 'demo.html'), + }, + output: { + entryFileNames: `demo-${config.version}/[name].js`, + chunkFileNames: `demo-${config.version}/[name].js`, + assetFileNames: `demo-${config.version}/[name].[ext]`, + }, + }, + }, + } +}) diff --git a/vite.config.site.taro.ts b/vite.config.site.taro.ts new file mode 100644 index 0000000000..e69de29bb2 diff --git a/vite.config.site.ts b/vite.config.site.ts index f89b305d4d..887b76ee31 100644 --- a/vite.config.site.ts +++ b/vite.config.site.ts @@ -1,9 +1,10 @@ /// import { defineConfig, UserConfig } from 'vite' -import { resolve, join } from 'path' +import reactRefresh from '@vitejs/plugin-react' +import { join, resolve } from 'path' // @ts-ignore import atImport from 'postcss-import' -import autoprefixer from 'autoprefixer' +import { readFileSync } from 'node:fs' import config from './package.json' const projectID = process.env.VITE_APP_PROJECT_ID || '' @@ -12,12 +13,27 @@ let fileStr = `@import "@/styles/variables.scss";@import "@/sites/assets/styles/ if (projectID) { fileStr = `@import '@/styles/variables-${projectID}.scss';\n@import "@/sites/assets/styles/variables.scss";\n@import '@/styles/font-${projectID}/iconfont.css';\n@import '@/styles/theme-${projectID}.scss';\n` } +const refRandom = Math.random().toString(36).slice(-8) // https://vitejs.dev/config/ export default defineConfig(async (): Promise => { + const mdx = await import('@mdx-js/rollup') + const remarkGfm = await import('remark-gfm') + const remarkDirective = await import('remark-directive') return { - mode: 'production', - base: `/h5/react/${projectID === 'jmapp' ? 'jdesign' : '3x'}`, + base: '/h5/react/3x', + server: { + port: 2021, + host: '0.0.0.0', + open: '/h5/react/3x/index.react.html', + proxy: { + '/devServer': { + target: 'https://nutui.jd.com', + changeOrigin: true, + rewrite: (path) => path.replace(/^\/devServer/, ''), + }, + }, + }, resolve: { alias: [ { @@ -84,41 +100,69 @@ export default defineConfig(async (): Promise => { css: { preprocessorOptions: { scss: { - // example : additionalData: `@import "./src/dclearesign/styles/variables";` - // dont need include file extend .scss + // example : additionalData: `@import "./src/design/styles/variables";` api: 'modern-compiler', additionalData: fileStr, // 这里查看可选值：https://github.com/sass/sass/blob/1c9ec00/js-api-doc/deprecations.d.ts#L180 silenceDeprecations: ['import', 'global-builtin'], }, postcss: { - plugins: [ - atImport({ path: join(__dirname, 'src`') }), - autoprefixer({ - overrideBrowserslist: [ - '> 0.5%', - 'last 2 versions', - 'ie > 11', - 'iOS >= 10', - 'Android >= 5', - ], - }), - ], + plugins: [atImport({ path: join(__dirname, 'src`') })], }, }, }, + plugins: [ + { + enforce: 'pre', + ...mdx.default({ + providerImportSource: '@mdx-js/react', + mdExtensions: [], + mdxExtensions: ['.md'], + remarkPlugins: [remarkGfm.default, remarkDirective.default], + }), + }, + { + name: 'test', + apply: 'serve', + async load(id: string) { + if (id.endsWith('.scss')) { + // 移除 @import 语句 + const filePath = resolve(process.cwd(), id) + const scssCode = await readFileSync(filePath, 'utf-8') + const modifiedCode = scssCode.replace( + /@import\s+['"](\.{2}?\/)[^'".]+(.s?css)['"];/g, + '' + ) + return modifiedCode + } + }, + }, + + reactRefresh(), + ], + test: { + setupFiles: ['./vitest.setup.ts'], + globals: true, + environment: 'happy-dom', + coverage: { + all: false, + provider: 'v8', + }, + include: ['src/packages/**/*.(test|spec).(ts|tsx)'], + reporters: ['default', 'html'], + }, build: { - target: 'es2015', - outDir: `./dist-demo/${projectID === 'jmapp' ? 'jdesign' : '3x'}/`, + outDir: './dist-site/h5', + assetsDir: `${config.version}-${refRandom}`, cssCodeSplit: true, rollupOptions: { input: { - mobile: resolve(__dirname, 'demo.html'), + react: resolve(__dirname, 'index.html'), }, output: { - entryFileNames: `demo-${config.version}/[name].js`, - chunkFileNames: `demo-${config.version}/[name].js`, - assetFileNames: `demo-${config.version}/[name].[ext]`, + entryFileNames: `${config.version}-${refRandom}/[name].js`, + chunkFileNames: `${config.version}-${refRandom}/[name].js`, + assetFileNames: `${config.version}-${refRandom}/[name].[ext]`, }, }, },