Use Cases #

In graphic development, you may need to use JS to process the data passed from the backend. All functions can be called directly in the graphic’s JS code area.

Data Convention: All examples use the following standard 2D array, where the first row is the header and subsequent rows are data:

dataset = [['category', 'C1', 'C2'],
           ['R1',        12,   18],
           ['R2',        10,   17]]

Dataset Transformation #

ds_transform(dataset) #

Row-column transpose: Swaps rows and columns of a 2D array (matrix transpose). Commonly used for axis flipping.

result = ds_transform(dataset)
// [['category', 'R1', 'R2'], ['C1', 12, 10], ['C2', 18, 17]]

ds_createMap(dataset) #

Generate key → [] dictionary: Converts a 2D array to a dictionary with first column values as keys and remaining columns as arrays. Commonly used in ECharts to get series data by name.

result = ds_createMap(dataset)
// { "category": ["C1", "C2"], "R1": [12, 18], "R2": [10, 17] }
let r1Data = result['R1']  // [12, 18]

ds_createMap_all(dataset) #

Generate object array: Converts a 2D array to [{col1: val, col2: val, ...}, ...] format (skips header row). Commonly used for pie chart data, ECharts dataset source, and field-name-based access.

result = ds_createMap_all(dataset)
// [{"category":"R1","C1":12,"C2":18}, {"category":"R2","C1":10,"C2":17}]
let pieData = ds_createMap_all(dataset).map(item => ({name: item.category, value: item.C1}))

ds_mapToList(dataset) #

Object array to 2D array: Reverses ds_createMap_all — converts object array back to standard 2D format (header + data rows).

ds_pivot(dataset, indexs=null, column=null, value=null) #

Data pivot (rows to columns): Pivots detail data in “dimension + pivot column + value” format to a wide table. Defaults to last two columns as pivot and value.

dataset3 = [['City', 'Type', 'Count'], ['Changsha', 'A', 35], ['Shanghai', 'B', 19]]
result = ds_pivot(dataset3)
// [["City", "A", "B"], ["Changsha", 35, 0], ["Shanghai", 0, 19]]

ds_tree(dataset, label='label', children='children') #

Generate tree structure: Converts “parent, child” 2D array to nested tree structure for ECharts tree/treemap. Supports fatherName/childName fields to separate codes from display names.

dataset = [["father", "child"], ["Hunan", "Changsha"], ["Hunan", "Chenzhou"], ["Guangdong", "Guangzhou"]]
result = ds_tree(dataset)
// [{id:"Hunan", label:"Hunan", children:[{id:"Changsha",label:"Changsha"},{id:"Chenzhou",label:"Chenzhou"}]}, ...]

ds_distinct(a, b=[]) #

Array deduplication: Removes duplicates from one or two merged arrays.

ds_distinct(['A', 'B', 'A', 'C'])  // ['A', 'B', 'C']
ds_distinct(['A', 'B'], ['B', 'C', 'D'])  // ['A', 'B', 'C', 'D']

ds_filter(dataset, fun) #

Dataset filtering: Filters data rows using a function. Header row is always preserved. fun receives each row; true keeps, false removes.

result = ds_filter(dataset, item => item[0] === 'R1')
// [['category','C1','C2'], ['R1', 12, 18]]

ds_sort(dataset, index=0, asc=true) #

Dataset sorting: Sorts data rows by specified column index (header preserved). Supports ascending/descending and custom compare functions.

ds_sort(dataset, 1)         // Ascending by column 1
ds_sort(dataset, 1, false)  // Descending by column 1
ds_sort(dataset, (a, b) => b[2] - a[2])  // Custom compare

ds_remove_column(dataset, remove_list=[0]) #

Remove columns: Deletes specified column indices from a 2D array.

ds_split(data, sep=',', head_add=[]) #

Split first column: Splits the first column’s string by separator into multiple fields and merges into the dataset.

ds_sumColumn(dataset, column) #

Column sum: Sums all numeric values in the specified column (from row 1, skipping header).

ds_sumColumn(dataset, 1)  // 22 (12 + 10)

ds_percentAcc(dataset, row) #

Cumulative percentage row: Calculates cumulative percentage for the specified row and appends it to the dataset. Commonly used for Pareto charts.

Dataset Association #

ds_leftjoin(a, b, withhead=true, type=1) #

Left join: Left joins two datasets by their first column. All rows from a are preserved; unmatched columns in b are filled with 0.

dataset2 = [['category', 'C3'], ['R1', 38], ['R6', 13]]
result = ds_leftjoin(dataset, dataset2)
// [['category','C1','C2','C3'], ['R1',12,18,38], ['R2',10,17,0]]

ds_crossjoin(a, b, withhead=true) #

Cross join (inner join): Only preserves rows where first columns match (SQL INNER JOIN).

ds_fulljoin(a, b, withhead=true) #

Full outer join: Preserves all rows from both datasets, filling unmatched with 0 (SQL FULL OUTER JOIN).

ds_union(a, b, withhead=true) #

Vertical merge (UNION ALL): Concatenates two datasets vertically, using the first dataset’s header.

Dataset Refresh #

ds_param(name) #

Get parameter: Gets a value from the global parameter dictionary filter_param by name.

let city = ds_param('city')  // 'Changsha'

ds_setParam('name', value) #

Set global parameter: Writes a parameter to filter_param. When value is empty/null/undefined, the parameter is automatically deleted.

ds_setParam('city', 'Changsha')  // filter_param becomes {city: 'Changsha'}
ds_setParam('city', '')           // Removes the parameter

// Typical linkage scenario
myChart.on('click', function(params) {
    ds_setParam('city', params.name)
    ds_refresh(2)
})

ds_refresh(index, param=filter_param, r=null) #

Refresh graphic / get data: Triggers the specified graphic to re-request data and render.

ds_refresh(2)                              // Refresh with global params
ds_refresh(2, {city: 'Changsha'})          // Refresh with custom params
let data = ds_refresh(2, filter_param, 'list')  // Get data as 2D array
ds_refresh(2, filter_param, 0)              // Async refresh without waiting

ds_my(callback=null, force=false) #

Get current user info: Gets username, name, OA roles/position/department, and Django groups. Returns {username, name, roles:[], position, department, groups:[]}.

let my = ds_my()
if (my.roles.includes('admin')) { /* admin logic */ }
ds_setParam('dept', ds_my().department)

Data Processing #

ds_rowname(dataset, start_row=1, column=0) #

Get column data: Extracts all values from the specified column starting from a given row. Commonly used for dimension lists.

ds_rowname(dataset)  // ['R1', 'R2']

ds_getStatistic(dataset) #

Process metric data: Unifies multiple dataset dictionaries into [[metric names...], [metric values...]] format for indicator card components.

ds_toThousands(num) #

Number to thousands format: Converts a number to comma-separated thousands string.

ds_toThousands(1234567)  // '1,234,567'

ds_round(num, qty=2) #

Decimal formatting: Rounds a number to specified decimal places (default 2), returns string.

ds_round(3.14159)      // '3.14'
ds_round(3.14159, 4)   // '3.1416'

ds_generateLastDay(n=15, joinChat='-') #

Generate recent N days: Generates a date array for the last N days (with header row ['zymd']).

result = ds_generateLastDay(5)
// [['zymd'], ['2024-01-11'], ..., ['2024-01-15']]

ds_generateUUID() #

Generate UUID: Generates a random UUID v4 string.

base64.encode(str) / base64.decode(str) #

Base64 encode/decode: Global utility supporting UTF-8 characters including Chinese.

new Date().format('yyyy-MM-dd hh:mm:ss') #

Date formatting: Date prototype extension for formatted date strings.

new Date().format('yyyy-MM-dd')  // '2024-01-15'

Component Rendering #

ds_formatArray(dataset, formatStr) #

Format array to string: Replaces $fieldName placeholders in a format string with each row’s data, joining results with newlines.

ds_formatArray(dataset6, '$name scored $score, grade $grade')
// 'Alice scored 95, grade A\nBob scored 82, grade B'

ds_vue(eid, dataset, param=null, ds_list=null) #

Dynamic Vue component rendering: Asynchronously loads Vue + ElementUI and creates a Vue instance on the specified DOM element.

await ds_vue('#container_1', dataset)
let vm = await ds_vue('#container_1', dataset, {city: 'Changsha'}, [2, 3])

ds_chart(dataset, index=999, chartType=null) #

Dynamic chart rendering: Auto-detects and renders ECharts graphics (pie or bar/line), supports click-to-switch chart type. Also accepts ECharts option objects or HTML strings.

await ds_chart(dataset, 1)           // Auto-detect type
await ds_chart(dataset, 1, 'pie')    // Force pie chart
await ds_chart({xAxis:{...}, series:[...]}, 1)  // Pass ECharts option
await ds_chart('<div>No data</div>', 1)          // Render HTML

ds_loadcss(css, id=null) #

Dynamically load styles: Injects CSS into <head>. Supports built-in CSS names, full URLs, or CSS strings.

ds_loadcss('smt_swiper')  // Load /static/smartchart/opt/smt_swiper.css
ds_loadcss('.my-box { color: red; }', 'my-style')  // Inject CSS string

ds_loadjs(name, async=false, force=false) #

Dynamically load JS: Loads JavaScript scripts. Supports built-in JS names or full URLs. Already-loaded scripts are skipped (use force=true to reload).

ds_loadjs('smt_log')
await ds_loadjs('/static/echart/dist/echarts.min.js', true)

ds_loadjson(mapURL, mmap=null) #

Load JSON / Register map: Synchronously loads a JSON file and returns parsed object. When mmap is provided, also registers as ECharts map.

ds_loadjson('/static/echart/map/hunan.json', 'hunan')

ds_scroll(name, interval=1000, step=10) #

Container auto-scroll: Auto-scrolls container content downward, loops back to top at bottom.

ds_liMarquee(name, marconfig=null) #

Seamless list scrolling: Based on liMarquee plugin for seamless scrolling with rich configuration.

ds_swiper(name, swconfig={}) #

Carousel component: Based on Swiper plugin for content carousel.

startSelectAnimate(myChart, dataLen, interval=1000, showtip=1) #

Chart carousel highlight: Auto-highlights ECharts data items in sequence with tooltip. Commonly used for unattended large-screen displays.

clickaction(myChart) #

Click highlight lock: Binds click-to-highlight effect on ECharts graphics — clicked item stays highlighted, click again to cancel. Useful for drill-down linkage.

addWaterMarker(str) #

Page watermark: Generates diagonal text watermark on page background.

Map and 3D #

ds_loadBmap(ak=null) #

Load Baidu Map: Dynamically loads Baidu Map JS API. Auto-reads bmap_ak from backend config if no AK provided.

ds_load3d() #

Load Three.js 3D environment: Dynamically loads three.js, OrbitControls, and SmartChart 3D wrapper libraries.

get_geoscatterList(dataset, geoCoordMap) #

Generate map scatter data: Matches “name, value” dataset with coordinate dictionary to generate ECharts effectScatter data format.

let geoCoordMap = {'Changsha': [112.98, 28.19], 'Guangzhou': [113.26, 23.13]}
let scatterData = get_geoscatterList(dataset, geoCoordMap)
// [{name:'Changsha', value:[112.98, 28.19, 100]}, ...]

get_geoflyList(dataset, geoCoordMap) #

Generate map flyline data: Matches “origin, destination, value” dataset with coordinates to generate ECharts lines series data.

Excel Dataset #

ds_excel_refresh(dataset) #

Refresh complex reports: Batch writes data to LuckySheet spreadsheet. Use #dfN.fieldName placeholders in cells to specify fill locations. Dataset format: {df0: 2D array, df1: 2D array, ...}.

ds_excel_value(fillCells, clear=false) #

Get cell values: Batch reads cell values from LuckySheet by coordinates (e.g., 'A1'). Commonly used in data entry scenarios.

let [name, amount, date] = ds_excel_value(['B2', 'C2', 'D2'])
ds_save(1, [[name, amount, date]])

Data Upload/Download #

ds_save(index, contents, update=0, id=null) #

Save/update data: Writes data to SmartChart dataset storage. update=0 for insert, update=1 for update (matched by first column primary key).

ds_save(1, [['name', 'sales'], ['Changsha', 100]])      // Insert
ds_save(1, [['name', 'sales'], ['Changsha', 150]], 1)  // Update

ds_download(filename, dataset, xls=0) #

Download data: Downloads dataset as CSV (default) or Excel (.xlsx when xls=1).

ds_download('sales_data', dataset)      // CSV
ds_download('sales_data', dataset, 1)   // Excel

ds_uploadfile(blob, filename, name=null, callback=null, ossConfig=null) #

Upload file: Uploads a Blob to the server, executes callback on success. Commonly used with file input elements.

document.getElementById('fileInput').addEventListener('change', function(e) {
    let file = e.target.files[0]
    ds_uploadfile(file, file.name, 'my_category', function(data) {
        console.log('Uploaded to:', data.url)
    })
})

Common JS Native Functions #

dataset.push(['R3', 5, 9])         // Append row
dataset.unshift(['header', 'C1'])  // Prepend row
dataset.slice(1)                   // Skip header
dataset.slice(-3)                  // Last 3 rows

// for loop (best performance, SmartChart recommended)
for (let i = 0; i < dataset.length; i++) { let row = dataset[i] }

// map (generate new array)
let values = dataset.slice(1).map(row => row[1])

// find (first matching element)
let row = dataset.slice(1).find(row => row[0] === 'R1')

// concat (merge arrays)
let merged = dataset.concat(other.slice(1))

Raw Data Format Reference #

Given SQL = SELECT dim1, dim2, metric FROM table, the standard 2D array format:

dataset = [['category', 'C1', 'C2'],  // Row 0: header (SQL field names)
           ['R1',        12,   18],    // Row 1+: data
           ['R2',        10,   17]]

• Row 0: Header, corresponds to SQL query field names
• Row 1+: Data rows; first column is typically a dimension (category), subsequent columns are metrics
• All transformation functions accept this format as input; output format is consistent (except for ds_createMap, ds_createMap_all, and other conversion functions)