視覺映射組件的controller屬性

visualMap[i]-continuous.controller   |   Object

visualMap 組件中，控制器的 inRange 和 outOfRange 設(shè)置。如果沒有這個 controller 設(shè)置，控制器會使用外層的 inRange 和 outOfRange 設(shè)置；如果有這個 controller 設(shè)置，則會采用這個設(shè)置。適用于一些控制器視覺效果需要特殊定制或調(diào)整的場景。

visualMap[i]-continuous.controller.inRange   |   Object

定義在選中范圍中的視覺元素。（用戶可以和 visualMap 組件交互，用鼠標(biāo)或觸摸選擇范圍）

可選的視覺元素有：

• symbol: 圖元的圖形類別。
• symbolSize: 圖元的大小。
• color: 圖元的顏色。
• colorAlpha: 圖元的顏色的透明度。
• opacity: 圖元以及其附屬物（如文字標(biāo)簽）的透明度。
• colorLightness: 顏色的明暗度，參見 HSL。
• colorSaturation: 顏色的飽和度，參見 HSL。
• colorHue: 顏色的色調(diào)，參見 HSL。

inRange 能定義目標(biāo)系列（參見 visualMap-continuous.seriesIndex）視覺形式，也同時定義了 visualMap-continuous 本身的視覺樣式。通俗來講就是，假如 visualMap-continuous控制的是散點(diǎn)圖，那么 inRange 同時定義了散點(diǎn)圖的 顏色、尺寸 等，也定義了 visualMap-continuous 本身的 顏色、尺寸 等。這二者能對應(yīng)上。

定義方式，例如：

visualMap: [
    {
        ...,
        inRange: {
            color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
            symbolSize: [30, 100]
        }
    }
]

如果想分別定義 visualMap-continuous 本身的視覺樣式和 目標(biāo)系列 的視覺樣式，則這樣定義：

visualMap: [
    {
        ...,
        // 表示 目標(biāo)系列 的視覺樣式。
        target: {
            inRange: {
                color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
                symbolSize: [60, 200]
            }
        },
        // 表示 visualMap-continuous 本身的視覺樣式。
        controller: {
            inRange: {
                symbolSize: [30, 100]
            }
        }
    }
]

或者這樣定義：

visualMap: [
    {
        ...,
        // 表示 目標(biāo)系列 的視覺樣式 和 visualMap-continuous 共有的視覺樣式。
        inRange: {
            color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
            symbolSize: [60, 200]
        },
        // 表示 visualMap-continuous 本身的視覺樣式，會覆蓋共有的視覺樣式。比如，symbolSize 覆蓋成為 [30, 100]，而 color 不變。
        controller: {
            inRange: {
                symbolSize: [30, 100]
            }
        }
    }
]

? 關(guān)于視覺通道 ?

• inRange 中，可以有任意幾個的『視覺通道』定義（如 color、symbolSize 等）。這些視覺通道，會被同時采用。
• 一般來說，建議使用 透明度（opacity） ，而非 顏色透明度（colorAlpha） （他們細(xì)微的差異在于，前者能也同時控制圖元中的附屬物（如 label）的透明度，而后者只能控制圖元本身顏色的透明度）。
• 視覺映射的方式：支持兩種方式：線性映射、查表映射。

? 視覺通道 -- 線性映射 ?

線性映射 表示 series.data 中的每一個值（dataValue）會經(jīng)過線性映射計(jì)算，從 [visualMap.min, visualMap.max] 映射到設(shè)定的 [visual value 1, visual value 2] 區(qū)間中的某一個視覺的值（下稱 visual value）。

例如，我們設(shè)置了 [visualMap.min, visualMap.max] 為 [0, 100]，并且我們有 series.data: [50, 10, 100]。我們想將其映射到范圍為 [0.4, 1] 的 opacity 上，從而達(dá)到用透明度表達(dá)數(shù)值大小的目的。那么 visualMap 組件會對 series.data 中的每一個 dataValue 做線性映射計(jì)算，得到一個 opacityValue。最終得到的 opacityValues 為 [0.7, 0.44, 1]。

visual 范圍也可以反向，例如上例，可以設(shè)定 opacity 范圍為 [1, 0.4]，則上例得到的 opacityValues 為 [0.7, 0.96, 0.4]。

注意，[visualMap.min, visualMap.max] 須手動設(shè)置，不設(shè)置則默認(rèn)取 [0, 100]，而非 series.data 中的 dataMin 和 dataMax。

如何設(shè)定為線性映射？以下情況時，會設(shè)定為 線性映射：

• 當(dāng) visualMap 為 visualMap-continuous 時，或者
• 當(dāng) visualMap 為 visualMap-piecewise 且 未設(shè)置 visualMap-piecewise.categories 時。

視覺通道的值（visual value）：

• 視覺通道的值一般都以 Array 形式表示，例如：color: ['#333', '#777']。
• 如果寫成 number 或 string，會轉(zhuǎn)成 Array。例如，寫成 opacity: 0.4 會轉(zhuǎn)成 opacity: [0.4, 0.4]，color: '#333' 會轉(zhuǎn)成 color: ['#333', '#333']。
• 對于 圖形大?。╯ymbolSize）、透明度（opacity）、顏色透明度（colorAlpha）、顏色明暗度（colorLightness）、顏色飽和度（colorSaturation）、色調(diào)（colorHue）：形如Array 的視覺范圍總是表示：[最小數(shù)據(jù)值對應(yīng)的視覺值, 最大數(shù)據(jù)值對應(yīng)的視覺值]。比如：colorLightness: [0.8, 0.2]，表示 series.data 中，和 visualMap.min 相等的值（如果有的話）映射到 顏色明暗 的 0.8，和 visualMap.max 相等的值（如果有的話）映射到 顏色明暗 的 0.2，中間其他數(shù)據(jù)值，按照線性計(jì)算出映射結(jié)果。
• 對于 顏色（color），使用數(shù)組表示例如：['#333', '#78ab23', 'blue']。意思就是以這三個點(diǎn)作為基準(zhǔn)，形成一種『漸變』的色帶，數(shù)據(jù)映射到這個色帶上。也就是說，與 visualMap.min 相等的值會映射到 '#333'，與 visualMap.max 相等的值會映射到 'blue'。對于 visualMap.min 和 visualMap.max 中間的其他點(diǎn)，以所給定的 '#333', '#78ab23', 'blue' 這三個顏色作為基準(zhǔn)點(diǎn)進(jìn)行分段線性插值，得到映射結(jié)果。
• 對于 圖形類別（symbol）：使用數(shù)據(jù)表示例如：['circle', 'rect', 'diamond']。與 visualMap.min 相等的值會映射到 'circle'，與 visualMap.max 相等的值會映射到 'diamond'。對于 中間的其他點(diǎn)，會根據(jù)他們和 visualMap.min 和 visualMap.max 的數(shù)值距離，映射到 'circle', 'rect', 'diamond' 中某個值上。

visual value 的取值范圍：

• 透明度（opacity）、顏色透明度（colorAlpha）、顏色明暗度（colorLightness）、顏色飽和度（colorSaturation），visual value取值范圍是 [0, 1]。
• 色調(diào)（colorHue）取值范圍是 [0, 360]。
• 顏色（color）：顏色可以使用 RGB 表示，比如 'rgb(128, 128, 128)'，如果想要加上 alpha 通道，可以使用 RGBA，比如 'rgba(128, 128, 128, 0.5)'，也可以使用十六進(jìn)制格式，比如 '#ccc'。
• 圖形類別（symbol）：

ECharts 提供的標(biāo)記類型包括 'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow'

也可以通過 'image://url' 設(shè)置為圖片，其中 url 為圖片的鏈接，或者 dataURI。

可以通過 'path://' 將圖標(biāo)設(shè)置為任意的矢量路徑。這種方式相比于使用圖片的方式，不用擔(dān)心因?yàn)榭s放而產(chǎn)生鋸齒或模糊，而且可以設(shè)置為任意顏色。路徑圖形會自適應(yīng)調(diào)整為合適的大小。路徑的格式參見 SVG PathData?？梢詮?Adobe Illustrator 等工具編輯導(dǎo)出。

? 視覺通道 -- 查表映射 ?

查表映射 表示 series.data 中的所有值（dataValue）是可枚舉的，會根據(jù)給定的映射表查表得到映射結(jié)果。

例如，在 visualMap-piecewise 中，我們設(shè)定了 visualMap-piecewise.categories 為 ['Demon Hunter', 'Blademaster', 'Death Knight', 'Warden', 'Paladin']。我們有 series.data: ['Demon Hunter', 'Death Knight', 'Warden', 'Paladin']。然后我們可以定立查表映射規(guī)則：color: {'Warden': 'red', 'Demon Hunter': 'black'}，于是 visualMap 組件會按照表來將 dataValue 映射到 color。

如何設(shè)定為查表映射？當(dāng) visualMap 為 visualMap-piecewise 且 設(shè)置了 visualMap-piecewise.categories 時，會進(jìn)行查表映射。

視覺通道的值（visual value）：一般使用 Object 或 Array 來表示，例如：

visualMap: {
    type: 'piecewise',
    // categories 定義了 visualMap-piecewise 組件顯示出來的項(xiàng)。
    categories: [
        'Demon Hunter', 'Blademaster', 'Death Knight', 'Warden', 'Paladin'
    ],
    inRange: {
        // visual value 可以配成 Object：
        color: {
            'Warden': 'red',
            'Demon Hunter': 'black',
            '': 'green' // 空字串，表示除了'Warden'、'Demon Hunter'外，都對應(yīng)到 'green'。
        }
        // visual value 也可以只配一個單值，表示所有都映射到一個值，如：
        color: 'green',
        // visual value 也可以配成數(shù)組，這個數(shù)組須和 categories 數(shù)組等長，
        // 每個數(shù)組項(xiàng)和 categories 數(shù)組項(xiàng)一一對應(yīng)：
        color: ['red', 'black', 'green', 'yellow', 'white']
    }
}

參見示例

? 修改視覺編碼 ?

如果在圖表被渲染后（即已經(jīng)使用 setOption 設(shè)置了初始 option 之后），想修改 visualMap 的各種 視覺編碼，按照慣例，再次使用 setOption 即可。例如：

chart.setOption({
    visualMap: {
        inRange: {color: ['red', 'blue']}
    }
});

但請注意：

• visualMap option 中的這幾個屬性，inRange, outOfRange, target, controller，在 setOption 時不支持 merge。否則會帶來過于復(fù)雜的 merge 邏輯。也就是說，setOption 時，一旦修改了以上幾個屬性中的一項(xiàng)，其他項(xiàng)也會被清空，而非保留當(dāng)前狀態(tài)。所以，設(shè)置 visual 值時，請一次性全部設(shè)置，而非只設(shè)置一部分。
• 不推薦使用 getOption -> 修改option -> setOption 的方式：

// 不推薦這樣做（盡管也能達(dá)到和上面的例子相同的結(jié)果）：
var option = chart.getOption(); // 獲取所有option。
option.visualMap.inRange.color = ['red', 'blue']; // 改動color（我想要改變 color）。

// 如下兩處也要進(jìn)行同步改動，否則可能達(dá)不到期望效果。
option.visualMap.target.inRange.color = ['red', 'blue'];
option.visualMap.controller.inRange.color = ['red', 'blue'];

chart.setOption(option); // option設(shè)置回 visualMap

注意，inRange 沒有指定，則會默認(rèn)會設(shè)置 color: ['#f6efa6', '#d88273', '#bf444c']，如果你不想要這個color，可以 inRange: {color: null} 來去除。

visualMap[i]-continuous.controller.outOfRange   |   Object

定義在選中范圍外的視覺元素。（用戶可以和 visualMap 組件交互，用鼠標(biāo)或觸摸選擇范圍）

可選的視覺元素有：

• symbol: 圖元的圖形類別。
• symbolSize: 圖元的大小。
• color: 圖元的顏色。
• colorAlpha: 圖元的顏色的透明度。
• opacity: 圖元以及其附屬物（如文字標(biāo)簽）的透明度。
• colorLightness: 顏色的明暗度，參見 HSL。
• colorSaturation: 顏色的飽和度，參見 HSL。
• colorHue: 顏色的色調(diào)，參見 HSL。

outOfRange 能定義目標(biāo)系列（參見 visualMap-continuous.seriesIndex）視覺形式，也同時定義了 visualMap-continuous 本身的視覺樣式。通俗來講就是，假如 visualMap-continuous控制的是散點(diǎn)圖，那么 outOfRange 同時定義了散點(diǎn)圖的 顏色、尺寸 等，也定義了 visualMap-continuous 本身的 顏色、尺寸 等。這二者能對應(yīng)上。

定義方式，例如：

visualMap: [
    {
        ...,
        outOfRange: {
            color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
            symbolSize: [30, 100]
        }
    }
]

如果想分別定義 visualMap-continuous 本身的視覺樣式和 目標(biāo)系列 的視覺樣式，則這樣定義：

visualMap: [
    {
        ...,
        // 表示 目標(biāo)系列 的視覺樣式。
        target: {
            outOfRange: {
                color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
                symbolSize: [60, 200]
            }
        },
        // 表示 visualMap-continuous 本身的視覺樣式。
        controller: {
            outOfRange: {
                symbolSize: [30, 100]
            }
        }
    }
]

或者這樣定義：

visualMap: [
    {
        ...,
        // 表示 目標(biāo)系列 的視覺樣式 和 visualMap-continuous 共有的視覺樣式。
        outOfRange: {
            color: ['#121122', 'rgba(3,4,5,0.4)', 'red'],
            symbolSize: [60, 200]
        },
        // 表示 visualMap-continuous 本身的視覺樣式，會覆蓋共有的視覺樣式。比如，symbolSize 覆蓋成為 [30, 100]，而 color 不變。
        controller: {
            outOfRange: {
                symbolSize: [30, 100]
            }
        }
    }
]

? 關(guān)于視覺通道 ?

• outOfRange 中，可以有任意幾個的『視覺通道』定義（如 color、symbolSize 等）。這些視覺通道，會被同時采用。
• 一般來說，建議使用 透明度（opacity） ，而非 顏色透明度（colorAlpha） （他們細(xì)微的差異在于，前者能也同時控制圖元中的附屬物（如 label）的透明度，而后者只能控制圖元本身顏色的透明度）。
• 視覺映射的方式：支持兩種方式：線性映射、查表映射。

? 視覺通道 -- 線性映射 ?

線性映射 表示 series.data 中的每一個值（dataValue）會經(jīng)過線性映射計(jì)算，從 [visualMap.min, visualMap.max] 映射到設(shè)定的 [visual value 1, visual value 2] 區(qū)間中的某一個視覺的值（下稱 visual value）。

例如，我們設(shè)置了 [visualMap.min, visualMap.max] 為 [0, 100]，并且我們有 series.data: [50, 10, 100]。我們想將其映射到范圍為 [0.4, 1] 的 opacity 上，從而達(dá)到用透明度表達(dá)數(shù)值大小的目的。那么 visualMap 組件會對 series.data 中的每一個 dataValue 做線性映射計(jì)算，得到一個 opacityValue。最終得到的 opacityValues 為 [0.7, 0.44, 1]。

visual 范圍也可以反向，例如上例，可以設(shè)定 opacity 范圍為 [1, 0.4]，則上例得到的 opacityValues 為 [0.7, 0.96, 0.4]。

注意，[visualMap.min, visualMap.max] 須手動設(shè)置，不設(shè)置則默認(rèn)取 [0, 100]，而非 series.data 中的 dataMin 和 dataMax。

如何設(shè)定為線性映射？以下情況時，會設(shè)定為 線性映射：

• 當(dāng) visualMap 為 visualMap-continuous 時，或者
• 當(dāng) visualMap 為 visualMap-piecewise 且 未設(shè)置 visualMap-piecewise.categories 時。

視覺通道的值（visual value）：

• 視覺通道的值一般都以 Array 形式表示，例如：color: ['#333', '#777']。
• 如果寫成 number 或 string，會轉(zhuǎn)成 Array。例如，寫成 opacity: 0.4 會轉(zhuǎn)成 opacity: [0.4, 0.4]，color: '#333' 會轉(zhuǎn)成 color: ['#333', '#333']。
• 對于 圖形大小（symbolSize）、透明度（opacity）、顏色透明度（colorAlpha）、顏色明暗度（colorLightness）、顏色飽和度（colorSaturation）、色調(diào)（colorHue）：形如Array 的視覺范圍總是表示：[最小數(shù)據(jù)值對應(yīng)的視覺值, 最大數(shù)據(jù)值對應(yīng)的視覺值]。比如：colorLightness: [0.8, 0.2]，表示 series.data 中，和 visualMap.min 相等的值（如果有的話）映射到 顏色明暗 的 0.8，和 visualMap.max 相等的值（如果有的話）映射到 顏色明暗 的 0.2，中間其他數(shù)據(jù)值，按照線性計(jì)算出映射結(jié)果。
• 對于 顏色（color），使用數(shù)組表示例如：['#333', '#78ab23', 'blue']。意思就是以這三個點(diǎn)作為基準(zhǔn)，形成一種『漸變』的色帶，數(shù)據(jù)映射到這個色帶上。也就是說，與 visualMap.min 相等的值會映射到 '#333'，與 visualMap.max 相等的值會映射到 'blue'。對于 visualMap.min 和 visualMap.max 中間的其他點(diǎn)，以所給定的 '#333', '#78ab23', 'blue' 這三個顏色作為基準(zhǔn)點(diǎn)進(jìn)行分段線性插值，得到映射結(jié)果。
• 對于 圖形類別（symbol）：使用數(shù)據(jù)表示例如：['circle', 'rect', 'diamond']。與 visualMap.min 相等的值會映射到 'circle'，與 visualMap.max 相等的值會映射到 'diamond'。對于 中間的其他點(diǎn)，會根據(jù)他們和 visualMap.min 和 visualMap.max 的數(shù)值距離，映射到 'circle', 'rect', 'diamond' 中某個值上。

visual value 的取值范圍：

• 透明度（opacity）、顏色透明度（colorAlpha）、顏色明暗度（colorLightness）、顏色飽和度（colorSaturation），visual value取值范圍是 [0, 1]。
• 色調(diào)（colorHue）取值范圍是 [0, 360]。
• 顏色（color）：顏色可以使用 RGB 表示，比如 'rgb(128, 128, 128)'，如果想要加上 alpha 通道，可以使用 RGBA，比如 'rgba(128, 128, 128, 0.5)'，也可以使用十六進(jìn)制格式，比如 '#ccc'。
• 圖形類別（symbol）：

ECharts 提供的標(biāo)記類型包括 'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow'

也可以通過 'image://url' 設(shè)置為圖片，其中 url 為圖片的鏈接，或者 dataURI。

可以通過 'path://' 將圖標(biāo)設(shè)置為任意的矢量路徑。這種方式相比于使用圖片的方式，不用擔(dān)心因?yàn)榭s放而產(chǎn)生鋸齒或模糊，而且可以設(shè)置為任意顏色。路徑圖形會自適應(yīng)調(diào)整為合適的大小。路徑的格式參見 SVG PathData。可以從 Adobe Illustrator 等工具編輯導(dǎo)出。

? 視覺通道 -- 查表映射 ?

查表映射 表示 series.data 中的所有值（dataValue）是可枚舉的，會根據(jù)給定的映射表查表得到映射結(jié)果。

例如，在 visualMap-piecewise 中，我們設(shè)定了 visualMap-piecewise.categories 為 ['Demon Hunter', 'Blademaster', 'Death Knight', 'Warden', 'Paladin']。我們有 series.data: ['Demon Hunter', 'Death Knight', 'Warden', 'Paladin']。然后我們可以定立查表映射規(guī)則：color: {'Warden': 'red', 'Demon Hunter': 'black'}，于是 visualMap 組件會按照表來將 dataValue 映射到 color。

如何設(shè)定為查表映射？當(dāng) visualMap 為 visualMap-piecewise 且 設(shè)置了 visualMap-piecewise.categories 時，會進(jìn)行查表映射。

視覺通道的值（visual value）：一般使用 Object 或 Array 來表示，例如：

visualMap: {
    type: 'piecewise',
    // categories 定義了 visualMap-piecewise 組件顯示出來的項(xiàng)。
    categories: [
        'Demon Hunter', 'Blademaster', 'Death Knight', 'Warden', 'Paladin'
    ],
    outOfRange: {
        // visual value 可以配成 Object：
        color: {
            'Warden': 'red',
            'Demon Hunter': 'black',
            '': 'green' // 空字串，表示除了'Warden'、'Demon Hunter'外，都對應(yīng)到 'green'。
        }
        // visual value 也可以只配一個單值，表示所有都映射到一個值，如：
        color: 'green',
        // visual value 也可以配成數(shù)組，這個數(shù)組須和 categories 數(shù)組等長，
        // 每個數(shù)組項(xiàng)和 categories 數(shù)組項(xiàng)一一對應(yīng)：
        color: ['red', 'black', 'green', 'yellow', 'white']
    }
}

參見示例

? 修改視覺編碼 ?

如果在圖表被渲染后（即已經(jīng)使用 setOption 設(shè)置了初始 option 之后），想修改 visualMap 的各種 視覺編碼，按照慣例，再次使用 setOption 即可。例如：

chart.setOption({
    visualMap: {
        inRange: {color: ['red', 'blue']}
    }
});

但請注意：

• visualMap option 中的這幾個屬性，inRange, outOfRange, target, controller，在 setOption 時不支持 merge。否則會帶來過于復(fù)雜的 merge 邏輯。也就是說，setOption 時，一旦修改了以上幾個屬性中的一項(xiàng)，其他項(xiàng)也會被清空，而非保留當(dāng)前狀態(tài)。所以，設(shè)置 visual 值時，請一次性全部設(shè)置，而非只設(shè)置一部分。
• 不推薦使用 getOption -> 修改option -> setOption 的方式：

// 不推薦這樣做（盡管也能達(dá)到和上面的例子相同的結(jié)果）：
var option = chart.getOption(); // 獲取所有option。
option.visualMap.inRange.color = ['red', 'blue']; // 改動color（我想要改變 color）。

// 如下兩處也要進(jìn)行同步改動，否則可能達(dá)不到期望效果。
option.visualMap.target.inRange.color = ['red', 'blue'];
option.visualMap.controller.inRange.color = ['red', 'blue'];

chart.setOption(option); // option設(shè)置回 visualMap