Front-End/highcharts

[Highcharts] Labels and string formatting

SeanK 2022. 5. 13. 10:08

Labels and string formatting

Highcharts에서 텍스트가 사용되는 곳이면 어디든 formatters 혹은 format 옵션을 이용해 변형을 할 수 있다. 모든 format 스트링 옵션은 상응하는 formatter 콜백 함수가 있다. formattera 콜백은 더 유연한 반면, format 스트링은 보통 더 콤팩트하며, JSON과 호환 가능하다.

HTML IN HIGHCHARTS

Highcharts에서 텍스트와 레이블은 html로 주어진다. 하지만 html은 svg로 파싱 되고 렌더링 되기 때문에 오로지 subset만이 지원된다. 다음과 같은 태그들이 지원된다: <b>, <strong>, <i>, <em>, <br/>, <span>. Spans는 스타일 특성으로 꾸밀 수 있는데, 오로지 텍스트 관련  CSS인 svg만이 가능하다. 

Highcharts에서 텍스트를 다루는 곳 대부분에서 useHTML이라는 옵션이 따라다닌다. 이 옵션이 true이면, 차트 상단에 html로 텍스트가 놓이게 된다. 만약에 레이블에 이미지를 넣거나, 툴팁에 테이블 등을 추가하고 싶다면 이 기능은 유용한다. 하지만 아래의 경우에는 좋지 못하다:

  • 다른 svg 콘텐츠보다 최상단에 항상 위치한다. 특히 툴팁이 useHTML레이블보다 아래에 렌더링 될 수 있다. Highcharts v6.1.1 이후로는 tooltip.outside 옵션을 true로 설정해 문제를 해결할 수 있다. 
  • 실험단계인 exporting.allowHTML 옵션을 사용하지 않는 이상, export 된 차트에서는 똑같이 렌더링 되지 않는다. 

html를 사용하면 양방향 텍스트가 있는 일부 오래된 브라우저 문제를 해결할 수도 있다.

FILTERING

보안 문제로, Highcharts는 버전 9 이후부터 알 수 없는 태그나 특성은 필터링한다. 

만약 환경설정이 신뢰할 수 있는 소스에서 온다면 태그, 특성 혹은 참조 패턴을 allow lists에 추가할 수 있다.

Highcharts.AST.allowedTags.push('blink');
Highcharts.AST.allowedAttributes.push('data-value');
// Allow links to the `tel` protocol
Highcharts.AST.allowedReferences.push('tel:');

FORMAT STRINGS

Format stirng은 변수들이 추가되는 레이블 탬플릿이다. Format stirng은 Highcharts 2.3에서 소개되었고 3.0에서 숫자와 날자 형식도 지원하도록 개선되었다. Format stirng의 예로는 xAxis.labels.format, tooltip.pointFormat, 그리고 legend.labelFomat이 있다.

 

변수는 브래킷 노테이션에 삽입된다.

예: "The point value at {point.x} is {point.y}"

 

숫자는 c라이브러리 함수 sprintf의 부동 소수점 규칙의 집합으로 포맷된다. formatting은 변수 브래킷 안에 첨부되고 콜론으로 구분된다. 주의할 점은 온점과 콤마는 각각 소수점과 1000천을 의미하지만 이는 언어 세팅에 따라 실제로 달라져 렌더링 된다. 예를 들어:

  • 소수점 2자리: {point.y:.2f}
  • 1000 구분자, 소수점 없음: {point.y:,.0f}
  • 1000 구분자, 소수점 하나: {point.y:,.1f}

날자는 숫자와 마찬가지로 포맷이 콜론 뒤에 붙는다. 포멧 형식은 Highcharts.dateFormat()과 같다. 예를 들어:

  • Full date: {value:%Y-%m-%d}

FORMATTER CALLBACKS

레이블에 완전한 스트링 제어와 추가적인 스크립트를 위해서 formatter 콜백을 사용해야 할 수도 있다. 이 formatter는 HTML을 리턴한다. xAxis.labels.formatter, tooltip.formatter 그리고 legend.labelFormatter 등을 그 예로 들 수 있다. 때때로 Highcharts.dateFormat()과 Hightcharts.numberFormat()을 formatter로부터 불러와야 할 수도 있다. 

ADVANCED FORMAT STRINGS

6.0.6 이후로, accessibility 모듈은 배열과 복수 조건 등 더 많은 포맷 스트링을 지원한다. 적용 가능한 옵션은 lang.accessibility에서 찾을 수 있다. 아래와 같이 배을 인덱싱 할 수 있다:

Format: 'This is the first index: {myArray[0]}. The last: {myArray[-1]}.'
Context: { myArray: [0, 1, 2, 3, 4, 5] }
Result: 'This is the first index: 0. The last: 5.'

 또한 #each() 함수를 이용해 순환시킬 수도 있다. 이는 브래킷 표현식 콘텐츠의 각 엘리먼트를 반복하도록 한다. 예:

Format: 'List contains: {#each(myArray)cm }'
Context: { myArray: [0, 1, 2] }
Result: 'List contains: 0cm 1cm 2cm '

#each() 함수는 옵션으로 길이 파라미터를 가진다. 만약 양수라면, 해당 파라미터는 순환할 최대 엘리먼트 수를 특정하게 된다. 만약 음수라면, 전체 배열의 길이에서 해당 숫자만큼 뺀 값만큼 순환한다. 예:

Format: 'List contains: {#each(myArray, -1), }and {myArray[-1]}.'
Context: { myArray: [0, 1, 2, 3] }
Result: 'List contains: 0, 1, 2, and 3.'

콘텍스트 객체가 단수인지 복수인지에 의존하는 스트링의 경우 #plural() 함수를 이용해 스트링을 선택하라. 기본 아규먼트는 #plural(obj, plural, singular)이다. 예:

Format: 'Has {numPoints} {#plural(numPoints, points, point}.'
Context: { numPoints: 5 }
Result: 'Has 5 points.'

옵션으로 추가할 수 있는 파라미터로는 dual과 none이 있다:

#plural(obj, plural, singular, dual, none) 예:

Format: 'Has {#plural(numPoints, many points, one point, two points, none}.'
Context: { numPoints: 2 }
Result: 'Has two points.'

dual과 none 파라미터는 제공된다면 우선 적용된다.