kepler.gl
v3.0.0
Kepler.gl-это агроностическое, высокопроизводительное веб-приложение для визуального исследования крупномасштабных наборов данных геолокации. Построенный на вершине Maplibre GL и Deck.gl, Kepler.gl может привести миллионы точек, представляющих тысячи поездок, и выполнять пространственные агрегации на лету.
Kepler.gl также является компонентом React, который использует Redux для управления его состоянием и потоком данных. Он может быть встроен в другие приложения React-RETUX и очень настраивается. Для получения информации о том, как встроить kepler.gl в ваше приложение, взгляните на это пошаговое руководство по Vis.academy.
Используйте узел 18.18.2 или выше, старые версии узлов не были поддержаны/ проверены. Для достижения наилучших результатов используйте NVM nvm install .
Установить узел ( > 18.18.2 ), пряжа и зависимости проекта
npm install --save kepler.gl
// or
yarn add kepler.glKepler.gl построен на Mapbox. Вам понадобится токен доступа к Mapbox для его использования.
Если вы не используете модуль, все в порядке. Пакет Kepler.GL NPM включает в себя предварительно скомпилированные производственные сборки UMD в папке UMD. Вы можете добавить тег скрипта в свой HTML -файл, когда он следует:
< script src =" https://unpkg.com/kepler.gl/umd/keplergl.min.js " />или если хотите, вы можете загрузить конкретную версию
< script src =" https://unpkg.com/[email protected]/umd/keplergl.min.js " />Взгляните на руководство по разработке, чтобы разработать Kepler.gl локально.
Вот основные шаги по импорту kepler.gl в ваше приложение. Вы также посмотрите на папку «Примеры». Каждый пример в папке может быть установлен и работать локально.
Kepler.gl использует Redux для управления своим внутренним состоянием, а также промежуточное программное обеспечение React-Palm для обработки побочных эффектов.
Вам также нужно добавить taskMiddleware of react-palm в ваш магазин. Мы активно работаем над решением, где react-palm не потребуется, однако это все еще очень легкий инструмент управления побочными эффектами, который легче проверить, чем React-Thunk.
import { createStore , combineReducers , applyMiddleware , compose } from 'redux' ;
import keplerGlReducer from '@kepler.gl/reducers' ;
import { enhanceReduxMiddleware } from '@kepler.gl/middleware' ;
const initialState = { } ;
const reducers = combineReducers ( {
// <-- mount kepler.gl reducer in your app
keplerGl : keplerGlReducer ,
// Your other reducers here
app : appReducer
} ) ;
// using createStore
export default createStore (
reducer ,
initialState ,
applyMiddleware (
enhanceReduxMiddleware ( [
/* Add other middlewares here */
] )
)
) ;Или если использовать Enhancer:
// using enhancers
const initialState = { } ;
const middlewares = enhanceReduxMiddleware ( [
// Add other middlewares here
] ) ;
const enhancers = [ applyMiddleware ( ... middlewares ) ] ;
export default createStore ( reducer , initialState , compose ( ... enhancers ) ) ; Если вы установите REDUCER kepler.gl в другом адресе вместо keplerGl , или Reducer kepler.gl не устанавливается в корне вашего состояния, вам нужно будет указать путь к нему, когда вы установите компонент с помощью Prop getState .
Узнайте больше о редукторах.
import KeplerGl from '@kepler.gl/components' ;
const Map = props => (
< KeplerGl id = "foo" width = { width } mapboxApiAccessToken = { token } height = { height } / >
) ; id (строка, требуется)map Идентификатор этого экземпляра Keplergl. id требуется, если в вашем приложении есть несколько экземпляров Keplergl. Он определяет название предложения состояния Keplergl, которое хранится в редукторе Keplergl. Например, состояние компонента keplergl с id foo хранится в state.keplerGl.foo .
Если вы создаете несколько экземпляров Kepler.gl, используя один и тот же идентификатор, состояние kepler.gl, определенное в записи, будет переопределено последним экземпляром и сбросит в пустое состояние.
mapboxApiAccessToken (строка, требуется*)undefinedПо умолчанию Kepler.gl использует Mapbox-gl.js для отображения своих базовых карт. Вы можете создать бесплатную учетную запись на Mapbox и создать токен на www.mapbox.com/account/access-tokens.
Если вы заменили стили карты Kepler.gl по умолчанию своими собственными, и они не являются стилями Mapbox. mapboxApiAccessToken не потребуется.
Узнайте больше о пользовательских стилях карт.
getState (функция, необязательно)state => state.keplerGlПуть к корнему состоянию keplergl в вашем редукторе.
width (число, необязательно)800Ширина интерфейса keplergl.
height (число, необязательно)800 appName (String, необязательно)Kepler.GlИмя приложения отображается в заголовке боковой панели
version (строка, необязательно)v1.0Версия отображается в заголовке боковой панели
onSaveMap (функция, необязательно)undefinedДействие вызвано, когда нажимайте URL Save Map в заголовке боковой панели.
onViewStateChange (функция, необязательно)undefinedviewState - обновленный объект состояния представления, содержащий параметры, такие как долгота, широта, масштаб и т. Д.Действие вызвано при обновлении карты ViewPort.
getMapboxRef(mapbox, index) (функция, необязательно)undefined Функция вызвана, когда KeplerGL добавляет или удаляет компонент MapContainer имеющую внутреннюю карту карт.
Аргумент mapbox является MapRef при добавлении или null при удалении.
Аргумент index равен 0 для одной карты или 1 для дополнительной карты (поскольку KeplerGL поддерживает необязательное представление карты разделения).
actions (объект, необязательно){}Создатели действий для замены по умолчанию Kepler.gl Action Creator. Используйте пользовательские действия только тогда, когда вы хотите изменить полезную нагрузку действий.
mint (логический, необязательный)true Загрузить новое пустое состояние при установке компонента. Когда Parse mint: true Kepler.gl Component всегда будет загружать свежее состояние при повторном сетке одного и того же компонента, состояние внутри этого компонента будет уничтожено после его нерешенного. Благодаря анализу mint: false Kepler.gl будет хранить состояние компонента в магазине, даже если оно не будет установлено, и использовать его в качестве начального состояния при повторной монтаже. Это полезно при установлении Kepler.gl в модале и сохраняет ту же карту при повторном открытии.
Узнайте больше о компонентах.
theme (объект | строка, необязательно)null Один из "dark" , "light" или "base" вы можете передать имя темы или объект, используемый для настройки стиля Kepler.gl. Kepler.gl предоставляет 'light' тему, помимо темы «Dark» по умолчанию. При передаче объекта темы kepler.gl будет использовать значение, передаваемое вводом для переопределения значений из темы.
Узнайте больше о пользовательской теме
mapboxApiUrl (String, необязательно)https://api.mapbox.comЕсли вы используете свой собственный сервер Tile Mapbox, вы можете передать URL -адрес API собственного сервера Tile.
mapStylesReplaceDefault (логический, необязательный)false Kepler.gl предоставляет 4 стиля карты на выбор. Пропустите true если вы хотите предоставить свои собственные mapStyles . См. ниже.
mapStyles (массив, необязательно)[] Вы можете предоставить дополнительные стили карты, которые будут отображаться на панели выбора стиля карты. По умолчанию дополнительные стили карты будут добавлены в стили карты по умолчанию. Если Pass mapStylesReplaceDefault: true , они заменит по умолчанию. Kepler.gl попытается группировать слои вашего стиля в зависимости от соглашения о именовании id и использовать его, чтобы обеспечить видимость переключения уровня базовых карт. Предоставьте свои собственные layerGroups , чтобы переопределить по умолчанию для более точной группировки слоев.
Каждый mapStyles должен обладать следующими свойствами:
id (строка, требуемая) уникальная строка, которая не должна быть одной из этих зарезервированных dark light muted . muted_nightlabel (строка, требуется) имя для отображения на панели выбора стиля картыurl (строка, требуется) URL -адрес стиля Mapbox или URL -адрес, указывающий на объект стиля карты JSON, написанный в спецификации стиля Mapbox GL.icon (строка, необязательно) изображения стиля, он может быть URL или URL данных изображенияlayerGroups (массив, необязательно) const mapStyles = [
{
id : 'my_dark_map' ,
label : 'Dark Streets 9' ,
url : 'mapbox://styles/mapbox/dark-v9' ,
icon : ` ${ apiHost } /styles/v1/mapbox/dark-v9/static/-122.3391,37.7922,9.19,0,0/400x300?access_token= ${ accessToken } &logo=false&attribution=false` ,
layerGroups : [
{
slug : 'label' ,
filter : ( { id } ) => id . match ( / (?=(label|place-|poi-)) / ) ,
defaultVisibility : true
} ,
{
// adding this will keep the 3d building option
slug : '3d building' ,
filter : ( ) => false ,
defaultVisibility : false
}
]
}
] ;Узнайте больше о пользовательских стилях карт.
initialUiState (объект, необязательно)undefined Интенсивное состояние пользовательского интерфейса, применяемое к uistate Reducer, значение будет неглубоким объединенным с помощью default INITIAL_UI_STATE
localeMessages (объект, необязательно)undefined изменение перевода по умолчанию или добавить новый переводУзнайте больше о локализации.
keplerGl Reducer. Одним из преимуществ использования состояния Reducer Over React Component для обработки состояния Keplergl является гибкость для настройки его поведения. Если в вашем приложении есть только один экземпляр KeplerGl или никогда не собираетесь отправлять действия, чтобы Keplergl извне самого компонента, вам не нужно беспокоиться о пересылке отправки и может перейти к следующему разделу. Но жизнь полна настройки, и мы хотим сделать вашу как можно более приятным.
Существует несколько способов отправки действий в конкретный экземпляр KeplerGl .
Каждое действие отображается с Reducer Updater в Kepler.gl. Вы можете импортировать обновляющий обновления Reducer, соответствующий конкретному действию, и позвонить в предыдущее состояние и полезную нагрузку с действием, чтобы получить обновленное состояние. Например, updateVisDataUpdater является обновлением для ActionTypes.UPDATE_VIS_DATA (взгляните на каждого редуктора reducers/vis-state.js для действия для картирования обновления). Вот пример того, как вы можете прослушать действие приложения QUERY_SUCCESS и вызовать updateVisDataUpdater чтобы загрузить данные в kepler.gl.
import { keplerGlReducer , visStateUpdaters } from '@kepler.gl/reducers' ;
// Root Reducer
const reducers = combineReducers ( {
keplerGl : keplerGlReducer ,
app : appReducer
} ) ;
const composedReducer = ( state , action ) => {
switch ( action . type ) {
case 'QUERY_SUCCESS' :
return {
... state ,
keplerGl : {
... state . keplerGl ,
// 'map' is the id of the keplerGl instance
map : {
... state . keplerGl . map ,
visState : visStateUpdaters . updateVisDataUpdater ( state . keplerGl . map . visState , {
datasets : action . payload
} )
}
}
} ;
}
return reducers ( state , action ) ;
} ;
export default composedReducer ;Узнайте больше об использовании Updaters для изменения состояния kepler.gl
connect Вы можете добавить функцию отправки в свой компонент, которая отправляет действия в определенный компонент keplerGl , используя Connect.
// component
import KeplerGl from '@kepler.gl/components' ;
// action and forward dispatcher
import { toggleFullScreen , forwardTo } from '@kepler.gl/actions' ;
import { connect } from 'react-redux' ;
const MapContainer = props => (
< div >
< button onClick = { ( ) => props . keplerGlDispatch ( toggleFullScreen ( ) ) } / >
< KeplerGl
id = "foo"
/ >
< / div >
)
const mapStateToProps = state => state
const mapDispatchToProps = ( dispatch , props ) => ( {
dispatch ,
keplerGlDispatch : forwardTo ( ‘foo’ , dispatch )
} ) ;
export default connect (
mapStateToProps ,
mapDispatchToProps
) ( MapContainer ) ; Вы также можете просто обернуть действие в прямое действие с помощью wrapTo помощника
// component
import KeplerGl from '@kepler.gl/components' ;
// action and forward dispatcher
import { toggleFullScreen , wrapTo } from '@kepler.gl/actions' ;
// create a function to wrapper action payload to 'foo'
const wrapToMap = wrapTo ( 'foo' ) ;
const MapContainer = ( { dispatch } ) => (
< div >
< button onClick = { ( ) => dispatch ( wrapToMap ( toggleFullScreen ( ) ) } / >
< KeplerGl
id = "foo"
/ >
< / div >
) ;Узнайте больше о направленных действиях
Kepler.GL реализует стиль CSS с использованием стиля-компонентов. Используя указанный Framework Kepler.gl, предлагает возможность настроить свой стиль/тему, используя следующие подходы:
Доступные свойства для настройки перечислены здесь тема.
Пример индивидуальной темы.
Вы можете настроить тему kepler.gl, передавая тему реквизита в Cepler.gl React Component, когда она следует:
const white = '#ffffff' ;
const customTheme = {
sidePanelBg : white ,
titleTextColor : '#000000' ,
sidePanelHeaderBg : '#f7f7F7' ,
subtextColorActive : '#2473bd'
} ;
return (
< KeplerGl
mapboxApiAccessToken = { MAPBOX_TOKEN }
id = "map"
width = { 800 }
height = { 800 }
theme = { customTheme }
/ >
) ;Как видите, объект Customtheme определяет определенные свойства, которые будут переопределять правила стиля Kepler.gl по умолчанию.
Чтобы настроить тему kepler.gl, используя Themeprovider, вы можете просто обернуть kepler.gl, используя Themeprovider, когда она следует:
import { ThemeProvider } from 'styled-components' ;
const white = '#ffffff' ;
const customTheme = {
sidePanelBg : white ,
titleTextColor : '#000000' ,
sidePanelHeaderBg : '#f7f7F7' ,
subtextColorActive : '#2473bd'
} ;
return (
< ThemeProvider theme = { customTheme } >
< KeplerGl mapboxApiAccessToken = { MAPBOX_TOKEN } id = "map" width = { 800 } height = { 800 } / >
< / ThemeProvider >
) ; Каждый хочет гибкости, чтобы отобразить пользовательские компоненты Kepler.gl. Kepler.gl имеет систему впрыска зависимостей, которая позволяет вам вводить компоненты в замену существующих. Все, что вам нужно сделать, это создать фабрику компонентов для той, которую вы хотите заменить, импортировать исходную фабрику компонентов и вызовать injectComponents в корневом компоненте вашего приложения, где установлен KeplerGl . Взгляните на examples/demo-app/src/app.js и посмотрите, как это делает пользовательский заголовок боковой панели в Kepler.gl
import { injectComponents , PanelHeaderFactory } from '@kepler.gl/components' ;
// define custom header
const CustomHeader = ( ) => < div > My kepler.gl app < / div > ;
const myCustomHeaderFactory = ( ) => CustomHeader ;
// Inject custom header into Kepler.gl, replacing default
const KeplerGl = injectComponents ( [ [ PanelHeaderFactory , myCustomHeaderFactory ] ] ) ;
// render KeplerGl, it will render your custom header instead of the default
const MapContainer = ( ) => (
< div >
< KeplerGl id = "foo" / >
< / div >
) ; Использование withState помощника для добавления состояния редуктора и действий в настраиваемый компонент в качестве дополнительных реквизитов.
import { withState , injectComponents , PanelHeaderFactory } from '@kepler.gl/components' ;
import { visStateLens } from '@kepler.gl/reducers' ;
// custom action wrap to mounted instance
const addTodo = text =>
wrapTo ( 'map' , {
type : 'ADD_TODO' ,
text
} ) ;
// define custom header
const CustomHeader = ( { visState , addTodo } ) => (
< div onClick = { ( ) => addTodo ( 'hello' ) } > { ` ${
Object . keys ( visState . datasets ) . length
} dataset loaded` } < / div >
) ;
// now CustomHeader will receive `visState` and `addTodo` as additional props.
const myCustomHeaderFactory = ( ) =>
withState (
// keplerGl state lenses
[ visStateLens ] ,
// customMapStateToProps
headerStateToProps ,
// actions
{ addTodo }
) ( CustomHeader ) ;Узнайте больше о замене компонента пользовательского интерфейса
Чтобы взаимодействовать с экземпляром Kepler.gl и добавить к нему новые данные, вы можете отправить действие addDataToMap из любой точки вашего приложения. Он добавляет набор данных или несколько наборов данных в экземпляр Kepler.gl и обновляет полную конфигурацию (MapState, MapStyle, Visstate).
Объект data *Требуется
datasets (Array <Object> | Object) *Требуемые наборы данных могут быть набором данных или массивом наборов данных, которые каждый объект данных должен иметь info и свойство data .
datasets.info объект -Info набора данныхdatasets.info.id String ID этого набора данных. Если конфигурация определен, id должен соответствовать dataId в конфигурации.datasets.info.label String Отображаемое имя этого набора данныхdatasets.data объект *Требуется объект данных в табличном формате с 2 fields свойств и rowsdatasets.data.fields Array <object> *Требуемый массив полей,datasets.data.fields.name String *Требуемое имя поля,datasets.data.rows Array <Array> *Требуется массив строк, в табличном формате с fields и rows Объект options
options.centerMap Boolean default: true , если centerMap установлен на true Kepler.GL, разместит представление карты в границы точек данныхoptions.readOnly Boolean default: false If readOnly установлен на true левая панель настройки будет скрытаoptions.keepExistingConfig Boolean default: false чтобы продолжать выходить из конфигурации карты, включая слои, фильтры и расщепления. объект config Этот объект будет содержать полную конфигурацию экземпляра kpler.gl {mapstate, mapstyle, isststate}
Kepler.gl предоставляет простой API KeplerGlSchema.getConfigToSave для создания каждых действий JSON текущей конфигурации экземпляра Kepler.
// app.js
import { addDataToMap } from '@kepler.gl/actions' ;
const sampleTripData = {
fields : [
{ name : 'tpep_pickup_datetime' , format : 'YYYY-M-D H:m:s' , type : 'timestamp' } ,
{ name : 'pickup_longitude' , format : '' , type : 'real' } ,
{ name : 'pickup_latitude' , format : '' , type : 'real' }
] ,
rows : [
[ '2015-01-15 19:05:39 +00:00' , - 73.99389648 , 40.75011063 ] ,
[ '2015-01-15 19:05:39 +00:00' , - 73.97642517 , 40.73981094 ] ,
[ '2015-01-15 19:05:40 +00:00' , - 73.96870422 , 40.75424576 ]
]
} ;
const sampleConfig = {
visState : {
filters : [
{
id : 'me' ,
dataId : 'test_trip_data' ,
name : 'tpep_pickup_datetime' ,
type : 'timeRange' ,
view : 'enlarged'
}
]
}
} ;
this . props . dispatch (
addDataToMap ( {
datasets : {
info : {
label : 'Sample Taxi Trips in New York City' ,
id : 'test_trip_data'
} ,
data : sampleTripData
} ,
option : {
centerMap : true ,
readOnly : false
} ,
config : sampleConfig
} )
) ;Узнайте больше о AddDatatomap и сохранении и загрузке карт с помощью схемы Manager.
