diff --git a/src/content/reference/rsc/use-server.md b/src/content/reference/rsc/use-server.md index 4d6fb4639..475e802e3 100644 --- a/src/content/reference/rsc/use-server.md +++ b/src/content/reference/rsc/use-server.md @@ -1,18 +1,17 @@ --- title: "'use server'" -titleForTitleTag: "'use server' directive" +titleForTitleTag: "Diretiva `'use server'`" --- -`'use server'` is for use with [using React Server Components](/learn/start-a-new-react-project#bleeding-edge-react-frameworks). +`'use server'` deve ser usado com [usando React Server Components](/learn/start-a-new-react-project#bleeding-edge-react-frameworks). - -`'use server'` marks server-side functions that can be called from client-side code. +`'use server'` marca funções do lado do servidor que podem ser chamadas a partir do código do lado do cliente. @@ -20,11 +19,11 @@ titleForTitleTag: "'use server' directive" --- -## Reference {/*reference*/} +## Referência {/*reference*/} ### `'use server'` {/*use-server*/} -Add `'use server'` at the top of an async function body to mark the function as callable by the client. We call these functions [_Server Functions_](/reference/rsc/server-functions). +Adicione `'use server'` no início do corpo de uma função `async` para marcar a função como chamável pelo cliente. Chamamos essas funções de [_Funções do Servidor_](/reference/rsc/server-functions). ```js {2} async function addToCart(data) { @@ -33,78 +32,78 @@ async function addToCart(data) { } ``` -When calling a Server Function on the client, it will make a network request to the server that includes a serialized copy of any arguments passed. If the Server Function returns a value, that value will be serialized and returned to the client. +Ao chamar uma Server Function no cliente, ela fará uma requisição de rede ao servidor que inclui uma cópia serializada de quaisquer argumentos passados. Se a Server Function retornar um valor, esse valor será serializado e retornado ao cliente. + +Em vez de marcar funções individualmente com `'use server'`, você pode adicionar a diretiva no topo de um arquivo para marcar todas as exportações dentro desse arquivo como Server Functions que podem ser usadas em qualquer lugar, inclusive importadas no código do cliente. -Instead of individually marking functions with `'use server'`, you can add the directive to the top of a file to mark all exports within that file as Server Functions that can be used anywhere, including imported in client code. +#### Ressalvas {/*caveats*/} -#### Caveats {/*caveats*/} -* `'use server'` must be at the very beginning of their function or module; above any other code including imports (comments above directives are OK). They must be written with single or double quotes, not backticks. -* `'use server'` can only be used in server-side files. The resulting Server Functions can be passed to Client Components through props. See supported [types for serialization](#serializable-parameters-and-return-values). -* To import a Server Functions from [client code](/reference/rsc/use-client), the directive must be used on a module level. -* Because the underlying network calls are always asynchronous, `'use server'` can only be used on async functions. -* Always treat arguments to Server Functions as untrusted input and authorize any mutations. See [security considerations](#security). -* Server Functions should be called in a [Transition](/reference/react/useTransition). Server Functions passed to [`
`](/reference/react-dom/components/form#props) or [`formAction`](/reference/react-dom/components/input#props) will automatically be called in a transition. -* Server Functions are designed for mutations that update server-side state; they are not recommended for data fetching. Accordingly, frameworks implementing Server Functions typically process one action at a time and do not have a way to cache the return value. +* `'use server'` deve estar no início da função ou módulo; acima de qualquer outro código, incluindo imports (comentários acima das diretivas são OK). Elas devem ser escritas com aspas simples ou duplas, não crases. +* `'use server'` só pode ser usado em arquivos do lado do servidor. As Server Functions resultantes podem ser passadas para Client Components por meio de props. Veja os [tipos suportados para serialização](#serializable-parameters-and-return-values). +* Para importar Server Functions do [código do cliente](/reference/rsc/use-client), a diretiva deve ser usada em nível de módulo. +* Como as chamadas de rede subjacentes são sempre assíncronas, `'use server'` só pode ser usado em funções `async`. +* Sempre trate os argumentos das Server Functions como entrada não confiável e autorize quaisquer mutações. Veja [considerações de segurança](#security). +* As Server Functions devem ser chamadas em uma [Transition](/reference/react/useTransition). Server Functions passadas para [``](/reference/react-dom/components/form#props) ou [`formAction`](/reference/react-dom/components/input#props) serão automaticamente chamadas em uma transition. +* As Server Functions são projetadas para mutações que atualizam o estado do lado do servidor; não são recomendadas para busca de dados. Consequentemente, frameworks que implementam Server Functions normalmente processam uma ação por vez e não têm uma maneira de armazenar em cache o valor de retorno. -### Security considerations {/*security*/} +### Considerações de segurança {/*security*/} -Arguments to Server Functions are fully client-controlled. For security, always treat them as untrusted input, and make sure to validate and escape arguments as appropriate. +Os argumentos das Server Functions são totalmente controlados pelo cliente. Para segurança, sempre trate-os como entrada não confiável e certifique-se de validar e escapar dos argumentos conforme apropriado. -In any Server Function, make sure to validate that the logged-in user is allowed to perform that action. +Em qualquer Server Function, certifique-se de validar se o usuário logado tem permissão para executar essa ação. -To prevent sending sensitive data from a Server Function, there are experimental taint APIs to prevent unique values and objects from being passed to client code. +Para evitar o envio de dados sensíveis de uma Server Function, existem APIs experimentais de taint para impedir que valores e objetos exclusivos sejam passados para o código do cliente. -See [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueValue) and [experimental_taintObjectReference](/reference/react/experimental_taintObjectReference). +Veja [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueValue) e [experimental_taintObjectReference](/reference/react/experimental_taintObjectReference). -### Serializable arguments and return values {/*serializable-parameters-and-return-values*/} - -Since client code calls the Server Function over the network, any arguments passed will need to be serializable. - -Here are supported types for Server Function arguments: - -* Primitives - * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) - * [number](https://developer.mozilla.org/en-US/docs/Glossary/Number) - * [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) - * [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean) - * [undefined](https://developer.mozilla.org/en-US/docs/Glossary/Undefined) - * [null](https://developer.mozilla.org/en-US/docs/Glossary/Null) - * [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), only symbols registered in the global Symbol registry via [`Symbol.for`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for) -* Iterables containing serializable values - * [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) - * [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) - * [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) - * [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) - * [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) and [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) +### Argumentos e valores de retorno serializáveis {/*serializable-parameters-and-return-values*/} + +Como o código do cliente chama a Server Function pela rede, quaisquer argumentos passados precisarão ser serializáveis. + +Aqui estão os tipos suportados para os argumentos da Server Function: + +* Primitivos + * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) + * [number](https://developer.mozilla.org/en-US/docs/Glossary/Number) + * [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) + * [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean) + * [undefined](https://developer.mozilla.org/en-US/docs/Glossary/Undefined) + * [null](https://developer.mozilla.org/en-US/docs/Glossary/Null) + * [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), apenas símbolos registrados no registro global de Symbol via [`Symbol.for`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for) +* Iteráveis contendo valores serializáveis + * [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + * [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) + * [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) + * [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) + * [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) e [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) * [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) -* [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instances -* Plain [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object): those created with [object initializers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), with serializable properties -* Functions that are Server Functions +* Instâncias [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) +* [Objetos](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) simples: aqueles criados com [inicializadores de objeto](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), com propriedades serializáveis +* Funções que são Server Functions * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) -Notably, these are not supported: -* React elements, or [JSX](/learn/writing-markup-with-jsx) -* Functions, including component functions or any other function that is not a Server Function -* [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript) -* Objects that are instances of any class (other than the built-ins mentioned) or objects with [a null prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects) -* Symbols not registered globally, ex. `Symbol('my new symbol')` -* Events from event handlers +Notavelmente, estes não são suportados: +* Elementos React ou [JSX](/learn/writing-markup-with-jsx) +* Funções, incluindo funções de componente ou qualquer outra função que não seja uma Server Function +* [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript) +* Objetos que são instâncias de qualquer classe (além dos built-ins mencionados) ou objetos com [um protótipo nulo](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects) +* Símbolos não registrados globalmente, ex. `Symbol('meu novo símbolo')` +* Eventos de manipuladores de eventos -Supported serializable return values are the same as [serializable props](/reference/rsc/use-client#passing-props-from-server-to-client-components) for a boundary Client Component. - +Os valores de retorno serializáveis suportados são os mesmos que os [props serializáveis](/reference/rsc/use-client#passing-props-from-server-to-client-components) para um Client Component de limite. -## Usage {/*usage*/} +## Uso {/*usage*/} -### Server Functions in forms {/*server-functions-in-forms*/} +### Server Functions em formulários {/*server-functions-in-forms*/} -The most common use case of Server Functions will be calling functions that mutate data. On the browser, the [HTML form element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) is the traditional approach for a user to submit a mutation. With React Server Components, React introduces first-class support for Server Functions as Actions in [forms](/reference/react-dom/components/form). +O caso de uso mais comum das Server Functions será chamar funções que mutam dados. No navegador, o [elemento de formulário HTML](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) é a abordagem tradicional para um usuário enviar uma mutação. Com React Server Components, o React introduz suporte de primeira classe para Server Functions como Actions em [formulários](/reference/react-dom/components/form). -Here is a form that allows a user to request a username. +Aqui está um formulário que permite a um usuário solicitar um nome de usuário. ```js [[1, 3, "formData"]] // App.js @@ -125,15 +124,15 @@ export default function App() { } ``` -In this example `requestUsername` is a Server Function passed to a ``. When a user submits this form, there is a network request to the server function `requestUsername`. When calling a Server Function in a form, React will supply the form's [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as the first argument to the Server Function. +Neste exemplo, `requestUsername` é uma Server Function passada para um ``. Quando um usuário envia este formulário, há uma requisição de rede para a função do servidor `requestUsername`. Ao chamar uma Server Function em um formulário, o React fornecerá o [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) do formulário como o primeiro argumento para a Server Function. -By passing a Server Function to the form `action`, React can [progressively enhance](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) the form. This means that forms can be submitted before the JavaScript bundle is loaded. +Ao passar uma Server Function para o formulário `action`, o React pode [aprimorar progressivamente](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) o formulário. Isso significa que formulários podem ser enviados antes que o bundle JavaScript seja carregado. -#### Handling return values in forms {/*handling-return-values*/} +#### Manipulando valores de retorno em formulários {/*handling-return-values*/} -In the username request form, there might be the chance that a username is not available. `requestUsername` should tell us if it fails or not. +No formulário de solicitação de nome de usuário, pode haver a chance de um nome de usuário não estar disponível. `requestUsername` deve nos dizer se falha ou não. -To update the UI based on the result of a Server Function while supporting progressive enhancement, use [`useActionState`](/reference/react/useActionState). +Para atualizar a UI com base no resultado de uma Server Function ao mesmo tempo em que suporta o aprimoramento progressivo, use [`useActionState`](/reference/react/useActionState). ```js // requestUsername.js @@ -165,19 +164,19 @@ function UsernameForm() {
-

Last submission request returned: {state}

+

Última solicitação de envio retornou: {state}

); } ``` -Note that like most Hooks, `useActionState` can only be called in [client code](/reference/rsc/use-client). +Observe que, como a maioria dos Hooks, `useActionState` só pode ser chamado em [código do cliente](/reference/rsc/use-client). -### Calling a Server Function outside of `
` {/*calling-a-server-function-outside-of-form*/} +### Chamando uma Server Function fora de `` {/*calling-a-server-function-outside-of-form*/} -Server Functions are exposed server endpoints and can be called anywhere in client code. +As Server Functions são expostas como endpoints do servidor e podem ser chamadas em qualquer lugar no código do cliente. -When using a Server Function outside a [form](/reference/react-dom/components/form), call the Server Function in a [Transition](/reference/react/useTransition), which allows you to display a loading indicator, show [optimistic state updates](/reference/react/useOptimistic), and handle unexpected errors. Forms will automatically wrap Server Functions in transitions. +Ao usar uma Server Function fora de um [formulário](/reference/react-dom/components/form), chame a Server Function em uma [Transition](/reference/react/useTransition), que permite que você exiba um indicador de carregamento, mostre [atualizações de estado otimistas](/reference/react/useOptimistic) e lide com erros inesperados. Os formulários automaticamente encapsularão Server Functions em transitions. ```js {9-12} import incrementLike from './actions'; @@ -196,8 +195,8 @@ function LikeButton() { return ( <> -

Total Likes: {likeCount}

- ; +

Total de curtidas: {likeCount}

+ ; ); } @@ -214,4 +213,4 @@ export default async function incrementLike() { } ``` -To read a Server Function return value, you'll need to `await` the promise returned. +Para ler um valor de retorno da Server Function, você precisará fazer `await` na promise retornada.