首页
话题
消息
手册
我的
返回介绍

Autocompleter

发布于 2019-05-06 字数11074 浏览 915 评论 0

Overview and use case

An autocompleter enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering. It provides suggestions to insert while the user is typing into the content. For example, with the charmap plugin enabled, typing :amp should show the ampersand item in the menu. Pressing esc should close the autocomplete menu.

How to create custom autocompleters

The method for adding a custom autocompleter is in the UI Registry part of the editor API editor.ui.registry:

  • editor.ui.registry.addAutocompleter(name, configuration)

The two arguments this method take are:

  • name – A unique name for the autocompleter.
  • configuration – An object containing the user’s configuration.

Configuration options

Name Value Requirement Description
ch string Required The character to trigger the autocompleter.
fetch (pattern: string, maxResults: number) => Promise<AutocompleterItem[]> Required A function that is passed the current matched text pattern and the maximum number of expected results. The function should return a promise containing matching results.
onAction (api, rng: Range, value: string) => void Required A function invoked when a fetched item is selected.
columns number or ‘auto’ Optional default: auto – The number of columns to show. If set to 1 column, then icons and text are displayed, otherwise only icons are displayed.
matches (rng: Range, text: string, pattern: string) => boolean Optional default: isStartOfWord – A predicate function that takes a range, the current text node content and the matched text content and returns a boolean indicating if the autocompleter should trigger.
maxResults number Optional default: 10 – The maximum number of results that should be fetched.
minChars number Optional default: 1 – The minimum number of characters that must be typed before the autocompleter will trigger (excluding the trigger char).

The fetch function is called whenever the trigger char is pressed and the matches predicate returns true. It is a function that takes the matched text pattern and returns a promise containing matching results. This allows for asynchronous fetching of the autocompleter items. The results should be a list of objects with the following details:

  • value: Value of the item. This will be passed to the onAction callback when selected.
  • text: Text to display for the item.
  • icon: Name of the icon to be displayed. Must be a single unicode character or correspond to an icon in the icon pack.

Note: If two or more autocompleters use the same trigger character, then the fetched results will be merged together before being displayed.

API

Name Value Description
hide () => void Hides the autocompleter menu.

Example

This example shows how the charmap plugin adds the standard autocompleter. The autocompleter will show whenever a : character is typed plus at least one additional character.

TinyMCE HTML JS Edit on CodePen


<textarea id="autocompleter">
  <p>Type <b>:</b> below and then keep typing to reduce further matches. For example, typing <b>:amp</b> should show the ampersand item in the menu. Pressing esc should close the autocomplete menu.</p>
  <p></p>
</textarea>



var specialChars = [
  { text: 'exclamation mark', value: '!' },
  { text: 'at', value: '@' },
  { text: 'hash', value: '#' },
  { text: 'dollars', value: '$' },
  { text: 'percent sign', value: '%' },
  { text: 'caret', value: '^' },
  { text: 'ampersand', value: '&' },
  { text: 'asterisk', value: '*' }
];

tinymce.init({
  selector: 'textarea#autocompleter',
  height: 250,
  setup: function (editor) {
    /* An autocompleter that allows you to insert special characters */
    editor.ui.registry.addAutocompleter('specialchars', {
      ch: ':',
      minChars: 1,
      columns: 'auto',
      fetch: function (pattern) {
        var matchedChars = specialChars.filter(function (char) {
          return char.text.indexOf(pattern) !== -1;
        });

        return new tinymce.util.Promise(function (resolve) {
          var results = matchedChars.map(function (char) {
            return {
              value: char.value,
              text: char.text,
              icon: char.value
            }
          });
          resolve(results);
        });
      },
      onAction: function (autocompleteApi, rng, value) {
        editor.selection.setRng(rng);
        editor.insertContent(value);
        autocompleteApi.hide();
      }
    });
  }
});


(function() { var isIE = !!window.MSInputMethodContext && !!document.documentMode; if (isIE && document.getElementsByClassName(“ie11_optional”)[0] !== undefined) { document.getElementsByClassName(“ie11_optional”)[0].style.display = ‘none’; } })(); (function() { var specialChars = [ { text: ‘exclamation mark’, value: ‘!’ }, { text: ‘at’, value: ‘@’ }, { text: ‘hash’, value: ‘#’ }, { text: ‘dollars’, value: ‘$’ }, { text: ‘percent sign’, value: ‘%’ }, { text: ‘caret’, value: ‘^’ }, { text: ‘ampersand’, value: ‘&’ }, { text: ‘asterisk’, value: ‘*’ } ]; tinymce.init({ selector: ‘textarea#autocompleter’, height: 250, setup: function (editor) { /* An autocompleter that allows you to insert special characters */ editor.ui.registry.addAutocompleter(‘specialchars’, { ch: ‘:’, minChars: 1, columns: ‘auto’, fetch: function (pattern) { var matchedChars = specialChars.filter(function (char) { return char.text.indexOf(pattern) !== -1; }); return new tinymce.util.Promise(function (resolve) { var results = matchedChars.map(function (char) { return { value: char.value, text: char.text, icon: char.value } }); resolve(results); }); }, onAction: function (autocompleteApi, rng, value) { editor.selection.setRng(rng); editor.insertContent(value); autocompleteApi.hide(); } }); } }); })(); (function() { /* TODO: more js, less jekyll */ var id = “autocompleter”; var html = decodeURIComponent(“%0A%3Ctextarea%20id=%22autocompleter%22%3E%0A%20%20%3Cp%3EType%20%3Cb%3E:%3C/b%3E%20below%20and%20then%20keep%20typing%20to%20reduce%20further%20matches.%20For%20example,%20typing%20%3Cb%3E:amp%3C/b%3E%20should%20show%20the%20ampersand%20item%20in%20the%20menu.%20Pressing%20esc%20should%20close%20the%20autocomplete%20menu.%3C/p%3E%0A%20%20%3Cp%3E%3C/p%3E%0A%3C/textarea%3E%0A%0A”); var js = decodeURIComponent(“%0Avar%20specialChars%20=%20[%0A%20%20%7B%20text:%20’exclamation%20mark’,%20value:%20′!’%20%7D,%0A%20%20%7B%20text:%20’at’,%20value:%20’@’%20%7D,%0A%20%20%7B%20text:%20’hash’,%20value:%20’#’%20%7D,%0A%20%20%7B%20text:%20’dollars’,%20value:%20’$’%20%7D,%0A%20%20%7B%20text:%20’percent%20sign’,%20value:%20’%25’%20%7D,%0A%20%20%7B%20text:%20’caret’,%20value:%20’%5E’%20%7D,%0A%20%20%7B%20text:%20’ampersand’,%20value:%20’&’%20%7D,%0A%20%20%7B%20text:%20’asterisk’,%20value:%20’*’%20%7D%0A];%0A%0Atinymce.init(%7B%0A%20%20selector:%20’textarea#autocompleter’,%0A%20%20height:%20250,%0A%20%20setup:%20function%20(editor)%20%7B%0A%20%20%20%20/*%20An%20autocompleter%20that%20allows%20you%20to%20insert%20special%20characters%20*/%0A%20%20%20%20editor.ui.registry.addAutocompleter(‘specialchars’,%20%7B%0A%20%20%20%20%20%20ch:%20′:’,%0A%20%20%20%20%20%20minChars:%201,%0A%20%20%20%20%20%20columns:%20’auto’,%0A%20%20%20%20%20%20fetch:%20function%20(pattern)%20%7B%0A%20%20%20%20%20%20%20%20var%20matchedChars%20=%20specialChars.filter(function%20(char)%20%7B%0A%20%20%20%20%20%20%20%20%20%20return%20char.text.indexOf(pattern)%20!==%20-1;%0A%20%20%20%20%20%20%20%20%7D);%0A%0A%20%20%20%20%20%20%20%20return%20new%20tinymce.util.Promise(function%20(resolve)%20%7B%0A%20%20%20%20%20%20%20%20%20%20var%20results%20=%20matchedChars.map(function%20(char)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20value:%20char.value,%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20text:%20char.text,%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20icon:%20char.value%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D);%0A%20%20%20%20%20%20%20%20%20%20resolve(results);%0A%20%20%20%20%20%20%20%20%7D);%0A%20%20%20%20%20%20%7D,%0A%20%20%20%20%20%20onAction:%20function%20(autocompleteApi,%20rng,%20value)%20%7B%0A%20%20%20%20%20%20%20%20editor.selection.setRng(rng);%0A%20%20%20%20%20%20%20%20editor.insertContent(value);%0A%20%20%20%20%20%20%20%20autocompleteApi.hide();%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D);%0A%20%20%7D%0A%7D);%0A%0A”); var css = “”; var tabNames = [“run”,”html”,”js”]; /* Note: there are some other fields we could populate here to polish this. */ /* See: https://blog.codepen.io/documentation/api/prefill/ */ var data = { title: “TinyMCE Example”, description: ”, html: html, css: css, css_external: ‘https://www.tiny.cloud/css/codepen.min.css’, js: js, js_external: ‘https://cloud.tinymce.com/5/tinymce.min.js?apiKey=qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc’ }; document.getElementById(“codepen_data_autocompleter”).value = JSON.stringify(data); /* TODO: */ var tabs = tabNames.map(function(t) { return { tab: document.getElementById(“codepen_tab_” + t + “_” + id), pane: document.getElementById(“codepen_pane_” + t + “_” + id) }; }); tabs.forEach(function(t) { t.tab.onclick = function(e) { tabs.forEach(function(tt) { tt.pane.style.display = t === tt ? ‘block’ : ‘none’; tt.tab.className = t === tt ? ‘codepen_tab_selected’ : ‘codepen_tab_deselected’; }); e.preventDefault(); }; }); if (document.getElementById(“codepen_tab_codepen_” + id) !== null) { document.getElementById(“codepen_tab_codepen_” + id).onclick = function() { document.getElementById(“codepen_form_” + id).submit(); }; } })();

您暂时不能评论!

管理员开启了需要登录才能够评论,你可以免费注册一个本站的账号。

还没有评论!

目前还没有任何评论,快来抢沙发吧!