= ({
33 | name,
34 | previewUrl,
35 | imageTagAttributes = {},
36 | images = [],
37 | content,
38 | children,
39 | }) => {
40 | const renderer = useContext(KrpanoRendererContext);
41 | const currentScene = useContext(CurrentSceneContext);
42 |
43 | React.useEffect(() => {
44 | const contentImageMeta: XMLMeta = {
45 | tag: 'image',
46 | attrs: imageTagAttributes,
47 | children: [],
48 | };
49 |
50 | // multires
51 | if (images.length > 1) {
52 | contentImageMeta.children!.push(
53 | ...(images as SceneImageWithMultires[]).map(
54 | ({ tiledImageWidth, tiledImageHeight, tileSize, asPreview = false, type, ...img }) => {
55 | const imgXML: XMLMeta = {
56 | tag: 'level',
57 | // FIXME: tiledImageWidth等值使用者不一定会提供，需要进行检查、提示以及fallback
58 | attrs: {
59 | tiledImageWidth,
60 | tiledImageHeight,
61 | asPreview,
62 | },
63 | children: [
64 | {
65 | tag: type,
66 | attrs: { ...img },
67 | },
68 | ],
69 | };
70 |
71 | if (tileSize) {
72 | imgXML.attrs = Object.assign(imgXML.attrs, { tileSize });
73 | }
74 |
75 | return imgXML;
76 | }
77 | )
78 | );
79 | } else if (images.length === 1) {
80 | const { type, ...img } = images[0] as SceneImage;
81 |
82 | // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
83 | contentImageMeta.children!.push({
84 | tag: type,
85 | attrs: { ...img },
86 | });
87 | }
88 |
89 | renderer?.setTag('scene', name, {
90 | content:
91 | content ||
92 | `${previewUrl ? `` : ''}${
93 | images.length > 0 ? buildXML(contentImageMeta) : ''
94 | }`,
95 | });
96 |
97 | return () => {
98 | renderer?.removeScene(name);
99 | };
100 | }, [renderer, name, images, imageTagAttributes, content, previewUrl]);
101 |
102 | React.useEffect(() => {
103 | if (currentScene === name) {
104 | renderer?.loadScene(name);
105 | Logger.log(`Scene ${name} loaded due to currentScene change.`);
106 | }
107 | }, [name, renderer, currentScene]);
108 |
109 | return {currentScene === name ? children : null}
;
110 | };
111 |
112 | export default Scene;
113 |
--------------------------------------------------------------------------------
/src/components/View.tsx:
--------------------------------------------------------------------------------
1 | import React, { useContext } from 'react';
2 | import { KrpanoRendererContext } from '../contexts/KrpanoRendererContext';
3 |
4 | /**
5 | * @see https://krpano.com/docu/xml/#view
6 | */
7 | export interface ViewProps {
8 | hlookat?: number;
9 | vlookat?: number;
10 | fov?: number;
11 | fovMin?: number;
12 | fovMax?: number;
13 | camRoll?: number;
14 | /**
15 | * @see https://krpano.com/docu/xml/#view.fovtype
16 | */
17 | fovType?: 'VFOV' | 'HFOV' | 'DFOV' | 'MFOV' | 'SFOV';
18 | maxPixelZoom?: number;
19 | mFovRatio?: number;
20 | distortion?: number;
21 | distortionFovLink?: number;
22 | stereographic?: boolean;
23 | pannini?: number;
24 | architectural?: number;
25 | architecturalOnlyMiddle?: boolean;
26 | /**
27 | * @see https://krpano.com/docu/xml/#view.limitview
28 | */
29 | limitView?: 'off' | 'auto' | 'lookat' | 'range' | 'fullrange' | 'offrange';
30 | hlookatMin?: number;
31 | hlookatMax?: number;
32 | vlookatMin?: number;
33 | vlookatMax?: number;
34 | rx?: number;
35 | ry?: number;
36 | tx?: number;
37 | ty?: number;
38 | tz?: number;
39 | ox?: number;
40 | oy?: number;
41 | oz?: number;
42 | children?: null;
43 | }
44 |
45 | export const View: React.FC = ({ children, ...viewAttrs }) => {
46 | const renderer = useContext(KrpanoRendererContext);
47 |
48 | React.useEffect(() => {
49 | renderer?.setTag('view', null, { ...viewAttrs });
50 | }, [renderer, viewAttrs]);
51 |
52 | return {children}
;
53 | };
54 |
55 | export default View;
56 |
--------------------------------------------------------------------------------
/src/contexts/CurrentSceneContext.ts:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | export const CurrentSceneContext = React.createContext(null);
4 |
--------------------------------------------------------------------------------
/src/contexts/KrpanoRendererContext.ts:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import KrpanoActionProxy from '../KrpanoActionProxy';
3 |
4 | export const KrpanoRendererContext = React.createContext(null);
5 |
--------------------------------------------------------------------------------
/src/hooks/useEventCallback.ts:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | /**
4 | * This hook is design to cache component's callback from props, and avoid unnecessary re-render cause by arrow function.
5 | * This pattern might cause problems in the concurrent mode.
6 | *
7 | * [related section in react doc](https://reactjs.org/docs/hooks-faq.html#how-to-read-an-often-changing-value-from-usecallback)
8 | *
9 | * [related github ticket](https://github.com/facebook/react/issues/14099#issuecomment-440013892)
10 | *
11 | * @param callback callback to memorize
12 | * @returns mutable ref object
13 | */
14 | export default function useEventCallback(callback: T): React.MutableRefObject {
15 | const callbackRef = React.useRef(callback);
16 |
17 | React.useLayoutEffect(() => {
18 | callbackRef.current = callback;
19 | }, [callback]);
20 |
21 | return callbackRef;
22 | }
23 |
--------------------------------------------------------------------------------
/src/hooks/useKrpano.ts:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import { IKrpanoConfig } from '../types';
3 |
4 | export const useKrpano = (config: IKrpanoConfig): void => {
5 | React.useEffect(() => {
6 | const defaultConfig: Partial = {
7 | html5: 'prefer',
8 | xml: null,
9 | consolelog: process.env.NODE_ENV === 'development',
10 | };
11 | const embedpano = () => {
12 | if (typeof window.embedpano === 'function') window.embedpano(Object.assign({}, defaultConfig, config));
13 | };
14 |
15 | if (typeof window.embedpano === 'function') {
16 | embedpano();
17 | } else {
18 | // TODO: install krpano
19 | throw new Error('Krpano required');
20 | }
21 | }, [config]);
22 | };
23 |
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | export * from './components/Krpano';
2 | export * from './components/View';
3 | export * from './components/Scene';
4 | export * from './components/Hotspot';
5 | export * from './components/Events';
6 |
7 | export * from './KrpanoActionProxy';
8 | export * from './types';
9 | export * from './contexts/KrpanoRendererContext';
10 | export * from './hooks/useKrpano';
11 |
--------------------------------------------------------------------------------
/src/types.ts:
--------------------------------------------------------------------------------
1 | import KrpanoActionProxy from './KrpanoActionProxy';
2 |
3 | /**
4 | * @see https://krpano.com/docu/html/#wmode
5 | */
6 | export interface IKrpanoConfig {
7 | /**
8 | * 全景图xml路径。需要手动设置为null才不会加载。
9 | * @see https://krpano.com/docu/html/#xml
10 | */
11 | xml?: string | null;
12 | /** 挂载点id */
13 | target: string;
14 | swf?: string;
15 | id?: string;
16 | bgcolor?: string;
17 | /**
18 | * @see https://krpano.com/docu/html/#html5
19 | */
20 | html5?: string;
21 | flash?: string;
22 | wmode?: string;
23 | localfallback?: string;
24 | vars?: Record;
25 | initvars?: Record;
26 | consolelog?: boolean;
27 | basepath?: string;
28 | mwheel?: boolean;
29 | capturetouch?: boolean;
30 | focus?: boolean;
31 | webglsettings?: Record;
32 | webxr?: string;
33 | mobilescale?: number;
34 | touchdevicemousesupport?: boolean;
35 | fakedevice?: string;
36 | onready?: (renderer: NativeKrpanoRendererObject) => void;
37 | }
38 |
39 | export interface NativeKrpanoRendererObject {
40 | get(key: string): any;
41 | call(action: string): void;
42 | }
43 |
44 | export type EventCallback = (renderer: KrpanoActionProxy) => void;
45 |
46 | declare global {
47 | interface Window {
48 | embedpano?: (config: IKrpanoConfig) => void;
49 | }
50 | }
51 |
--------------------------------------------------------------------------------
/src/utils.test.ts:
--------------------------------------------------------------------------------
1 | import { buildKrpanoAction, buildKrpanoTagSetterActions, buildXML, mapObject, mapEventPropsToJSCall } from './utils';
2 |
3 | describe('buildKrpanoAction()', () => {
4 | test('call', () => {
5 | expect(buildKrpanoAction('set', 'view.fov', 120)).toMatchSnapshot();
6 |
7 | expect(buildKrpanoAction('addhotspot', 'hotspotName')).toMatchSnapshot();
8 |
9 | expect(buildKrpanoAction('loadscene', 'scene1', 'null', 'MERGE', 'BLEND(0.5)')).toMatchSnapshot();
10 | });
11 | });
12 |
13 | describe('buildKrpanoTagSetterActions()', () => {
14 | test('call without tag name', () => {
15 | expect(buildKrpanoTagSetterActions('view', { fov: 90 })).toMatchSnapshot();
16 | });
17 | test('call with tag name', () => {
18 | expect(
19 | buildKrpanoTagSetterActions('scene[scene1]', { autoload: false, content: '' })
20 | ).toMatchSnapshot();
21 |
22 | expect(
23 | buildKrpanoTagSetterActions('hotspot[hotspotName]', {
24 | ath: 10,
25 | atv: 20,
26 | c: undefined,
27 | })
28 | ).toMatchSnapshot();
29 | });
30 |
31 | test('assignstyle', () => {
32 | expect(
33 | buildKrpanoTagSetterActions('hotspot[hotspotName]', {
34 | ath: 10,
35 | atv: 20,
36 | style: 'hotspot_style1',
37 | })
38 | ).toMatchSnapshot();
39 | });
40 |
41 | test('escape string', () => {
42 | expect(
43 | buildKrpanoTagSetterActions('hotspot[hotspotName]', {
44 | needEscape: `It's normal string
`,
45 | content: `It's xml string, keep everything`,
46 | })
47 | ).toMatchSnapshot();
48 | });
49 | });
50 |
51 | describe('buildXML()', () => {
52 | test('empty attrs & children', () => {
53 | expect(
54 | buildXML({
55 | tag: 'tagName',
56 | attrs: {},
57 | })
58 | ).toMatchSnapshot();
59 | });
60 |
61 | test('empty children', () => {
62 | expect(
63 | buildXML({
64 | tag: 'tagName',
65 | attrs: {
66 | key1: 'val1',
67 | key2: 2,
68 | },
69 | })
70 | ).toMatchSnapshot();
71 | });
72 |
73 | test('children empty array', () => {
74 | expect(
75 | buildXML({
76 | tag: 'tagName',
77 | attrs: {
78 | key1: 'val1',
79 | key2: 2,
80 | },
81 | children: [],
82 | })
83 | ).toMatchSnapshot();
84 | });
85 |
86 | test('one childreny', () => {
87 | expect(
88 | buildXML({
89 | tag: 'tagName',
90 | attrs: {
91 | key1: 'val1',
92 | key2: 2,
93 | },
94 | children: [
95 | {
96 | tag: 'inner',
97 | attrs: {
98 | k: 'v',
99 | },
100 | },
101 | ],
102 | })
103 | ).toMatchSnapshot();
104 | });
105 | });
106 |
107 | describe('mapObject()', () => {
108 | test('call', () => {
109 | const obj = { a: 1, b: 2 };
110 |
111 | expect(mapObject(obj, (k, v) => ({ [k]: (v as number) + 1 }))).toEqual({
112 | a: 2,
113 | b: 3,
114 | });
115 | });
116 | });
117 |
118 | describe('mapEventPropsToJSCall()', () => {
119 | test('call', () => {
120 | const obj = { a: 1, b: 2, onClick: () => console.log(1) };
121 |
122 | expect(mapEventPropsToJSCall(obj, k => `js(${k}, selector)`)).toEqual({
123 | onClick: 'js(onClick, selector)',
124 | });
125 | });
126 | });
127 |
--------------------------------------------------------------------------------
/src/utils.ts:
--------------------------------------------------------------------------------
1 | import escapeHTML from 'escape-html';
2 |
3 | type FuncName = 'set' | 'loadxml' | 'loadscene' | 'addhotspot' | 'removehotspot' | 'nexttick';
4 |
5 | /**
6 | * 执行单个函数
7 | * @param func 函数名
8 | * @param params 参数列表
9 | */
10 | export const buildKrpanoAction = (func: FuncName, ...params: Array): string =>
11 | `${func}(${params.map(p => `${p}`).join(', ')});`;
12 |
13 | /**
14 | * 动态添加标签用
15 | * @see https://krpano.com/forum/wbb/index.php?page=Thread&threadID=15873
16 | */
17 | export const buildKrpanoTagSetterActions = (
18 | name: string,
19 | attrs: Record
20 | ): string =>
21 | Object.keys(attrs)
22 | .map(key => {
23 | const val = attrs[key];
24 | key = key.toLowerCase();
25 | if (val === undefined) {
26 | return '';
27 | }
28 | // 如果属性值中有双引号，需要改用单引号
29 | let quote = '"';
30 | if (val.toString().includes(quote)) {
31 | // eslint-disable-next-line quotes
32 | quote = "'";
33 | }
34 | if (key === 'style') {
35 | return `assignstyle(${name}, ${val});`;
36 | }
37 | if (typeof val === 'boolean' || typeof val === 'number') {
38 | return `set(${name}.${key}, ${val});`;
39 | }
40 | // content是XML文本，不能转义，因为不涉及用户输入也不需要
41 | return `set(${name}.${key}, ${quote}${key === 'content' ? val : escapeHTML(val.toString())}${quote});`;
42 | })
43 | .filter(str => !!str)
44 | .join('');
45 |
46 | export const Logger = {
47 | enabled: false,
48 | log: (...args: any[]): void => {
49 | /* istanbul ignore next */
50 | if (Logger.enabled && process.env.NODE_ENV === 'development') {
51 | console.log(...args);
52 | }
53 | },
54 | };
55 |
56 | export interface XMLMeta {
57 | tag: string;
58 | attrs: Record;
59 | children?: XMLMeta[];
60 | }
61 |
62 | /**
63 | * 根据元数据构建xml
64 | */
65 | export const buildXML = ({ tag, attrs, children }: XMLMeta): string => {
66 | const attributes = Object.keys(attrs)
67 | .map(key => `${key.toLowerCase()}="${attrs[key]}"`)
68 | .join(' ');
69 |
70 | if (children && children.length) {
71 | return `<${tag} ${attributes}>${children.map(child => buildXML(child)).join('')}`;
72 | }
73 | return `<${tag} ${attributes} />`;
74 | };
75 |
76 | /**
77 | * 对Object进行map操作
78 | */
79 | export const mapObject = (
80 | obj: Record,
81 | mapper: (key: string, value: unknown) => Record
82 | ): Record => {
83 | return Object.assign(
84 | {},
85 | ...Object.keys(obj).map(key => {
86 | const value = obj[key];
87 | return mapper(key, value);
88 | })
89 | );
90 | };
91 |
92 | /**
93 | * 主要用于绑定Krpano事件和js调用。提取某个对象中的onXXX属性并替换为对应的调用字符串，丢弃其他属性
94 | */
95 | export const mapEventPropsToJSCall = (
96 | obj: Record,
97 | getString: (key: string, value: unknown) => string
98 | ): Record =>
99 | mapObject(obj, (key, value) => {
100 | if (key.startsWith('on') && typeof value === 'function') {
101 | return { [key]: getString(key, value) };
102 | }
103 | return {};
104 | }) as Record;
105 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "module": "CommonJS",
4 | "target": "ESNext",
5 | "lib": ["dom", "esnext"],
6 | "moduleResolution": "node",
7 | "jsx": "react",
8 | "sourceMap": true,
9 | "esModuleInterop": true,
10 | "noImplicitReturns": true,
11 | "noImplicitThis": true,
12 | "noImplicitAny": true,
13 | "strictNullChecks": true,
14 | "suppressImplicitAnyIndexErrors": true,
15 | "noUnusedLocals": true,
16 | "noUnusedParameters": true,
17 | "allowSyntheticDefaultImports": true,
18 | "importHelpers": true,
19 | "noEmitHelpers": true,
20 | "noEmit": true,
21 | "experimentalDecorators": true,
22 | "skipLibCheck": true
23 | },
24 | "include": ["src"],
25 | "exclude": ["node_modules", "dist", "example"]
26 | }
27 |
--------------------------------------------------------------------------------
/tsconfig.typing.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "./tsconfig.json",
3 | "compilerOptions": {
4 | "noEmit": false,
5 | "declaration": true,
6 | "emitDeclarationOnly": true,
7 | "declarationDir": "dist"
8 | },
9 | "exclude": ["node_modules", "dist", "example"]
10 | }
11 |
--------------------------------------------------------------------------------