pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 16.6 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 override _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 * 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: '<red>Red</red>, <blue>Blue</blue>, <green>Green</green>',\n * style: {\n * tagStyles: {\n * red: { fill: 'red' },\n * blue: { fill: 'blue' },\n * green: { fill: 'green' },\n * }\n * }\n * });\n * ```\n * @standard\n */\n public override get tagStyles(): Record<string, HTMLTextStyleOptions> | undefined\n {\n return this._tagStyles;\n }\n /** @standard */\n public override set tagStyles(value: Record<string, HTMLTextStyleOptions> | undefined)\n {\n if (this._tagStyles === value) return;\n\n this._tagStyles = value ?? {};\n this.update();\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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"}