pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 15.5 kB

Source Map (JSON)

View Raw

{"version":3,"file":"HTMLTextStyle.mjs","sources":["../../../src/scene/text-html/HTMLTextStyle.ts"],"sourcesContent":["/* eslint-disable accessor-pairs */\nimport { warn } from '../../utils/logging/warn';\nimport { TextStyle } from '../text/TextStyle';\nimport { textStyleToCSS } from './utils/textStyleToCSS';\n\nimport type { FillInput, StrokeInput } from '../graphics/shared/FillTypes';\nimport type { TextStyleOptions } from '../text/TextStyle';\n\n/**\n * Options for HTML text style, extends standard text styling with HTML-specific capabilities.\n * Omits certain base text properties that don't apply to HTML rendering.\n * @example\n * ```ts\n * // Basic HTML text style\n * const text = new HTMLText({\n * text: 'Hello World',\n * style: {\n * fontSize: 24,\n * fill: '#ff0000',\n * fontFamily: 'Arial',\n * align: 'center'\n * }\n * });\n *\n * // Custom tag styling\n * const taggedText = new HTMLText({\n * text: '<custom>Custom Tag</custom>',\n * style: {\n * fontSize: 16,\n * tagStyles: {\n * custom: {\n * fontSize: 32,\n * fill: '#00ff00',\n * fontStyle: 'italic'\n * }\n * }\n * }\n * });\n * ```\n * @category text\n * @standard\n */\nexport interface HTMLTextStyleOptions extends Omit<TextStyleOptions, 'leading' | 'textBaseline' | 'trim' | 'filters'>\n{\n /**\n * List of CSS style overrides to apply to the HTML text.\n * These styles are added after the built-in styles and can override any default styling.\n * @advanced\n */\n cssOverrides?: string[];\n\n /**\n * Custom styles to apply to specific HTML tags.\n * Allows for consistent styling of custom elements without CSS overrides.\n * @example\n * ```ts\n * const text = new HTMLText({\n * text: `\n * <red>Main Title</red>\n * <grey>The subtitle</grey>\n * <blue>Regular content text</blue>\n * `,\n * style: {\n * tagStyles: {\n * red: {\n * fill: '#ff0000',\n * },\n * grey: {\n * fill: '#666666',\n * },\n * blue: {\n * fill: 'blue',\n * }\n * }\n * }\n * });\n * ```\n * @standard\n */\n tagStyles?: Record<string, HTMLTextStyleOptions>;\n}\n\n/**\n * A TextStyle object rendered by the HTMLTextSystem.\n * @category text\n */\nexport class HTMLTextStyle extends TextStyle\n{\n private _cssOverrides: string[] = [];\n private _cssStyle: string;\n /**\n * Custom styles to apply to specific HTML tags.\n * Allows for consistent styling of custom elements without CSS overrides.\n * @example\n * new HTMLText({\n * text:'<red>Red</red>,<blue>Blue</blue>,<green>Green</green>',\n * style:{\n * fontFamily: 'DM Sans',\n * fill: 'white',\n * fontSize:100,\n * tagStyles:{\n * red:{\n * fill:'red',\n * },\n * blue:{\n * fill:'blue',\n * },\n * green:{\n * fill:'green',\n * }\n * }\n * }\n * );\n * @standard\n */\n public tagStyles: Record<string, HTMLTextStyleOptions>;\n\n constructor(options: HTMLTextStyleOptions = {})\n {\n super(options);\n\n this.cssOverrides = options.cssOverrides ?? [];\n this.tagStyles = options.tagStyles ?? {};\n }\n\n /**\n * List of CSS style overrides to apply to the HTML text.\n * These styles are added after the built-in styles and can override any default styling.\n * @advanced\n */\n set cssOverrides(value: string | string[])\n {\n this._cssOverrides = value instanceof Array ? value : [value];\n this.update();\n }\n\n /** @advanced */\n get cssOverrides(): string[]\n {\n return this._cssOverrides;\n }\n\n /**\n * Updates the text style and triggers a refresh of the CSS style cache.\n * This method is called automatically when style properties are changed.\n * @example\n * ```ts\n * // Update after multiple changes\n * const text = new HTMLText({\n * text: 'Hello World',\n * style\n * });\n *\n * style.fontSize = 32;\n * style.fill = '#00ff00';\n * style.fontFamily = 'Arial';\n * style.update(); // Apply all changes at once\n * ```\n * @advanced\n * @see {@link HTMLTextStyle#cssStyle} For accessing the generated CSS\n * @see {@link HTMLTextStyle#cssOverrides} For managing CSS overrides\n */\n public update()\n {\n this._cssStyle = null;\n super.update();\n }\n\n /**\n * Creates a new HTMLTextStyle object with the same values as this one.\n * This creates a deep copy of all style properties, including dropShadow and tag styles.\n * @example\n * ```ts\n * // Create original style\n * const originalStyle = new HTMLTextStyle({\n * fontSize: 24,\n * fill: '#ff0000',\n * tagStyles: {\n * header: { fontSize: 32, fill: '#00ff00' }\n * }\n * });\n *\n * // Clone the style\n * const clonedStyle = originalStyle.clone();\n *\n * // Modify cloned style independently\n * clonedStyle.fontSize = 36;\n * clonedStyle.fill = '#0000ff';\n *\n * // Original style remains unchanged\n * console.log(originalStyle.fontSize); // Still 24\n * console.log(originalStyle.fill); // Still '#ff0000'\n * ```\n *\n * Properties that are cloned:\n * - Basic text properties (fontSize, fontFamily, etc.)\n * - Fill and stroke styles\n * - Drop shadow configuration\n * - CSS overrides\n * - Tag styles (deep copied)\n * - Word wrap settings\n * - Alignment and spacing\n * @returns {HTMLTextStyle} A new HTMLTextStyle instance with the same properties\n * @see {@link HTMLTextStyle} For available style properties\n * @see {@link HTMLTextStyle#cssOverrides} For CSS override handling\n * @see {@link HTMLTextStyle#tagStyles} For tag style configuration\n * @standard\n */\n public clone(): HTMLTextStyle\n {\n return new HTMLTextStyle({\n align: this.align,\n breakWords: this.breakWords,\n dropShadow: this.dropShadow ? { ...this.dropShadow } : null,\n fill: this._fill,\n fontFamily: this.fontFamily,\n fontSize: this.fontSize,\n fontStyle: this.fontStyle,\n fontVariant: this.fontVariant,\n fontWeight: this.fontWeight,\n letterSpacing: this.letterSpacing,\n lineHeight: this.lineHeight,\n padding: this.padding,\n stroke: this._stroke,\n whiteSpace: this.whiteSpace,\n wordWrap: this.wordWrap,\n wordWrapWidth: this.wordWrapWidth,\n cssOverrides: this.cssOverrides,\n tagStyles: { ...this.tagStyles },\n });\n }\n\n /**\n * The CSS style string that will be applied to the HTML text.\n * @advanced\n */\n get cssStyle(): string\n {\n if (!this._cssStyle)\n {\n this._cssStyle = textStyleToCSS(this);\n }\n\n return this._cssStyle;\n }\n\n /**\n * Add a style override, this can be any CSS property\n * it will override any built-in style. This is the\n * property and the value as a string (e.g., `color: red`).\n * This will override any other internal style.\n * @param {string} value - CSS style(s) to add.\n * @example\n * style.addOverride('background-color: red');\n * @advanced\n */\n public addOverride(...value: string[]): void\n {\n const toAdd = value.filter((v) => !this.cssOverrides.includes(v));\n\n if (toAdd.length > 0)\n {\n this.cssOverrides.push(...toAdd);\n this.update();\n }\n }\n\n /**\n * Remove any overrides that match the value.\n * @param {string} value - CSS style to remove.\n * @example\n * style.removeOverride('background-color: red');\n * @advanced\n */\n public removeOverride(...value: string[]): void\n {\n const toRemove = value.filter((v) => this.cssOverrides.includes(v));\n\n if (toRemove.length > 0)\n {\n this.cssOverrides = this.cssOverrides.filter((v) => !toRemove.includes(v));\n this.update();\n }\n }\n\n /**\n * Sets the fill style for the text. HTML text only supports color fills (string or number values).\n * Texture fills are not supported and will trigger a warning in debug mode.\n * @example\n * ```ts\n * // Using hex colors\n * const text = new HTMLText({\n * text: 'Colored Text',\n * style: {\n * fill: 0xff0000 // Red color\n * }\n * });\n *\n * // Using CSS color strings\n * text.style.fill = '#00ff00'; // Hex string (Green)\n * text.style.fill = 'blue'; // Named color\n * text.style.fill = 'rgb(255,0,0)' // RGB\n * text.style.fill = '#f0f'; // Short hex\n *\n * // Invalid usage (will trigger warning in debug)\n * text.style.fill = {\n * type: 'pattern',\n * texture: Texture.from('pattern.png')\n * }; // Not supported, falls back to default\n * ```\n * @param value - The fill color to use. Must be a string or number.\n * @throws {Warning} In debug mode when attempting to use unsupported fill types\n * @see {@link TextStyle#fill} For full fill options in canvas text\n * @standard\n */\n override set fill(value: FillInput)\n {\n // if its not a string or a number, then its a texture!\n if (typeof value !== 'string' && typeof value !== 'number')\n {\n // #if _DEBUG\n warn('[HTMLTextStyle] only color fill is not supported by HTMLText');\n // #endif\n }\n\n super.fill = value;\n }\n\n /**\n * Sets the stroke style for the text. HTML text only supports color strokes (string or number values).\n * Texture strokes are not supported and will trigger a warning in debug mode.\n * @example\n * ```ts\n * // Using hex colors\n * const text = new HTMLText({\n * text: 'Outlined Text',\n * style: {\n * stroke: 0xff0000 // Red outline\n * }\n * });\n *\n * // Using CSS color strings\n * text.style.stroke = '#00ff00'; // Hex string (Green)\n * text.style.stroke = 'blue'; // Named color\n * text.style.stroke = 'rgb(255,0,0)' // RGB\n * text.style.stroke = '#f0f'; // Short hex\n *\n * // Using stroke width\n * text.style = {\n * stroke: {\n * color: '#ff0000',\n * width: 2\n * }\n * };\n *\n * // Remove stroke\n * text.style.stroke = null;\n *\n * // Invalid usage (will trigger warning in debug)\n * text.style.stroke = {\n * type: 'pattern',\n * texture: Texture.from('pattern.png')\n * }; // Not supported, falls back to default\n * ```\n * @param value - The stroke style to use. Must be a string, number, or stroke configuration object\n * @throws {Warning} In debug mode when attempting to use unsupported stroke types\n * @see {@link TextStyle#stroke} For full stroke options in canvas text\n * @standard\n */\n override set stroke(value: StrokeInput)\n {\n // if its not a string or a number, then its a texture!\n if (value && typeof value !== 'string' && typeof value !== 'number')\n {\n // #if _DEBUG\n warn('[HTMLTextStyle] only color stroke is not supported by HTMLText');\n // #endif\n }\n\n super.stroke = value;\n }\n}\n"],"names":[],"mappings":"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"}