ExtReact 7.5.0

显示私有类

顶部

Ext JS 客户指南

本指南记录了将 Ext JS 组件添加到 React 应用程序所需的步骤。

要求

Node 8.11+
npm 6+
React 16.5
Webpack 4+
Babel 7
Ext JS 6.6+
Java 8 *

* Java 要求仅适用于 Linux。如果未安装 Java，Java 会自动与 Windows 和 Mac OS 上的 ExtReact Webpack 插件捆绑在一起）

使用 Ext JS 组件创建新的 React 应用程序

如果您从头开始，我们建议克隆 ext-react monorepo 并复制其中一个样板以创建一个新的应用程序

例如，要使用现代样板

git clone https://github.com/sencha/ext-react.git
cp -r ext-react/packages/ext-react-modern-boilerplate /path/to/new/app

要使用经典样板，请将最后一行替换为

cp -r ext-react/packages/ext-react-classic-boilerplate /path/to/new/app

然后，按照样板的 README.md 中的说明设置和运行您的新应用程序。

将 Ext JS 添加到现有的 React 应用程序

如果您需要将 Ext JS 组件添加到现有的 React 应用程序，请按照以下步骤操作

添加 ext-react

Sencha 提供了一组软件包，可帮助将 Ext JS 集成到 React 中。通过从 npm 安装它们，将它们添加到您的 React 应用程序中

npm install --save @sencha/ext-react
npm install --save @sencha/ext @sencha/ext-modern @sencha/ext-modern-theme-material
npm install --save-dev @sencha/ext-react-webpack-plugin @sencha/ext-react-babel-plugin html-webpack-plugin

配置 Webpack

ExtReact 需要一个 webpack 插件来捆绑和优化您在应用程序中使用的 ExtReact 组件。按如下所示将其添加到您的 webpack 配置中

// import the plugins
const HtmlWebpackPlugin = require('html-webpack-plugin')
const ExtReactWebpackPlugin = require('@sencha/ext-react-webpack-plugin');
...

// then, in your webpack config options:
return {
  plugins: [
    new HtmlWebpackPlugin({
      template: 'index.html',
      hash: true
    }), 
    new ExtWebpackPlugin({
      framework: 'react',
      port: port,
      emit: true,
      browser: browserprofile,
      genProdData,
      watch: watchprofile,
      profile: buildprofile, 
      environment: buildenvironment, 
      verbose: buildverbose,
      theme: 'theme-material',
      packages: []
    }),
  ]
}

注意：如果您使用 html-webpack-plugin，请确保它在插件数组中位于 ExtReactWebpackPlugin 之前，以便 ext.js 和 ext.css 的标签包含在生成的 index.html 中。

如果使用 webpack-dev-server，请确保构建目录位于 contentBase 配置中。

contentBase: "./build"

如果 contentBase 设置为另一个目录，您可以将值更改为数组并添加“build”

contentBase: ["static", "./build"]

有关配置 ExtReactWebpackPlugin 的更多信息，请参阅使用 Webpack 构建。

您还可以使用 ExtReact Modern Boilerplate 中的 webpack 配置文件进行参考

配置 Babel

为了构建您的应用程序，@sencha/ext-react-babel-plugin 必须包含在您的 babel 配置中，并且必须关闭 ES6 模块转译。这是一个 .babelrc 示例

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "modules": false
      }
    ],
    "@babel/preset-react"
  ],
  "plugins": [
    "react-hot-loader/babel",
    "@sencha/ext-react-babel-plugin",
    "@babel/plugin-transform-runtime",
    "@babel/plugin-syntax-dynamic-import",
    "@babel/plugin-syntax-import-meta",
    "@babel/plugin-proposal-class-properties",
    "@babel/plugin-proposal-json-strings",
    [
      "@babel/plugin-proposal-decorators",
      {
        "legacy": true
      }
    ],
    "@babel/plugin-proposal-function-sent",
    "@babel/plugin-proposal-export-namespace-from",
    "@babel/plugin-proposal-numeric-separator",
    "@babel/plugin-proposal-throw-expressions"
  ],
  "ignore": [
    "build"
  ],
  "env": {
    "test": {
      "presets": [
        "@babel/preset-env",
        "@babel/preset-react"
      ],
      "plugins": [
        "@babel/plugin-syntax-dynamic-import",
        "@babel/plugin-syntax-import-meta",
        "@babel/plugin-proposal-class-properties",
        "@babel/plugin-proposal-json-strings",
        [
          "@babel/plugin-proposal-decorators",
          {
            "legacy": true
          }
        ],
        "@babel/plugin-proposal-function-sent",
        "@babel/plugin-proposal-export-namespace-from",
        "@babel/plugin-proposal-numeric-separator",
        "@babel/plugin-proposal-throw-expressions"
      ]
    }
  }
}

注意：在 babel 中禁用 ES6 模块转译不会阻止您使用 import 语句。它只是将这些语句的处理推迟到 Webpack，这启用了 tree-shaking，并将有助于减少应用程序捆绑包的大小。

更新 index.html

如果您使用 html-webpack-plugin，则 ExtReactWebpackPlugin 生成的 JavaScript 和 CSS 资源将在构建时自动添加到您的 index.html 文件中。如果不是，您需要手动添加它们

<!doctype html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <link href="ext-react/ext.css" rel="stylesheet">
    ...
</head>
<body>
    ...
    <script type="text/javascript" src="ext-react/ext.js"></script>
    ...
</body>

HTML Doctype

ExtReact 组件需要 HTML5 doctype 声明才能正确显示。请确保此声明存在于您的 HTML 文档的顶部

<!doctype html>

Viewport Meta Tag

ExtReact 需要 viewport meta 标签。这应添加到您的 index.html 中的 <head> 元素中。

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">

启动您的应用程序

@sencha/ext-react 软件包提供了一个 launch 函数，用于代替 ReactDOM.render()

`launch(React.Element/Function)`

要启动您的应用程序，请将以下内容添加到您的 index.js 文件（您的 webpack 入口点）：当与 React v16 及更高版本一起使用时，开发人员需要在使用 Ext JS 组件之前在根目录添加一个名为 ExtReact 的新组件。最好的方法是在应用程序的入口点或启动方法中添加它，然后 ExtJS 组件可以在整个应用程序中的任何位置使用。

import { launch } from '@sencha/ext-react';
import { ExtReact } from '@sencha/ext-react'

import App from './App';

launch(<ExtReact><App/><ExtReact>);

launch 函数将指定的组件渲染到文档正文中。它还接受一个回调函数，该函数返回要渲染的组件

launch(() => {
  // do some initialization before initial render
  // ...

  // return the component to be rendered
  return <App/>;
})

launch 函数有两个用途

它会延迟应用程序的初始渲染，直到 ExtReact 类系统完全初始化
它创建一个视口，这对于创建占据屏幕完整高度和宽度的组件是必需的。

使用 launch 时，您不需要在 index.html 文件中单独的目标 <div id="root"/>。如果您有一个，则应将其删除。上面的代码替换了启动 React 应用程序的典型代码，该代码通常类似于

import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App/>, document.getElementById('root'));

renderWhenReady(Component)

如果您不需要创建全屏组件（例如，如果您将 ExtReact 组件与其他布局系统一起使用），您可以将 renderWhenReady 高阶组件应用于包含 ExtReact 元素的顶层组件，省略 launch 函数，并像 React 的惯例一样渲染到目标元素。如果您要构建基于 ExtReact 的组件库，并且不希望要求使用您的库的应用程序调用 launch，则这尤其有用。

// App.js
import React, { Component } from 'react'
import { Panel } from '@sencha/ext-modern'
import { renderWhenReady } from '@sencha/ext-react'
import { ExtReact } from '@sencha/ext-react'


class App extends Component {
  render() {
    return (
      <ExtReact>
        <Panel title="ExtReact">Hello World!</Panel>
      </ExtReact>
    )
  }
}

export default renderWhenReady(App);

// index.js
import ReactDOM from 'react-dom'
import App from './App'
import { render } from '@sencha/ext-react'

render(<App/>, document.getElementById('root'))

React Hot Loader

这是一个示例，该示例使用 launch 函数的回调参数来启用 react-hot-loader。回调传递一个 DOM 元素，该元素可以在调用 ReactDOM.render 时用作目标。

import React from 'react'
import ReactDOM from 'react-dom'
import { AppContainer } from 'react-hot-loader'
import { launch } from '@sencha/ext-react';
import { ExtReact } from '@sencha/ext-react'
import App from './App'

let viewport;

const render = (Component, target) => {
    ReactDOM.render(
        <ExtReact>
            <AppContainer>
                <Component/>
            </AppContainer>
        </ExtReact>,
        target
    )
}

launch(target => render(App, viewport = target));

if (module.hot) {
    module.hot.accept('./App', () => render(App, viewport));
}

`fullscreen` 配置

大多数使用 ExtReact 的应用程序都是占据浏览器窗口完整高度和宽度的单页应用程序。为了实现这一点，您的应用程序中的根 ExtReact 组件应配置为将 fullscreen prop 设置为 true。例如

import { Container } from '@sencha/ext-modern';

export default function App() {
  return (
    <Container fullscreen>
      ...
    </Container>
  )
}

ESLint

如果您使用 ESLint，请添加 Ext 作为允许的全局变量

"globals": {
    "Ext": true
}

在 React 中使用 Ext JS 组件

导入组件

@sencha/ext-react 软件包使所有具有 xtype 的 Ext JS 类都可用作 React 组件。组件名称派生自 xtype 的大写驼峰形式。例如，Ext.grid.Grid 的 xtype 为 grid，可以按如下方式导入

import { Grid } from '@sencha/ext-modern';

如果使用经典工具包，请从 @encha/ext-classic 导入。

import { Grid } from '@encha/ext-classic';

xtype 中的破折号将转换为下划线。例如，可以使用以下方式导入 "d3-heatmap" xtype

import { D3_HeatMap } from '@encha/ext-D3';

配置组件

React props 将转换为 Ext JS configs。这是 Ext.grid.Grid 的典型用法

import React, { Component } from 'react';
import { Grid, Column } from '@encha/ext-modern';

export default class UsersGrid extends Component {

    store = Ext.create('Ext.data.Store', {
        fields: ['name', 'email'],
        data: [
            { name: 'Tim Smith', email: '[email protected]' },
            { name: 'Jill Lindsey', email: '[email protected]' }
        ]
    })

    render() {        
        return (
            <Grid title="Users" store={this.store}>
                <Column text="Name" dataIndex="name"/>
                <Column text="Email" dataIndex="email"/>
            </Grid>
        )
    }

}

在上面的示例中，我们使用 props 设置 Grid 的 title 和 store configs。我们使用 Column 子元素而不是使用 columns prop 来设置 columns config。两种形式都是可以接受的，但我们认为对于 React 开发人员来说，使用子元素更直观，因此这是您将在我们所有示例中看到的形式。ExtReact 自动知道将某些子元素（如 Column）映射到父组件上的 configs。另一个例子是 Menu

<Button text="Options">
    <Menu>
        <MenuItem text="Options 1"/>
        <MenuItem text="Options 2"/>
        <MenuItem text="Options 3"/>
    </Menu>
</Button>

也可以写成

<Button 
    text="Options"
    menu={[
        { text: 'Option 1' },
        { text: 'Option 2' },
        { text: 'Option 3' }
    ]}
/>

处理事件

任何以 "on" 开头后跟大写字母的 prop 都会自动转换为 Ext JS 事件监听器。由于 Ext JS 事件都是小写的，因此不会保留大小写。您可以随意使用驼峰式大小写，这在 React 中很常见。

import React, { Component } from 'react';
import { SliderField } from '@encha/ext-modern';

export default function MyComponent() {
    return (
        <SliderField
            minValue={0}
            maxValue={100}
            onChange={(slider, value) => console.log(`Value set to ${value}`)}
        />
    )
}

事件处理程序 props 也可以采用带有附加选项的对象

<Button 
    onPaint={{
        single: true, // handler will only be called once
        fn: () => {...}
    }}
/>

您也可以使用 listeners 对象，这在传统的 Ext JS 中很常见

import React, { Component } from 'react';
import { SliderField } from '@encha/ext-modern';

export default function MyComponent() {
    return (
        <SliderField
            minValue={0}
            maxValue={100}
            listeners={{
                change: (slider, value) => console.log(`Value set to ${value}`)
            }}
        />
    )
}

特殊 Props

`rel`

任何采用 Ext.Widget 子类的 prop 都可以替换为子元素。要使用子元素替换 prop，请将子元素的 rel prop 设置为要替换的 prop 的名称。例如，Button 上的 menu prop 可以替换为子 <Menu> 元素

<Button text="Theme">
    <Menu rel="menu">
        <MenuItem text="Triton"/>
        <MenuItem text="iOS"/>
        <MenuItem text="Material"/>
    </Menu>
</Button>

`defaults`

使用 defaults prop 将一组 props 应用于所有子项。例如，对容器中的所有项目使用 flex: 1

<Container layout="vbox" defaults={{ flex: 1 }}>
    <Container>Item</Container>
</Container>

`ref` Prop

Refs 指向 Ext JS 组件实例

import React, { Component } from 'react';
import { SliderField } from '@encha/ext-modern';

export default class MyComponent {
    render() {
        return (
            <SliderField
                ref={ slider => this.slider = slider }
                minValue={0}
                maxValue={100}
                onChange={() => this.onChange()}
            />         
        )
    }

    onChange() {
        console.log('Slider value', this.slider.cmp.getValue()); // this.slider is an Ext.field.Slider
    }
}

在 ExtReact 组件内部使用 HTML 元素和非 ExtReact 组件

当 HTML 元素出现在 ExtReact 组件中时，它们会被包装在 Ext.Component 实例中。这允许 ExtReact 布局正确放置非 ExtReact 组件。例如...

<Panel layout="hbox">
    <div>left</div>
    <div>right</div>
</Panel>

... 将导致两个并排的 div。创建的组件结构等效于

Ext.create({
    xtype: 'panel',
    layout: 'hbox'
    items: [{
        xtype: 'component',
        html: '<div>left</div>'
    }, {
        xtype: 'component',
        html: '<div>right</div>'
    }]
});

创建您自己的 Ext JS 组件

您可以使用 Ext.define 创建自己的 Ext JS 组件，就像在传统的 Ext JS 代码中一样。使用来自 @extjs/reactor 的 reactify 函数将您的 Ext JS 组件转换为 React 组件。例如

import { reactify } from '@sencha/ext-react';

const MyGrid = Ext.define('MyPackage.view.MyGrid', {
    extend: 'Ext.grid.Grid',
    ...
})

export default reactify(MyGrid);

目录

简介

术语、图标和标签

访问级别

成员类型

成员语法

成员标志

类图标

成员图标

导航和功能

类成员快速导航菜单

Getter 和 Setter 方法

历史记录栏

搜索和过滤器

API 文档类元数据

展开和折叠示例和类成员

桌面 -vs- 移动视图

查看类源代码

ExtReact 7.5.0

目录

Ext JS 客户指南

要求

使用 Ext JS 组件创建新的 React 应用程序

将 Ext JS 添加到现有的 React 应用程序

添加 ext-react

配置 Webpack

配置 Babel

更新 index.html

HTML Doctype

Viewport Meta Tag

启动您的应用程序

launch(React.Element/Function)

renderWhenReady(Component)

React Hot Loader

fullscreen 配置

ESLint

在 React 中使用 Ext JS 组件

导入组件

配置组件

处理事件

特殊 Props

rel

defaults

ref Prop

在 ExtReact 组件内部使用 HTML 元素和非 ExtReact 组件

创建您自己的 Ext JS 组件

ExtReact 7.5.0

`launch(React.Element/Function)`

`fullscreen` 配置

`rel`

`defaults`

`ref` Prop