Ankieta badawcza: podziel się z nami opinią o Blockly

Ta strona została przetłumaczona przez Cloud Translation API.

Struktura bloku w formacie JSON

Z tego dokumentu dowiesz się, jak używać formatu JSON do definiowania danych wejściowych, pól (w tym etykiet) i połączeń w bloku. Jeśli nie znasz tych terminów, przed kontynuowaniem przeczytaj artykuł Anatomia bloku.

Możesz też zdefiniować dane wejściowe, pola i połączenia w języku JavaScript.

Przegląd

W JSON-ie opisujesz strukturę bloku za pomocą co najmniej jednego ciągu znaków wiadomości (message0, message1, ...) i odpowiadających im tablic argumentów (args0, args1, ...). Ciągi znaków wiadomości składają się z tekstu, który jest przekształcany w etykiety, oraz tokenów interpolacji (%1, %2, ...), które oznaczają lokalizacje połączeń i pól niebędących etykietami. Tablice argumentów opisują sposób obsługi tokenów interpolacji.

Na przykład ten blok:

Blok ustawiania zmiennej. Zawiera etykietę „ustaw”, menu wyboru zmiennej, etykietę „na” i pole wprowadzania wartości.

jest zdefiniowany w tym formacie JSON:

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {
      "type": "field_variable",
      "name": "VAR",
      "variable": "item",
      "variableTypes": [""]
    },
    {
      "type": "input_value",
      "name": "VALUE"
    }
  ]
}

Pierwszy token interpolacji (%1) reprezentuje pole zmiennej (type: "field_variable"). Jest on opisany przez pierwszy obiekt w tablicy args0. Drugi token (%2) reprezentuje połączenie wejściowe na końcu danych wejściowych (type: "input_value"). Jest on opisany przez drugi obiekt w tablicy args0.

Wiadomości i metody wprowadzania

Gdy token interpolacji oznacza połączenie, w rzeczywistości oznacza koniec danych wejściowych, które zawierają to połączenie. Dzieje się tak, ponieważ połączenia w polach wartości i instrukcji są renderowane na końcu pola. Dane wejściowe zawierają wszystkie pola (w tym etykiety) po poprzednich danych wejściowych i do bieżącego tokena. W sekcjach poniżej znajdziesz przykładowe wiadomości i utworzone na ich podstawie dane wejściowe.

Przykład 1

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {"type": "field_variable", ...} // token %1
    {"type": "input_value", ...}    // token %2
  ],
}

Spowoduje to utworzenie pola wprowadzania pojedynczej wartości z 3 polami: etykietą ("set"), polem zmiennej i inną etykietą ("to").

Zmapuj komunikat „set %1 to %2” na pole wprowadzania wartości z 3 polami.

Przykład 2

JSON

{
  "message0": "%1 + %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_value", ...} // token %2
  ],
}

Spowoduje to utworzenie 2 wartości wejściowych. Pierwszy nie ma pól, a drugi ma jedno pole ("+").

Zmapuj wiadomość „%1 + %2” na 2 dane wejściowe wartości.

Przykład 3

JSON

{
  "message0": "%1 + %2 %3",
  "args0": [
    {"type": "input_value", ...}   // token %1
    {"type": "input_end_row", ...} // token %2
    {"type": "input_value", ...}   // token %3
  ],
}

Spowoduje to utworzenie:

wartość wpisana bez pól,
Dane wejściowe na końcu wiersza z polem etykiety ("+"), które powodują, że następne dane wejściowe są renderowane w nowym wierszu, oraz
Wartość wpisana bez pól.

Zmapuj komunikat „%1 + %2 %3” na 2 wartości wejściowe i wartość wejściową końca wiersza.

Wpisywanie fikcyjnych danych na końcu wiadomości

Jeśli ciąg znaków message kończy się tekstem lub polami, nie musisz dodawać tokena interpolacji dla fikcyjnego wejścia, które je zawiera – Blockly zrobi to za Ciebie. Na przykład zamiast definiować blok lists_isEmpty w ten sposób:

JSON

{
  "message0": "%1 is empty %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_dummy", ...} // token %2
  ],
}

Zmapuj komunikat „%1 is empty” na pole wejściowe wartości i automatycznie utworzone pole wejściowe zastępcze.

Możesz pozwolić Blockly dodać fikcyjne dane wejściowe i zdefiniować je w ten sposób:

JSON

{
  "message0": "%1 is empty",
  "args0": [
    {"type": "input_value", ...} // token %1
  ],
}

Zmapuj komunikat „%1 is empty” na pole wejściowe wartości i automatycznie utworzone pole wejściowe zastępcze.

Automatyczne dodawanie końcowego fikcyjnego tekstu wejściowego umożliwia tłumaczom zmianę message bez konieczności modyfikowania argumentów opisujących tokeny interpolacji. Więcej informacji znajdziesz w artykule Kolejność tokenów interpolacji.

implicitAlign

W rzadkich przypadkach automatycznie utworzone końcowe fikcyjne dane wejściowe muszą być wyrównane do "RIGHT" lub "CENTRE". Jeśli nie podasz żadnej opcji, domyślna wartość to "LEFT".

W przykładzie poniżej message0 to "send email to %1 subject %2 secure %3" , a Blockly automatycznie dodaje fikcyjne dane wejściowe w trzecim wierszu. Ustawienie parametru implicitAlign0 na wartość "RIGHT" powoduje wyrównanie tego wiersza do prawej strony.

blokadę wysyłania e-maili. Pierwszy wiersz ma etykietę „Wyślij e-maila do” i pole do wpisania wartości. W drugim wierszu znajduje się etykieta „subject” i pole do wpisania wartości. W trzecim wierszu znajduje się etykieta „bezpieczne” i pole wyboru. Wiersz jest wyrównany do prawej strony.

implicitAlign dotyczy wszystkich danych wejściowych, które nie są wyraźnie zdefiniowane w definicji bloku JSON, w tym danych wejściowych na końcu wiersza, które zastępują znaki nowego wiersza ('\n'). Istnieje też wycofana właściwość lastDummyAlign0, która działa tak samo jak implicitAlign0.

Podczas projektowania bloków dla języków zapisywanych od prawej do lewej (arabskiego i hebrajskiego) lewa i prawa strona są odwrócone. W ten sposób "RIGHT" wyrówna pola do lewej.

Wiele wiadomości

Niektóre bloki są naturalnie podzielone na 2 lub więcej oddzielnych części. Rozważmy ten blok powtarzania, który ma 2 wiersze:

Blok powtarzania z 2 wierszami. W pierwszym wierszu znajduje się etykieta „repeat”, pole do wpisania wartości i etykieta „times”. W drugim wierszu znajduje się etykieta „do” i pole wprowadzania instrukcji.

Jeśli ten blok zostałby opisany za pomocą jednego komunikatu, właściwość message0 miałaby wartość "repeat %1 times %2 do %3", gdzie %2 oznacza koniec wiersza. Ten ciąg tekstowy jest trudny do przetłumaczenia, ponieważ trudno jest wyjaśnić, co oznacza podstawienie %2. W niektórych językach %2 znak końca wiersza może być nawet niepożądany. Może być wiele bloków, które chcą udostępnić tekst z drugiego wiersza. Lepszym rozwiązaniem jest użycie więcej niż jednej właściwości message i args:

JSON

{
  "message0": "repeat %1 times",
  "args0": [
    {"type": "input_value", ...} // token %1 in message0
  ],
  "message1": "do %1",
  "args1": [
    {"type": "input_statement", ...} // token %1 in message1
  ],
}

Przypisz komunikat „repeat %1 times” do pola wejściowego wartości i automatycznie utworzonego pola wejściowego fikcyjnej wartości, a komunikat „do %1” do pola wejściowego instrukcji.

W formacie JSON można zdefiniować dowolną liczbę właściwości message, args i implicitAlign, zaczynając od 0 i zwiększając je kolejno. Pamiętaj, że Blok Factory nie może dzielić wiadomości na kilka części, ale można to zrobić ręcznie.

Kolejność tokenów interpolacji

Podczas lokalizowania bloków może być konieczna zmiana kolejności tokenów interpolacji w wiadomości. Jest to szczególnie ważne w przypadku języków, w których kolejność słów jest inna niż w języku angielskim. Na przykład zaczęliśmy od bloku zdefiniowanego przez wiadomość "set %1 to %2":

Blok ustawiania zmiennej z etykietą „set” (ustaw), polem menu zmiennej, etykietą „to” (na) i zewnętrznym polem wprowadzania wartości.

Teraz wyobraź sobie hipotetyczny język, w którym "set %1 to %2" trzeba odwrócić, aby uzyskać "put %2 in %1". Zmiana wiadomości (w tym kolejności tokenów interpolacji) i pozostawienie tablicy argumentów bez zmian spowoduje powstanie tego bloku:

Blok ustawiania zmiennej z etykietą „put”, wbudowanym polem wprowadzania wartości, etykietą „to” i menu zmiennej.

Blockly automatycznie zmienił kolejność pól, utworzył fikcyjne pole wejściowe i przełączył się z zewnętrznych na wewnętrzne pola wejściowe.

Możliwość zmiany kolejności tokenów interpolacji w wiadomości ułatwia lokalizację. Więcej informacji znajdziesz w artykule Interpolacja wiadomości JSON.

Obsługa tekstu

Tekst po obu stronach tokena interpolacji jest przycinany do białych znaków. Tekst, w którym używany jest znak % (np. w odniesieniu do procentu), powinien zawierać %%, aby nie był interpretowany jako token interpolacji.

Blockly automatycznie zastępuje też każdy znak nowego wiersza (\n) w ciągu wiadomości wejściem końca wiersza.

JSON

{
  "message0": "set %1\nto %2",
  "args0": [
    {"type": "field_variable", ...}, // token %1
    {"type": "input_value", ...},    // token %2
  ]
}

$Zmapuj znak nowego wiersza w ciągu „set %1\nto %2” na dane wejściowe końca wiersza.$

Tablice argumentów

Każdy ciąg znaków wiadomości jest powiązany z tablicą args o tej samej liczbie. Na przykład message0 pasuje do args0. Tokeny interpolacji (%1, %2, ...) odnoszą się do elementów tablicy args i muszą w pełni odpowiadać tablicy args0: nie mogą zawierać duplikatów ani pominięć. Numery tokenów odnoszą się do kolejności elementów w tablicy argumentów. Nie muszą one występować w kolejności w ciągu wiadomości.

Każdy obiekt w tablicy argumentów ma ciąg znaków type. Pozostałe parametry różnią się w zależności od typu:

Pola:
Dane wejściowe:
- input_value
- input_statement
- input_dummy
- input_end_row

Możesz też zdefiniować własne pola niestandardowe i dane wejściowe niestandardowe i przekazywać je jako argumenty.

pola alternatywne,

Każdy obiekt może też mieć pole alt. Jeśli Blockly nie rozpoznaje type obiektu, zamiast niego używany jest obiekt alt. Jeśli na przykład do Blockly zostanie dodane nowe pole o nazwie field_time, bloki korzystające z tego pola mogą używać alt do zdefiniowania rezerwy field_input dla starszych wersji Blockly:

JSON

{
  "message0": "sound alarm at %1",
  "args0": [
    {
      "type": "field_time",
      "name": "TEMPO",
      "hour": 9,
      "minutes": 0,
      "alt":
        {
          "type": "field_input",
          "name": "TEMPOTEXT",
          "text": "9:00"
        }
    }
  ]
}

Obiekt alt może mieć własny obiekt alt, co umożliwia tworzenie łańcuchów. Jeśli ostatecznie Blockly nie może utworzyć obiektu w tablicy args0 (po próbie utworzenia dowolnych obiektów alt), obiekt jest po prostu pomijany.

Struktura bloku w formacie JSON Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Przegląd

JSON

Wiadomości i metody wprowadzania

Przykład 1

JSON

Przykład 2

JSON

Przykład 3

JSON

Wpisywanie fikcyjnych danych na końcu wiadomości

JSON

JSON

implicitAlign

Wiele wiadomości

JSON

Kolejność tokenów interpolacji

Obsługa tekstu

JSON

Tablice argumentów

pola alternatywne,

JSON

Struktura bloku w formacie JSON