Document Themes​​

Document themes​​ in ​​SpreadJS​​ make it easy to coordinate colors and fonts across your workbook, allowing for quick updates. Themes provide a unified appearance by using predefined sets of colors and fonts. For example, the ​​Accent1​​ color may appear differently in the ​​Office​​ and ​​Apex​​ themes.

SpreadJS includes built-in themes, but you can also design custom themes manually to achieve a unique look for your worksheet. Additionally, you may further customize the colors and fonts of any existing theme as needed.

The following are the Themes supported by SpreadJS out of the box:

You can apply a theme to a worksheet using the currentTheme method:

sheet.currentTheme('Apex') //using a built-in theme name
sheet.currentTheme(GC.Spread.Sheets.Themes.Metro) //using a theme instance

Example: Using Apex theme

Example: Using Metro theme

Understanding Document Themes​

A ​​theme​​ in SpreadJS consists of:

• ​​Theme Colors​​ – A predefined set of colors used for text, backgrounds, accents, and hyperlinks.

• ​​Theme Fonts​​ – A combination of headings and body fonts applied throughout the worksheet.

Applying a theme ensures that all elements in your worksheet follow a cohesive design.

Theme Colors​

SpreadJS provides built-in themes (e.g., ​​Office, Apex​​) with different color schemes. Each theme includes:

ThemeColor Brightness Variations​

Each theme color has ​​darker/lighter variations​​ (e.g., Accent 1 80, Dark 1 50). uses a ​​-100 to 100 brightness scale​​ for theme colors, where:

• ​​Negative values (-100 to 0)​​ = Darker variants

• ​​0​​ = Base theme color

• ​​Positive values (0 to 100)​​ = Lighter variants

Hyperlink and FollowedHyperlink theme color doesn't support brightness variations.

You can apply the theme colors programmatically:

// Darker variants (negative values)
sheet.getRange("A1").backColor("Accent 1 -60");  // 60% darker
sheet.getRange("B1").backColor("Background 1 -40");  // 40% darker

// Base color (0 brightness)
sheet.getRange("C1").backColor("Accent 1 0");  // Default color
sheet.getRange("D1").backColor("Accent 1 0");  // Default color

// Lighter variants (positive values)
sheet.getRange("E1").backColor("Accent 1 60");  // 60% lighter
sheet.getRange("F1").backColor("Background 1 25");  // 25% lighter

Theme Fonts​

Themes include two named fonts that help maintain consistency in your document's appearance.

1. ​​Body Font​​

   • Used for regular text content (e.g., cell values, paragraphs, or non-heading text).

   • Typically, a clean, readable font like Calibri

   • Applies automatically to most worksheet cells unless overridden.

2. ​​Headings Font​​

   • Designed for titles, headers, or emphasized text (e.g., chart titles, table headers).

   • Often a slightly more distinctive font (e.g., Cambria)

   • Used in elements like axis labels, legends, or manually formatted headings.

Theme font only defines the "font family" and does not include other font attributes.

The following are the theme fonts for each built-in theme

The above table only provides Latin fonts.

You can apply the theme font programmatically

sheet.getCell(1,3).value("Apply Heading Font to Cell").themeFont("Headings");
sheet.getCell(2,3).value("Apply Body Font to Cell").themeFont("Body");

Example: Using Apex theme

Example: Using Metro theme

In SpreadJS cell styling, when both "themeFont" and "font" are present, the actual font applied to the cell is a combination of the "font family" corresponding to the "themeFont" and the other font attributes (excluding "font family") from the cell's "font" settings.

For example, when using a built-in Aspect theme and setting the cell style as follows:

var style = new GC.Spread.Sheets.Style();
style.themeFont = 'Body';
style.fontFamily = 'Arial';
style.fontSize = '20px';
style.fontWeight = 'bold';
style.fontStyle = 'italic';
sheet.setStyle(0, 0, style);
sheet.setValue(0,0,'Cell Fonts');

The resulting font will be “italic bold 20px Verdana”

Using East Asian Typefaces from Culture

SpreadJS offers comprehensive support for displaying and measuring text in both Latin and East Asian typefaces, adapting to cultural settings.

Through its theme system, SpreadJS enables East Asian typeface support via the ThemeFont class.

Culture-Based Font Selection

SpreadJS automatically applies appropriate typefaces based on the current culture:

• ​​Latin regions​​: Uses Latin typeface for headers, cells, column width measurement, etc.

• ​​East Asian regions​​: Uses East Asian typeface, ignoring Latin typeface configurations

Configure font script codes using the GC.Spread.Common.CultureInfo class:

class GC.Spread.Common.CultureInfo {
  fontScriptCode?: string;
}

To fully support Excel I/E, the fontScriptCode should be from the standard found at https://en.wikipedia.org/wiki/ISO_15924

Built-in Culture Compatibility

For backward compatibility, built-in cultures don't automatically apply fontScriptCode. To enable:

// Enable for Chinese (Simplified)
var cultureInfo = GC.Spread.Common.CultureManager.getCultureInfo('zh-cn');
cultureInfo.fontScriptCode = "Hans";
GC.Spread.Common.CultureManager.culture('zh-cn');

// Enable for Japanese
cultureInfo = GC.Spread.Common.CultureManager.getCultureInfo('ja-jp');
cultureInfo.fontScriptCode = "Jpan";
GC.Spread.Common.CultureManager.culture('ja-jp');

// Enable for Korean
cultureInfo = GC.Spread.Common.CultureManager.getCultureInfo('ko-kr');
cultureInfo.fontScriptCode = "Hang";
GC.Spread.Common.CultureManager.culture('ko-kr');

Configuring Custom Cultures

Add custom culture with East Asian support

var customCulture = new GC.Spread.Common.CultureInfo();
customCulture.fontScriptCode = 'Thai';
GC.Spread.Common.CultureManager.addCultureInfo('th-TH', customCulture);
GC.Spread.Common.CultureManager.culture('th-TH');

Once configured, SpreadJS will automatically use East Asian fonts when reading "Headings" or "Body" theme fonts:

// Set cell theme font to Body (will use East Asian font)
sheet.getCell(0, 0).themeFont("Body");

// Styles with themeFont will also use East Asian fonts
var style = new GC.Spread.Sheets.Style();
style.themeFont = "Body";
sheet.setStyle(1, 1, style);

Apply a theme with East Asian fonts to a worksheet

var theme = sheet.currentTheme();
theme.font().headingEastAsianFont('SimSun'); // Set East Asian headings font
theme.font().bodyEastAsianFont('SimSun');    // Set East Asian body font
sheet.currentTheme(theme);

Font Priority Rules

The font selection follows these priority rules:

1. East Asian font is specified in the theme

2. Font matching culture's font script code

3. Default Latin font

Examples

// Case 1: No font script code set (returns Latin font)
var font = theme.bodyFont(); // Returns "Calibri"

// Case 2: Font script code set but no East Asian font in theme
GC.Spread.Common.CultureManager.getCultureInfo().fontScriptCode = 'Hans';
var font = theme.bodyFont(); // Returns culture-specific font (e.g., "DengXian")

// Case 3: East Asian font explicitly set in theme
theme.font().bodyEastAsianFont('DengXian');
var font = theme.bodyFont(); // Returns "DengXian"

Font Script Typeface Configuration

Configure fallback font for a specific script

GC.Spread.Common.CultureManager.getCultureInfo().fontScriptCode = 'Hans';
theme.font().bodyFontScriptTypeface('Hans', 'SimSum');

// Equivalent to:
theme.font().bodyEastAsianFont('SimSum');

In Excel, the text on charts—such as titles, axes, legends, and chart areas—follows a specific policy for font selection. For instance, the chart area, axes, and legends typically use the Latin font from the theme. However, the title automatically detects the appropriate font based on the cursor's position. If East Asian text is nearby, it will use the East Asian font of the theme; otherwise, it defaults to the Latin font when Excel is opened in an East Asian locale. Similarly, text within shapes follows this same policy.

In contrast, SpreadJS operates differently: charts and shapes utilize only one font that corresponds to the current theme, without the dynamic font selection based on text proximity.