feat(ava/ntv): add escape phrase (#644)

* feat(ava/ntv): add escape phrase * docs: remove NtvTypes
antvis · Apr 20, 2023 · d2664fb · d2664fb
1 parent c459c29
commit d2664fb
Show file tree

Hide file tree

Showing 11 changed files with 61 additions and 13 deletions.
diff --git a/packages/ava-react/src/NarrativeTextVis/phrases/Phrase.tsx b/packages/ava-react/src/NarrativeTextVis/phrases/Phrase.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { Tooltip, TooltipProps } from 'antd';
-import { isTextPhrase, isEntityPhrase } from '@antv/ava';
+import { isTextPhrase, isEntityPhrase, isEscapePhrase } from '@antv/ava';
 import { isFunction, kebabCase, isEmpty, isNil } from 'lodash';
 
 import { NTV_PREFIX_CLS } from '../constants';
@@ -144,6 +144,10 @@ export const Phrase: React.FC<PhraseProps> = ({
     return defaultText;
   }
 
+  // use pre to render escape character
+  // 使用 pre 标签渲染特殊转义字符
+  if (isEscapePhrase(phrase)) return <pre>{phrase.value}</pre>;
+
   const descriptor = pluginManager?.getPhraseDescriptorBySpec(phrase);
   if (descriptor) {
     return <>{renderPhraseByDescriptor({ spec: phrase, descriptor, themeStyles, events })}</>;

diff --git a/packages/ava/src/index.ts b/packages/ava/src/index.ts
@@ -140,6 +140,7 @@ export {
   isCustomPhrase,
   isTextPhrase,
   isEntityType,
+  isEscapePhrase,
   ENTITY_TYPES,
 } from './ntv';
 export type {
@@ -156,6 +157,7 @@ export type {
   PhraseSpec,
   TextPhraseSpec,
   EntityPhraseSpec,
+  EscapePhraseSpec,
   CustomPhraseSpec,
   ValueAssessment,
   EntityType,

diff --git a/packages/ava/src/ntv/schema/phrase.ts b/packages/ava/src/ntv/schema/phrase.ts
@@ -1,7 +1,7 @@
 import { CustomMetaData, CommonProps } from './common';
 
 // P used for custom phrase;
-export type PhraseSpec = TextPhraseSpec | EntityPhraseSpec | CustomPhraseSpec<CustomMetaData>;
+export type PhraseSpec = TextPhraseSpec | EntityPhraseSpec | EscapePhraseSpec | CustomPhraseSpec<CustomMetaData>;
 
 export type TextPhraseSpec = CommonProps & {
   type: 'text';
@@ -12,6 +12,14 @@ export type TextPhraseSpec = CommonProps & {
   url?: string;
 };
 
+/**
+ * escape character 支持转义字符
+ */
+export type EscapePhraseSpec = CommonProps & {
+  type: 'escape';
+  value: string;
+};
+
 export type EntityPhraseSpec = CommonProps & {
   type: 'entity';
   value?: string;
@@ -79,7 +87,7 @@ export const ENTITY_TYPES = [
   'proportion',
 ] as const;
 
-export type EntityType = typeof ENTITY_TYPES[number];
+export type EntityType = (typeof ENTITY_TYPES)[number];
 
 export type EntityMetaData = {
   /**

diff --git a/packages/ava/src/ntv/types.ts b/packages/ava/src/ntv/types.ts
@@ -1,5 +1,3 @@
-/* export all needed types of NtvTypes */
-
 export type {
   NarrativeTextSpec,
   HeadlineSpec,
@@ -14,6 +12,7 @@ export type {
   PhraseSpec,
   TextPhraseSpec,
   EntityPhraseSpec,
+  EscapePhraseSpec,
   CustomPhraseSpec,
   ValueAssessment,
   EntityType,

diff --git a/packages/ava/src/ntv/utils/isSpecType.ts b/packages/ava/src/ntv/utils/isSpecType.ts
@@ -13,6 +13,7 @@ import type {
   CustomPhraseSpec,
   EntityPhraseSpec,
   TextPhraseSpec,
+  EscapePhraseSpec,
 } from '../schema';
 
 export function isCustomSection(spec: SectionSpec): spec is CustomBlockElement {
@@ -66,3 +67,7 @@ export function isEntityPhrase(spec: PhraseSpec): spec is EntityPhraseSpec {
 export function isTextPhrase(spec: PhraseSpec): spec is TextPhraseSpec {
   return spec?.type === 'text';
 }
+
+export function isEscapePhrase(spec: PhraseSpec): spec is EscapePhraseSpec {
+  return spec?.type === 'escape';
+}
diff --git a/playground/src/DevPlayground/NTV/index.tsx b/playground/src/DevPlayground/NTV/index.tsx
@@ -337,6 +337,38 @@ const App = () => {
       <NarrativeTextVis spec={templateSpec} />
       <Divider />
       <NarrativeTextVis spec={fluctuationSpec} pluginManager={ntvPluginManager} />
+      <Divider>转义字符</Divider>
+      <NarrativeTextVis
+        spec={{
+          sections: [
+            {
+              paragraphs: [
+                {
+                  type: 'normal',
+                  phrases: [
+                    {
+                      type: 'text',
+                      value: '在 text 中的转义字符字符 \r\n 无效，后面是 escape 类型短语，换行：',
+                    },
+                    {
+                      type: 'escape',
+                      value: '\n',
+                    },
+                    {
+                      type: 'text',
+                      value: '回车',
+                    },
+                    {
+                      type: 'escape',
+                      value: '\r',
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        }}
+      />
     </>
   );
 };

diff --git a/site/docs/guide/intro.en.md b/site/docs/guide/intro.en.md
@@ -174,7 +174,7 @@ It can automatically generate and render the proper chart for visualization base
 
 ### \<NarrativeTextVis /\>
 
-The `ntv` module is used to display data insights in narrative text. Contains the `NtvTypes` related spec declaration in `@antv/ava` and a react component `NarrativeTextVis` in `@antv/ava-react`.
+The `ntv` module is used to display data insights in narrative text. Contains the ntv-schema types, such as `NarrativeTextSpec`, related spec declaration in `@antv/ava` and a react component `NarrativeTextVis` in `@antv/ava-react`.
 
 Basic usage:
 

diff --git a/site/docs/guide/intro.zh.md b/site/docs/guide/intro.zh.md
@@ -173,7 +173,7 @@ AutoChart 是一个可以根据数据自动推荐合适的图表并渲染的 Rea
 
 ### \<NarrativeTextVis /\>
 
-`ntv` 模块用来展示数据洞察解读文本。包含 `@antv/ava` 中的 `NtvTypes` 相关 spec 声明，以及 `@antv/ava-react` 中一个 react 组件 `NarrativeTextVis`。
+`ntv` 模块用来展示数据洞察解读文本。包含 `@antv/ava` 中的 ntv-schema types（比如 `NarrativeTextSpec`）相关 spec 声明，以及 `@antv/ava-react` 中一个 react 组件 `NarrativeTextVis`。
 
 基本用法举例：
 

diff --git a/site/docs/guide/ntv/intro.zh.md b/site/docs/guide/ntv/intro.zh.md
@@ -34,8 +34,7 @@ order: 0
 获取 TS 类型定义：
 
 ```ts
-import { NtvTypes } from '@antv/ava';
-// NarrativeTextSpec
+import { NarrativeTextSpec } from '@antv/ava';
 ```
 
 一个 ntv-schema json 数据示例：
@@ -75,7 +74,7 @@ import { NtvTypes } from '@antv/ava';
 ### 2. 使用 `<NarrativeTextVis />` 渲染
 
 ```tsx
-import { NarrativeTextVis, NtvTypes } from "@antv/ava-react";
+import { NarrativeTextVis, NarrativeTextSpec } from "@antv/ava-react";
 
 const textSpec: NarrativeTextSpec = {
   // ...

diff --git a/site/docs/guide/ntv/ntv-comp.zh.md b/site/docs/guide/ntv/ntv-comp.zh.md
@@ -13,7 +13,7 @@ order: 2
 
 
 ```tsx
-import { NarrativeTextVis, NtvTypes } from '@antv/ava-react';
+import { NarrativeTextVis, NarrativeTextSpec } from '@antv/ava-react';
 
 const textSpec: NarrativeTextSpec = {
   // ...

diff --git a/site/docs/guide/ntv/ntv-schema.zh.md b/site/docs/guide/ntv/ntv-schema.zh.md
@@ -9,8 +9,7 @@ ntv-schema 一套用于声明式描述解读文本结构的 json schema，是 NT
 
 1. 使用类型定义
 ```ts
-import { NtvTypes } from '@antv/ava';
-// NarrativeTextSpec
+import { NarrativeTextSpec } from '@antv/ava';
 ```
 2. 使用 json-schema