React-Dialogic
一個專為 React 應用開發的對話系統 UI 套件
A dialogue system UI kit for React applications
Click here to see Demo

繁體中文
功能目的
React-Dialogic 旨在提供一個易於集成且功能豐富的對話系統,可用於:
- 視覺小說和互動遊戲
- 教學指引和用戶引導
- 互動式故事敘述
- 角色驅動的用戶介面
- 任何需要對話框和角色互動的應用
主要特性
1. 滿版顯示系統
- 組件初始化時自動佔滿整個視窗/容器
- 提供沉浸式體驗,背景填充整個視圖
- 響應式設計,適配不同屏幕尺寸和設備
2. 人物配置系統
- 支援設定角色信息(ID、名稱、圖片、聲音等)
- 多個表情/狀態的圖片管理
- 自定義角色文字顏色和顯示速度
- 角色在對話中的位置控制(左/右側)
3. 對話框系統
- 底部顯示對話文字區域
- 打字機效果逐字顯示文本
- 可調整文字顯示速度
- 支援文字特效和停頓
4. 選項系統
- 支援對話選項分支
- 選項結果影響後續對話流程
- 自定義選項樣式和效果
- 條件性選項顯示
5. 主題系統
- 預設多種主題風格
- 支援自定義主題配置
- 運行時動態切換主題
- 統一調整整體色系和風格
6. 背景管理
- 自定義背景圖片或顏色
- 背景轉場效果
- 透明背景選項,適應不同場景
7. 事件鉤子系統
onMessageStart
- 對話節點開始時觸發
onMessage
- 對話節點結束時觸發
onMessageEnd
- 對話流結束時觸發(無next屬性時)
- 自定義事件處理和遊戲邏輯整合
安裝
npm install react-dialogic
yarn add react-dialogic
基本用法
步驟一:引入組件和樣式
import { ReactDialogic } from 'react-dialogic';
import 'react-dialogic/dist/styles.css';
步驟二:定義角色配置
const Position = {
LEFT: 'left',
RIGHT: 'right',
CENTER: 'center'
};
const characters = {
yangGuo: {
name: '楊過',
images: {
default: '/images/yangGuo.png'
},
textColor: '#3a86ff',
defaultPosition: Position.LEFT
},
xiaoLongNv: {
name: '小龍女',
images: {
default: '/images/xiaoLongNv.png',
blindfolded: '/images/xiaoLongNv-blindfolded.png'
},
textColor: '#8338ec',
defaultPosition: Position.RIGHT
}
};
步驟三:定義對話場景
const dialogue = {
start: {
background: '/images/grassland.png',
sequence: [
{
speaker: 'yangGuo',
text: '姑姑,我們今天練什麼武功?',
position: Position.LEFT
},
{
speaker: 'xiaoLongNv',
text: '我們今天練習玉女心經。',
position: Position.RIGHT
},
{
text: '(兩人來到了練武場)'
},
{
speaker: 'xiaoLongNv',
text: '你想先練習哪個部分?',
choices: [
{ text: '內功心法', next: 'innerPower' },
{ text: '劍法招式', next: 'swordSkills' }
]
}
]
},
innerPower: {
background: '/images/cave.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: '讓我們先打坐冥想,修煉內功。',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: '好的,姑姑。',
position: Position.LEFT
},
{
text: '(兩人開始打坐)',
next: 'ending'
}
]
},
swordSkills: {
background: '/images/grassland.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: '拿起你的劍,讓我們練習劍法。',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: '遵命,姑姑。',
position: Position.LEFT
},
{
text: '(兩人開始練劍)',
next: 'ending'
}
]
},
ending: {
background: '/images/sunset.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: '今天的練習到此為止。',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: '謝謝姑姑指導。',
position: Position.LEFT
}
]
}
};
步驟四:使用組件
import React from 'react';
import { ReactDialogic } from 'react-dialogic';
import 'react-dialogic/dist/styles.css';
function App() {
const handleMessageStart = (item) => {
console.log('對話開始:', item);
};
const handleMessage = (item) => {
console.log('對話進行中:', item);
};
const handleMessageEnd = (item) => {
console.log('對話結束:', item);
};
return (
<div className="app">
<ReactDialogic
characters={characters}
dialogue={dialogue}
startScene="start"
onMessageStart={handleMessageStart}
onMessage={handleMessage}
onMessageEnd={handleMessageEnd}
/>
</div>
);
}
export default App;
步驟五:圖片引入(如使用打包工具如Webpack)
如果您使用Webpack等打包工具,可以直接引入本地圖片:
import yangGuoImg from './images/yangGuo.png';
import xiaoLongNvImg from './images/xiaoLongNv.png';
import blindfoldedImg from './images/xiaoLongNv-blindfolded.png';
import grasslandBg from './images/grassland.png';
import caveBg from './images/cave.png';
import sunsetBg from './images/sunset.png';
const characters = {
yangGuo: {
name: '楊過',
images: {
default: yangGuoImg
},
},
xiaoLongNv: {
name: '小龍女',
images: {
default: xiaoLongNvImg,
blindfolded: blindfoldedImg
},
}
};
const dialogue = {
start: {
background: grasslandBg,
},
};
自定義主題
React Dialogic 使用 CSS 變量來控制組件的外觀。您可以通過以下方式自定義主題:
方法一:覆蓋 CSS 變量
在您的 CSS 中覆蓋預設變量:
:root {
--dialogic-dialog-bg: rgba(255, 255, 255, 0.9);
--dialogic-dialog-border: #FF5500;
--dialogic-dialog-text: #333333;
--dialogic-name-text: #FF5500;
}
方法二:創建自定義主題類
您可以創建自己的主題類:
.theme-fantasy {
--dialogic-dialog-bg: rgba(64, 41, 93, 0.85);
--dialogic-dialog-border: #9951FF;
--dialogic-dialog-text: #FFFFFF;
--dialogic-name-text: #FFD700;
--dialogic-choice-bg: rgba(64, 41, 93, 0.7);
--dialogic-choice-bg-hover: rgba(153, 81, 255, 0.3);
--dialogic-choice-text: #FFFFFF;
--dialogic-choice-text-hover: #FFD700;
--dialogic-font-dialog: 'Tangerine', cursive;
--dialogic-font-choice: 'Tangerine', cursive;
--dialogic-typewriter-speed: 35ms;
--dialogic-dialog-radius: 12px;
--dialogic-choice-radius: 8px;
}
可用的 CSS 變量
以下是可用的 CSS 變量及其用途:
--dialogic-dialog-bg | 對話框背景色 | rgba(0, 0, 0, 0.8) |
--dialogic-dialog-border | 對話框邊框顏色 | #FFCC00 |
--dialogic-dialog-text | 對話文本顏色 | #FFFFFF |
--dialogic-name-text | 角色名稱顏色 | #FFCC00 |
--dialogic-choice-bg | 選項背景色 | rgba(0, 0, 0, 0.7) |
--dialogic-choice-bg-hover | 選項懸停背景色 | rgba(255, 204, 0, 0.3) |
--dialogic-choice-text | 選項文本顏色 | #FFFFFF |
--dialogic-choice-text-hover | 選項懸停文本顏色 | #FFCC00 |
--dialogic-font-dialog | 對話框字體 | 'Press Start 2P', system-ui, sans-serif |
--dialogic-font-choice | 選項字體 | 'Press Start 2P', system-ui, sans-serif |
--dialogic-typewriter-speed | 打字效果速度 | 40ms |
--dialogic-dialog-radius | 對話框圓角半徑 | 4px |
--dialogic-choice-radius | 選項圓角半徑 | 2px |
更多功能
- 角色進入/退出動畫
- 對話框出現/消失特效
- 背景切換過渡效果
- 音效和語音支援
- 自定義事件鉤子
- 鍵盤和觸控控制
- 無障礙支援
技術需求
- React 16.8+
- Tailwind CSS
- 可選:Three.js(進階動畫效果)
- 可選:Anime.js(進階動畫效果)
English
Purpose
React-Dialogic aims to provide an easy-to-integrate and feature-rich dialogue system for:
- Visual novels and interactive games
- Tutorials and user onboarding flows
- Interactive storytelling
- Character-driven user interfaces
- Any application requiring dialogue boxes and character interactions
Key Features
1. Fullscreen Display System
- Components automatically fill the entire window/container on initialization
- Provides an immersive experience with background filling the entire view
- Responsive design adapting to different screen sizes and devices
2. Character Configuration System
- Support for character information settings (ID, name, images, sounds, etc.)
- Multiple emotion/state image management
- Custom character text color and display speed
- Character positioning control (left/right side)
3. Dialogue Box System
- Bottom-anchored text display area
- Typewriter effect for character-by-character text display
- Adjustable text display speed
- Support for text effects and pauses
4. Choice System
- Support for dialogue option branches
- Choice results affecting subsequent dialogue flow
- Custom option styling and effects
- Conditional option display
5. Theme System
- Multiple preset theme styles
- Support for custom theme configuration
- Runtime dynamic theme switching
- Unified adjustment of overall color schemes and styles
6. Background Management
- Custom background images or colors
- Background transition effects
- Transparent background option for different contexts
7. Event Hook System
onMessageStart
- Triggered when a dialogue node begins
onMessage
- Triggered when a dialogue node ends
onMessageEnd
- Triggered when the dialogue flow ends (when no next property is present)
- Custom event handling and game logic integration
Installation
npm install react-dialogic
yarn add react-dialogic
Basic Usage
Step 1: Import Components and Styles
import { ReactDialogic } from 'react-dialogic';
import 'react-dialogic/dist/styles.css';
Step 2: Define Character Configuration
const Position = {
LEFT: 'left',
RIGHT: 'right',
CENTER: 'center'
};
const characters = {
yangGuo: {
name: 'Yang Guo',
images: {
default: '/images/yangGuo.png'
},
textColor: '#3a86ff',
defaultPosition: Position.LEFT
},
xiaoLongNv: {
name: 'Xiao Long Nv',
images: {
default: '/images/xiaoLongNv.png',
blindfolded: '/images/xiaoLongNv-blindfolded.png'
},
textColor: '#8338ec',
defaultPosition: Position.RIGHT
}
};
Step 3: Define Dialogue Scenes
const dialogue = {
start: {
background: '/images/grassland.png',
sequence: [
{
speaker: 'yangGuo',
text: 'Master, what skills shall we practice today?',
position: Position.LEFT
},
{
speaker: 'xiaoLongNv',
text: 'Today we will practice the Jade Maiden Heart Sutra.',
position: Position.RIGHT
},
{
text: '(The two arrived at the training area)'
},
{
speaker: 'xiaoLongNv',
text: 'Which part would you like to practice first?',
choices: [
{ text: 'Inner power cultivation', next: 'innerPower' },
{ text: 'Sword techniques', next: 'swordSkills' }
]
}
]
},
innerPower: {
background: '/images/cave.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: 'Let us sit in meditation to cultivate inner power.',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: 'Yes, master.',
position: Position.LEFT
},
{
text: '(They begin to meditate)',
next: 'ending'
}
]
},
swordSkills: {
background: '/images/grassland.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: 'Take your sword and let us practice sword techniques.',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: 'As you command, master.',
position: Position.LEFT
},
{
text: '(They begin sword practice)',
next: 'ending'
}
]
},
ending: {
background: '/images/sunset.png',
sequence: [
{
speaker: 'xiaoLongNv',
text: 'That\'s enough practice for today.',
position: Position.RIGHT
},
{
speaker: 'yangGuo',
text: 'Thank you for your guidance, master.',
position: Position.LEFT
}
]
}
};
Step 4: Use the Component
import React from 'react';
import { ReactDialogic } from 'react-dialogic';
import 'react-dialogic/dist/styles.css';
function App() {
const handleMessageStart = (item) => {
console.log('Dialogue start:', item);
};
const handleMessage = (item) => {
console.log('Dialogue in progress:', item);
};
const handleMessageEnd = (item) => {
console.log('Dialogue end:', item);
};
return (
<div className="app">
<ReactDialogic
characters={characters}
dialogue={dialogue}
startScene="start"
onMessageStart={handleMessageStart}
onMessage={handleMessage}
onMessageEnd={handleMessageEnd}
/>
</div>
);
}
export default App;
Step 5: Image Imports (When Using Bundlers like Webpack)
If you're using bundlers like Webpack, you can import local images directly:
import yangGuoImg from './images/yangGuo.png';
import xiaoLongNvImg from './images/xiaoLongNv.png';
import blindfoldedImg from './images/xiaoLongNv-blindfolded.png';
import grasslandBg from './images/grassland.png';
import caveBg from './images/cave.png';
import sunsetBg from './images/sunset.png';
const characters = {
yangGuo: {
name: 'Yang Guo',
images: {
default: yangGuoImg
},
},
xiaoLongNv: {
name: 'Xiao Long Nv',
images: {
default: xiaoLongNvImg,
blindfolded: blindfoldedImg
},
}
};
const dialogue = {
start: {
background: grasslandBg,
},
};
Custom Themes
React Dialogic uses CSS variables to control the appearance of components. You can customize the theme in the following ways:
Method 1: Override CSS Variables
Override default variables in your CSS:
:root {
--dialogic-dialog-bg: rgba(255, 255, 255, 0.9);
--dialogic-dialog-border: #FF5500;
--dialogic-dialog-text: #333333;
--dialogic-name-text: #FF5500;
}
Method 2: Create Custom Theme Classes
You can create your own theme classes:
.theme-fantasy {
--dialogic-dialog-bg: rgba(64, 41, 93, 0.85);
--dialogic-dialog-border: #9951FF;
--dialogic-dialog-text: #FFFFFF;
--dialogic-name-text: #FFD700;
--dialogic-choice-bg: rgba(64, 41, 93, 0.7);
--dialogic-choice-bg-hover: rgba(153, 81, 255, 0.3);
--dialogic-choice-text: #FFFFFF;
--dialogic-choice-text-hover: #FFD700;
--dialogic-font-dialog: 'Tangerine', cursive;
--dialogic-font-choice: 'Tangerine', cursive;
--dialogic-typewriter-speed: 35ms;
--dialogic-dialog-radius: 12px;
--dialogic-choice-radius: 8px;
}
Available CSS Variables
Here are the available CSS variables and their purposes:
--dialogic-dialog-bg | Dialog background color | rgba(0, 0, 0, 0.8) |
--dialogic-dialog-border | Dialog border color | #FFCC00 |
--dialogic-dialog-text | Dialog text color | #FFFFFF |
--dialogic-name-text | Character name color | #FFCC00 |
--dialogic-choice-bg | Choice background color | rgba(0, 0, 0, 0.7) |
--dialogic-choice-bg-hover | Choice hover background color | rgba(255, 204, 0, 0.3) |
--dialogic-choice-text | Choice text color | #FFFFFF |
--dialogic-choice-text-hover | Choice hover text color | #FFCC00 |
--dialogic-font-dialog | Dialog font | 'Press Start 2P', system-ui, sans-serif |
--dialogic-font-choice | Choice font | 'Press Start 2P', system-ui, sans-serif |
--dialogic-typewriter-speed | Typewriter effect speed | 40ms |
--dialogic-dialog-radius | Dialog border radius | 4px |
--dialogic-choice-radius | Choice border radius | 2px |
More Features
- Character entry/exit animations
- Dialogue box appearance/disappearance effects
- Background transition effects
- Sound effects and voice support
- Custom event hooks
- Keyboard and touch controls
- Accessibility support
Technical Requirements
- React 16.8+
- Tailwind CSS
- Optional: Three.js (for advanced animation effects)
- Optional: Anime.js (for advanced animation effects)
License
MIT