fontfamily.js 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module font/fontfamily
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import FontFamilyEditing from './fontfamily/fontfamilyediting';
  10. import FontFamilyUI from './fontfamily/fontfamilyui';
  11. /**
  12. * The font family plugin.
  13. *
  14. * For a detailed overview, check the {@glink features/font font feature} documentatiom
  15. * and the {@glink api/font package page}.
  16. *
  17. * This is a "glue" plugin which loads the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} and
  18. * {@link module:font/fontfamily/fontfamilyui~FontFamilyUI} features in the editor.
  19. *
  20. * @extends module:core/plugin~Plugin
  21. */
  22. export default class FontFamily extends Plugin {
  23. /**
  24. * @inheritDoc
  25. */
  26. static get requires() {
  27. return [ FontFamilyEditing, FontFamilyUI ];
  28. }
  29. /**
  30. * @inheritDoc
  31. */
  32. static get pluginName() {
  33. return 'FontFamily';
  34. }
  35. }
  36. /**
  37. * The font family option descriptor.
  38. *
  39. * @typedef {Object} module:font/fontfamily~FontFamilyOption
  40. *
  41. * @property {String} title The user-readable title of the option.
  42. * @property {String} model The attribute's unique value in the model.
  43. * @property {module:engine/view/elementdefinition~ElementDefinition} view View element configuration.
  44. * @property {Array.<module:engine/view/elementdefinition~ElementDefinition>} [upcastAlso] An array with all matched elements that
  45. * the view-to-model conversion should also accept.
  46. */
  47. /**
  48. * The configuration of the font family feature.
  49. * It is introduced by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature.
  50. *
  51. * Read more in {@link module:font/fontfamily~FontFamilyConfig}.
  52. *
  53. * @member {module:font/fontfamily~FontFamilyConfig} module:core/editor/editorconfig~EditorConfig#fontFamily
  54. */
  55. /**
  56. * The configuration of the font family feature.
  57. * This option is used by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature.
  58. *
  59. * ClassicEditor
  60. * .create( {
  61. * fontFamily: ... // Font family feature configuration.
  62. * } )
  63. * .then( ... )
  64. * .catch( ... );
  65. *
  66. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  67. *
  68. * @interface module:font/fontfamily~FontFamilyConfig
  69. */
  70. /**
  71. * Available font family options defined as an array of strings. The default value is:
  72. *
  73. * const fontFamilyConfig = {
  74. * options: [
  75. * 'default',
  76. * 'Arial, Helvetica, sans-serif',
  77. * 'Courier New, Courier, monospace',
  78. * 'Georgia, serif',
  79. * 'Lucida Sans Unicode, Lucida Grande, sans-serif',
  80. * 'Tahoma, Geneva, sans-serif',
  81. * 'Times New Roman, Times, serif',
  82. * 'Trebuchet MS, Helvetica, sans-serif',
  83. * 'Verdana, Geneva, sans-serif'
  84. * ]
  85. * };
  86. *
  87. * which configures 8 font family options. Each option consists of one or more comma–separated font family names. The first font name is
  88. * used as the dropdown item description in the UI.
  89. *
  90. * **Note:** The family names that consist of spaces should not have quotes (as opposed to the CSS standard). The necessary quotes
  91. * will be added automatically in the view. For example, the `"Lucida Sans Unicode"` will render as follows:
  92. *
  93. * <span style="font-family:'Lucida Sans Unicode', 'Lucida Grande', sans-serif">...</span>
  94. *
  95. * The "default" option removes the `fontFamily` attribute from the selection. In such case, the text will
  96. * be rendered in the view using the default font family defined in the styles of the web page.
  97. *
  98. * Font family can be applied using the command API. To do that, use the `fontFamily` command and pass the desired family as a `value`.
  99. * For example, the following code will apply the `fontFamily` attribute with the `'Arial'` `value` to the current selection:
  100. *
  101. * editor.execute( 'fontFamily', { value: 'Arial' } );
  102. *
  103. * Executing the `'fontFamily'` command without any value will remove the `fontFamily` attribute from the current selection.
  104. *
  105. * @member {Array.<String|module:font/fontfamily~FontFamilyOption>} module:font/fontfamily~FontFamilyConfig#options
  106. */
  107. /**
  108. * By default the plugin removes any `font-family` value that does not match the plugin's configuration. It means that if you paste content
  109. * with font families that the editor does not understand, the `font-family` attribute will be removed and the content will be displayed
  110. * with the default font.
  111. *
  112. * You can preserve pasted font family values by switching the `supportAllValues` option to `true`:
  113. *
  114. * const fontFamilyConfig = {
  115. * supportAllValues: true
  116. * };
  117. *
  118. * With this configuration font families not specified in the editor configuration will not be removed when pasting the content.
  119. *
  120. * @member {Boolean} module:font/fontfamily~FontFamilyConfig#supportAllValues
  121. */