kepler.gl
v3.0.0
kepler.gl是一種基於數據的高性能Web應用程序，用於可視化大規模地理位置數據集。 kepler.gl建立在Maplibre GL和Deck.gl的頂部，可以使數百萬分，代表數千個旅行，並隨時執行空間聚集。
kepler.gl也是一種使用Redux來管理其狀態和數據流的反應組件。它可以嵌入其他React-Redux應用程序中，並且非常可定制。有關如何在應用中嵌入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中間件來管理其內部狀態，以處理副作用。
您也需要將react-palm的taskMiddleware添加到您的商店中。我們正在積極地研究不需要react-palm解決方案，但是它仍然是一種非常輕巧的副作用管理工具，比反應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 */
] )
)
) ;或使用增強劑：
// using enhancers
const initialState = { } ;
const middlewares = enhanceReduxMiddleware ( [
// Add other middlewares here
] ) ;
const enhancers = [ applyMiddleware ( ... middlewares ) ] ;
export default createStore ( reducer , initialState , compose ( ... enhancers ) ) ;如果將kepler.gl還原固定在另一個地址而不是keplerGl ，或者kepler.gl降低器未安裝在狀態的根部，則需要在使用getState Prop安裝組件時指定其路徑。
閱讀有關還原器的更多信息。
import KeplerGl from '@kepler.gl/components' ;
const Map = props => (
< KeplerGl id = "foo" width = { width } mapboxApiAccessToken = { token } height = { height } / >
) ; id （字符串，必需）map此Keplergl實例的ID。如果您的應用中有多個KeplerGL實例，則需要id 。它定義了存儲在keplergl還原器中的開plergl狀態的道具名稱。例如，具有ID foo的Keplergl組件的狀態存儲在state.keplerGl.foo中。
如果您使用相同的ID創建多個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您還原器中的根開蛋白酶狀態的路徑。
width （數字，可選）800開頭UI的寬度。
height （數字，可選）800 appName （字符串，可選）Kepler.Gl側面面板標題顯示的應用程序名稱
version （字符串，可選）v1.0版本顯示在側面板標題中
onSaveMap （功能，可選）undefined在單擊側面面板標題中單擊“保存地圖URL”時調用的操作。
onViewStateChange （功能，可選）undefinedviewState更新的視圖狀態對象，其中包含經度，緯度，縮放等參數MAP視口更新時觸發操作。
getMapboxRef(mapbox, index) （功能，可選）undefined當KeplerGL添加或刪除具有內部MAPBOX映射的MapContainer組件時，調用的函數。
mapbox參數是添加時添加時MapRef或刪除時為null 。
單個映射index參數為0，對於附加地圖，索引參數為1（因為KeplerGL支持可選的拆分映射視圖）。
actions （對象，可選）{}動作創建者替換默認kepler.gl動作創建者。僅在要修改操作有效載荷時才使用自定義操作。
mint （布爾，可選）true安裝組件時是否加載新鮮的空狀態。當解析mint: true kepler.gl組件將始終加載新的狀態時，重新安裝相同的組件時，該組件內部內部的狀態一旦其卸載後將被破壞。通過解析mint: false kepler.gl即使將組件狀態保存在商店中，即使它被卸載，並在重新重新安裝時將其用作初始狀態。在將Kepler.gl安裝在模態中時，這很有用，並在重新打開時保留相同的地圖。
閱讀有關組件的更多信息。
theme （對象|字符串，可選）null "dark" ， "light"或"base"之一，您可以傳遞用於自定義kepler.gl樣式的主題名稱或對象。 kepler.gl除了默認的“黑暗”主題外，還提供了一個'light'主題。當傳遞到主題對象時，kepler.gl將使用傳遞的值作為輸入來覆蓋主題的值。
閱讀有關自定義主題的更多信息
mapboxApiUrl （字符串，可選）https://api.mapbox.com如果您使用自己的Mapbox Tile Server，則可以傳遞自己的圖塊服務器API URL。
mapStylesReplaceDefault （布爾，可選）false kepler.gl提供4種地圖樣式可供選擇。如果您想提供自己的mapStyles請通過true 。見下文。
mapStyles （數組，可選）[]您可以提供以地圖樣式選擇面板顯示的其他地圖樣式。默認情況下，將添加其他地圖樣式中的默認地圖樣式。如果通過mapStylesReplaceDefault: true ，它們將替換默認情況。 kepler.gl將嘗試根據其id命名約定對您的樣式進行分組，並使用它允許基本映射層的可見性。提供自己的layerGroups以覆蓋默認值以進行更準確的圖層分組。
每個mapStyles都應具有以下屬性：
id （字符串，必需）獨特的字符串，不應是muted保留的dark light之一。 muted_nightlabel （字符串，必需）將顯示在地圖樣式選擇面板中url （字符串，必需）MAPBOX樣式URL或指向MAP樣式JSON對像用Mapbox GL樣式規範編寫的URL。icon （字符串，可選）樣式的圖像圖標，可以是URL或圖像數據URLlayerGroups （數組，可選） 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還原器的Intial UI狀態，值將與默認的INITIAL_UI_STATE合併。
localeMessages （對象，可選）undefined修改默認翻譯或添加新的翻譯閱讀有關本地化的更多信息。
keplerGl還原器進行定制操作。使用還原器比React組件狀態處理Keplergl狀態的優點是自定義其行為的靈活性。如果您的應用程序中只有一個KeplerGl實例，或者從不打算從組件本身外部派遣操作來開頭，則無需擔心轉發調度並可以繼續進行下一節。但是生活充滿了自定義，我們希望使您的生活盡可能愉快。
有多種方法可以將操作派遣到特定的KeplerGl實例。
每個操作都映射到kepler.gl中的簡化器更新程序。您可以導入與特定操作相對應的還原更新程序，並使用先前的狀態和有效載荷來調用它以獲取更新的狀態。例如， updateVisDataUpdater是ActionTypes.UPDATE_VIS_DATA的更新程序（請查看每個reducers/vis-state.js以進行更新映射的操作）。這是一個示例，您可以如何收聽應用程序Action 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 ;閱讀有關使用更新程序修改kepler.gl狀態的更多信息
connect您可以使用CONNECT將派遣功能添加到組件中，該功能將操作分配給特定的keplerGl組件。
// 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 Helper一起進行前進動作
// 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樣式。通過使用上述框架Kepler.gl提供了使用以下方法自定義其樣式/主題的能力：
本主題列出了要自定義的可用屬性。
自定義主題示例。
您可以通過將主題道具傳遞給kepler.gl react組件來自定義kepler.gl主題：
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 }
/ >
) ;如您所見，castheme對象定義了某些屬性，這些屬性將覆蓋kepler.gl默認樣式規則。
為了使用theaprovider自定義kepler.gl主題，您可以使用theprovider在以下內容中簡單地包裝kepler.gl。
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具有依賴項注入系統，可讓您注入組件來替換現有的注入系統。您需要做的就是為要替換的組件創建一個組件工廠，導入原始組件工廠，並在安裝KeplerGl的應用程序組件上調用injectComponents 。查看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 ) ;閱讀有關更換UI組件的更多信息
要與kepler.gl實例進行交互並向其添加新數據，您可以從應用程序中的任何地方派遣addDataToMap操作。它將數據集或多個數據集添加到kepler.gl實例，並更新完整的配置（MapState，MapStyle，visstate）。
data對象*必需
datasets （Array <Object> |對象） *所需的數據集可以是每個數據集對象需要具有info和data屬性的數據集或數據集數組。
datasets.info對象- 數據集的infodatasets.info.id字符串ID。如果定義了配置，則id應匹配config中的dataId 。datasets.info.label字符串此數據集的顯示名稱datasets.data對象*需要數據對象，以2個屬性fields和rows表格格式datasets.data.fields數組<Object> *必需的字段數組，datasets.data.fields.name string *所需字段的名稱，datasets.data.rows數組<Array> *所需的行，以表格格式，帶有fields和rows options對象
options.centerMap boolean default: true如果將centerMap設置為true Kepler.gl將將映射視圖放置在數據點邊界中options.readOnly boolean default: false如果將readOnly設置為true則左設置面板將被隱藏options.keepExistingConfig boolean default: false是否繼續退出地圖配置，包括層，過濾器和拆分映射。 config對象此對象將包含完整的kepler.gl實例配置{mapstate，mapstyle，visstate}
kepler.gl提供了一個簡單的API KeplerGlSchema.getConfigToSave以生成當前Kepler實例配置的JSON BLOB。
// 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的更多信息，並使用Schema Manager保存和加載地圖。
